MCP Implementation Plan

Concrete, file-by-file build plan for the AMOF Model Context Protocol server. Target: scripts/amof/mcp/ (new package).

Existing Assets

Asset	Location	Status
RunManager	scripts/amof/api/run_manager.py	Complete -- 6 methods
RunStore	scripts/amof/api/run_store.py	Complete -- JSON persistence
command_builder.py	scripts/amof/api/command_builder.py	14 builder functions
runner.py	scripts/amof/api/services/runner.py	subprocess management
suggested_actions.py	scripts/amof/api/suggested_actions.py	Complete -- 561 lines
server_cmd.py	scripts/amof/commands/server_cmd.py	PID management
status.py	scripts/amof/commands/status.py	Structured dict return
EcosystemManager	scripts/amof/orchestrator/lifecycle.py	get_ecosystem_summary()

Phase 0: Foundation

MCP server skeleton that starts via stdio, manages session state, and provides decorator/formatting infrastructure.

server.py

import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server

from .session import SessionContext
from .tools import register_all_tools

def create_server() -> Server:
    server = Server("amof-mcp")
    ctx = SessionContext()
    register_all_tools(server, ctx)
    return server

async def run_stdio():
    server = create_server()
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream,
                        server.create_initialization_options())

def main():
    asyncio.run(run_stdio())

session.py

Session-scoped state: mode (ask/plan/execute), scope stack, active ecosystem, session ID, and confirmation tokens with 5-minute TTL.

decorators.py

Three decorators: mode_aware(safety) for mode policy enforcement, requires_scope(*scopes) for scope validation, and with_confirmation() for the two-phase confirmation protocol.

formatters.py

Response envelope builder with _context metadata, breadcrumb format, and suggested actions footer per the UX guide.

Phase 1: Read-Only Tools (MVP)

Module	Tools	LOC
tools/scope_tools.py	switch_ecosystem, scope_back, scope_info	~80
tools/global_tools.py	list_ecosystems, server_status, active_runs	~100
tools/ecosystem_tools.py	describe_ecosystem, get_status, validate_manifest	~120
tools/run_tools.py	get_run_status, get_run_logs, summarize_run, list_runs	~130
tools/release_tools.py	release_status, release_log, release_validate	~100

Phase 2: Async/Subprocess Tools

Mutating tools that run CLI commands as subprocesses and return run_id for polling.

McpRunAdapter

class McpRunAdapter:
    def execute(self, ecosystem, action, build_fn, *args):
        """Start subprocess in background thread.
        Returns {run_id, status: 'queued'}."""
        ...

    def execute_dry_run(self, ecosystem, action, build_fn, *args):
        """Build command, append --dry-run.
        Returns preview."""
        ...

New Tools

Tool	Safety	Integration
amof_install_ecosystem	dangerous-write	build_install_command()
amof_sync_ecosystem	safe-write	build_sync_command()
amof_push_ecosystem	dangerous-write	build_push_command()
amof_spin_deploy	dangerous-write	build_spin_deploy_command()
amof_spin_destroy	dangerous-write	build_spin_destroy_command()
amof_archive_ecosystem	dangerous-write	build_archive_command()
amof_discard_ecosystem	dangerous-write	build_discard_command()
amof_ticket_start	safe-write	build_ticket_start_command()
amof_release_bump	dangerous-write	cmd_release (direct Python)
amof_release_promote	dangerous-write	cmd_release (direct Python)

Phase 3: Server Lifecycle + Confirmation

Server tools: amof_server_start, stop, restart
amof_confirm tool for two-phase confirmation protocol
Token validation and expiry
Force flag integration with CLI

Phase 4: Observability + Telemetry

amof_get_global_telemetry aggregation
Session telemetry per tool call
JSONL event logging for MCP tool invocations
Cost tracking integration

Phase 5: Suggested Actions + Polish

Wire suggested_actions.py into all tool responses
Dynamic action inference rules
Mode-aware filtering
Suppression rules implementation

Acceptance Criteria

All 32 tools callable from Cursor via MCP stdio
Mode policy enforced: ask/plan/execute behavior correct per classification matrix
Confirmation protocol works end-to-end for all dangerous-write tools
Responses follow UX guide: breadcrumb, summary, key details, suggested actions
Suggested actions are context-aware and mode-filtered
Error responses include recovery guidance
Session state persists across tool calls