#!/usr/bin/env python3 """Third-party-package-free STDIO MCP server for a compiled Codex MMO mesh.""" from __future__ import annotations import hashlib import hmac import json import os import sys import traceback from typing import Any from mmo_profiles import agent_mcp_tool_names from mmo_runtime import ( ADMITTING_JOB_STATUSES, ADMITTING_SESSION_STATUSES, accept_result, cancel_job, control_agent_run, inspect_agent_run, integrate_patch, list_agent_runs, list_jobs, load_job, load_session, read_agent_trace, read_agent_trace_record, read_result, reject_result, spawn_job, spawn_jobs, wait_for_jobs, ) from mmo_schema import validate_instance from mmo_snapshot import load_snapshot from mmo_util import package_version, strict_json_loads PROTOCOL_VERSION = "2025-06-18" SERVER_NAME = "codex-mmo-agent-mesh" SESSION_ID = os.environ.get("MMO_ROOT_SESSION_ID", "") RUN_ID = os.environ.get("MMO_RUN_ID", "") CALLER_AGENT = os.environ.get("MMO_CALLER_AGENT", "") CALLER_JOB_ID = os.environ.get("MMO_CALLER_JOB_ID") or None CALLER_NATIVE = os.environ.get("MMO_CALLER_NATIVE") == "1" CALLER_TOKEN = os.environ.get("MMO_CALLER_TOKEN", "") NATIVE_CALLER_TOKEN = os.environ.get("MMO_NATIVE_CALLER_TOKEN", "") def _context() -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]: if not SESSION_ID or not RUN_ID or not CALLER_AGENT: raise RuntimeError("MMO MCP server is missing session/run/caller identity") session = load_session(SESSION_ID) if session.get("status") not in ADMITTING_SESSION_STATUSES: raise PermissionError("root session is not active") if session.get("current_run_id") != RUN_ID: raise PermissionError("MCP caller belongs to an inactive session run") snapshot = load_snapshot(session["snapshot_hash"]) resolved = snapshot["resolved"] if CALLER_AGENT not in resolved["agents"]: raise RuntimeError(f"unknown caller agent: {CALLER_AGENT}") if CALLER_JOB_ID: caller_job = load_job(CALLER_JOB_ID) if caller_job.get("session_id") != SESSION_ID: raise PermissionError("MCP caller job belongs to another session") if caller_job.get("run_id") != RUN_ID: raise PermissionError("MCP caller job belongs to another session run") if caller_job.get("status") not in ADMITTING_JOB_STATUSES: raise PermissionError("MCP caller job is not active") if not CALLER_NATIVE and caller_job.get("agent") != CALLER_AGENT: raise PermissionError("MCP caller role does not match its job") expected_caller_token = str(caller_job.get("mcp_caller_token_hash", "")) else: if not CALLER_NATIVE and CALLER_AGENT != session.get("root_agent"): raise PermissionError("only the root role may call without a job identity") expected_caller_token = str(session.get("root_mcp_token_hash", "")) observed_caller_token = hashlib.sha256(CALLER_TOKEN.encode("utf-8")).hexdigest() if ( not expected_caller_token or not CALLER_TOKEN or not hmac.compare_digest(expected_caller_token, observed_caller_token) ): raise PermissionError("invalid MCP caller capability token") if CALLER_NATIVE: expected = str(session.get("native_token_hashes", {}).get(CALLER_AGENT, "")) observed = hashlib.sha256(NATIVE_CALLER_TOKEN.encode("utf-8")).hexdigest() if not expected or not NATIVE_CALLER_TOKEN or not hmac.compare_digest(expected, observed): raise PermissionError("invalid native-agent MCP capability token") if "native" not in resolved["agents"][CALLER_AGENT].get("backends", []): raise PermissionError("caller role is not native-enabled") return session, resolved, resolved["agents"][CALLER_AGENT] def _child_description(agent_id: str, agent: dict[str, Any], resolved: dict[str, Any]) -> str: model = resolved["models"][agent["model"]] return ( f"{agent_id}: {agent.get('description') or 'profile participant'}; " f"model={model['display_name']}; permissions={agent['permissions']}; " f"trust={agent['trust']}; task_kinds={','.join(agent['allowed_task_kinds'])}; " f"max_active={agent['max_active']}" ) def _available_children( session: dict[str, Any], resolved: dict[str, Any], caller: dict[str, Any] ) -> list[str]: if session.get("tainted"): return [] return [ child for child in caller["can_spawn"] if "mcp" in resolved["agents"][child].get("backends", []) and session.get("route_availability", {}) .get(resolved["agents"][child]["route"], {}) .get("available") ] def _common_spawn_properties(children: list[str]) -> dict[str, Any]: return { "agent": { "type": "string", "enum": children, "description": "Profile participant to launch. Select by role capability.", }, "mode": { "type": "string", "enum": ["read-only", "workspace-write"], "default": "read-only", }, "cwd": { "type": "string", "description": "Optional directory inside the root session checkout.", }, "write_scope": { "type": "array", "items": {"type": "string", "minLength": 1}, "maxItems": 64, "description": "Required for workspace-write; smallest disjoint files/directories owned by the child.", }, "attachments": { "type": "array", "items": {"type": "string", "minLength": 1}, "maxItems": 12, "description": "Files inside the session root. Image files require an image-capable role and transport.", }, "label": {"type": "string", "maxLength": 80}, } def _literal_task_schema() -> dict[str, Any]: path_array = { "type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1, "maxItems": 32, } return { "oneOf": [ { "type": "object", "properties": { "operation": {"const": "locate"}, "needle": {"type": "string", "minLength": 1, "maxLength": 500}, "paths": path_array, "max_results": {"type": "integer", "minimum": 1, "maximum": 200}, }, "required": ["operation", "needle"], "additionalProperties": False, }, { "type": "object", "properties": { "operation": {"const": "references"}, "symbol": {"type": "string", "minLength": 1, "maxLength": 500}, "paths": path_array, "max_results": {"type": "integer", "minimum": 1, "maximum": 200}, }, "required": ["operation", "symbol"], "additionalProperties": False, }, { "type": "object", "properties": { "operation": {"const": "extract"}, "path": {"type": "string", "minLength": 1}, "start_line": {"type": "integer", "minimum": 1}, "end_line": {"type": "integer", "minimum": 1}, }, "required": ["operation", "path", "start_line", "end_line"], "additionalProperties": False, }, { "type": "object", "properties": { "operation": {"const": "summarize_supplied"}, "text": {"type": "string", "minLength": 1, "maxLength": 50000}, "max_points": {"type": "integer", "minimum": 1, "maximum": 50}, }, "required": ["operation", "text"], "additionalProperties": False, }, ] } def _spawn_schema(children: list[str], resolved: dict[str, Any]) -> dict[str, Any]: """Advertise one stable object shape; selected-role rules remain authoritative.""" agents = [resolved["agents"][child] for child in children] properties = _common_spawn_properties(children) required = ["agent"] low_trust = [agent for agent in agents if agent["trust"] == "low"] ordinary = [agent for agent in agents if agent["trust"] != "low"] if low_trust: properties["literal_task"] = _literal_task_schema() properties["literal_task"]["description"] = ( "Required only for a selected low-trust role; exact operation validation is server-side." ) if ordinary: task_kinds = sorted({kind for agent in ordinary for kind in agent["allowed_task_kinds"]}) properties["task_kind"] = { "type": "string", "enum": task_kinds, "description": "Must be allowed by the selected agent role.", } properties["task"] = { "type": "string", "minLength": min(int(agent["min_task_chars"]) for agent in ordinary), "maxLength": max(int(agent["max_task_chars"]) for agent in ordinary), "description": ( "Self-contained bounded brief: objective, context, non-goals, deliverable, and " "validation. The selected role's exact length and task-kind limits are enforced " "server-side. Do not delegate the caller's immediate critical path." ), } if low_trust and not ordinary: required.append("literal_task") elif ordinary and not low_trust: required.extend(["task_kind", "task"]) return { "type": "object", "properties": properties, "required": required, "additionalProperties": False, } def _control_tool_definitions( resolved: dict[str, Any], caller: dict[str, Any] ) -> list[dict[str, Any]]: controls = caller.get("controls", {}) controlled = sorted(controls) if isinstance(controls, dict) else [] if not controlled: return [] granted_actions = { action for grant in controls.values() if isinstance(grant, dict) for action in grant.get("actions", []) } role_text = ", ".join(controlled) base = { "agent_run_ref": { "type": "string", "pattern": "^ar_", "description": ( "Opaque run reference from agent_list for an authorized target role: " + role_text ), } } revision = { "expected_revision": { "type": "integer", "minimum": 0, "description": "Compare-and-swap revision returned by agent_inspect/status.", } } def schema(properties: dict[str, Any], required: list[str]) -> dict[str, Any]: return { "type": "object", "properties": {**base, **properties}, "required": ["agent_run_ref", *required], "additionalProperties": False, } mutation = { "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": False, } text = {"type": "string", "minLength": 1, "maxLength": 20000} efforts = sorted( { effort for role in controlled for effort in resolved["agents"][role].get("allowed_reasoning_efforts", []) } ) task_kinds = sorted( { kind for role in controlled for kind in resolved["agents"][role].get("allowed_task_kinds", []) } ) definitions: list[dict[str, Any]] = [ { "name": "agent_list", "description": ( "Discover authorized root, native Codex, and supervised MCP runs and their " "opaque run references." ), "inputSchema": { "type": "object", "properties": {}, "additionalProperties": False, }, "annotations": {"readOnlyHint": True, "openWorldHint": False}, }, { "name": "agent_inspect", "description": "Inspect durable and live state for an authorized agent run.", "inputSchema": schema({}, []), "annotations": {"readOnlyHint": True, "openWorldHint": False}, }, { "name": "agent_trace", "description": ( "Read a paginated durable event trace. Private reasoning is filtered while " "completed messages and empirical tool evidence are retained." ), "inputSchema": schema( { "cursor": {"type": "integer", "minimum": 0}, "limit": {"type": "integer", "minimum": 1, "maximum": 200}, }, [], ), "annotations": {"readOnlyHint": True, "openWorldHint": False}, }, { "name": "agent_trace_record", "description": ( "Read an oversized filtered trace record without loss. Use the record_cursor " "reported by agent_trace and follow next_cursor until null." ), "inputSchema": schema( { "record_cursor": {"type": "integer", "minimum": 0}, "cursor": {"type": "integer", "minimum": 0}, "max_chars": {"type": "integer", "minimum": 500, "maximum": 500000}, }, ["record_cursor"], ), "annotations": {"readOnlyHint": True, "openWorldHint": False}, }, { "name": "agent_steer", "description": "Inject guidance into the worker's active turn.", "inputSchema": schema({**revision, "input": text}, ["expected_revision", "input"]), "annotations": mutation, }, { "name": "agent_interrupt", "description": "Interrupt the active turn but retain its durable thread.", "inputSchema": schema(revision, ["expected_revision"]), "annotations": mutation, }, { "name": "agent_pause", "description": ( "Cold-pause a supervised worker: checkpoint evidence, retire its host, release " "capacity, and retain the exact thread for fresh-admission continuation." ), "inputSchema": schema(revision, ["expected_revision"]), "annotations": mutation, }, { "name": "agent_continue", "description": ( "Continue a paused, detached, or suspended run on its existing thread. " "Goal-mode runs may receive a larger total token budget within the compiled cap." ), "inputSchema": schema( { **revision, "input": text, "goal_token_budget": {"type": "integer", "minimum": 10000}, }, ["expected_revision"], ), "annotations": mutation, }, { "name": "agent_detach", "description": "Detach supervision while the durable run continues.", "inputSchema": schema(revision, ["expected_revision"]), "annotations": mutation, }, { "name": "agent_stop", "description": "Fully stop the run while retaining durable history and evidence.", "inputSchema": schema(revision, ["expected_revision"]), "annotations": mutation, }, { "name": "agent_finalize", "description": "Request evidence-only, contract-compliant finalization.", "inputSchema": schema({**revision, "input": text}, ["expected_revision"]), "annotations": mutation, }, { "name": "agent_compact", "description": "Start Codex compaction for the durable thread.", "inputSchema": schema(revision, ["expected_revision"]), "annotations": mutation, }, { "name": "agent_respond", "description": ( "Answer a pending app-server user-input, MCP-elicitation, or approval request " "with the exact response object required by that request method." ), "inputSchema": schema( { **revision, "request_id": {"oneOf": [{"type": "integer"}, {"type": "string"}]}, "response": {"type": "object"}, }, ["expected_revision", "request_id", "response"], ), "annotations": mutation, }, { "name": "agent_set_effort", "description": "Change reasoning effort within the role's compiled allowlist.", "inputSchema": schema( {**revision, "effort": {"type": "string", "enum": efforts}}, ["expected_revision", "effort"], ), "annotations": mutation, }, { "name": "agent_fork", "description": ( "Fork a persisted MCP worker into a normally admitted independent job. A native " "fork instead inherits its role, cwd, and sandbox inside the shared root host, " "obeys the native-thread limit, and rejects MCP-only scope or attachment overrides." ), "inputSchema": schema( { **revision, "task_kind": {"type": "string", "enum": task_kinds}, "input": text, "mode": { "type": "string", "enum": ["read-only", "workspace-write"], "default": "read-only", }, "cwd": {"type": "string"}, "write_scope": { "type": "array", "items": {"type": "string", "minLength": 1}, "maxItems": 64, }, "attachments": { "type": "array", "items": {"type": "string", "minLength": 1}, "maxItems": 12, }, "label": {"type": "string", "maxLength": 80}, }, ["expected_revision", "task_kind", "input"], ), "annotations": mutation, }, ] action_by_tool = { "agent_list": None, "agent_inspect": "inspect", "agent_trace": "trace", "agent_trace_record": "trace", "agent_steer": "steer", "agent_interrupt": "interrupt", "agent_pause": "pause", "agent_continue": "continue", "agent_detach": "detach", "agent_stop": "stop", "agent_finalize": "finalize", "agent_compact": "compact", "agent_respond": "respond", "agent_set_effort": "set_effort", "agent_fork": "fork", } return [ definition for definition in definitions if action_by_tool[definition["name"]] is None or action_by_tool[definition["name"]] in granted_actions ] def tool_definitions() -> list[dict[str, Any]]: session, resolved, caller = _context() children = _available_children(session, resolved, caller) child_text = ( "\n".join( "- " + _child_description(key, resolved["agents"][key], resolved) for key in children ) or "- none" ) spawn_description = ( "Start one real asynchronous profile participant and return immediately. Continue useful " "non-overlapping caller work; wait only at a dependency barrier. Available children:\n" + child_text ) tools: list[dict[str, Any]] = [] if children: single_schema = _spawn_schema(children, resolved) tools.extend( [ { "name": "agent_spawn", "description": spawn_description, "inputSchema": single_schema, "annotations": { "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": False, }, }, { "name": "agents_spawn", "description": ( "Start multiple independent participants in one tool turn. The complete batch is " "validated and admitted atomically: either every request starts or none does. " "Immediately continue the caller's distinct critical-path work.\n" + child_text ), "inputSchema": { "type": "object", "properties": { "agents": { "type": "array", "items": single_schema, "minItems": 1, "maxItems": 12, } }, "required": ["agents"], "additionalProperties": False, }, "annotations": { "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": False, }, }, ] ) management_tools = [ { "name": "agent_status", "description": "Poll visible descendants without blocking. Omit job_ids to list recent visible jobs.", "inputSchema": { "type": "object", "properties": { "job_ids": {"type": "array", "items": {"type": "string"}, "maxItems": 100}, "limit": {"type": "integer", "minimum": 1, "maximum": 1000}, }, "additionalProperties": False, }, "annotations": { "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": False, }, }, { "name": "agents_wait", "description": ( "Wait for specified descendants only when the next action genuinely depends on them. " "The wait is bounded to 120 seconds and returns compact state. Pass the exact progress " "revision map for every requested job to return at the first durable change." ), "inputSchema": { "type": "object", "properties": { "job_ids": { "type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 100, }, "timeout_seconds": {"type": "integer", "minimum": 0, "maximum": 120}, "include_results": {"type": "boolean"}, "after_revision": { "type": "object", "additionalProperties": { "type": "string", "minLength": 64, "maxLength": 64, }, }, }, "required": ["job_ids"], "additionalProperties": False, }, "annotations": { "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": False, }, }, { "name": "agent_result", "description": ( "Read a terminal descendant result without loss. Start at cursor 0 and follow " "next_cursor until null. Reading changes its lifecycle from unread to read; " "it does not accept, reject, consume, or integrate the result." ), "inputSchema": { "type": "object", "properties": { "job_id": {"type": "string"}, "cursor": {"type": "integer", "minimum": 0}, "max_chars": {"type": "integer", "minimum": 500, "maximum": 500000}, }, "required": ["job_id"], "additionalProperties": False, }, "annotations": { "readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": False, }, }, { "name": "agent_result_accept", "description": ( "Accept a result after reading and reviewing it. A writable result is still not " "integrated until agent_patch_integrate succeeds." ), "inputSchema": { "type": "object", "properties": { "job_id": {"type": "string"}, "reason": {"type": "string", "minLength": 1, "maxLength": 500}, }, "required": ["job_id", "reason"], "additionalProperties": False, }, "annotations": {"readOnlyHint": False, "openWorldHint": False}, }, { "name": "agent_result_reject", "description": "Reject a result after reading it, with an auditable evidence-based reason.", "inputSchema": { "type": "object", "properties": { "job_id": {"type": "string"}, "reason": {"type": "string", "minLength": 1, "maxLength": 500}, }, "required": ["job_id", "reason"], "additionalProperties": False, }, "annotations": {"readOnlyHint": False, "openWorldHint": False}, }, { "name": "agent_patch_integrate", "description": ( "Validate base fingerprints and git apply --check, then explicitly integrate an " "accepted isolated writable-worker patch into the canonical workspace." ), "inputSchema": { "type": "object", "properties": { "job_id": {"type": "string"}, "reason": {"type": "string", "minLength": 1, "maxLength": 500}, }, "required": ["job_id", "reason"], "additionalProperties": False, }, "annotations": { "readOnlyHint": False, "destructiveHint": True, "idempotentHint": False, "openWorldHint": False, }, }, { "name": "agent_cancel", "description": "Cancel a stale, duplicate, mis-scoped, or no-longer-useful descendant and its child subtree.", "inputSchema": { "type": "object", "properties": { "job_id": {"type": "string"}, "cascade": {"type": "boolean"}, "reason": { "type": "string", "maxLength": 500, "description": "Why the job is stale, duplicate, mis-scoped, or no longer useful.", }, }, "required": ["job_id"], "additionalProperties": False, }, "annotations": { "readOnlyHint": False, "destructiveHint": True, "idempotentHint": True, "openWorldHint": False, }, }, ] if caller["can_spawn"] or caller.get("controls"): if session.get("tainted"): management_tools = [ tool for tool in management_tools if tool["name"] != "agent_patch_integrate" ] tools.extend(management_tools) tools.extend(_control_tool_definitions(resolved, caller)) allowed = agent_mcp_tool_names( resolved["agents"], root_agent=str(resolved["profile"]["root"]), agent_id=CALLER_AGENT, ) return [tool for tool in tools if tool.get("name") in allowed] def _spawn_kwargs(arguments: dict[str, Any]) -> dict[str, Any]: return { "session_id": SESSION_ID, "caller_agent": CALLER_AGENT, "caller_job_id": CALLER_JOB_ID, "caller_native": CALLER_NATIVE, "agent_id": arguments["agent"], "task_kind": arguments.get("task_kind"), "task": arguments.get("task"), "literal_task": arguments.get("literal_task"), "mode": arguments.get("mode", "read-only"), "cwd_value": arguments.get("cwd"), "write_scope_values": arguments.get("write_scope", []), "attachments": arguments.get("attachments", []), "label": arguments.get("label"), } def _tool_call_validation_error(name: str, arguments: dict[str, Any]) -> str | None: definition = next( (item for item in tool_definitions() if item.get("name") == name), None, ) if definition is None: return f"unknown tool: {name}" validation_errors = validate_instance(arguments, definition["inputSchema"]) if validation_errors: return "invalid tool arguments: " + "; ".join(validation_errors[:12]) return None def _dispatch_tool(name: str, arguments: dict[str, Any]) -> Any: if name == "agent_spawn": result = spawn_job(**_spawn_kwargs(arguments)) result["coordination_note"] = ( "Participant started asynchronously. Continue useful non-overlapping work; " "do not wait unless the next action is blocked." ) return result if name == "agents_spawn": return spawn_jobs( arguments["agents"], session_id=SESSION_ID, caller_agent=CALLER_AGENT, caller_job_id=CALLER_JOB_ID, caller_native=CALLER_NATIVE, ) if name == "agent_status": job_ids = arguments.get("job_ids") return { "jobs": list_jobs( session_id=SESSION_ID, job_ids=job_ids, caller_job_id=CALLER_JOB_ID, caller_agent=CALLER_AGENT, caller_native=CALLER_NATIVE, limit=arguments.get("limit", 50), ) } if name == "agents_wait": return wait_for_jobs( arguments["job_ids"], session_id=SESSION_ID, caller_job_id=CALLER_JOB_ID, caller_agent=CALLER_AGENT, caller_native=CALLER_NATIVE, timeout_seconds=arguments.get("timeout_seconds", 30), include_results=arguments.get("include_results", False), after_revision=arguments.get("after_revision"), ) if name == "agent_result": return read_result( arguments["job_id"], session_id=SESSION_ID, caller_job_id=CALLER_JOB_ID, caller_agent=CALLER_AGENT, caller_native=CALLER_NATIVE, max_chars=arguments.get("max_chars"), cursor=arguments.get("cursor", 0), ) control_context: dict[str, Any] = { "session_id": SESSION_ID, "caller_job_id": CALLER_JOB_ID, "caller_agent": CALLER_AGENT, "caller_native": CALLER_NATIVE, } if name == "agent_list": return {"agents": list_agent_runs(**control_context)} if name == "agent_inspect": return inspect_agent_run(arguments["agent_run_ref"], **control_context) if name == "agent_trace": return read_agent_trace( arguments["agent_run_ref"], cursor=arguments.get("cursor", 0), limit=arguments.get("limit", 100), **control_context, ) if name == "agent_trace_record": return read_agent_trace_record( arguments["agent_run_ref"], record_cursor=arguments["record_cursor"], cursor=arguments.get("cursor", 0), max_chars=arguments.get("max_chars"), **control_context, ) control_actions = { "agent_steer": "steer", "agent_interrupt": "interrupt", "agent_pause": "pause", "agent_continue": "continue", "agent_detach": "detach", "agent_stop": "stop", "agent_finalize": "finalize", "agent_compact": "compact", "agent_respond": "respond", "agent_set_effort": "set_effort", "agent_fork": "fork", } if name in control_actions: extras = { key: value for key, value in arguments.items() if key not in {"agent_run_ref", "expected_revision"} } return control_agent_run( arguments["agent_run_ref"], control_actions[name], expected_revision=arguments["expected_revision"], **control_context, **extras, ) disposition_context: dict[str, Any] = { "session_id": SESSION_ID, "caller_job_id": CALLER_JOB_ID, "caller_agent": CALLER_AGENT, "caller_native": CALLER_NATIVE, } if name == "agent_result_accept": return accept_result(arguments["job_id"], arguments["reason"], **disposition_context) if name == "agent_result_reject": return reject_result(arguments["job_id"], arguments["reason"], **disposition_context) if name == "agent_patch_integrate": return integrate_patch( arguments["job_id"], arguments["reason"], session_id=SESSION_ID, caller_job_id=CALLER_JOB_ID, caller_agent=CALLER_AGENT, caller_native=CALLER_NATIVE, ) if name == "agent_cancel": return cancel_job( arguments["job_id"], session_id=SESSION_ID, caller_job_id=CALLER_JOB_ID, caller_agent=CALLER_AGENT, caller_native=CALLER_NATIVE, cascade=arguments.get("cascade", True), reason=arguments.get("reason"), ) raise AssertionError(f"unhandled advertised tool: {name}") def call_tool(name: str, arguments: dict[str, Any]) -> Any: validation_error = _tool_call_validation_error(name, arguments) if validation_error is not None: raise ValueError(validation_error) return _sanitize_mcp_result(_dispatch_tool(name, arguments)) _INTERNAL_MCP_FIELDS = frozenset( { "app_server_socket_path", "control_socket_path", "events_path", "full_result_path", "partial_result_path", "result_path", "root_app_server_socket", "root_control_socket", "socket", "socket_path", "stderr_path", "structured_result_path", } ) def _sanitize_mcp_result(value: Any, *, _path: tuple[str, ...] = ()) -> Any: """Remove supervisor locations without rewriting opaque model result payloads.""" if isinstance(value, dict): return { key: ( child if (not _path and key == "content") or (len(_path) == 2 and _path[0] == "results" and key == "preview") else _sanitize_mcp_result(child, _path=(*_path, key)) ) for key, child in value.items() if key not in _INTERNAL_MCP_FIELDS } if isinstance(value, list): return [_sanitize_mcp_result(child, _path=_path) for child in value] return value def _response(request_id: Any, result: Any) -> dict[str, Any]: return {"jsonrpc": "2.0", "id": request_id, "result": result} def _error(request_id: Any, code: int, message: str, data: Any = None) -> dict[str, Any]: value: dict[str, Any] = {"code": code, "message": message} if data is not None: value["data"] = data return {"jsonrpc": "2.0", "id": request_id, "error": value} def _emit(message: dict[str, Any]) -> None: sys.stdout.write( json.dumps(message, ensure_ascii=False, separators=(",", ":"), allow_nan=False) + "\n" ) sys.stdout.flush() def _valid_request_id(value: Any) -> bool: return isinstance(value, str) or (isinstance(value, int) and not isinstance(value, bool)) def _invalid_request(message: dict[str, Any], detail: str) -> dict[str, Any]: request_id = message.get("id") if _valid_request_id(message.get("id")) else None return _error(request_id, -32600, "invalid request", detail) def _validate_rpc_request(message: dict[str, Any]) -> dict[str, Any] | None: if message.get("jsonrpc") != "2.0": return _invalid_request(message, "jsonrpc must equal '2.0'") if not isinstance(message.get("method"), str): return _invalid_request(message, "method must be a string") if "id" in message and not _valid_request_id(message["id"]): return _invalid_request(message, "id must be a string or integer") if "params" in message and not isinstance(message["params"], dict): return _invalid_request(message, "params must be an object") return None def _method_params( message: dict[str, Any], request_id: Any, *, has_id: bool ) -> tuple[dict[str, Any] | None, dict[str, Any] | None]: params = message.get("params", {}) if isinstance(params, dict): return params, None if not has_id: return None, None return None, _error(request_id, -32602, "method parameters must be an object") def _valid_client_info(value: Any) -> bool: return ( isinstance(value, dict) and isinstance(value.get("name"), str) and bool(value["name"]) and isinstance(value.get("version"), str) and bool(value["version"]) ) def handle(message: dict[str, Any], state: dict[str, str]) -> dict[str, Any] | None: invalid = _validate_rpc_request(message) if invalid is not None: return invalid method = message.get("method") has_id = "id" in message request_id = message.get("id") if has_id else None params, params_error = _method_params(message, request_id, has_id=has_id) if params is None: return params_error if method == "initialize": if not has_id: return None if state["phase"] != "new": return _error(request_id, -32600, "server is already initialized") if ( not isinstance(params.get("protocolVersion"), str) or not params["protocolVersion"] or not isinstance(params.get("capabilities"), dict) or not _valid_client_info(params.get("clientInfo")) ): return _error(request_id, -32602, "invalid initialize parameters") _session, resolved, caller = _context() children = ", ".join(caller["can_spawn"]) or "none" controls = caller.get("controls", {}) controlled = ( "; ".join( f"{target}={','.join(grant.get('actions', []))}" for target, grant in sorted(controls.items()) ) if isinstance(controls, dict) and controls else "none" ) instructions = ( f"You are profile agent {CALLER_AGENT} in {resolved['profile']['id']}. " f"Permitted children: {children}. Permitted control targets: {controlled}. " ) if caller["can_spawn"]: instructions += ( "Spawn eligible independent work early, continue your own non-overlapping " "critical path, and wait only at a real dependency barrier. " ) else: instructions += "This role has no spawn authority; do not create agents. " if caller.get("controls"): instructions += ( "Call agent_list before control. Use opaque run references and only the exact " "action grants shown above. MCP pause checkpoints work and retires its host, detach " "lets it continue live, stop is terminal, and goal continuation is token-budgeted " "rather than clock-estimated. " ) else: instructions += "This role has no cross-agent control authority. " instructions += ( "First obtain every requested job's progress_revision with agent_status or an initial " "agents_wait call. Pass that exact map to later agents_wait calls as after_revision and " "keep result " "previews disabled unless needed. Read terminal output with agent_result from cursor " "0 through every next_cursor until null. Never open MMO supervisor state or result " "files directly; use agent_result, agent_inspect, agent_trace, and agent_trace_record." ) response = _response( request_id, { # This server supports one protocol revision. MCP requires the # server to return a supported revision when the client's # requested revision is unsupported, not echo the unknown one. "protocolVersion": PROTOCOL_VERSION, "capabilities": {"tools": {"listChanged": False}}, "serverInfo": {"name": SERVER_NAME, "version": package_version()}, "instructions": instructions, }, ) state["phase"] = "initializing" return response if method == "notifications/initialized": if has_id: return _error(request_id, -32600, "notifications/initialized must not include an id") if state["phase"] == "initializing": state["phase"] = "initialized" return None if method == "notifications/cancelled": if has_id: return _error(request_id, -32600, "notifications/cancelled must not include an id") return None if method == "ping": return _response(request_id, {}) if has_id else None if state["phase"] != "initialized": return _error(request_id, -32600, "server not initialized") if has_id else None if method == "tools/list": return _response(request_id, {"tools": tool_definitions()}) if has_id else None if method == "tools/call": if not has_id: return None name = params.get("name") arguments = params.get("arguments", {}) if not isinstance(name, str) or not isinstance(arguments, dict): return _error(request_id, -32602, "invalid tools/call parameters") validation_error = _tool_call_validation_error(name, arguments) if validation_error is not None: return _error(request_id, -32602, "invalid params", validation_error) try: result = _sanitize_mcp_result(_dispatch_tool(name, arguments)) return _response( request_id, { "content": [ { "type": "text", "text": json.dumps( result, ensure_ascii=False, separators=(",", ":"), allow_nan=False, ), } ], "structuredContent": result, "isError": False, }, ) except (OSError, RuntimeError, ValueError) as exc: return _response( request_id, { "content": [{"type": "text", "text": f"{type(exc).__name__}: {exc}"}], "isError": True, }, ) if not has_id: return None return _error(request_id, -32601, f"method not found: {method}") def main() -> int: state = {"phase": "new"} for raw in sys.stdin: line = raw.strip() if not line: continue message: Any = None try: message = strict_json_loads(line) except (json.JSONDecodeError, ValueError) as exc: _emit(_error(None, -32700, "parse error", str(exc))) continue if not isinstance(message, dict): _emit(_error(None, -32600, "invalid request", "message must be an object")) continue try: result = handle(message, state) if result is not None: _emit(result) except Exception as exc: print(traceback.format_exc(), file=sys.stderr, flush=True) if "id" in message and _valid_request_id(message.get("id")): _emit(_error(message.get("id"), -32603, str(exc))) return 0 if __name__ == "__main__": raise SystemExit(main())