# Kiro CLI MCP Server
A Model Context Protocol (MCP) server that enables IDE agents like Cursor and Windsurf to orchestrate kiro-cli with advanced session management, process pooling, and robust error handling.
## Overview
Kiro CLI MCP Server bridges the gap between IDE agents and kiro-cli by providing a standardized MCP interface with enterprise-grade features:
- **10x Performance Improvement**: Process pooling reduces response time from ~500ms to ~50ms
- **Multi-Session Management**: Isolated contexts for different projects/workflows
- **Production-Ready Reliability**: Comprehensive error handling, timeout management, and process cleanup
- **Mock Mode**: Development and testing without kiro-cli dependency
## Features
### Core Capabilities
- **Chat Integration**: Send messages to kiro-cli and receive AI responses
- **Session Management**: Create, switch, and manage multiple isolated sessions
- **Command Execution**: Execute kiro-cli commands (`/help`, `/mcp`, etc.)
- **Custom Agents**: Use and list available custom agents
- **History Management**: Store and retrieve conversation history per session
- **Async Operations**: Background task execution with progress polling
### Performance & Reliability
- **Process Pooling**: Reuse warm kiro-cli processes for 10x faster responses
- **Process Tree Cleanup**: Prevent orphaned processes across platforms
- **Automatic Fallback**: Mock mode when kiro-cli unavailable
- **Timeout Handling**: Configurable timeouts with graceful cleanup
- **Session Isolation**: Per-project working directories and conversation state
## Installation
### Prerequisites
- Python 3.10+
- kiro-cli installed and available in PATH (for full functionality - uses mock mode if unavailable)
### From Source (Current Method)
```bash
git clone https://github.com/your-org/kiro-cli-mcp.git
cd kiro-cli-mcp
pip install -e .
```
### Via pip (After PyPI Publication)
```bash
# Will be available after publishing to PyPI
pip install kiro-cli-mcp
```
### Via uvx (After PyPI Publication)
```bash
# Will be available after publishing to PyPI
uvx install kiro-cli-mcp
```
## Configuration
### IDE Integration
Add to your IDE's MCP configuration file:
**Cursor/Claude Desktop** (`~/.config/claude-desktop/mcp.json`):
```json
{
"mcpServers": {
"kiro-cli-mcp": {
"command": "uvx",
"args": ["kiro-cli-mcp"],
"env": {
"KIRO_MCP_LOG_LEVEL": "INFO"
}
}
}
}
```
**Windsurf** (`.windsurf/mcp.json`):
```json
{
"mcpServers": {
"kiro-cli-mcp": {
"command": "python",
"args": ["-m", "kiro_cli_mcp"],
"env": {
"KIRO_MCP_CLI_PATH": "/usr/local/bin/kiro-cli",
"KIRO_MCP_POOL_SIZE": "5"
},
"autoApprove": [
"kiro_session_list",
"kiro_agents_list",
"kiro_history"
]
}
}
}
```
### Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `KIRO_MCP_CLI_PATH` | Path to kiro-cli executable | `kiro-cli` |
| `KIRO_MCP_COMMAND_TIMEOUT` | Command timeout (seconds) - IDE-optimized | `30` |
| `KIRO_MCP_MAX_SESSIONS` | Maximum concurrent sessions | `10` |
| `KIRO_MCP_SESSION_TIMEOUT` | Session idle timeout (seconds) | `300` |
| `KIRO_MCP_CLEANUP_INTERVAL` | Session cleanup check interval (seconds) | `30` |
| `KIRO_MCP_LOG_LEVEL` | Logging level | `INFO` |
| `KIRO_MCP_DEFAULT_MODEL` | Default AI model for kiro-cli | `claude-opus-4.5` |
| `KIRO_MCP_DEFAULT_AGENT` | Default agent to use | `kiro_default` |
| `KIRO_MCP_LOG_RESPONSE` | Log full CLI responses for debugging | `true` |
| `KIRO_MCP_POOL_SIZE` | Process pool size | `5` |
| `KIRO_MCP_POOL_ENABLED` | Enable process pooling | `true` |
| `KIRO_MCP_POOL_IDLE_TIME` | Process idle time before recycling (seconds) | `300` |
| `KIRO_MCP_POOL_MAX_USES` | Max uses per process before recycling | `100` |
| `KIRO_MCP_MAX_ASYNC_TASKS` | Maximum concurrent async tasks | `100` |
| `KIRO_MCP_TASK_TTL` | Task result TTL (seconds) | `3600` |
## Available MCP Tools
### Session Management
- **`kiro_session_create`** - Create new session with optional agent and working directory
- **`kiro_session_list`** - List all active sessions
- **`kiro_session_switch`** - Switch to specific session
- **`kiro_session_end`** - End a session
- **`kiro_session_clear`** - Clear session history files
- **`kiro_session_save`** - Save session to file
### Chat & Commands
- **`kiro_chat`** - Send chat message and get AI response
- **`kiro_command`** - Execute kiro-cli commands (`/help`, `/mcp`, etc.)
- **`kiro_agents_list`** - List available custom agents
### History Management
- **`kiro_history`** - Get conversation history for session
- **`kiro_history_clear`** - Clear conversation history
### Async Operations
- **`kiro_chat_async`** - Start background chat task
- **`kiro_task_status`** - Poll task progress and results
- **`kiro_task_cancel`** - Cancel running task
- **`kiro_task_list`** - List active tasks
### Monitoring
- **`kiro_pool_stats`** - Get process pool performance statistics
## Usage Examples
### Basic Chat
```python
# Create session for project
await mcp_client.call_tool("kiro_session_create", {
"working_directory": "/path/to/project",
"agent": "code-reviewer"
})
# Send message
response = await mcp_client.call_tool("kiro_chat", {
"message": "Analyze this codebase and suggest improvements"
})
```
### Multi-Project Workflow
```python
# Project A
session_a = await mcp_client.call_tool("kiro_session_create", {
"working_directory": "/projects/frontend",
"agent": "react-expert"
})
# Project B
session_b = await mcp_client.call_tool("kiro_session_create", {
"working_directory": "/projects/backend",
"agent": "python-expert"
})
# Switch between projects
await mcp_client.call_tool("kiro_session_switch", {
"session_id": session_a["session_id"]
})
```
### Async Operations
```python
# Start long-running task
task = await mcp_client.call_tool("kiro_chat_async", {
"message": "Generate comprehensive test suite"
})
# Poll for progress
while True:
status = await mcp_client.call_tool("kiro_task_status", {
"task_id": task["task_id"]
})
if status["status"] == "completed":
break
await asyncio.sleep(1)
```
## Architecture
### MCP Protocol Integration
- **Server**: Built on official MCP SDK (`mcp.server.Server`)
- **Transport**: JSON-RPC 2.0 over stdio
- **Tools**: 16 registered tools with schema validation
- **Resources**: Minimal resource handling for extensibility
### Process Management
```
IDE Agent → MCP Server → Process Pool → kiro-cli instances
↓
Session Manager → Isolated contexts per project
```
### Key Components
- **SessionManager**: Multi-session isolation and lifecycle management
- **ProcessPool**: Warm process reuse for 10x performance improvement
- **CommandExecutor**: Robust command execution with timeout handling
- **StreamingTaskManager**: Async task execution with progress polling
### Performance Optimizations
1. **Process Pooling**: Reuse warm kiro-cli processes
2. **Session Affinity**: Route requests to appropriate process
3. **Intelligent Cleanup**: Remove idle/unhealthy processes
4. **Mock Mode**: Fast responses during development
## Development
### Setup
```bash
git clone https://github.com/your-org/kiro-cli-mcp.git
cd kiro-cli-mcp
pip install -e ".[dev]"
```
### Testing
```bash
# Run all tests
pytest
# With coverage
pytest --cov=kiro_cli_mcp --cov-report=html
# Property-based tests
pytest tests/test_config.py -v
```
### Code Quality
```bash
# Format code
ruff format .
# Lint
ruff check .
# Type checking
mypy src/
```
### Running Server
```bash
# Development mode with debug logging
python -m kiro_cli_mcp --log-level DEBUG
# With custom config
python -m kiro_cli_mcp --config config.json
```
### Contributing
1. Fork the repository
2. Create feature branch (`git checkout -b feature/amazing-feature`)
3. Commit changes (`git commit -m 'Add amazing feature'`)
4. Push to branch (`git push origin feature/amazing-feature`)
5. Open Pull Request
## Troubleshooting
### kiro-cli Not Found
Server automatically enables **mock mode** if kiro-cli is unavailable:
```bash
# Check kiro-cli availability
which kiro-cli
# Set custom path
export KIRO_MCP_CLI_PATH=/custom/path/to/kiro-cli
# Verify server mode
python -m kiro_cli_mcp --log-level DEBUG
# Look for: "✅ kiro-cli is available" or "❌ kiro-cli not available: enabling mock mode"
```
### Performance Issues
```bash
# Verify process pooling is enabled
python -m kiro_cli_mcp --log-level DEBUG
# Look for: "🔄 Using pooled process execution"
# Check pool statistics
# Use kiro_pool_stats tool to monitor performance
```
### Session Management
```bash
# Increase session limits
export KIRO_MCP_MAX_SESSIONS=20
export KIRO_MCP_SESSION_TIMEOUT=7200 # 2 hours
# Clear stuck sessions
# Sessions auto-cleanup after timeout
```
### Process Cleanup
If you encounter orphaned processes:
```bash
# Unix/Linux/macOS
pkill -f kiro-cli
# Windows
taskkill /F /IM kiro-cli.exe
# Check process groups (Unix)
ps -eo pid,pgid,cmd | grep kiro
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Support
- **Issues**: [GitHub Issues](https://github.com/your-org/kiro-cli-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/kiro-cli-mcp/discussions)
- **Documentation**: [Wiki](https://github.com/your-org/kiro-cli-mcp/wiki)
