MCP Factory

MCP Factory

*The test count is verifiable below (python -m pytest tests/ → 348 passed, 8 skipped) and enforced in CI by scripts/check_readme_counts.py, which fails the build if this README's counts drift from the live suite.*

60-Second Quickstart

From PyPI (registry users):

pip install jaimenbell-mcp-factory

mcp-factory-hub --serve

equivalent: python -m mcp_factory --serve

From a git checkout (contributors): see the python hub_server.py ... examples throughout this README — hub_server.py at the repo root is a backward-compat wrapper around the same mcp_factory.cli module the console script runs, so behavior is identical either way.

The manifest-driven engine behind the MCP Integration Sprint. Write one mcp.yaml for a bot repo and the factory generates the server stub and the ~/.claude.json entry; run the hub and it serves every bot's tools through a single MCP endpoint.

The SDK wrapper is the easy part. What makes an MCP server safe to put in front of a real internal tool — scoped auth/env, fail-soft error handling, validated manifests, a collision-safe registry, and a real test suite — is the engineering this engine is built around. That same production layer is hand-built per engagement; the factory scaffolds it, it doesn't fake it.

Browse before you reply

This repo is public so you can verify the discipline instead of taking my word for it. Every claim below maps to a file you can open:

Honesty rails: 348 is the real, reproducible count on a clean checkout — the same number the public CI run produces and gates on. mcp-factory generates the *scaffold* and runs the hub — it does not "generate the production server" or carry any client/CI claims. The hardened production layer (per-tool auth boundaries, the full failure set, two-axis version-pinning) is built per engagement on top of this engine. That applies to both Python scaffold styles below — see "Two Python styles" for exactly what the fastmcp variant does and doesn't add on top of that baseline.

Quick Start

Factory mode (generate config from one manifest)

# Reference an existing MCP server (no code generated — just the config entry)

python hub_server.py --manifest examples/fleet_health.yaml

Scaffold a new MCP server from scratch

python hub_server.py --manifest my_bot/mcp.yaml --output-dir my_bot/

Dry run — preview without writing

python hub_server.py --manifest my_bot/mcp.yaml --dry-run

Self-verify: compare factory output to live ~/.claude.json entry

python hub_server.py --manifest examples/fleet_health.yaml --verify ~/.claude.json

Output always goes to ~/.claude.json.factory-test by default — never to the live ~/.claude.json. Copy entries manually after review.

Scan mode (batch-register all bots)

# Dry-run diff: show what would change in ~/.claude.json

python hub_server.py --scan C:\path\to\projects

Apply: write ~/.claude.json after backing it up

python hub_server.py --scan C:\path\to\projects --apply

Force-update entries already registered

python hub_server.py --scan C:\path\to\projects --apply --force

