MCP Ecosystem Operations Tools

Design specification for the MCP ecosystem operations tools -- architecture overview, tool schemas, conversational intents mapping, and error handling.

Architecture Overview

MCP Client (Cursor / Claude Desktop)
    │
    ▼
MCP Server (stdio transport)
    │
    ├── Read-only tools ────► Direct Python calls
    │   (list, describe,       (get_available_ecosystems, eco_mgr,
    │    status, validate)      state.py, YAML parsing)
    │
    └── Async action tools ──► RunManager + subprocess
        (install, sync,         (build_*_command → run_subprocess_task)
         push, deploy, etc.)

Category	Safety	Mode Required	Pattern
Info/Query	read-only	ask	Direct function call, immediate JSON
Safe Write	safe-write	plan	RunManager subprocess, run_id for polling
Dangerous Write	dangerous-write	execute	RunManager subprocess + confirmation

Tool Schemas

amof_list_ecosystems

Category: Info/Query. Integration: get_available_ecosystems() + EcosystemManager.get_ecosystem_summary().

{
  "ecosystems": [
    {
      "name": "amof-platform",
      "path": "ecosystems/amof-platform",
      "repos_count": 3,
      "repos": ["amof", "amof-ui", "amof-backend"],
      "kb_files_count": 1,
      "journal_files_count": 45,
      "active_tasks": 0
    }
  ]
}

amof_get_ecosystem_status

Category: Async action (read-only). Integration: build_status_command() via subprocess.

{
  "workspace": {
    "ecosystem": "amof-platform",
    "workspace_branch": "workspace/amof-platform",
    "active_ticket": "PROJ-123",
    "ticket_count": 2
  },
  "repos": [
    {
      "name": "amof",
      "branch": "feat/amof-cloud",
      "commit": "abc1234",
      "mode": "RW",
      "status": "OK",
      "dirty": false,
      "unpushed": false
    }
  ]
}

amof_push_ecosystem

Category: Async action, dangerous-write. Requires confirmation. Integration: build_push_command() via subprocess.

// Confirmation gate (if confirm=false):
{
  "error": "confirmation_required",
  "message": "Push will modify remote state. Set confirm=true.",
  "repos_affected": ["amof", "amof-ui", "amof-backend"]
}

amof_spin_destroy

Category: Async action, dangerous-write. Requires type-to-confirm. Integration: build_spin_destroy_command() via subprocess.

// Type-to-confirm gate:
{
  "error": "type_to_confirm_failed",
  "message": "To destroy 'amof-platform', set confirm_name='amof-platform'."
}

Common Conversational Intents

User Says	Tool	Notes
"What ecosystems do I have?"	amof_list_ecosystems
"Show me repo status"	amof_get_ecosystem_status	Needs ecosystem context
"Set up the workspace"	amof_install_ecosystem	Dangerous-write, confirm
"Get latest code"	amof_sync_ecosystem	Safe-write
"Push everything"	amof_push_ecosystem	Dangerous-write, confirm
"Deploy the cluster"	amof_spin_deploy	Dangerous-write, preview-then-confirm
"Start working on PROJ-123"	amof_ticket_start	Safe-write
"What am I working on?"	amof_ticket_list	Read-only
"Archive this workspace"	amof_archive_ecosystem	Dangerous-write, confirm
"Delete everything"	amof_discard_ecosystem	Dangerous-write, type-to-confirm

Error Handling

Error Categories

Category	HTTP Code	Rendering
Ecosystem not found	404	Show available ecosystems, suggest amof_list_ecosystems
Run not found	404	Suggest amof_list_runs
Confirmation required	403	Return required fields + instructions
Mode insufficient	403	Explain required mode, show mode-switch hint
Subprocess failed	500	Return exit code + last 10 log lines
Manifest invalid	422	Return validation errors