mcp-factory

MCP Factory

テスト件数は以下のコマンド（python -m pytest tests/ → 348 passed, 8 skipped）で検証でき、CI では scripts/check_readme_counts.py によって、この README の件数が実際のテストスイートの件数と異なる場合にビルドが失敗するようになっています。

60 秒クイックスタート

PyPI からインストールする場合（レジストリユーザー向け）：

pip install jaimenbell-mcp-factory
mcp-factory-hub --serve
# equivalent: python -m mcp_factory --serve

Git チェックアウトから始める場合（コントリビューター向け）： この README 全体にある python hub_server.py ... の例を参照してください。リポジトリのルートにある hub_server.py は、コンソールスクリプトが実行するのと同じ mcp_factory.cli モジュールを呼び出す後方互換ラッパーなので、どちらを使っても動作は同じです。

MCP Integration Sprint を支える、マニフェスト駆動のエンジンです。 ボットのリポジトリ用に mcp.yaml を 1 つ作成すると、ファクトリーがサーバーのスタブと ~/.claude.json のエントリーを生成します。ハブを実行すると、単一の MCP エンドポイントを通じてすべてのボットのツールを提供します。

SDK のラッパーを作るのは簡単です。実際の社内ツールの前段に安全に配置できる MCP サーバーを実現するために重要なのは、適切な範囲に限定された認証／環境変数、障害を許容するエラー処理、検証済みマニフェスト、衝突に安全なレジストリ、そして実際のテストスイートです。このエンジンが重視しているのは、そうしたエンジニアリングです。同じ本番運用向けレイヤーは、案件ごとに手作業で構築されます。ファクトリーはその土台を生成しますが、実装を偽装するものではありません。

返信する前に確認してください

このリポジトリを公開しているのは、私の言葉を信じてもらうのではなく、開発の姿勢をご自身で確認していただくためです。以下の主張はすべて、実際に開いて確認できるファイルに対応しています。

主張	該当箇所	確認できる内容
検証済みで、環境変数の範囲が限定されたマニフェスト	mcp_factory/manifest.py	厳格な from_dict 検証（必須フィールドの欠落や無効な値があるとエラーを発生）；サーバーが参照できるシークレットの範囲を限定する env_required／env モデル
障害を許容するサブプロセスのプロキシ処理	mcp_factory/runtime/subprocess_adapter.py	型付きの SubprocessError、遅延起動、JSON-RPC エラーの通知、timeout／OSError で保護された終了処理と atexit クリーンアップ。停止したボットがクリーンなエラーを返し、ハブをクラッシュさせないこと
衝突に安全なマニフェスト駆動レジストリ	mcp_factory/runtime/registry.py · registry.json	<bot>.<tool> 名が重複すると CollisionError を発生；レジストリは手作業で保守するのではなく、マニフェストから構築
クリーンなチェックアウトでのテスト	tests/	348 passed, 8 skipped, 0 failed（Python 3.12）；8 件のスキップは実際の統合テスト、または必要なものが存在しない場合に何もしないリントチェックです

誠実さを守るための指針： 348 は、クリーンなチェックアウトで再現できる実際の件数です。公開 CI の実行結果と同じ件数であり、CI の判定にも使用されています。mcp-factory が生成するのは土台であり、ハブを実行します。「本番サーバーを生成」したり、クライアントや CI に関する主張を裏付けたりするものではありません。堅牢な本番運用向けレイヤー（ツールごとの認証境界、あらゆる障害への対応、二軸のバージョン固定）は、このエンジンの上に案件ごとに構築されます。これは以下の 2 種類の Python の土台の両方に当てはまります。標準の構成に対して fastmcp 版が追加するものと追加しないものの詳細は、「2 種類の Python スタイル」を参照してください。

クイックスタート

ファクトリーモード（1 つのマニフェストから設定を生成）

# 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

出力先は、デフォルトでは常に ~/.claude.json.factory-test です。実際に使用中の ~/.claude.json が変更されることはありません。内容を確認したうえで、エントリーを手動でコピーしてください。

Scan モード（すべてのボットを一括登録）

# 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 はすべての projects/*/mcp.yaml ファイルを検出して検証し、現在の ~/.claude.json と差分を比較します。デフォルトのルートは C:\path\to\projects です。--apply を指定すると、書き込み前に ~/.claude.json.scan-backup-<timestamp> にタイムスタンプ付きのバックアップが作成されます。

