mcp-multi-poc-alpha

mcp-multi-poc

単一の PyPI パッケージから複数の MCP サーバーを提供する PoC です。サーバーを選択するサブコマンドと、必要に応じて依存関係を追加するオプショナルエクストラを使用します。 Couchbase の MCP モノレポに関する疑問を検証するためのものです（alpha = 運用、beta = 分析、tabulate = 分析 SDK — fastmcp の推移的依存関係に含まれないものを選択しています。httpx と pyyaml は含まれるため、オプショナルエクストラのガードが意図せず無効になります）。

この PoC で回答すること

#	質問	テスト箇所
1	2 つの MCP レジストリエントリーを同じ PyPI パッケージに紐付けられますか？	server.alpha.json と server.beta.json の両方を公開
2	1 つのパッケージの README にある複数の mcp-name コメントを、レジストリの所有権検証で受け入れますか？	上記の 2 つの HTML コメント
3	レジストリのスキーマ／バリデーターは、identifier 内のエクストラ構文（mcp-multi-poc[beta]）を受け入れますか？	server.beta.json — 拒否された場合はプレーンな identifier に切り替え、エクストラを指定できないことを記録
4	クライアントは、レジストリのメタデータにあるサブコマンド形式（uvx mcp-multi-poc alpha）を正しく実行しますか？	クライアント（Claude Desktop／MCP Inspector）から両方のサーバーをインストール
5	パッケージ名と異なる名前のコンソールスクリプト（mcp-multi-poc-beta）を実行する、スキーマ上有効な方法はありますか？	server.beta-script.json。5a（失敗）：identifier = スクリプト名 → 404。identifier は実在する PyPI パッケージでなければなりません。5b（現在のファイル）：identifier = 実在するパッケージ、スクリプト名を位置指定の runtimeArgument として埋め込み → uvx --from 'mcp-multi-poc[beta]' mcp-multi-poc-beta mcp-multi-poc。追加された identifier は余分な引数になるため、サーバー側で無視する必要があります。5b も失敗した場合は、スクリプトごとにシムパッケージを用意します

これまでの調査結果（2026-07-31）

• Q1 — PyPI パッケージごとに複数エントリー：可能です。 共有パッケージを使って mcp-multi-poc-alpha を公開しました。
• Q2 — 1 つの README に複数の mcp-name コメント：可能です（コメントが 3 つある状態で alpha の検証に成功）。
• Q3 — identifier 内のエクストラ：不可。ただし runtimeArguments で指定できます。 identifier 内のエクストラは、PyPI の完全一致検索に失敗します — PyPI package 'mcp-multi-poc[beta]' not found (status: 404)。代替手段は 有効です：プレーンな identifier: mcp-multi-poc と runtimeArguments: --from "mcp-multi-poc[beta]" を指定した mcp-multi-poc-beta の公開に成功しました（レジストリに掲載され、/v0/servers API で確認済み）。
• Q5a — 名前の異なるコンソールスクリプトを identifier に指定：不可（公開時に確認）。 同じ 404 の仕組み（'mcp-multi-poc-beta' not found）です。レジストリは、ほかの処理に先立って identifier が実在する PyPI パッケージかどうかを検証します。
• Q5b — スクリプト名を位置指定の runtimeArgument にする：可能、公開済み。 io.github.nithishr/mcp-multi-poc-beta-script は公開済みです（2026-07-31 公開。description を 100 文字の上限まで短縮したところで検証上の問題が解消しました）。ローカルでは uvx --from 'mcp-multi-poc[beta]' mcp-multi-poc-beta mcp-multi-poc で MCP の初期化ハンドシェイクが完了します — main() が argv を解析しないため、末尾の identifier は暗黙に無視されます。注意点：余分な argv を許容するエントリーポイントでのみ安全です（click では ignore_unknown_options と allow_extra_args、またはダミーのオプショナル引数が必要）。また、クライアントが runtimeArguments の順序を維持することに依存します — メタデータの中でも検証例が最も少ない経路です。レジストリの UI では、identifier が実行可能な名前として表示されます。本番環境でサーバーごとに異なるスクリプトを使う場合は、スクリプトごとにシムパッケージを用意することを推奨します（identifier == スクリプト名、runtimeArguments は不要）。
• 判明したレジストリ検証の制限： description は 100 文字以下、identifier は実在する PyPI パッケージのリテラルでなければならない（エクストラは拒否）、runtimeArguments／packageArguments の内容は検証されません。

