# Komodo MCP Server

Model Context Protocol (MCP) server for [Komodo](https://github.com/mbecker20/komodo) - enabling natural language infrastructure management through Claude.

Control your servers, deployments, builds, and infrastructure using conversational AI instead of complex API calls.

## Features

- 60+ MCP tools across 6 modules
- Natural language server management
- Automated deployment workflows
- Real-time monitoring and alerts
- Build pipeline integration
- HMAC-based secure authentication
- Automatic retry logic
- Type-safe TypeScript implementation

## Quick Start

### Installation

```bash
# Clone the repository
git clone https://github.com/your-org/komodo-mcp.git
cd komodo-mcp

# Install dependencies
npm install

# Build the server
npm run build
```

### Configuration

Create a `.env` file with your Komodo credentials:

```bash
KOMODO_URL=https://your-komodo-instance.com
KOMODO_API_KEY=your-api-key
KOMODO_API_SECRET=your-api-secret
```

### Add to Claude

#### Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "komodo": {
      "command": "node",
      "args": ["C:/absolute/path/to/komodo-mcp/dist/index.js"],
      "env": {
        "KOMODO_URL": "https://your-komodo-instance.com",
        "KOMODO_API_KEY": "your-api-key",
        "KOMODO_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

#### Claude Code (CLI)

```bash
claude mcp add komodo -- node /absolute/path/to/komodo-mcp/dist/index.js
```

Then set environment variables in your shell profile.

### First Commands

Ask Claude to interact with your Komodo infrastructure:

```
"Show me all my servers"
"Deploy my API to production"
"What critical alerts do I have?"
"Restart the database server"
"Build version 2.5.0 and deploy to staging"
```

## Available Tools

### Read Module (16 tools)

Read-only access to all Komodo resources:

**Servers**
- `komodo_read_ListServers` - List all servers with filtering
- `komodo_read_GetServer` - Get detailed server information

**Deployments**
- `komodo_read_ListDeployments` - List deployments
- `komodo_read_GetDeployment` - Get deployment details

**Stacks**
- `komodo_read_ListStacks` - List Docker Compose stacks
- `komodo_read_GetStack` - Get stack configuration

**Builds**
- `komodo_read_ListBuilds` - List build configurations
- `komodo_read_GetBuild` - Get build details and history

**Repositories**
- `komodo_read_ListRepos` - List connected repositories
- `komodo_read_GetRepo` - Get repository information

**Procedures**
- `komodo_read_ListProcedures` - List automation procedures
- `komodo_read_GetProcedure` - Get procedure details

**Actions**
- `komodo_read_ListActions` - List configured actions
- `komodo_read_GetAction` - Get action configuration

**Alerts**
- `komodo_read_ListAlerts` - List system alerts
- `komodo_read_GetAlert` - Get detailed alert information

### Execute Module (9 tools)

Trigger actions and manage infrastructure:

**Deployments**
- `komodo_execute_Deploy` - Execute a deployment

**Builds**
- `komodo_execute_Build` - Trigger a build process

**Server Lifecycle**
- `komodo_execute_StartServer` - Start a server
- `komodo_execute_StopServer` - Stop a server
- `komodo_execute_RestartServer` - Restart a server

**Procedures**
- `komodo_execute_RunProcedure` - Execute a procedure

**Actions**
- `komodo_execute_TriggerAction` - Trigger an action

**Repository Operations**
- `komodo_execute_PullRepo` - Pull latest repository changes
- `komodo_execute_CloneRepo` - Clone a repository

## Usage Examples

### Server Management

```
User: Check the health of all production servers

Claude: [Lists all servers with status, CPU, memory metrics]
        [Highlights any issues or alerts]
        [Suggests actions if needed]

User: Restart the database server

Claude: [Executes restart]
        [Monitors status]
        [Confirms healthy state]
```

### Deployment Workflow

```
User: Deploy version 2.5.0 to staging then production

Claude: [Triggers build for v2.5.0]
        [Deploys to staging]
        [Runs health checks]
        [Waits for approval]
        [Deploys to production]
        [Verifies all instances]
```

### Monitoring

```
User: Give me a complete infrastructure health report

Claude: [Analyzes all servers]
        [Checks all deployments]
        [Reviews active alerts]
        [Generates comprehensive report]
        [Recommends actions]
```

See [EXAMPLES.md](./docs/EXAMPLES.md) for more real-world scenarios.

## Documentation

### User Guides

- [Usage Guide](./docs/USAGE.md) - Complete usage guide with examples
- [API Reference](./docs/API_REFERENCE.md) - Detailed API documentation for all 60 tools
- [Examples](./docs/EXAMPLES.md) - Real-world usage scenarios
- [Troubleshooting](./docs/TROUBLESHOOTING.md) - Common issues and solutions
- [Migration Guide](./docs/MIGRATION.md) - Migrate from direct API usage

### Technical Documentation

- [Architecture](./docs/ARCHITECTURE.md) - System architecture and design
- [API Mapping](./docs/API_MAPPING.md) - Komodo API to MCP tool mapping
- [Environment](./docs/ENVIRONMENT.md) - Environment variable configuration

## Development

### Requirements

- Node.js 20+
- TypeScript 5+
- npm 9+

### Build

```bash
npm run build          # Build for production
npm run dev            # Build and watch for changes
npm run clean          # Clean build artifacts
```

### Testing

```bash
npm test               # Run all tests
npm run test:watch     # Run tests in watch mode
npm run test:coverage  # Generate coverage report
```

### Linting & Formatting

```bash
npm run lint           # Check code style
npm run lint:fix       # Fix code style issues
npm run format         # Format code with Prettier
npm run format:check   # Check code formatting
npm run typecheck      # TypeScript type checking
```

## Environment Variables

### Required

| Variable | Description | Example |
|----------|-------------|---------|
| `KOMODO_URL` | Komodo API base URL | `https://komodo.example.com` |
| `KOMODO_API_KEY` | API key for authentication | `km_key_abc123...` |
| `KOMODO_API_SECRET` | API secret for HMAC signing | `km_secret_xyz789...` |

### Optional

| Variable | Description | Default |
|----------|-------------|---------|
| `KOMODO_TIMEOUT` | Request timeout (ms) | `30000` |
| `KOMODO_RETRY_COUNT` | Number of retries on failure | `3` |
| `KOMODO_RETRY_DELAY` | Delay between retries (ms) | `1000` |
| `KOMODO_LOG_LEVEL` | Logging level | `info` |
| `KOMODO_SSL_VERIFY` | Verify SSL certificates | `true` |

See [ENVIRONMENT.md](./docs/ENVIRONMENT.md) for complete configuration details.

## License

MIT License - see [LICENSE](./LICENSE) file for details.

## Support

- **Documentation**: [docs/](./docs/)
- **Issues**: [GitHub Issues](https://github.com/your-org/komodo-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/komodo-mcp/discussions)
- **Komodo**: [github.com/mbecker20/komodo](https://github.com/mbecker20/komodo)

## Acknowledgments

- [Komodo](https://github.com/mbecker20/komodo) - Infrastructure automation platform
- [Model Context Protocol](https://modelcontextprotocol.io) - MCP specification
- [Anthropic](https://www.anthropic.com) - Claude AI assistant

---

**Built with ❤️ for the Komodo community**

Start managing your infrastructure naturally - no more complex API calls, just conversation with Claude.

Get started: [Quick Start](#quick-start) | [Documentation](./docs/USAGE.md) | [Examples](./docs/EXAMPLES.md)