スキップのロジック： ~/.claude.json に名前がすでに存在するマニフェストは、--force を指定しない限りスキップされます。これにより、手動で作成したエントリを誤って上書きすることを防ぎます。

Serve モード（ランタイムハブ — すべてのボットを単一の MCP で管理）

# 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

ハブは起動時に、各 --scan-root 配下のすべての mcp.yaml マニフェストをスキャンし、各ボットのツールを <bot>.<tool> 名前空間で公開します（例：fleet-health.fleet_status、my-bot.run_scan）。ツールは、遅延起動するボットごとのサブプロセス MCP サーバーにプロキシされます。

ハブのメタツール： _hub.list_bots は、登録済みのボットとそのサブプロセスのステータスを返します。

ハブは ~/.claude.json に mcp-factory-hub として事前登録されています（scripts/register_hub.py を参照）。

Node.js テンプレート

mcp.yaml で runtime.type: node を設定すると、Factory は Node.js のスタブを生成します。

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

生成されるスタブは、stdio トランスポートと引数検証用の zod を使用する @modelcontextprotocol/sdk を利用します。動作するデモについては examples/node_example.yaml を参照してください。

2 つの Python スタイル：raw SDK と FastMCP

runtime.type: python の場合、同じマニフェストから、Factory は次の 2 つのスタイルのいずれかをスキャフォールドできます。

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

どちらのスタイルも同じ tools:／env_required: フィールドを読み込み、同じ stdio JSON-RPC ワイヤープロトコルで通信するサーバーを生成します。ランタイムハブの SubprocessAdapter は、アダプターを変更せずにどちらもプロキシできます（実際に生成して呼び出すテストについては tests/test_fastmcp_template.py::TestFastmcpServeSmoke を参照してください）。

	style: raw (python_server.py.j2)	style: fastmcp (python_fastmcp.j2)
SDK	公式の mcp パッケージ、mcp.server.Server	fastmcp（fastmcp==3.4.2 を厳密に固定 — 4.0.0b1 はサンプリング／ルートを壊すベータ版のため、バージョンを浮動させないでください）
ツール登録	手動の @server.list_tools()／@server.call_tool() ディスパッチ	ツールごとに 1 つの @mcp.tool(...) デコレーター付き関数
引数スキーマ	引数ごとに手動で構築する JSON Schema の辞書	実際の Python パラメーターに指定する Annotated[type, Field(description=...)] — FastMCP がシグネチャから JSON Schema を導出し、必須／任意も判定します
ツール本体	# TODO: implement スタブ	同じスタブを try/except Exception で囲んだもの — 実装後に実行時エラーが発生してもプロセスはクラッシュせず、構造化された {"status": "error", ...} を返します
env_required	スキャフォールドのレベルでは強制されません	起動時に _check_required_env() を実行するよう展開され、宣言された変数がない場合は標準エラーに警告を出します — これは存在確認であり、認証情報の検証ではありません

制約について、正直に説明します： どちらのスタイルも、ツールごとの認可、レート制限、またはハブレベルの subprocess_adapter.py が標準で提供する「完全な障害対応」（型付きエラー、遅延起動、atexit クリーンアップ）を実装していません。これらは、どちらのスキャフォールドを使う場合も、個別の案件ごとに追加で構築する必要があります。fastmcp テンプレートのフェイルソフトなラッパーと環境変数の存在確認は、新たに追加された実際のコードです（mcp_factory/templates/python_fastmcp.j2 を参照）。認証についてのマーケティング上の主張ではありません。FastMCP のデコレーターモデルでは簡潔に追加できたため実装されましたが、raw テンプレートには（まだ）移植されていません。そのため、標準で提供される機能には 2 つのスタイルで若干の違いがあります。リソース、プロンプト、HTTP／SSE トランスポート、ミドルウェアベースの認証など、これ以外の FastMCP 固有機能が案件で必要な場合、生成されたファイルは通常の FastMCP アプリなので、直接拡張できます。

動作するデモマニフェストについては examples/fastmcp_example.yaml を参照してください。

mcp.yaml スキーマ

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

主なルール

