BuzzbeeSCD/komodo-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b5ef49576443d9640b09eb117520d765da7556b1
komodo-mcp-server/PLAN.md
T

12 KiB
Raw Blame History

Komodo MCP Server — Implementation Plan

Date: 2026-09-07 Status: Planning (pre-OpenChamber handoff) Author: Hermes Conrad, Grade 36 Bureaucrat

1. Problem Statement

We run Komodo (build/deploy platform) at 10.10.2.114:9120 / komodo.example.com. Currently all Komodo operations go through raw curl + komodo-token.sh auth. An MCP server would let any Hermes agent (or any MCP-capable tool) interact with Komodo natively — query builds, trigger deploys, inspect stacks, manage secrets — without bespoke shell scripts per operation.

2. Research Findings

Check Result
GitHub search ("komodo mcp server") Zero results — no existing project
GitHub search ("mcp server" + "komodo-dev") None
Komodo official docs / integrations No MCP mention — they have REST/RPC API only
npm registry ("komodo mcp") None
Similar projects (mcp-servers monorepo, etc.) No Komodo adapter exists anywhere

Conclusion: We are building the first Komodo MCP server. Clean slate, no competition. This is Form 1-A territory — originator's privilege.

3. Komodo API Surface

3.1 Architecture

  • Protocol: RPC-style HTTP. All calls: POST /{read|write|execute}/{RequestName}
  • Auth: Authorization: Bearer <JWT> (obtained via login POST)
  • Content-Type: application/json for all requests
  • Response: JSON (list endpoints return bare arrays, not wrapped data)
  • REST-style paths (/servers, /api/servers) → serve the SPA HTML, do NOT use

3.2 Endpoint Categories

Read (~50 endpoints)

read/ListStacks, read/ListStackServices
read/ListBuilds, read/GetBuild
read/ListServers, read/GetServer
read/ListProcedures, read/GetProcedure
read/ListDeployments, read/GetDeployment
read/ListAlerters, read/GetAlerter
read/ListImageRegistryAccounts, read/GetImageRegistryAccount
read/ListSyncResources, read/GetSyncResource
read/ListResources, read/GetResource
read/ListResourceSyncContents
read/SearchStacks, read/SearchBuilds, read/SearchServers
read/SearchProcedures, read/SearchDeployments, read/SearchAlerters
read/SearchImageRegistryAccounts, read/SearchSyncResources
read/ListServerStats
read/GetStack, read/GetStackServices
read/GetDeploymentLogs
read/GetResourceSyncDifferences
read/GetBuildAggregatedStatus
read/GetUser, read/ListUsers, read/GetLicenseInfo
read/GetGlobalStats, read/GetResourceStats
read/ListTags, read/GetTag, read/ListTagMappings
read/ListBinding, read/GetBinding
read/GetConcurrencyLimitUsage
read/ListExecutions
read/ListAccessRequests, read/GetAccessRequest

Write (~60 endpoints)

write/CreateStack, write/UpdateStack, write/DeleteStack
write/CreateBuild, write/UpdateBuild, write/DeleteBuild
write/CreateServer, write/UpdateServer, write/DeleteServer
write/CreateProcedure, write/UpdateProcedure, write/DeleteProcedure
write/CreateDeployment, write/UpdateDeployment, write/DeleteDeployment
write/CreateAlerter, write/UpdateAlerter, write/DeleteAlerter
write/CreateImageRegistryAccount, write/UpdateImageRegistryAccount
write/CreateSyncResource, write/UpdateSyncResource, write/DeleteSyncResource
write/UpdateStackServiceNames
write/UpdateServerTemplate, write/UpdateServerTemplateInstances
write/BindStack, write/BindServer
write/AddTag, write/UpdateTag, write/DeleteTag, write/UpdateTagMapping
write/UpdateBinding, write/UpdateAllBindings
write/MarkResourceSyncDeployed
write/UpdateUser, write/UpdateUserPermissions
write/UpdateConcurrencyLimit
write/AcknowledgeAccessRequest
write/CreateTagMapping, write/DeleteTagMapping
write/UpdateProcedureSchedule
write/CreateCustomPermission, write/UpdateCustomPermission, write/DeleteCustomPermission
write/UpdateCustomPermissionTagBindings

