AgentMode

An advanced MCP (Model Context Protocol) server that brings powerful agentic capabilities to AI assistants, implemented as a Spring Boot application. It exposes a comprehensive set of system-, terminal-, file-, notes-, todo-, git-, and history-related tools via MCP so compatible clients can invoke them safely and efficiently.

🚀 Features

• 🔧 Terminal Operations - Execute commands, manage processes, and track history
• 📁 File Management - Complete file system operations with safety checks
• 📝 Notes Management - Create, organize, and persist notes
• ✅ Todo List - Advanced task management with priorities, states, and due dates
• 🔄 Git Integration - Comprehensive Git operations for version control
• 📊 Tool History - Track and reverse tool executions with timestamps
• 🛡️ Thread Safety - All operations are fully thread-safe for concurrent use
• 📈 System Monitoring - Real-time system resources and environment information

🏗️ Tech Stack

• Java 21 - Modern Java with latest language features
• Spring Boot 3.5.7 - Enterprise-grade application framework
• Spring AI MCP Server Starter (org.springframework.ai:spring-ai-starter-mcp-server)
• Gradle 8.14.3 - Build system with wrapper included
• Concurrent Programming - Thread-safe design with synchronized operations

📋 Requirements

• JDK 21 installed and available on PATH
• Internet access to download dependencies on first build
• Git (for Git operations tools)

🔧 Build

# Clean build with tests
./gradlew clean build

# Build without tests
./gradlew clean build -x test

Build Artifacts:

• Runnable Boot jar: build/libs/AgentMode-0.0.1-SNAPSHOT.jar
• Test reports: build/reports/tests/test/index.html
• Code coverage: build/reports/jacoco/test/html/index.html

🚀 Run

Using Gradle (Recommended for development)

./gradlew bootRun

Using the built JAR

java -jar build/libs/AgentMode-0.0.1-SNAPSHOT.jar

With custom configuration

java -jar build/libs/AgentMode-0.0.1-SNAPSHOT.jar --spring.config.location=classpath:/application.properties

When the app starts, the MCP server auto-configures and registers all available tools. Check the startup logs to see how many tools were registered and configuration details.

🧪 Test

# Run all tests
./gradlew test

# Run tests with coverage report
./gradlew test jacocoTestReport

# Run specific test class
./gradlew test --tests TodoListTest

# Run tests with continuous mode
./gradlew test --continuous

Test report will be written to build/reports/tests/test/index.html.

🛠️ Available Tools

The server discovers tools from Spring services using @Tool annotations. All tools are thread-safe and include comprehensive error handling.

💻 Terminal & Command Execution

File: terminal/Terminal.java

• execute-command: Execute a command array (each arg is a separate array element). Records successful commands to history.

File: terminal/AsyncProcessManager.java

• start-command-async: Start background processes and track them with unique IDs
• check-command-status: Check the status of running background processes
• get-command-output: Get output from completed background processes
• stop-command: Stop running background processes
• list-running-commands: List all currently running background processes

📚 Command History

File: terminal/CommandHistory.java

• clear-command-history: Clear all command history
• get-command-history: Get command history list (thread-safe copy)
• history-save-to-file: Save history to a file (set overwrite=true to replace)
• history-load-from-file: Load history from a file

🖥️ System Information & Environment

Files: terminal/OsInfo.java, terminal/EnvironmentTools.java

• get-os, get-os-architecture, get-os-version, get-os-family, is-64-bit
• get-shell-type, get-username, get-java-version, get-java-home
• get-working-directory, get-home-directory, get-temp-directory
• get-environment-variable, get-all-environment-variables
• get-system-property, get-all-system-properties

📊 System Resources

File: terminal/SystemResources.java

• get-available-processors, get-max-memory, get-total-memory, get-free-memory
• get-system-load-average, get-disk-space-info (for a given path)
• get-memory-info, get-system-info

📁 File Operations

File: files/FileOperations.java

• file-read: Read UTF-8 text files
• file-write: Write UTF-8 content (with overwrite control)
• file-append: Append content to files
• file-copy: Copy files and directories
• file-move: Move/rename files and directories
• file-delete: Delete files and directories (recursive option)
• dir-list: List directory contents
• dir-mkdir: Create directories (recursive option)
• file-stat: Get file metadata (size, type, modified time)
• file-exists: Check if paths exist

🎯 Git Operations

File: git/GitTools.java

• git-clone: Clone repositories
• git-status: Get repository status
• git-branch: List and manage branches
• git-add: Add files to staging
• git-commit: Create commits
• git-push: Push to remote repositories
• git-pull: Pull from remote repositories
• git-log: View commit history
• git-checkout: Switch branches or checkout files
• git-merge: Merge branches

📝 Notes Management

File: notes/Notes.java