• runtime.script ＋既存ファイル → ファクトリーはそのファイルを参照し、ひな形の生成をスキップします
• runtime.script ＋ファイルが存在しない → 検証エラー（新しいひな形には runtime.output を使用してください）
• runtime.output → 生成するスタブの明示的なパス（絶対パスを推奨）
• script も output もない → 設定の書き込み時にエラー

title と annotations

どちらも任意ですが、宣言する価値があります。

title は人が読む表示名であり、name をプログラム上の識別子として使えるようにします。表示名の優先順位は title → annotations.title → name です。ファクトリーはトップレベルの title のみを公開するため、1 つのマニフェストで競合する表示名を 2 つ宣言することはできません。

annotations は見た目以上に重要です。4 つのヒントには慎重なデフォルト値があり、destructiveHint と openWorldHint はどちらもデフォルトで true、readOnlyHint は false になります。そのため、何も宣言していないツールは、慎重なクライアントによって、最も危険な動作をするものとして扱われます。読み取り専用ツールに readOnlyHint: true を宣言することで、この扱いを回避できます。受け付けられるのは上記の 4 つのヒント名のみで、それぞれ実際のブール値でなければなりません。また、不明なキーは黙って無視されず、エラーになります（誤記である readonlyHint を使うと、ツールが通信上で注釈なしとして扱われてしまいます）。

注釈はセキュリティ境界ではなくヒントです。仕様では、信頼されていないサーバーからの注釈に基づいてクライアントがツールの使用を決定してはならないと明記されています。注釈はクライアントの UX に情報を提供しますが、何かを強制するものではありません。

2 つの Python テンプレートでは、どちらのフィールドも出力されます。Node テンプレートでは、まだ出力されません。リポジトリに node_modules が含まれていないため、呼び出し形式を変更してもテストで実行できず、検証されていない生成コードを出荷するより、現在の形式を維持するほうがよいためです。Node のマニフェストで宣言すること自体は引き続き有効であり、将来との互換性もあります。

生成時のツール設計リント

マニフェストの検証はセキュリティゲートです。生成されるサーバーにコードを注入する可能性があるものはすべて、フェイルクローズで拒否します。ただし、生成されたツールの品質については何も保証しません。マニフェストが完全に有効でも、エージェントのパフォーマンスを目に見えて低下させるサーバーが生成されることがあります。

そのため、ファクトリーモードの実行時には毎回、3つのスコープにわたる15のルールを対象としたツール設計リント（ステップ 2）も実行されます。

スコープ	チェック項目
マニフェスト	ツール数の上限、大文字・小文字や区切り文字を無視した場合に衝突する名前、サーバー間で衝突する一般的すぎる名前
ツール	空または内容の乏しい説明、埋め草の説明、名前を言い換えただけの説明、snake_case でない名前や長すぎる名前、アノテーションの欠落、上限のない一覧表示ツール、名前と矛盾するアノテーション
引数	説明のないパラメーター、名前だけでは用途がわからないパラメーター、説明もなくスキーマ形状が不明な構造化（object／array）パラメーター

デフォルトでは助言的なチェックです。検出結果を表示して生成を続行し、終了コード 0 を返します。 --lint-strict を指定すると、重大度が error の検出結果は致命的なエラーになります。結果を報告し、スキャフォールドを出力せず、終了コード 3 で終了します。

mcp-factory-hub --manifest examples/fastmcp_example.yaml --lint-strict

意図的に設けている特性は3つあります。

• 判別能力がない場合は、問題なしとはせず、INDETERMINATE と報告します。該当するのは、runtime.script が存在するマニフェスト（ファクトリーはサーバーを生成せず、手書きのファイルを参照するため、ツール一覧が実際のサーバーと一致しない可能性があります）、またはテンプレートのないランタイムです。--lint-strict は判定不能の結果を理由に処理をブロックしません。判定がないことを、判定があることに置き換えてはなりません。
• ツール名の文字セットに関するルールはありません。SEP-986 では定義されていますが、マニフェスト独自の識別子検証のほうがすでに厳しく、解析時に違反が拒否されるため、リントに到達する入力でそのルールが発動することはありません。失敗し得ないチェックはチェックではありません。上流で適用されていないのは SEP-986 の長さに関する部分だけなので、ルールも長さに関するものだけです。
• すべてのルールには陽性対照テストが付属します。既知の不適切なツール定義ではルールが発動し、既知の適切な定義では発動しないことを証明するテストに加え、形式の整ったマニフェストから検出結果がゼロになることを確認するスイートレベルのテストもあります。examples/ 内の例も、tests/test_examples_lint_clean.py によってリントの対象となります。

