f0c3c773ff
- Rename acquire_cron_lock → acquire_run_lock in lib/formula-session.sh and all five *-run.sh call sites - Update all *-run.sh file headers: "Cron wrapper" → "Polling-loop wrapper" - Rewrite docs/updating-factory.md: replace crontab check with pgrep, replace "Crontab empty after restart" section with polling-loop equivalent - Update docs/EVAL-MCP-SERVER.md to reflect polling-loop reality - Update lib/guard.sh, lib/AGENTS.md, lib/ci-setup.sh comments - Update formulas/*.toml comments (cron → polling loop) - Update dev/dev-poll.sh usage comment - Update tests/smoke-init.sh to handle compose vs bare-metal scheduling - Update .woodpecker/agent-smoke.sh comments - Update site HTML: architecture.html, quickstart.html, index.html - Clarify _install_cron_impl is bare-metal only (compose uses polling loop) - Keep site/collect-engagement.sh and site/collect-metrics.sh cron refs (genuinely cron-driven on the website host, separate from factory loop) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
104 lines
4.3 KiB
Markdown
104 lines
4.3 KiB
Markdown
# 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 already runs a long-lived polling loop
|
|
(`docker/agents/entrypoint.sh`), so an MCP server is not architecturally
|
|
alien — the loop could keep an MCP client alive across iterations. However,
|
|
adding a second long-running process increases the monitoring surface and
|
|
restart complexity.
|
|
|
|
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.
|