mcp-server-shipping

個人用 MCP サーバーの配布

ライブラリのようにほかのコードからインポートされるのではなく、プロジェクトをまたいで個人が利用する MCP サーバーの作成を目的とするリポジトリ向けのワークフローです。動作するリポジトリを「どのプロジェクトからでも読み込める」状態にする方法と、開発マシンとそれ以外の環境での違いを説明します。具体的な名前のほうがプレースホルダーより読みやすいため、作業例では作者自身のサーバー（*-polite-mcp リポジトリ群）を使用しています。すべての箇所で、ご自身のものに置き換えてください。

エージェントスキルの配布は、仕組みの異なる別の作業です。既存のスキルの編集内容をデプロイする方法も説明しているskill-authoring-taudeltaスキルを参照してください。

このスキルが読み取り、実行、書き込みするもの

このスキルにはスクリプトはなく、操作は実行を指示するコマンドを通じて行います。

• 実行：uv tool install、claude mcp add、claude mcp list。
• 書き込み：uv tool installは、uvのツールディレクトリ内にツール環境を作成し、PATH（デフォルトでは~/.local/bin/）にシムを配置します。claude mcp add --scope userはサーバーの登録情報をClaude Codeのユーザーレベル設定に書き込み、--scope projectはリポジトリの.mcp.jsonに書き込みます。どちらも、同じツールのuninstall／removeで元に戻せます。それ以外には何も書き込みません。また、サーバーのあるリポジトリにも、手動で追加する[project.scripts]のエントリ以外は何も書き込みません。
• ネットワーク：uv tool install git+…は、指定したリポジトリをクローンします。

リポジトリごとの開発ループ

ここで取り上げるのは、一般的なことが2つと、作者自身のスタックが1つです。 一般的なこととして、この種のリポジトリでは、コミット済みのロックファイルから環境を再同期し、毎回新たに依存関係を解決しないワンコマンドのセットアップと、CIで実行するものと同じチェックを自動修正してから実行するワンコマンドのゲートが必要です。リポジトリですでに使っている方法が最適です。重要なのは、どのランナーを使うかではなく、どちらもワンコマンドで実行できることです。

この節の残りでは、作者自身の構成を作業例として説明します。指示ではありません。作者のマシンでは、このリポジトリ群の各リポジトリは、手作業で書いたtasks.pyのロジックの代わりに、開発依存関係としてrepo-tasks（PyPIを使わず、Gitをアーティファクトストアとして使用）を採用しています。そのため、リポジトリ独自のtasks.pyはfrom repo_tasks import nsだけです。セットアップコマンドはinv dev-env.setup、ゲートはinv quality.precommitです。また、AGENTS.md／CLAUDE.md／スキルのひな形は、リポジトリ作成時にscaffoldapyで生成されます。全体を通して、ご自身の同等のものに置き換えてください。

使用するランナーにかかわらず、ここから得るべきルールは次のとおりです。 タスクランナーはプロジェクトごとの依存関係であり、PATHにあることを前提にしてはいけません。すでに有効化済みのシェルの外部から実行するもの（CIのステップ、プロジェクト生成フック、あらゆる自動化など）は、必ずプロジェクト独自の環境を通じて実行してください（uv管理のプロジェクトならuv run <runner> <task>）。裸のコマンド名が、このプロジェクトのコピーではなく別のコピー、あるいは何も解決しない可能性があるからです。この節はその間違いを防ぐためのもので、どのランナーを使うかには左右されません。

安定した PATH 上のバイナリにするための単一のエントリーポイントと uv tool install

server.py を作成する前に、MCP リポジトリの pyproject.toml に [project.scripts] エントリーポイント（例： olx-polite-mcp = "olx_polite_mcp.server:main"）を追加してください。後から付け足すのではなく、最初から追加します。そのうえで、uv run／uvx の呼び出しを claude mcp add に指定するのではなく、実際のツールとして uv tool でインストールします（olx-polite-mcp/README.md でエンドツーエンドの動作を検証済みです）。uv tool install は分離された環境を構築し、PATH 上（デフォルトでは ~/.local/bin/）に shim を配置するため、登録時に使うのはパスやフラグを同期し続ける必要のない、単独のバイナリ名になります。

開発中は、ローカルの作業ツリーからインストールします（編集可能モードです。再インストールしなくてもローカルの変更が反映されるため、リポジトリをそのパスに置いたままにする必要があります）。

uv tool install -e <path-to-your-checkout>

積極的な開発を終えたら、GitHub からインストールします（再現性を確保するには @<tag>／@<sha> を指定し、デフォルトブランチを使う場合は省略します）。

uv tool install git+https://github.com/TheodoreAD/olx-polite-mcp

どちらの方法でも、インストール元にかかわらず、登録コマンドは同じ 1 行です。

claude mcp add --scope user olx-polite-mcp olx-polite-mcp

インストール元を切り替えるには、もう一方のソースを指定して uv tool install を再実行します（uv が既存のツールを置き換えます）。登録済みのコマンド名は変わらないため、claude mcp remove や再度の add は必要ありません。 --scope user（local／project ではなく）を使うと、スキルがすでにグローバルにインストールされている方法と一致し、サーバーを 1 つのプロジェクトだけでなく、このマシン上のすべてのプロジェクトで使えます。サーバーをクローンした全員が自動的に利用できるようにしたい_利用側の_リポジトリでは、代わりに --scope project を使ってください（olx-polite-mcp/README.md のプロジェクトスコープの例を参照）。これは、個人が複数のプロジェクトで使う場合とは異なるケースです。

編集可能モードと GitHub からのインストールは組み合わせられません（編集可能モードでは uv が参照できる実際の作業ディレクトリが必要ですが、Git からのインストールではそのようなディレクトリが公開されないためです）。「ローカルで編集し、GitHub から取得したかのようにインストール」するには、自分で git clone し、そのクローンに対して uv tool install -e を実行します。これは、ディスク上のリポジトリから編集可能モードでインストールする方法と同じです。

プロジェクトスコープおよびユーザースコープのサーバーは、新しいセッションで起動する前に、claude の起動時に一度承認する必要があります（保留中のサーバーは claude mcp list に表示されます）。すでに承認済みの実行中セッションでは、引き続き利用できます。

配布：PyPI は使わない

この規模（個人利用、非商用）では、Git リモートから直接解決する uv tool install（上記を参照）により、GitHub リポジトリ自体が配布物の保管場所になります。バージョン更新、公開、認証情報といった手続きは不要です。固定する価値のある安定した状態になったリポジトリでは @<tag>／@<sha> を指定してください。開発中は、参照を指定せずデフォルトブランチを追跡する方法で問題ありません。

詳しい理由

references/rationale.md — git+uv が PyPI（および最初に作成した uvx／uv run 版の草案）より優れていた理由、--scope user を使う理由、そして登録コマンド 1 つで両方のインストール元に対応できる理由を説明しています。