新しい MCP の追加方法

1. ボットのリポジトリルート（または examples/）に mcp.yaml を作成します
2. ファクトリーを実行します：

   python hub_server.py --manifest path/to/mcp.yaml
   

3. ~/.claude.json.factory-test を確認し、エントリーが正しいことを確かめます
4. エントリーを mcpServers の下にある ~/.claude.json にコピーします
5. Claude Code を再起動します

ボットに既存のサーバーがない場合、ファクトリーは generated/<name>_server.py にスタブを生成します。# TODO: implement の箇所を実装し、以降の実行でスタブを使うように runtime.script をスタブのパスに設定します。

ランタイムハブのアーキテクチャ

hub_server.py --serve
  └── mcp_factory/runtime/
      ├── hub.py               async MCP server (lists + routes all tools)
      ├── registry.py          maps <bot>.<tool> → manifest + adapter
      └── subprocess_adapter.py  spawns per-bot MCP server, proxies JSON-RPC

サブプロセスのライフサイクル：

• アダプターは最初のツール呼び出し時に遅延起動します（事前には起動しません）
• ハブのセッション中はプロセスを維持します（ボットごとに1プロセス）
• _hub.list_bots() はステータスとして、idle（未起動）または running を報告します
• ハブ終了時に atexit ですべてのアダプターを停止します。5 秒経過しても停止しない場合は stop() が強制終了します

ツールの命名規則： <bot-name>.<tool-name> — ハイフンはそのまま保持し、ドットを区切り文字にします。 例：fleet-health.fleet_status、my-bot.get_alerts。

4 日目 — workflow_runner.py

hub_server.py から独立した、リサーチワークフロー用のスタンドアロン CLI ハーネスです。

# Discover and list all SKILL.md workflows
python -m mcp_factory.workflow_runner --list

# Run a specific workflow
python -m mcp_factory.workflow_runner --run my-skill

# Validate all discovered SKILL.md files
python -m mcp_factory.workflow_runner --validate

# Write/update registry.json from discovered skills
python -m mcp_factory.workflow_runner --write-registry

# Check for drift between discovered skills and registry.json
python -m mcp_factory.workflow_runner --check

# Control cache behavior
python -m mcp_factory.workflow_runner --run my-skill --cache-policy force-refresh
python -m mcp_factory.workflow_runner --run my-skill --cache-policy read-only

仕組み

workflow_runner.py は、デフォルトで ~/research をスキャンし（--scan-root で変更できます）、YAML フロントマターを含む SKILL.md ファイルを探します。各 SKILL.md は、次のメタデータを持つ名前付きワークフローを定義します。

---
name: my-skill
description: What this workflow does
output_path_template: "~/vault/output/{date}/{name}.md"
---
Prompt body passed to claude -p subprocess...

• 検出： git ls-files を使って、各スキャンルート配下にある追跡対象の SKILL.md ファイルを列挙します
• 検証： 必須のフロントマターフィールド（name、description）を確認します
• キャッシュ： プロンプトの内容をキーとする SHA ベースのキャッシュを使用します。auto（デフォルト）は出力に変更がなければ再実行をスキップし、force-refresh は常に再実行し、read-only は書き込みを一切行いません
• 実行： サブプロセスとして claude -p <prompt> を呼び出し、出力をストリーミングします
• 出力の書き込み： output_path_template を展開し、結果を Vault に書き込みます
• レジストリ： --write-registry は検出したスキルを registry.json に保存します。--check は書き込みを行わずに、ファイルシステムとレジストリ間の差異を検出します

ディレクトリ構成