Execute (~40 endpoints)

execute/RunBuild
execute/DeployStack, execute/DeployStackService
execute/RunProcedure, execute/RunProcedureStage
execute/RunDeploymentAction, execute/RunDeploymentSync
execute/RunResourceSync, execute/RunResourceSyncSync
execute/RunStackRefreshCache, execute/RunStackRefreshContent
execute/RunStackPull, execute/RunStackPullDeployment
execute/RunStackStop, execute/RunStackRestart
execute/RunStackPause, execute/RunStackUnpause
execute/RunStackRemoveOrphanContainers
execute/RunStackToggleServiceDependencies
execute/RunStackAutoUpdate, execute/RunStackCommit
execute/RunServerRefresh, execute/RunServerRefreshContainers
execute/RunServerUpdatePeriphery, execute/RunServerPruneImages
execute/RunServerPruneContainers, execute/RunServerPruneNetworks
execute/RunServerStats, execute/RunServerRunCommand
execute/RunServerScripts, execute/RunServerCopy
execute/RunServerMove, execute/RunDeploymentExecute
execute/RunDeploymentRedeploy, execute/RunDeploymentDestroy
execute/RunDeploymentStop, execute/RunDeploymentLogs
execute/RunSyncDeployment
execute/GetMcpToken

3.3 Auth Flow

  1. POST /auth/login with { username, password } → returns JWT
  2. Use JWT as Authorization: Bearer <token> for all subsequent requests
  3. Token expiry: unknown — cache and re-login on 401

3.4 Our Instance

  • Host: 10.10.2.114:9120 (LXC 121 on yavin)
  • NPM Proxy: https://komodo.example.com (websockets ON)
  • Deploy host: 10.10.2.52 (ProjectE)
  • Registry: git.example.com (Gitea built-in)
  • Secrets: Bitwarden items — never write to files

4. Design Decisions

4.1 Tool Grouping (NOT one tool per endpoint)

Komodo has 150+ endpoints. Exposing each as a separate MCP tool would overwhelm any model. Instead, group by entity type with action-based tools:

MCP Tool Komodo Endpoints Covered
komodo_list All read/List* + read/Search* endpoints
komodo_get All read/Get* endpoints
komodo_create All write/Create* endpoints
komodo_update All write/Update* endpoints
komodo_delete All write/Delete* endpoints
komodo_execute All execute/* endpoints
komodo_logs execute/GetDeploymentLogs, read/GetDeploymentLogs

Each tool takes a resource_type enum (stack, build, server, procedure, deployment, alerter, etc.) plus a params object. The server maps resource_type → Komodo endpoint.

~7 tools total — manageable for any model, covers full API surface.

4.2 Transport

  • HTTP/SSE on a configurable port (default: 9800)
  • Hermes connects via mcp_servers.komodo.url: http://localhost:9800/sse
  • No stdio — this runs as a persistent service on the homelab

4.3 Auth Management

  • Credentials stored in Bitwarden, fetched at runtime via bw CLI
  • Token cached in memory, auto-refreshed on 401
  • Config in MCP server startup args or env vars pointing to Bitwarden item IDs

4.4 Tech Stack

  • Runtime: Node.js 22+ (consistent with existing MCP servers)
  • Language: TypeScript
  • MCP SDK: @modelcontextprotocol/sdk
  • HTTP transport: StreamableHTTPServerTransport (modern MCP standard)
  • No external deps beyond MCP SDK — raw HTTP to Komodo API

4.5 Location

  • Gitea repo: BuzzbeeSCD/komodo-mcp-server (private)
  • Deploy: On the same LXC as Komodo (10.10.2.114) or as a Hermes MCP server running locally
  • Local dev: /home/user/workspace/komodo-mcp-server/

5. Implementation Plan

Phase 1: Scaffold + Auth

  1. Init TypeScript project with MCP SDK
  2. Implement Komodo auth (JWT login, token caching, auto-refresh)
  3. Basic server skeleton with health check
  4. Single komodo_read tool as proof-of-concept

Phase 2: Full CRUD Coverage

  1. Implement komodo_list with resource_type routing
  2. Implement komodo_get with resource_type + ID routing
  3. Implement komodo_create / komodo_update / komodo_delete
  4. Validation layer — required params per resource_type

Phase 3: Execute Operations

  1. Implement komodo_execute for build/deploy/procedure triggers
  2. Implement komodo_logs for deployment log retrieval
  3. SSE support for long-running operations (builds, deploys)

Phase 4: Packaging + Deploy

  1. systemd service unit for persistent operation
  2. Hermes config integration (mcp_servers.komodo)
  3. Bitwarden credential integration
  4. Documentation + skill creation

6. Tool Schemas (Draft)

komodo_list

{
  "name": "komodo_list",
  "description": "List or search Komodo resources (stacks, builds, servers, procedures, deployments, alerters, etc.)",
  "parameters": {
    "resource_type": {
      "type": "string",
      "enum": ["stack", "build", "server", "procedure", "deployment", "alerter", "image_registry_account", "sync_resource", "user", "tag", "execution", "access_request"]
    },
    "search": { "type": "string", "description": "Optional search/filter query" },
    "project": { "type": "string", "description": "Filter by project name or ID" }
  }
}

komodo_get

{
  "name": "komodo_get",
  "description": "Get a single Komodo resource by ID",
  "parameters": {
    "resource_type": { "type": "string", "enum": ["..." /* same as list */] },
    "id": { "type": "string", "description": "Resource ID or name" }
  }
}

