# Read Module Implementation
## Overview
The Read module provides 16 MCP tools for read-only data retrieval from the Komodo API. It implements consistent patterns for listing and retrieving resources across 8 resource types.
## Architecture
### File Structure
```
src/
├── modules/
│ └── read.ts # Core read operations (16 functions)
├── tools/
│ └── read.ts # MCP tool definitions (16 tools)
├── types/
│ └── komodo.ts # TypeScript type definitions
└── utils/
└── api-client.ts # HTTP client with HMAC authentication
```
### Components
#### 1. API Client (`src/utils/api-client.ts`)
Provides authenticated HTTP requests to the Komodo API:
- **HMAC-SHA256 Authentication**: Signs requests with API secret
- **Environment Configuration**: Reads from `KOMODO_URL`, `KOMODO_API_KEY`, `KOMODO_API_SECRET`
- **Timeout Handling**: Configurable request timeouts
- **Error Handling**: Structured error responses
**Example Usage:**
```typescript
import { get } from '../utils/api-client.js';
const servers = await get('/servers', { status: 'running' });
```
#### 2. Type Definitions (`src/types/komodo.ts`)
Comprehensive TypeScript types for all Komodo resources:
- **BaseResource**: Common fields (id, name, created_at, updated_at)
- **Server**: Server configuration and status
- **Deployment**: Container deployment details
- **Stack**: Multi-service stack definitions
- **Build**: Build job information
- **Repo**: Repository configuration
- **Procedure**: Automated procedure definitions
- **Action**: Scheduled/triggered actions
- **Alert**: System alerts and notifications
- **ListResponse<T>**: Paginated list wrapper
- **ErrorResponse**: Error details
#### 3. Read Module (`src/modules/read.ts`)
Core business logic implementing 16 read operations:
**Pattern:**
```typescript
export async function list{Resource}(params?: {
page?: number;
page_size?: number;
// Resource-specific filters
}): Promise<ListResponse<Resource>> {
return get<ListResponse<Resource>>('/resources', params);
}
export async function get{Resource}(id: string): Promise<Resource> {
return get<Resource>(`/resource/${id}`);
}
```
#### 4. MCP Tools (`src/tools/read.ts`)
Exposes read operations as MCP tools following the ToolHandler pattern:
```typescript
interface ToolHandler {
name: string;
description: string;
inputSchema: Record<string, unknown>;
handler: (args: Record<string, unknown>) => Promise<unknown>;
}
```
## Implemented Tools
### Servers (2 tools)
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_read_ListServers` | `GET /servers` | List all servers with filtering |
| `komodo_read_GetServer` | `GET /server/{id}` | Get server details by ID |
**List Filters:** `status` (running, stopped, pending, error)
### Deployments (2 tools)
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_read_ListDeployments` | `GET /deployments` | List all deployments |
| `komodo_read_GetDeployment` | `GET /deployment/{id}` | Get deployment details |
**List Filters:** `server_id`, `status` (running, stopped, deploying, failed)
### Stacks (2 tools)
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_read_ListStacks` | `GET /stacks` | List all stacks |
| `komodo_read_GetStack` | `GET /stack/{id}` | Get stack details |
**List Filters:** `status` (active, inactive, deploying)
### Builds (2 tools)
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_read_ListBuilds` | `GET /builds` | List all builds |
| `komodo_read_GetBuild` | `GET /build/{id}` | Get build details |
**List Filters:** `repo_id`, `status` (pending, building, success, failed)
### Repositories (2 tools)
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_read_ListRepos` | `GET /repos` | List all repositories |
| `komodo_read_GetRepo` | `GET /repo/{id}` | Get repository details |
**List Filters:** `provider` (github, gitlab, bitbucket, other)
### Procedures (2 tools)
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_read_ListProcedures` | `GET /procedures` | List all procedures |
| `komodo_read_GetProcedure` | `GET /procedure/{id}` | Get procedure details |
**List Filters:** `trigger` (manual, scheduled, webhook)
### Actions (2 tools)
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_read_ListActions` | `GET /actions` | List all actions |
| `komodo_read_GetAction` | `GET /action/{id}` | Get action details |
**List Filters:** `type` (script, api, notification), `enabled` (boolean)
### Alerts (2 tools)
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_read_ListAlerts` | `GET /alerts` | List all alerts |
| `komodo_read_GetAlert` | `GET /alert/{id}` | Get alert details |
**List Filters:** `severity` (info, warning, error, critical), `resolved` (boolean), `resource_type`
## Pagination
All list operations support pagination:
```typescript
{
page: number; // Page number (default: 1)
page_size: number; // Items per page (default: 50)
}
```
**Response Format:**
```typescript
{
items: T[];
total: number;
page?: number;
page_size?: number;
}
```
## Authentication
All requests use HMAC-SHA256 authentication:
**Required Headers:**
```
X-Komodo-Api-Key: <KOMODO_API_KEY>
X-Komodo-Timestamp: <unix_timestamp>
X-Komodo-Signature: HMAC-SHA256(body + timestamp, KOMODO_API_SECRET)
```
**Environment Variables:**
- `KOMODO_URL`: Base URL of Komodo API
- `KOMODO_API_KEY`: API key for authentication
- `KOMODO_API_SECRET`: Secret for request signing
- `KOMODO_TIMEOUT`: Request timeout in ms (default: 30000)
## Error Handling
All tools include comprehensive error handling:
1. **Network Errors**: Connection failures, timeouts
2. **Authentication Errors**: Invalid credentials, signature mismatch
3. **API Errors**: Resource not found, validation errors
4. **Logging**: All operations logged with context
**Error Response Format:**
```typescript
{
error: string;
message: string;
code?: string;
details?: unknown;
}
```
## Integration
The Read module is integrated into the main MCP server:
**File:** `src/index.ts`
```typescript
import { readTools } from './tools/read.js';
// Registration
const allTools: ToolHandler[] = [
...chatTools,
...conversationTools,
...fileTools,
...projectTools,
...agentTools,
...taskTools,
...readTools, // 16 read tools
];
```
## Usage Examples
### List Servers
```typescript
// Via MCP tool
{
"tool": "komodo_read_ListServers",
"args": {
"page": 1,
"page_size": 20,
"status": "running"
}
}
```
### Get Server Details
```typescript
// Via MCP tool
{
"tool": "komodo_read_GetServer",
"args": {
"id": "server-123"
}
}
```
### List Deployments by Server
```typescript
// Via MCP tool
{
"tool": "komodo_read_ListDeployments",
"args": {
"server_id": "server-123",
"status": "running"
}
}
```
### List Critical Alerts
```typescript
// Via MCP tool
{
"tool": "komodo_read_ListAlerts",
"args": {
"severity": "critical",
"resolved": false
}
}
```
## Testing
To test the Read module:
1. Set environment variables:
```bash
export KOMODO_URL="https://komodo.example.com"
export KOMODO_API_KEY="your-api-key"
export KOMODO_API_SECRET="your-api-secret"
```
2. Build and run the MCP server:
```bash
npm install
npm run build
node dist/index.js
```
3. Test via Claude Desktop or Claude Code by calling the MCP tools
## Best Practices
1. **Type Safety**: All operations are fully typed
2. **Error Handling**: All errors are caught and formatted
3. **Logging**: All operations are logged with context
4. **Consistent Patterns**: List/Get pattern across all resources
5. **Documentation**: All tools have clear descriptions and schemas
## Future Enhancements
Potential improvements for future versions:
1. **Caching**: Cache frequently accessed resources
2. **Batch Operations**: Retrieve multiple resources at once
3. **Webhooks**: Subscribe to resource changes
4. **Search**: Full-text search across resources
5. **Filtering**: Advanced filtering with logical operators
6. **Sorting**: Custom sort orders for list operations
## Related Documentation
- [API_MAPPING.md](./API_MAPPING.md) - Complete API endpoint mapping
- [ENVIRONMENT.md](./ENVIRONMENT.md) - Environment configuration
- Main README for project setup and installation
