# Komodo MCP Quick Start Guide
## Installation
```bash
# Clone repository
git clone <repo-url>
cd komodo-mcp
# Install dependencies
npm install
# Build
npm run build
```
## Configuration
Create `.env` file:
```bash
KOMODO_API_URL=https://api.komodo.example.com
KOMODO_API_KEY=your_api_key
KOMODO_API_SECRET=your_api_secret
LOG_LEVEL=info
```
## Running the Server
```bash
# Start MCP server on stdio
npm run start
# Or run directly
node dist/index.js
```
## Testing Integration
Run smoke tests to verify all 60 tools are properly integrated:
```bash
# Build first
npm run build
# Run smoke tests
node dist/tests/integration-smoke.test.js
```
Expected output:
```
=== Integration Smoke Tests ===
✓ PASS: Registry has 6 modules
✓ PASS: Registry has 60 tools
✓ PASS: No duplicate tool names
✓ PASS: All modules have tools
✓ PASS: Registry validation passes
...
=== Summary ===
Passed: 15/15
Failed: 0/15
Success Rate: 100.0%
```
## Using Tools
### Via MCP Protocol
Tools are accessed via the Model Context Protocol:
```json
{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}
```
Response includes all 60 tools:
```json
{
"tools": [
{
"name": "komodo_auth_Login",
"description": "Authenticate with Komodo API...",
"inputSchema": { ... }
},
...
]
}
```
### Calling a Tool
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "komodo_read_ListServers",
"arguments": {
"page": 1,
"page_size": 10,
"status": "running"
}
},
"id": 2
}
```
## Module Overview
### 1. Auth Module (8 tools)
```bash
# Login
komodo_auth_Login { apiKey, apiSecret }
# Validate token
komodo_auth_ValidateToken { token? }
# Create API key
komodo_auth_CreateApiKey { name, permissions }
```
### 2. User Module (10 tools)
```bash
# List users
komodo_user_ListUsers { page?, page_size?, role?, enabled? }
# Create user
komodo_user_CreateUser { username, email, password, role }
# Grant permission
komodo_user_GrantPermission { userId, permission, resourceType?, resourceId? }
```
### 3. Read Module (16 tools)
```bash
# List servers
komodo_read_ListServers { page?, page_size?, status? }
# Get server details
komodo_read_GetServer { id }
# List deployments
komodo_read_ListDeployments { page?, server_id?, status? }
```
### 4. Write Module (8 tools)
```bash
# Create server
komodo_write_CreateServer { name, address, port?, region?, tags? }
# Update server
komodo_write_UpdateServer { id, name?, address?, port?, tags? }
# Create deployment
komodo_write_CreateDeployment { name, serverId, repoId, branch?, buildId?, environment? }
```
### 5. Execute Module (9 tools)
```bash
# Deploy
komodo_execute_Deploy { id, options? }
# Start server
komodo_execute_StartServer { id, options? }
# Run procedure
komodo_execute_RunProcedure { id, variables?, options? }
```
### 6. Terminal Module (9 tools)
```bash
# Create session
komodo_terminal_CreateSession { serverId, workingDirectory?, shell? }
# Execute command
komodo_terminal_ExecuteCommand { sessionId, command, timeout?, captureOutput? }
# Get output
komodo_terminal_GetOutput { sessionId, lines?, clear? }
```
## Common Workflows
### Workflow 1: Deploy Application
```javascript
// 1. Authenticate
const auth = await callTool('komodo_auth_Login', {
apiKey: 'your_key',
apiSecret: 'your_secret'
});
// 2. List servers
const servers = await callTool('komodo_read_ListServers', {
status: 'running'
});
// 3. Create deployment
const deployment = await callTool('komodo_write_CreateDeployment', {
name: 'my-app',
serverId: servers.items[0].id,
repoId: 'repo-123',
branch: 'main'
});
// 4. Execute deployment
const result = await callTool('komodo_execute_Deploy', {
id: deployment.id
});
```
### Workflow 2: Execute Remote Commands
```javascript
// 1. Create terminal session
const session = await callTool('komodo_terminal_CreateSession', {
serverId: 'server-123',
workingDirectory: '/app'
});
// 2. Execute commands
await callTool('komodo_terminal_ExecuteCommand', {
sessionId: session.id,
command: 'npm install'
});
await callTool('komodo_terminal_ExecuteCommand', {
sessionId: session.id,
command: 'npm run build'
});
// 3. Get output
const output = await callTool('komodo_terminal_GetOutput', {
sessionId: session.id,
lines: 100
});
// 4. Close session
await callTool('komodo_terminal_CloseSession', {
sessionId: session.id
});
```
### Workflow 3: User Management
```javascript
// 1. Create user
const user = await callTool('komodo_user_CreateUser', {
username: 'developer1',
email: 'dev@example.com',
password: 'secure_password',
role: 'developer'
});
// 2. Grant permissions
await callTool('komodo_user_GrantPermission', {
userId: user.id,
permission: 'execute',
resourceType: 'deployment'
});
// 3. Add to team
await callTool('komodo_user_ManageTeamMembers', {
teamId: 'team-123',
action: 'add',
userId: user.id
});
```
## Error Handling
All errors follow a consistent format:
```json
{
"error": "Error message",
"code": "ERROR_CODE",
"details": {
"module": "read",
"tool": "komodo_read_GetServer",
"status": 404
},
"timestamp": "2024-01-26T12:00:00.000Z"
}
```
### Error Codes
- `UNAUTHORIZED` - Authentication failed
- `NOT_FOUND` - Resource not found
- `VALIDATION_ERROR` - Invalid parameters
- `NETWORK_ERROR` - Connection issue
- `TIMEOUT_ERROR` - Request timeout
- `RATE_LIMIT_ERROR` - Too many requests
- `INTERNAL_ERROR` - Server error
### Retry Behavior
- Network/timeout errors: Auto-retry 3 times with exponential backoff
- Auth/validation errors: No retry
- Rate limit errors: No retry (implement client-side backoff)
## Debugging
### Enable Debug Logging
```bash
LOG_LEVEL=debug npm run start
```
### View Registry Stats
```javascript
// In code
import { registry } from './registry.js';
console.log(registry.getStats());
// {
// totalModules: 6,
// totalTools: 60,
// authRequiredTools: 52,
// authTools: 8,
// userTools: 10,
// readTools: 16,
// writeTools: 8,
// executeTools: 9,
// terminalTools: 9
// }
```
### Validate Integration
```javascript
import { registry } from './registry.js';
const validation = registry.validate();
console.log(validation);
// {
// valid: true,
// errors: []
// }
```
## Troubleshooting
### Issue: Server won't start
**Check:**
1. Node.js version >= 20.0.0
2. Dependencies installed (`npm install`)
3. Build completed (`npm run build`)
4. Environment variables set
### Issue: Tool not found
**Check:**
1. Tool name follows convention: `komodo_{module}_{operation}`
2. Run smoke tests to verify registration
3. Check registry stats
### Issue: Authentication errors
**Check:**
1. API key and secret are correct
2. HMAC signature is valid
3. Timestamp is within acceptable range (< 5 minutes)
### Issue: Network errors
**Check:**
1. Komodo API URL is accessible
2. Network connectivity
3. Firewall settings
4. Proxy configuration
## Performance Tips
1. **Batch operations**: Group related operations when possible
2. **Cache reads**: Cache frequently accessed read-only data
3. **Reuse sessions**: Keep terminal sessions alive for multiple commands
4. **Pagination**: Use pagination for large lists to reduce response time
5. **Parallel calls**: Make independent calls in parallel
## Security Best Practices
1. **Rotate API keys**: Regularly rotate API keys
2. **Minimum permissions**: Grant only necessary permissions
3. **Secure storage**: Never commit API keys to version control
4. **Token expiration**: Use short-lived tokens when possible
5. **Audit logs**: Enable and monitor audit logs
## Next Steps
- Read the [Integration Architecture](./INTEGRATION_ARCHITECTURE.md) for detailed technical information
- Explore the [API Reference](./API_REFERENCE.md) for complete tool documentation
- Check the [Examples](./examples/) directory for code samples
- Review the [Contributing Guide](../CONTRIBUTING.md) for development guidelines
