# Execute Module
The Execute module provides 9 MCP tools for triggering actions and operations on Komodo resources. All operations are POST requests that initiate asynchronous processes.
## Overview
| Tool | API Endpoint | Description |
|------|-------------|-------------|
| `komodo_execute_Deploy` | `POST /execute/deploy/{id}` | Execute a deployment |
| `komodo_execute_Build` | `POST /execute/build/{id}` | Trigger a build process |
| `komodo_execute_StartServer` | `POST /execute/server/{id}/start` | Start a server |
| `komodo_execute_StopServer` | `POST /execute/server/{id}/stop` | Stop a server |
| `komodo_execute_RestartServer` | `POST /execute/server/{id}/restart` | Restart a server |
| `komodo_execute_RunProcedure` | `POST /execute/procedure/{id}` | Execute a procedure |
| `komodo_execute_TriggerAction` | `POST /execute/action/{id}` | Trigger an action |
| `komodo_execute_PullRepo` | `POST /execute/repo/{id}/pull` | Pull repository changes |
| `komodo_execute_CloneRepo` | `POST /execute/repo/{id}/clone` | Clone a repository |
## Tool Details
### 1. komodo_execute_Deploy
Execute a deployment on Komodo.
**Input Schema:**
```typescript
{
id: string; // Deployment ID (required)
options?: {
force?: boolean; // Force deployment even if no changes
stopBeforeStart?: boolean; // Stop before starting
skipPull?: boolean; // Skip repository pull
}
}
```
**Response:**
```typescript
{
success: boolean;
deploymentId: string;
jobId?: string;
status: 'queued' | 'running' | 'completed' | 'failed';
message: string;
startedAt?: string;
logs?: string[];
}
```
**Example:**
```typescript
const result = await executeHandlers.handleDeploy({
id: 'deployment-123',
options: {
force: true,
stopBeforeStart: true
}
});
```
---
### 2. komodo_execute_Build
Trigger a build process on Komodo.
**Input Schema:**
```typescript
{
id: string; // Build ID (required)
options?: {
skipCache?: boolean; // Skip build cache
skipPull?: boolean; // Skip repository pull
forceBuild?: boolean; // Force rebuild
}
}
```
**Response:**
```typescript
{
success: boolean;
buildId: string;
jobId?: string;
status: 'queued' | 'building' | 'completed' | 'failed';
message: string;
startedAt?: string;
image?: string;
logs?: string[];
}
```
**Example:**
```typescript
const result = await executeHandlers.handleBuild({
id: 'build-456',
options: {
skipCache: true,
forceBuild: true
}
});
```
---
### 3. komodo_execute_StartServer
Start a server on Komodo.
**Input Schema:**
```typescript
{
id: string; // Server ID (required)
options?: {
timeout?: number; // Timeout in seconds
waitForHealthy?: boolean; // Wait for healthy status
}
}
```
**Response:**
```typescript
{
success: boolean;
serverId: string;
action: 'start';
status: 'running' | 'starting' | 'error';
message: string;
timestamp: string;
containerInfo?: {
id?: string;
name?: string;
state?: string;
};
logs?: string[];
}
```
**Example:**
```typescript
const result = await executeHandlers.handleStartServer({
id: 'server-789',
options: {
waitForHealthy: true,
timeout: 60
}
});
```
---
### 4. komodo_execute_StopServer
Stop a running server on Komodo.
**Input Schema:**
```typescript
{
id: string; // Server ID (required)
options?: {
timeout?: number; // Timeout in seconds
force?: boolean; // Force stop (SIGKILL)
removeContainer?: boolean; // Remove container after stop
}
}
```
**Response:**
```typescript
{
success: boolean;
serverId: string;
action: 'stop';
status: 'stopped' | 'stopping' | 'error';
message: string;
timestamp: string;
containerInfo?: {
id?: string;
name?: string;
state?: string;
};
logs?: string[];
}
```
**Example:**
```typescript
const result = await executeHandlers.handleStopServer({
id: 'server-789',
options: {
force: false,
removeContainer: true
}
});
```
---
### 5. komodo_execute_RestartServer
Restart a server on Komodo.
**Input Schema:**
```typescript
{
id: string; // Server ID (required)
options?: {
timeout?: number; // Timeout in seconds
force?: boolean; // Force restart
waitForHealthy?: boolean; // Wait for healthy status
}
}
```
**Response:**
```typescript
{
success: boolean;
serverId: string;
action: 'restart';
status: 'running' | 'starting' | 'error';
message: string;
timestamp: string;
containerInfo?: {
id?: string;
name?: string;
state?: string;
};
logs?: string[];
}
```
**Example:**
```typescript
const result = await executeHandlers.handleRestartServer({
id: 'server-789',
options: {
waitForHealthy: true,
timeout: 120
}
});
```
---
### 6. komodo_execute_RunProcedure
Execute a procedure on Komodo.
**Input Schema:**
```typescript
{
id: string; // Procedure ID (required)
variables?: Record<string, string>; // Procedure variables
options?: {
async?: boolean; // Run asynchronously
timeout?: number; // Timeout in seconds
}
}
```
**Response:**
```typescript
{
success: boolean;
procedureId: string;
executionId?: string;
status: 'queued' | 'running' | 'completed' | 'failed' | 'partial';
message: string;
startedAt?: string;
completedAt?: string;
duration?: number;
steps?: Array<{
step: number;
name: string;
status: 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
output?: string;
error?: string;
duration?: number;
}>;
variables?: Record<string, string>;
output?: string;
}
```
**Example:**
```typescript
const result = await executeHandlers.handleRunProcedure({
id: 'procedure-101',
variables: {
environment: 'production',
version: '1.2.3'
},
options: {
timeout: 300
}
});
```
---
### 7. komodo_execute_TriggerAction
Trigger an action on Komodo.
**Input Schema:**
```typescript
{
id: string; // Action ID (required)
payload?: Record<string, any>; // Action payload
options?: {
async?: boolean; // Execute asynchronously
retryOnFailure?: boolean; // Retry on failure
}
}
```
**Response:**
```typescript
{
success: boolean;
actionId: string;
executionId?: string;
type: 'webhook' | 'script' | 'notification' | 'custom';
status: 'queued' | 'executing' | 'completed' | 'failed';
message: string;
startedAt?: string;
completedAt?: string;
duration?: number;
result?: {
statusCode?: number;
response?: any;
output?: string;
error?: string;
};
}
```
**Example:**
```typescript
const result = await executeHandlers.handleTriggerAction({
id: 'action-202',
payload: {
message: 'Deployment completed',
environment: 'production'
},
options: {
retryOnFailure: true
}
});
```
---
### 8. komodo_execute_PullRepo
Pull latest changes from a repository.
**Input Schema:**
```typescript
{
id: string; // Repository ID (required)
options?: {
branch?: string; // Branch to pull
force?: boolean; // Force pull, discard local changes
submodules?: boolean; // Update submodules
}
}
```
**Response:**
```typescript
{
success: boolean;
repoId: string;
operation: 'pull';
status: 'queued' | 'running' | 'completed' | 'failed';
message: string;
timestamp: string;
branch?: string;
commit?: {
hash?: string;
author?: string;
message?: string;
timestamp?: string;
};
changes?: {
files_changed?: number;
insertions?: number;
deletions?: number;
};
logs?: string[];
}
```
**Example:**
```typescript
const result = await executeHandlers.handlePullRepo({
id: 'repo-303',
options: {
branch: 'main',
submodules: true
}
});
```
---
### 9. komodo_execute_CloneRepo
Clone a repository.
**Input Schema:**
```typescript
{
id: string; // Repository configuration ID (required)
options?: {
branch?: string; // Branch to clone
depth?: number; // Shallow clone depth
submodules?: boolean; // Clone submodules
overwrite?: boolean; // Overwrite existing repository
}
}
```
**Response:**
```typescript
{
success: boolean;
repoId: string;
operation: 'clone';
status: 'queued' | 'running' | 'completed' | 'failed';
message: string;
timestamp: string;
branch?: string;
commit?: {
hash?: string;
author?: string;
message?: string;
timestamp?: string;
};
path?: string;
logs?: string[];
}
```
**Example:**
```typescript
const result = await executeHandlers.handleCloneRepo({
id: 'repo-404',
options: {
branch: 'develop',
depth: 1,
submodules: true
}
});
```
---
## Module Structure
```
src/tools/execute/
├── index.ts # Tool definitions and exports
├── handlers.ts # Handler registry and routing
├── Deploy.ts # Deploy operation handler
├── Build.ts # Build operation handler
├── ServerLifecycle.ts # Server start/stop/restart handlers
├── RunProcedure.ts # Procedure execution handler
├── TriggerAction.ts # Action trigger handler
├── RepoOperations.ts # Repository pull/clone handlers
└── README.md # This file
```
## Error Handling
All execute operations include comprehensive error handling:
1. **Validation Errors**: Invalid input parameters
2. **Authentication Errors**: Missing or invalid credentials
3. **Authorization Errors**: Insufficient permissions
4. **Resource Errors**: Resource not found or unavailable
5. **Execution Errors**: Operation failed during execution
6. **Timeout Errors**: Operation exceeded timeout limit
Errors are logged and returned with descriptive messages.
## Logging
All execute operations are logged with:
- Operation start/completion
- Request parameters
- Response status
- Execution duration
- Error details (if applicable)
## Async Execution
Most execute operations are asynchronous by nature:
- Operations return immediately with a job/execution ID
- Status can be checked using the Read module
- Some operations support `waitForHealthy` or synchronous mode
- Logs are streamed or available after completion
## Best Practices
1. **Always check operation status** after execution
2. **Use appropriate timeouts** for long-running operations
3. **Handle partial failures** in multi-step procedures
4. **Monitor logs** for troubleshooting
5. **Use force options cautiously** to avoid data loss
6. **Implement retry logic** for transient failures
7. **Validate IDs** before executing operations
## Integration Example
```typescript
import { ExecuteHandlers } from './tools/execute/handlers';
import { KomodoClient } from './core/KomodoClient';
// Initialize
const client = new KomodoClient(config);
const executeHandlers = new ExecuteHandlers(client);
// Deploy application
const deployResult = await executeHandlers.handleDeploy({
id: 'my-app-deployment',
options: {
stopBeforeStart: true,
force: false
}
});
console.log(`Deployment ${deployResult.status}: ${deployResult.message}`);
console.log(`Job ID: ${deployResult.jobId}`);
// Monitor deployment status
if (deployResult.jobId) {
// Poll job status using Read module
// See Read module documentation
}
```
## Related Modules
- **Read Module**: Query operation status and results
- **Write Module**: Create/update resource configurations
- **Terminal Module**: Interactive command execution
- **Auth Module**: Authentication for operations
## Version History
- **v1.0.0**: Initial implementation with 9 execute tools
- Deploy, Build, Server lifecycle operations
- Procedure and Action execution
- Repository operations