--scan discovers all projects/*/mcp.yaml files, validates each, and diffs them against the current ~/.claude.json. Default root is C:\path\to\projects. With --apply, a timestamped backup is created at ~/.claude.json.scan-backup- before writing.

Skip logic: manifests whose name already exists in ~/.claude.json are skipped unless --force is passed. This prevents accidentally overwriting manually-crafted entries.

Serve mode (runtime hub — single MCP for all bots)

# Run the hub as a live MCP server (stdio transport)

python hub_server.py --serve

Serve with multiple scan roots (repeatable)

python hub_server.py --serve \ --scan-root C:\path\to\projects \ --scan-root C:\path\to\Claude

Register+serve in one step (scan --apply then start hub)

python hub_server.py --register \ --scan-root C:\path\to\projects \ --scan-root C:\path\to\Claude

The hub scans all mcp.yaml manifests under each --scan-root at startup, then exposes every bot's tools under the . namespace (e.g., fleet-health.fleet_status, my-bot.run_scan). Tools are proxied to per-bot subprocess MCP servers with lazy startup.

Hub meta-tool: _hub.list_bots returns the registered bots and their subprocess status.

Hub is pre-registered in ~/.claude.json as mcp-factory-hub (see scripts/register_hub.py).

Node.js template

Factory generates Node.js stubs when runtime.type: node is set in mcp.yaml:

runtime:

type: node command: "node" output: "path/to/server.js"

Generated stubs use @modelcontextprotocol/sdk with stdio transport and zod for argument validation. See examples/node_example.yaml for a working demo.

Two Python styles: raw SDK vs. FastMCP

For runtime.type: python, the factory can scaffold either of two styles from the exact same manifest:

runtime:

type: python command: "python" style: raw # default — official mcp SDK, hand-rolled list_tools/call_tool

style: fastmcp # FastMCP v3 (PrefectHQ/fastmcp), decorator-based tool registration

Both styles read the same tools: / env_required: fields and produce a server that speaks the same stdio JSON-RPC wire protocol — the runtime hub's SubprocessAdapter proxies either one without any adapter changes (see tests/test_fastmcp_template.py::TestFastmcpServeSmoke for a live generate-and-call test).

Gaps, stated honestly: neither style implements per-tool authorization, rate limiting, or the "full failure set" the hub-level subprocess_adapter.py gives you for free (typed errors, lazy start, atexit cleanup) — that's still a per-engagement build on top of either scaffold. The fastmcp template's fail-soft wrapper and env-presence check are new, real code (read mcp_factory/templates/python_fastmcp.j2), not a marketing claim about auth — they were added because FastMCP's decorator model made them cheap to include cleanly; they have not (yet) been backported to the raw template, which is why the two styles differ slightly in what ships out of the box. If your engagement needs FastMCP-specific features beyond this (resources, prompts, HTTP/SSE transport, middleware-based auth), the generated file is a normal FastMCP app — extend it directly.

See examples/fastmcp_example.yaml for a working demo manifest.

mcp.yaml Schema

name: my-bot                   # REQUIRED — unique MCP server name (key in claude.json)

description: > # REQUIRED — shown in Claude's tool descriptions What this bot does and when to use it.

runtime: # REQUIRED type: python # python | node | binary command: "C:\\Python314\\python.exe" # full path to interpreter script: "path/to/server.py" # existing server (skips scaffold generation) output: "path/to/out.py" # where to write generated scaffold (omit = auto) style: raw # python only: raw (default) | fastmcp — see "Two Python styles"

tools: # REQUIRED — list of MCP tools to expose

• name: tool_name # REQUIRED — programmatic identifier title: "Tool Name" # Optional — human display name (see below) description: > # REQUIRED — used by Claude for routing What this tool does. annotations: # Optional — the four MCP behaviour hints readOnlyHint: true # tool does not modify anything destructiveHint: false # tool does not perform destructive updates idempotentHint: true # repeat calls have no additional effect openWorldHint: false # tool does not touch an open external world args: # Optional list of arguments
• name: arg_name # REQUIRED type: string # string | number | boolean | object | array required: true # default: true description: "..." # shown in Claude's tool schema

env_required: # env var names that must be set at runtime

• MY_API_KEY

env: # static env vars injected into claude.json entry MY_API_KEY: "" # leave value empty — fill in ~/.claude.json manually

tags: [trading, health] # for documentation / future routing priority: high # high | medium | low

Key rules

• runtime.script + existing file → factory references it, skips scaffold
• runtime.script + missing file → validation error (use runtime.output for new scaffolds)
• runtime.output → explicit path for generated stub (absolute recommended)
• Neither script nor output → error at config-write step

title and annotations

Both are optional and both are worth declaring.

title is the human display name, which lets name stay a programmatic identifier. Display precedence is title → annotations.title → name; the factory exposes only the top-level title so one manifest cannot declare two competing display names.

annotations matters more than it looks. The four hints have pessimistic defaults — destructiveHint and openWorldHint both default to true, readOnlyHint to false —