komodo_execute

{
  "name": "komodo_execute",
  "description": "Execute a Komodo operation (build, deploy, procedure run, server refresh, etc.)",
  "parameters": {
    "operation": {
      "type": "string",
      "enum": ["run_build", "deploy_stack", "deploy_stack_service", "run_procedure", "run_procedure_stage", "run_resource_sync", "refresh_stack_cache", "refresh_stack_content", "stack_pull", "stack_stop", "stack_restart", "stack_pause", "stack_unpause", "server_refresh", "server_update_periphery", "server_prune_images", "server_prune_containers", "server_run_command", "server_scripts", "get_mcp_token"]
    },
    "id": { "type": "string", "description": "Resource ID or name" },
    "params": { "type": "object", "description": "Additional parameters for the operation" }
  }
}

7. Risks & Mitigations

Risk Mitigation
Token expiry unknown Re-login on 401; cache token in memory
Komodo API undocumented endpoints Start with known endpoints from komodo-ops skill; expand empirically
150+ endpoints in enum lists overwhelm models Keep resource_type enum short — ~12 types, not 150 endpoints
Long-running builds block MCP tool calls Use fire-and-forget for execute ops; return execution ID for status polling
SSE transport complexity Use stdio for local Hermes integration first, HTTP later if remote access needed

8. Success Criteria

  • komodo_list returns live data from our Komodo instance
  • komodo_execute run_build triggers an actual build
  • komodo_execute deploy_stack triggers an actual deploy
  • Token auto-refreshes on expiry without manual intervention
  • Hermes can use Komodo tools via mcp_servers.komodo config
  • Service runs as systemd unit with auto-restart

9. Files to Create

komodo-mcp-server/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts          # Entry point, MCP server setup
│   ├── komodo-client.ts  # Komodo API client (auth, HTTP, token caching)
│   ├── tools/
│   │   ├── list.ts       # komodo_list tool
│   │   ├── get.ts        # komodo_get tool
│   │   ├── create.ts     # komodo_create tool
│   │   ├── update.ts     # komodo_update tool
│   │   ├── delete.ts     # komodo_delete tool
│   │   ├── execute.ts    # komodo_execute tool
│   │   └── logs.ts       # komodo_logs tool
│   └── types.ts          # Komodo API type definitions
├── references/
│   └── api.md            # Full endpoint → tool mapping reference
└── README.md
Reference in New Issue View Git Blame Copy Permalink