# Komodo MCP Server Implementation
## Overview
Komodo MCP Server is a Model Context Protocol implementation that provides 60+ tools across 6 modules for comprehensive IDE automation and AI-assisted development through Komodo IDE integration.
## Implementation Status
### Completed Files
#### Core Server (src/)
- **index.ts** - Main MCP server entry point with:
- Server initialization with stdio transport
- 60 tool registration across 6 modules
- Error handling and graceful shutdown
- Server lifecycle hooks
- Structured logging
#### Tool Modules (src/tools/)
1. **chat.ts** - 10 tools for real-time chat interaction
- chat_send, chat_stream, chat_get_history
- chat_clear_history, chat_set_context, chat_get_context
- chat_add_context, chat_remove_context
- chat_export, chat_import
2. **conversation.ts** - 10 tools for conversation management
- conversation_create, conversation_get, conversation_list
- conversation_update, conversation_delete, conversation_search
- conversation_export, conversation_import
- conversation_get_templates, conversation_apply_template
3. **file.ts** - 10 tools for file operations
- file_read, file_write, file_create
- file_delete, file_move, file_copy
- file_search, file_get_info, file_list, file_watch
4. **project.ts** - 10 tools for project management
- project_create, project_open, project_close
- project_get_info, project_list, project_build
- project_clean, project_run, project_test, project_analyze
5. **agent.ts** - 10 tools for AI agent management
- agent_spawn, agent_list, agent_get
- agent_stop, agent_restart, agent_send_message
- agent_get_logs, agent_get_metrics
- agent_set_config, agent_coordinate
6. **task.ts** - 10 tools for task management
- task_create, task_get, task_list
- task_update, task_delete, task_execute
- task_cancel, task_schedule
- task_get_result, task_get_report
#### Utilities (src/utils/)
- **logger.ts** - Structured logging utility
- Logs to stderr to keep stdout clean for MCP
- Multiple log levels (debug, info, warn, error)
- Module-specific loggers
- **komodo-client.ts** - Komodo API client
- HTTP request wrapper with authentication
- Automatic error handling
- Structured API responses
#### Types (src/types/)
- **komodo.ts** - TypeScript type definitions
- KomodoConfig, ChatMessage, Conversation
- FileInfo, Project, Agent, Task
- ApiResponse for consistent responses
#### Configuration
- **package.json** - Project configuration
- Dependencies: @modelcontextprotocol/sdk, axios
- Build scripts and development tools
- ES module configuration
- **tsconfig.json** - TypeScript configuration
- ES2022 target with Node16 modules
- Strict type checking enabled
- Source maps and declarations
- **.gitignore** - Git ignore patterns
- Standard Node.js exclusions
- Build artifacts and temporary files
- **README.md** - Comprehensive documentation
- Setup instructions
- Usage examples
- Tool module descriptions
- Development guidelines
## Architecture
```
komodo-mcp/
├── src/
│ ├── index.ts # Main server entry point
│ ├── tools/ # Tool implementations (6 modules × 10 tools)
│ │ ├── chat.ts
│ │ ├── conversation.ts
│ │ ├── file.ts
│ │ ├── project.ts
│ │ ├── agent.ts
│ │ └── task.ts
│ ├── types/ # TypeScript type definitions
│ │ └── komodo.ts
│ └── utils/ # Utility functions
│ ├── logger.ts
│ └── komodo-client.ts
├── dist/ # Compiled output (created by build)
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md
```
## Key Features
### 1. MCP Server
- **Protocol**: Model Context Protocol (MCP) v0.5
- **Transport**: stdio (standard input/output)
- **Error Handling**: Graceful error responses without crashes
- **Logging**: Structured JSON logs to stderr
### 2. Tool Registration
- Automatic tool discovery from 6 modules
- Duplicate tool name detection
- 60 tools total across all modules
### 3. Error Handling
- Process-level handlers for SIGINT, SIGTERM
- Uncaught exception and unhandled rejection handlers
- Tool-specific error wrapping
- Graceful shutdown
### 4. API Client
- Configurable Komodo API endpoint
- HMAC authentication support via API key
- Automatic retry logic (built into axios)
- Type-safe responses
## Next Steps
### 1. Build the Project
```bash
# Install dependencies
npm install
# Install TypeScript if not installed
npm install --save-dev typescript@5.3.3 @types/node@20.11.0
# Build
npm run build
# Verify build output
ls -la dist/
```
### 2. Configure Environment
Create `.env` file:
```bash
KOMODO_HOST=localhost
KOMODO_PORT=8080
KOMODO_API_KEY=your_api_key_here
LOG_LEVEL=info
```
### 3. Test the Server
```bash
# Run directly
npm start
# Or test compilation
node dist/index.js
```
### 4. Add to MCP Client
Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"komodo": {
"command": "node",
"args": ["/absolute/path/to/komodo-mcp/dist/index.js"]
}
}
}
```
### 5. Development
```bash
# Watch mode
npm run dev
# Lint code
npm run lint
# Clean build
npm run clean && npm run build
```
## Tool Usage Examples
### Chat Module
```typescript
// Send a chat message
{
"tool": "chat_send",
"arguments": {
"message": "Hello, how can I help?",
"conversationId": "conv-123"
}
}
```
### File Module
```typescript
// Read a file
{
"tool": "file_read",
"arguments": {
"path": "/path/to/file.ts"
}
}
```
### Agent Module
```typescript
// Spawn an agent
{
"tool": "agent_spawn",
"arguments": {
"type": "coder",
"name": "my-coding-agent",
"capabilities": ["code", "refactor", "test"]
}
}
```
## API Integration
All tools communicate with Komodo IDE through the `komodoClient`:
1. **Authentication**: API key passed in Authorization header
2. **Endpoints**: REST API at `http://{host}:{port}/api`
3. **Responses**: Structured ApiResponse<T> format
4. **Errors**: Handled gracefully with error messages
## Security
- **API Keys**: Stored in environment variables
- **Validation**: Input validation on all tool calls
- **Error Messages**: Sanitized before returning to client
- **Logging**: Sensitive data excluded from logs
## Performance
- **Async Operations**: All tools use async/await
- **Non-Blocking**: stdio transport prevents blocking
- **Memory**: Efficient Map-based tool registry
- **Error Recovery**: Isolated tool execution prevents cascading failures
## Troubleshooting
### Build Issues
```bash
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
# Clean build
npm run clean
npm run build
```
### Runtime Issues
```bash
# Check logs (stderr)
npm start 2> error.log
# Verify dependencies
npm ls @modelcontextprotocol/sdk
# Test Komodo API connection
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:8080/api/health
```
## Contributing
1. Add new tools to appropriate module file
2. Export from module
3. Tools auto-register on server start
4. Follow ToolHandler interface
5. Include comprehensive inputSchema
6. Add error handling
7. Log important operations
## License
MIT
## Support
For issues and questions, please visit the project repository.
