process-compose-api-mcp

MCP server (stdio) for controlling a process-compose instance through its OpenAPI endpoints.

Features

• API client is generated by orval from downloaded OpenAPI (swagger-doc.latest.yaml)
• Tools now cover all 20 documented API operations, plus 2 convenience tools: process_compose_tail_logs, process_compose_health_summary
• Destructive actions require an explicit process name
• Bulk/project destructive operations require explicit confirm=true
• 10s API timeout for each upstream request
• 404 process errors include process name suggestions when available
• Local log file reads are disabled (logs are fetched only via API endpoint)

Requirements

• Node.js >= 22.18.0
• process-compose API endpoint reachable from this MCP process

Install and Build

npm install
npm run build

Static checks:

npm run typecheck

Code quality checks (Biome):

npm run check

Auto-fix format/lint issues:

npm run check:fix

Full local CI gate:

npm run ci

Run locally:

node dist/index.js

Run via npx (published package):

npx process-compose-api-mcp

Run tests:

npm test

Run live integration test against a real process-compose instance:

npm run test:integration

Integration test validates real operations end-to-end: list/get/restart/stop/start/logs/project state against a live process-compose.

Environment Variables

• PC_API_BASE_URL (default: http://localhost:8080)
• PC_API_TOKEN (optional bearer token sent as Authorization: Bearer ...)
• PC_PORT (optional helper-script port override, default 19081)
• PC_OPENAPI_DOWNLOAD_URL (optional openapi download URL override)
• PC_OPENAPI_OUTPUT_DIR (optional openapi download output directory override)

Example:

export PC_API_BASE_URL="http://127.0.0.1:8080"
export PC_API_TOKEN="your-token-if-needed"
npx process-compose-api-mcp

Claude Code MCP Config (stdio)

Use the built server as a stdio MCP server:

{
  "mcpServers": {
    "process-compose": {
      "command": "npx",
      "args": ["-y", "process-compose-api-mcp"],
      "env": {
        "PC_API_BASE_URL": "http://127.0.0.1:8080"
      }
    }
  }
}

Sample Local Usage

# 1) build
npm run build

# 2) run MCP server
PC_API_BASE_URL=http://127.0.0.1:8080 npx process-compose-api-mcp

# 3) sync API spec + regenerate client from process-compose
PC_PORT=19081 npm run pc:openapi:sync

Process Compose helper scripts:

# Start process-compose (default port 19081)
npm run pc:up

# Detached mode
npm run pc:up:detached

# Download http://localhost:19081/swagger/doc.json as local snapshots (json + yaml)
npm run pc:openapi:download

# Generate TypeScript client from downloaded yaml via orval
npm run pc:openapi:generate

# Download + generate in one step
npm run pc:openapi:sync

# Stop process-compose
npm run pc:down

OpenAPI download output:

• openapi/process-compose/swagger-doc.latest.json
• openapi/process-compose/swagger-doc.<version>.<timestamp>.json
• openapi/process-compose/swagger-doc.latest.yaml
• openapi/process-compose/swagger-doc.<version>.<timestamp>.yaml
• openapi/process-compose/download-meta.json

Sample Node Process (Managed by process-compose)

Sample process file:

• examples/processes/heartbeat.mjs

Sample process-compose file:

• examples/process-compose.yaml

Run with process-compose (example API port 18080):

cd examples
process-compose -p 18080 -t=false up

Manage the process from another shell:

process-compose -p 18080 process list
process-compose -p 18080 process stop heartbeat
process-compose -p 18080 process start heartbeat

Connect this MCP server to that process-compose instance:

PC_API_BASE_URL=http://127.0.0.1:18080 npx process-compose-api-mcp

Troubleshooting

OpenAPI spec download failed

• Verify process-compose API is running and reachable.
• Check PC_API_BASE_URL points to the correct host/port.
• Set PC_OPENAPI_DOWNLOAD_URL explicitly (for example http://localhost:19081/swagger/doc.json).
• Confirm the OpenAPI response is valid JSON and includes a paths object.

Port mismatch

• Common issue: process-compose is on a different port than 8080.
• Set the correct base URL:

  export PC_API_BASE_URL="http://127.0.0.1:<actual-port>"