ローカルのスモークテスト（公開前）

cd mcp-registry-poc
uv venv && uv pip install -e .
mcp-multi-poc alpha          # starts alpha on stdio (Ctrl+C to exit)
mcp-multi-poc beta           # must FAIL with the friendly extras message
uv pip install -e ".[beta]"
mcp-multi-poc beta           # now starts
mcp-multi-poc                # bare command runs alpha (backward-compat check)
mcp-multi-poc-beta           # Option 1 script works locally once extra installed

PyPI 公開後の uvx の動作：

uvx mcp-multi-poc alpha                  # base only
uvx "mcp-multi-poc[beta]" beta           # extras via uvx — key UX under test
uvx --from "mcp-multi-poc[beta]" mcp-multi-poc-beta   # Option 1 fallback form

公開手順（手動、順番どおり）

1. PyPIでmcp-multi-pocがすでに使われている場合は、別の名前を選び、一貫して名前を変更します （pyprojectのname、[project.scripts]、両方のserver.json識別子）。
2. 実際のPyPIにビルドして公開します（レジストリの検証ではpypi.orgから取得するため、 TestPyPIは使用できません）：uv build && uv publish。
3. mcp-publisherをインストールしてログインします： mcp-publisher login github（対話式） — io.github.<username>名前空間と一致する必要があります。
4. エントリーを公開します： mcp-publisher publish server.alpha.json、... server.beta.json、および ... server.beta-script.json — 最後のものは検証に失敗する想定です。 正確なエラーを記録します（CLIがファイルを./server.jsonに置くことを要求する場合は、 事前にそれぞれを所定の場所にコピーします）。
5. レジストリAPIで確認します： curl "https://registry.modelcontextprotocol.io/v0/servers?search=mcp-multi-poc"
6. レジストリのメタデータを使ってクライアントで両方のサーバーを設定し、 echo（alpha）とmake_table（beta）を呼び出します。
7. 上記の各質問について結果を記録してから、PoCエントリーを非推奨にするか削除します。

Q4 — 公開したエントリーをクライアントからテストする

ほとんどのクライアントはまだ公式レジストリから直接インストールできないため、Q4は2つに分かれます： （a）仕様で必須とされるコマンドの組み立て （uvx <runtimeArguments> <identifier> <packageArguments>）でサーバーが正常に動作するか、 （b）レジストリを利用するクライアントがその組み立てを再現するか、です。

1. 実際に公開された内容を取得し、packagesブロックを確認します： curl "https://registry.modelcontextprotocol.io/v0/servers?search=mcp-multi-poc"
2. MCP Inspector — 手動で組み立てたコマンドに対して対話式にツールを呼び出します：

   npx @modelcontextprotocol/inspector uvx mcp-multi-poc alpha
   npx @modelcontextprotocol/inspector uvx --from "mcp-multi-poc[beta]" mcp-multi-poc beta
   

3. Claude Code — 同じコマンドをstdioサーバーとして使い、echo / make_tableを呼び出します：

   claude mcp add poc-alpha -- uvx mcp-multi-poc alpha
   claude mcp add poc-beta -- uvx --from "mcp-multi-poc[beta]" mcp-multi-poc beta
   

   （Claude Desktopの場合、対応するclaude_desktop_config.jsonのエントリーは次のとおりです：）

   {
     "mcpServers": {
       "poc-alpha": { "command": "uvx", "args": ["mcp-multi-poc", "alpha"] },
       "poc-beta":  { "command": "uvx", "args": ["--from", "mcp-multi-poc[beta]", "mcp-multi-poc", "beta"] }
     }
   }
   

4. レジストリネイティブのインストール（実際の（b）テスト）：VS CodeのMCPサーバー ギャラリーは公式レジストリを利用しています。そこでmcp-multi-pocを検索して インストールします。これにより、クライアントが runtimeArguments + identifier + packageArgumentsを独自に組み立てるかをテストできます。エントリーの 表示が遅れたり、掲載前にキュレーションされたりする場合があります。

ステップ2～3で証明できるのは（a）のみです。（b）を証明できるのはステップ4（または別のレジストリ利用クライアント）だけです。 これは、beta/beta-scriptエントリーが実際に依存するものです。