
Mcp Factory
io.github.jaimenbell由 GitHub 帳號 jaimenbell 發布v0.1.3更新於 Oct 24, 2026
Manifest-driven MCP server scaffolder and runtime hub for tool integrations.
概覽
一個本機 Python 工具,可從 YAML 清單產生 MCP 伺服器骨架,並執行一個 hub,透過單一 MCP 端點暴露所有已註冊機器人的工具。
- 可以做什麼
- 依單一 mcp.yaml 清單產生 MCP 伺服器骨架與用戶端設定項目,支援 Python(原生 SDK 或 FastMCP)與 Node.js 樣式,可先試執行預覽,並附帶可設為嚴格模式的工具設計檢查。掃描專案目錄中的清單,與用戶端設定做差異比對或寫入套用,寫入前會建立帶時間戳記的備份。作為執行階段 hub,把每個機器人的工具註冊到 bot.tool 命名空間下,並視需要啟動各機器人子程序伺服器來代理呼叫。透過 hub 中繼工具列出已註冊機器人及其子程序狀態。探索、驗證、執行並快取 SKILL.md 研究工作流程,並讓登錄檔保持同步。
- 適用情境
- 當你維護多個 MCP 伺服器或機器人儲存庫,希望以清單驅動的方式統一產生骨架、註冊到用戶端並透過單一本機端點全部暴露時適用。也適合在發布伺服器前對工具名稱、描述與參數做一次檢查。
- 執行需求
- 以 PyPI 套件(jaimenbell-mcp-factory)透過 pip 安裝,作為本機 stdio 程序執行,需要 Python;僅 Node 樣式骨架需要 Node.js 與 MCP SDK。它會讀寫用戶端設定檔(如 ~/.claude.json),並掃描專案目錄中的 mcp.yaml 清單。未宣告驗證或環境變數。
安裝
在 SourceWeft 中
- 開啟 儀表板中的 Mcp Factory,將其新增到工作區。
- 為需要使用其工具的對話啟用該服務。
Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。
其他 MCP 客戶端
參照 儲存庫 中的啟動說明。
README
MCP Factory
[CI] [tests] [python] [PyPI] [MCP Registry]
The test count is verifiable below (
python -m pytest tests/→ 348 passed, 8 skipped) and enforced in CI byscripts/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):
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:
348is 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)
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)
--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-<timestamp> 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)
The hub scans all mcp.yaml manifests under each --scan-root at startup, then exposes every bot's tools under the <bot>.<tool> 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:
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:
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
Key rules
runtime.script+ existing file → factory references it, skips scaffoldruntime.script+ missing file → validation error (useruntime.outputfor new scaffolds)runtime.output→ explicit path for generated stub (absolute recommended)- Neither
scriptnoroutput→ 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 — so a tool that declares nothing is treated by a
careful client as the most dangerous thing it could be. Declaring
readOnlyHint: true on a read-only tool is how you opt out of that. Only the
four hint names above are accepted, each must be a real boolean, and an unknown
key is a hard error rather than a silent drop (the typo readonlyHint would
otherwise leave the tool effectively unannotated on the wire).
Annotations are hints, not a security boundary — the spec is explicit that a client should never make tool-use decisions based on annotations from an untrusted server. They inform a client's UX; they do not enforce anything.
Both fields are emitted by the two Python templates. The Node template does not
render them yet — the repo vendors no node_modules, so an altered call shape
could not be executed in test, and shipping unverified generated code is worse
than shipping the current shape. Declaring them in a node manifest is still
valid and forward-compatible.
Generation-time tool-design lint
Manifest validation is a security gate: it fails closed on anything that could inject code into a generated server. It says nothing about whether the resulting tools are any good. A manifest can be perfectly valid and still produce a server that makes an agent measurably worse.
Every run of factory mode therefore also runs a tool-design lint (Step 2), covering 15 rules across three scopes:
It is advisory by default — findings print, generation proceeds, exit 0.
--lint-strict makes error-severity findings fatal: it reports them, writes no
scaffold, and exits 3.
Three deliberate properties:
- It reports
INDETERMINATE, not a clean bill, when it has no discriminating power — a manifest whoseruntime.scriptexists (the factory references that hand-written file rather than generating one, so the tool list may not match the real server), or a runtime with no template.--lint-strictnever blocks on an indeterminate result: the absence of a verdict must not be converted into one. - There is no tool-name charset rule, even though SEP-986 defines one. The manifest's own identifier validation is already stricter and rejects violations at parse time, so such a rule could never fire on any input reaching the lint — and a check that cannot fail is not a check. Only the length half of SEP-986 is unenforced upstream, so only the length half is a rule.
- Every rule ships a positive control: a test proving it fires on a known-bad
tool definition and stays silent on a known-good one, plus a suite-level test
asserting a well-formed manifest produces zero findings. The examples in
examples/are themselves held to the lint bytests/test_examples_lint_clean.py.
How to Add a New MCP
- Write
mcp.yamlat your bot repo root (or inexamples/) - Run the factory:
- Review
~/.claude.json.factory-test— confirm the entry looks correct - Copy the entry into
~/.claude.jsonundermcpServers - Restart Claude Code
If the bot has no existing server, the factory generates a stub at generated/<name>_server.py. Fill in the # TODO: implement sections and set runtime.script to the stub path for future runs.
Runtime Hub Architecture
Subprocess lifecycle:
- Adapters start lazily on first tool call (no upfront spawn)
- Keep-alive for the hub session (one process per bot)
_hub.list_bots()reports status:idle(not yet started) orrunning- All adapters stopped via
atexiton hub exit;stop()kills if needed after 5 s
Tool naming: <bot-name>.<tool-name> — hyphens preserved, dots as separator.
Example: fleet-health.fleet_status, my-bot.get_alerts.
Day 4 — workflow_runner.py
Standalone CLI harness for research workflows, independent of hub_server.py.
How it works
workflow_runner.py scans ~/research by default (override with --scan-root) for SKILL.md files containing YAML frontmatter. Each SKILL.md defines a named workflow with metadata:
- Discover:
git ls-filesto enumerate trackedSKILL.mdfiles under each scan root - Validate: checks required frontmatter fields (
name,description) - Cache: SHA-based cache keyed on prompt content;
auto(default) skips re-run if output unchanged,force-refreshalways re-runs,read-onlynever writes - Run: invokes
claude -p <prompt>as a subprocess, streams output - Write output: expands
output_path_template, writes result to vault - Registry:
--write-registrypersists discovered skills toregistry.json;--checkdetects drift between filesystem and registry without writing
Directory Layout
Self-Verification
The examples/fleet_health.yaml manifest references an example server. Running:
confirms the factory produces a matching ~/.claude.json entry.
Running Tests
On a clean checkout (Python 3.12), with pip install -e .[dev]: 348 passed, 8 skipped, 0 failed — the same numbers the public CI run produces and gates on.
The 8 skipped tests skip automatically when the resource or condition they need is absent:
test_integration_fleet_health.py(5 tests) requires a fleet-healthserver.pyon disk (FLEET_HEALTH_SERVER_PATH).test_node_template.py(1 test) requiresnodeand@modelcontextprotocol/sdk(node_modules/) to be present.test_examples_lint_clean.py(2 tests) skipsexamples/fleet_health.yaml, which references an existing hand-written server — the tool-design lint correctly reportsINDETERMINATEthere rather than judging code it cannot see, and a skip is the honest way to record that.
test_smoke_hub.py (4 tests) no longer needs a live bot fleet to run for real: the hub's demo-manifest fallback (see below) gives it something to discover even against an empty scan root, so these run unconditionally on a clean checkout now.
(On the maintainer's fleet machine, where the fleet-health server and live bots exist, the remaining skipped integration tests run for real and the passed count is higher — but this README claims only what a clean checkout and public CI reproduce.)
The fastmcp-style template tests (test_fastmcp_template.py) are not in this skip list — fastmcp is installed as a [dev] extra, so they run for real on a standard dev setup.
Commercial support
Maintained by Jaimen Bell. For production MCP integrations, custom servers, or agent-reliability work, see jaimenbell.dev.
Building your own MCP server? The MCP Starter Kit has templates, a build playbook, and packaging war-stories from shipping this one.
mcp-name: io.github.jaimenbell/mcp-factory
來源:README.md,提交 65126fb
工具
0版本歷史
1- v0.1.3最新Sep 16, 2026
評分
已滿足適用檢查項的 50%
該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。
- 近 30 天內可連通25 分
請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。
- 已宣告認證方式10 分
請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。
- 已列出工具15 分
請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。
- 描述必需15 分
- 圖示10 分
- 文件15 分
- 授權條款10 分