mcp-factory/
├── hub_server.py              # CLI entry point (factory / scan / serve)
├── mcp_factory/
│   ├── manifest.py            # Manifest dataclass + YAML loader + validation
│   ├── generator.py           # Python MCP server stub scaffolder
│   ├── config.py              # claude.json entry builder + comparator
│   ├── scan.py                # --scan mode: manifest discovery + diff/apply
│   ├── workflow_runner.py     # Day 4: standalone CLI harness for SKILL.md workflows
│   ├── templates/              # packaged as data so `pip install` ships them too
│   │   ├── python_server.py.j2    # Jinja2 template — raw mcp SDK stubs (style: raw, default)
│   │   ├── python_fastmcp.j2      # Jinja2 template — FastMCP v2 stubs (style: fastmcp)
│   │   └── node_server.js.j2      # Jinja2 template for generated Node.js stubs
│   └── runtime/
│       ├── subprocess_adapter.py  # subprocess MCP client (JSON-RPC proxy)
│       ├── registry.py            # tool registry with collision detection
│       └── hub.py                 # async hub MCP server
├── tests/
│   ├── fixtures/
│   │   ├── fleet_health.yaml   # Day 1 self-verification fixture
│   │   ├── minimal.yaml        # Minimal valid manifest
│   │   └── mock_mcp_server.py  # Stdlib-only mock MCP server for adapter tests
│   ├── test_manifest.py
│   ├── test_generator.py
│   ├── test_subprocess_adapter.py
│   ├── test_registry.py
│   ├── test_scan.py
│   ├── test_hub_cli.py
│   ├── test_mcp_pkg.py
│   ├── test_node_template.py
│   ├── test_python_template.py
│   ├── test_fastmcp_template.py  # style: fastmcp generation + import + serve-smoke tests
│   ├── test_register_flag.py
│   ├── test_registration.py
│   ├── test_smoke_hub.py
│   ├── test_watcher.py
│   ├── test_workflow_runner.py  # Day 4: workflow_runner unit + integration tests
│   └── test_integration_fleet_health.py  # live integration tests (skipped if server absent)
├── examples/
│   ├── fleet_health.yaml      # Example manifest referencing an existing server
│   ├── node_example.yaml      # Example manifest for the node template
│   └── fastmcp_example.yaml   # Example manifest for the fastmcp template
└── pyproject.toml

自己検証

examples/fleet_health.yaml マニフェストは、サンプルサーバーを参照しています。次を実行すると、

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

ファクトリーが一致する ~/.claude.json エントリーを生成することを確認できます。

テストの実行

python -m pytest tests/ -v

クリーンなチェックアウト環境（Python 3.12）で pip install -e .[dev] を実行した場合、348 件成功、8 件スキップ、0 件失敗となります。これは公開 CI の実行結果と同じ件数であり、ゲート条件として使用されています。

スキップされた 8 件のテストは、必要なリソースまたは条件が存在しない場合に自動的にスキップされます。

• test_integration_fleet_health.py（5 件のテスト）では、ディスク上に fleet-health の server.py が必要です（FLEET_HEALTH_SERVER_PATH）。
• test_node_template.py（1 件のテスト）では、node と @modelcontextprotocol/sdk（node_modules/）が必要です。
• test_examples_lint_clean.py（2 件のテスト）では、既存の手書きサーバーを参照する examples/fleet_health.yaml をスキップします。ツール設計の lint は、見ることのできないコードを判定せず、そこで正しく INDETERMINATE を報告します。それを記録する正直な方法がスキップです。

test_smoke_hub.py（4 件のテスト）は、実際に実行するために稼働中のボットフリートが必要なくなりました。ハブのデモマニフェストへのフォールバック（以下を参照）により、空のスキャンルートに対しても検出対象が得られるため、クリーンなチェックアウト環境で常に実行されるようになりました。

（フリートヘルスサーバーと稼働中のボットが存在するメンテナーのフリートマシンでは、残りのスキップされた統合テストも実際に実行され、成功件数はさらに増えます。ただし、この README ではクリーンなチェックアウト環境と公開 CI で再現できる内容のみを記載しています。）

fastmcp スタイルのテンプレートテスト（test_fastmcp_template.py）は、このスキップリストには含まれません。fastmcp は [dev] 追加依存関係としてインストールされるため、標準的な開発環境で実際に実行されます。

商用サポート

Jaimen Bell がメンテナンスしています。本番環境向けの MCP 統合、カスタムサーバー、またはエージェントの信頼性向上に関する取り組みについては、jaimenbell.dev をご覧ください。

独自の MCP サーバーを構築していますか？MCP Starter Kit には、テンプレート、ビルド手順書、このサーバーをリリースした経験に基づくパッケージ化の実例が収録されています。

mcp-name: io.github.jaimenbell/mcp-factory