• add-note, add-note-bulk: Add single or multiple notes
• remove-note, remove-note-bulk: Remove single or multiple notes
• clear-notes: Clear all notes
• get-notes: Get all notes (thread-safe copy)
• notes-save-to-file: Save notes to file
• notes-load-from-file: Load notes from file

✅ Todo List Management

File: todoList/TodoList.java

• Task Creation:
  • add-to-todo-list, add-to-todo-list-simple
  • add-to-todo-list-bulk, add-to-todo-list-bulk-simple
• Task Removal:
  • remove-from-todo-list, remove-from-todo-list-bulk
• Priority Management:
  • add-to-priority-list, add-to-priority-list-bulk
  • remove-from-priority-list, remove-from-priority-list-bulk
  • get-priority-map, clear-priority-list
• State Management:
  • add-to-state-list, add-to-state-list-bulk
  • remove-from-state-list, remove-from-state-list-bulk
  • get-state-map, clear-state-list
• Due Date Management:
  • add-due-date, add-due-date-bulk
  • remove-due-date, remove-due-date-bulk
  • get-due-date-map, clear-due-date-list
• Data Access:
  • get-todo-map, get-todo-titles
  • clear-todo-list, reset

📊 Tool History & Reversal

File: history/ToolHistory.java

• get-tool-history: Get complete tool execution history with timestamps
• get-tool-history-by-tool: Filter history by specific tool name
• get-tool-usage-stats: Get usage statistics for all tools
• get-tool-history-size: Get current history size
• clear-tool-history: Clear all tool history
• reverse-tools: Reverse the effects of the last N tool executions

⚙️ Configuration

The MCP server starter auto-configures sensible defaults. For custom configuration, create application.properties:

# MCP Server Configuration
spring.ai.mcp.server.port=8080
spring.ai.mcp.server.path=/mcp

# Logging Configuration
logging.level.me.touchie771.agentMode=INFO
logging.pattern.console=%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n

Consult Spring AI MCP Server Starter documentation for advanced configuration options.

🔌 Usage with MCP Clients

1. Start the application (see Run section above)
2. Connect an MCP-compatible client (IDE integrations, Claude Desktop, etc.)
3. Configure the client to connect to http://localhost:8080/mcp
4. Invoke tools by name with the expected parameters

Example Usage

# Start the server
./gradlew bootRun

# In your MCP client, you can now:
# - Execute commands: execute-command(["ls", "-la"])
# - Manage files: file-read("/path/to/file.txt")
# - Track history: get-tool-history()
# - Reverse operations: reverse-tools(3)

🐛 Troubleshooting

Common Issues

• Build fails with duplicate tool names: Ensure each @Tool(name = ...) across services is unique
• Java version issues: Verify java -version reports 21. The Gradle toolchain is configured for Java 21
• Dependency download failures: Check network connectivity and proxy settings
• Mockito agent warning during tests: Non-fatal warning on newer JDKs; tests should still pass
• Thread safety violations: All tools are synchronized, but report any concurrency issues found

Debug Mode

Enable debug logging:

./gradlew bootRun --args='--logging.level.me.touchie771.agentMode=DEBUG'

Health Checks

The application exposes health endpoints:

• http://localhost:8080/actuator/health - Application health
• http://localhost:8080/actuator/info - Application information

📁 Project Structure

AgentMode/
├── src/main/java/me/touchie771/agentMode/
│   ├── AgentModeApplication.java          # Main application class
│   ├── files/
│   │   └── FileOperations.java           # File system operations
│   ├── git/
│   │   └── GitTools.java                 # Git operations
│   ├── history/
│   │   ├── ToolHistory.java              # Tool execution history
│   │   └── ToolExecutionRecord.java      # History record model
│   ├── notes/
│   │   └── Notes.java                    # Notes management
│   ├── terminal/
│   │   ├── AsyncProcessManager.java      # Background process management
│   │   ├── CommandHistory.java           # Command history tracking
│   │   ├── EnvironmentTools.java         # Environment variables
│   │   ├── OsInfo.java                   # Operating system info
│   │   ├── SystemResources.java          # System resource monitoring
│   │   └── Terminal.java                 # Command execution
│   └── todoList/
│       ├── Task.java                     # Task model
│       ├── TaskPriority.java             # Priority enum
│       ├── TaskState.java                # State enum
│       └── TodoList.java                 # Todo list management
├── src/test/                             # Test classes
├── build.gradle                          # Build configuration
├── gradle/                               # Gradle wrapper
├── README.md                             # This file
├── CONTRIBUTING.md                       # Contribution guidelines
└── LICENSE                               # License file

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for detailed guidelines:

• Development setup
• Code style and standards
• Adding new tools
• Testing requirements
• Submission process

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Spring AI MCP Documentation
• Spring Boot Documentation
• Issue Tracker
• Discussions

---

Built with ❤️ for the AI community