disinto/docs/EVAL-MCP-SERVER.md

Evaluation: MCP server wrapper for factory tools

Issue: #713 Date: 2026-03-26 Status: Not recommended at this time

Question

Should disinto expose factory tools as an MCP (Model Context Protocol) server, in addition to the existing SKILL.md skill?

Current state

The SKILL.md skill (v0.2.0) already exposes factory operations to MCP-compatible clients via three bash scripts:

Script	Capability	MCP tool equivalent
skill/scripts/factory-status.sh	Agent health, open issues, CI pipelines	factory_status, list_issues, ci_status
skill/scripts/file-issue.sh	Create issues with labels	file_issue
skill/scripts/read-journal.sh	Read planner/supervisor journals	read_journal

The dependency graph analysis (lib/build-graph.py) is available but runs locally — not exposed through the skill scripts.

Analysis

What an MCP server would add

An MCP server would provide typed JSON-RPC tool definitions with schemas for each parameter, structured error responses, and transport-level features (SSE streaming, session management). Clients could discover tools programmatically instead of parsing SKILL.md instructions.

What it would cost

1. New language dependency. The entire factory is bash. An MCP server requires TypeScript (@modelcontextprotocol/sdk) or Python (mcp package). This adds a build step, runtime dependency, and language that no current contributor or agent maintains.

2. Persistent process. The factory is cron-driven — no long-running daemons. An MCP server must stay up, be monitored, and be restarted on failure. This contradicts the factory's event-driven architecture (AD-004).

3. Thin wrapper over existing APIs. Every proposed MCP tool maps directly to a forge API call or a skill script invocation. The MCP server would be curl with extra steps:

   MCP client → MCP server (TypeScript) → forge API (HTTP) → Forgejo
   

   vs. the current path:

   SKILL.md instruction → bash script → forge API (HTTP) → Forgejo
   

4. Maintenance surface. MCP SDK versioning, transport configuration (stdio vs SSE), authentication handling, and registry listings all need ongoing upkeep — for a wrapper that adds no logic of its own.

Overlap with SKILL.md

The SKILL.md skill already works with Claude Code, Claude Desktop, and any client that supports the skill/tool-use protocol. The scripts it references are the same scripts an MCP server would wrap. Adding MCP does not unlock new capabilities — it provides an alternative invocation path.

When MCP would make sense

• Non-Claude MCP clients need to operate the factory (VS Code Copilot, Cursor, custom agents using only MCP transport).
• Type safety becomes a real issue — structured schemas prevent misformed requests that natural language instructions currently handle.
• The factory adopts a server model — if a persistent API gateway is added for other reasons, exposing MCP tools becomes low marginal cost.
• Graph queries need remote access — build-graph.py is the one tool that doesn't have a simple curl equivalent and could benefit from structured input/output schemas.

Recommendation

Do not build an MCP server now. The SKILL.md skill already covers the primary use case (human-assisted factory operation via Claude). The six proposed MCP tools map 1:1 to existing scripts and API calls, so the server would be pure glue code in a language the factory doesn't use.

Revisit when any of these conditions are met:

1. A concrete use case requires MCP transport (e.g., a VS Code extension that operates the factory and cannot use SKILL.md).
2. The factory adds a persistent API gateway (forge proxy, webhook receiver) that could host MCP endpoints at near-zero marginal cost.
3. Graph analysis (build-graph.py) is needed by external clients — this is the strongest candidate for a standalone MCP tool since it has complex input/output that benefits from typed schemas.

If revisiting, scope to a minimal stdio-transport server wrapping only factory_status and query_graph. Do not duplicate what the skill scripts already provide unless there is demonstrated client demand.