mcp-server-template

本番運用を想定したMCPサーバーへの出発地点。

MCPドキュメントのクイックスタートを使えば、10行で動くツールが手に入ります。しかし、そのツールが自分の管理下にない何かによって呼ばれるようになったとき、あなたがその後3週間で追加していくことになるのが、このテンプレートです。

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b          # fine on a laptop

ここに足りないのは機能ではありません。重要なのは、ツールがハングしたとき、例外を投げたとき、想定外の結果を返したとき、一度に40回呼ばれたとき――そして、そのときにモデルに見せてもよいものは何か――です。

このテンプレートが解決する問題

MCPツールの呼び出し元は言語モデルであり、それがエンジニアリングの考え方を変えます。

• モデルはスタックトレースを読めるないが、それをあったままユーザーにしゃべります。つまり、トレースバックの漏れは無意味なだけでなく、情報の開示でもあることになります。

• モデルには自分の締め切りがあります。ハングするツールは遅い回答を生むのではなく、その会話を終わらせるのです。

• モデルは末尾を切り詰めた結果と完全な結果を区別できない。コンテキストに静かにあふれてもエラーにはならず、回答の質が下がる。あなたはそれをまず顧客から知らされることになるでしょう。

• モデルは、許せば再試行します。だから「見つからない」と「上流が落ちている」は別の回答にしなければなりません。さもなければ、最初から存在しないレコードを狙ってサービスに叩き続けることになります。

これの一つひとつは、一度だけ、一つの場所で処理されます。金曜の午後に追加したツールも、最初の日に注意深く書いたツールと同じ保護を受けられます。

Related MCP server: Graft

得られるもの

クイックスタート

git clone https://github.com/muhammadwaqasmbd/mcp-server-template
cd mcp-server-template
make install
make test
make run          # stdio, ready for a desktop MCP client

ネット越しに提供するには次のようにします:

TRANSPORT=streamable-http PORT=8000 python -m mcp_server_template

デスクトップクライアントから使う

{
  "mcpServers": {
    "template": {
      "command": "python",
      "args": ["-m", "mcp_server_template"],
      "cwd": "/absolute/path/to/mcp-server-template"
    }
  }
}

自前のツールを追加する

関数を書くだけです。他のことは他は何もありません。

# src/mcp_server_template/tools/orders.py
from ..errors import InvalidInput, UpstreamUnavailable

async def cancel_order(order_id: str) -> dict:
    """Cancel an order. Returns the order's new state."""
    if not order_id.strip():
        raise InvalidInput("order_id must not be empty")     # model can fix this
    ...
    raise UpstreamUnavailable("order service timed out")     # model may retry

ガードの後ろに登録します:

mcp.tool(name="cancel_order", description="Cancel an order by id.")(
    guard.wrap(orders.cancel_order)
)

これで、タイムアウト、並行制約、エラー境界、切り詰め、ログがすべて手に入ります。それらはあなたが一切書いていません。

モデルが修正できるときは InvalidInput を、再試行が効くかもしれないときは UpstreamUnavailable を投げてください。単に偽という出力は通常通りに返します ― レコードが存在しないのはエラーではなく、それが答えなのです。

アーキテクチャ

server.py      the ONLY module that imports the MCP SDK
   │
   ├── guard.py          timeout · concurrency · error boundary · truncation · timing
   ├── errors.py         what a model is allowed to see, and secret redaction
   ├── observability.py  JSON logs on stderr, correlation ids
   ├── config.py         validated once at boot, immutable thereafter
   └── tools/            plain functions. No protocol knowledge. No decorators

依存の矢印は一方向です:ツールはMCPについて何も知らず、ガードはあなたのツールについて何もしません。だからサーバーなしでテストがミリ秒単位で実行できるしくみまり、SDKの変更がたった一つのファイルにしか触れないのです。

このテンプレートが意図的にやらないこと

境界を正直に語ることは、機能一覧を長くすることよりも価値があります。

• 認証はしません。 stdio では、OS の境界がそのままセキュリティの境界です。HTTP経由で公開するなら、その前に本物の認証を置いてください。SDK で対応しています。ここに配線してしまえば、あなたがまだ選んでいない前提の元の脅威モデルを暗に想定することになります。

• ツールの中に再試行ロジックは持ちません。 ガードが失敗が再試行可能かどうかを報告し、再試行の判断は呼び出し元に属する。呼び出し元はそのための文脈と予算を持っています。

• 発信者ごとのレート制限はしません。 並行上限は総作業量を制限するものであって、呼び出し元IDごとの公平性ではありません。それが要るなら、その前にID要ります。

• 永続化・キュー・スケジューラは持ちません。 ひっそりジョブランナーになったツールサーバーは、誰も設計していない分散システムです。

• 結果の分割ストリーミングはしません。 時間のかかるツールには追加する価値がありますが、エラー境界が複雑になるため、また多くのツールは必要としないから、含めていません。

テスト

make test

このテストスイートは意図的に、失敗の姿に焦点を当てていて、カバレッジではありません。ハングしたツールがキャンセルされること、想定外の例外のメッセージが漏れないこと、大きい出力が目に見える形で切り詰められること、並行した10回の呼び出しでも上限が守られること、そしてブロッキングする同期ツールがイベントループを枯渇させないことを検証します。

ライセンス

MIT — LICENSE を参照。

Muhammad Waqas が作っています。彼は規制の厳しい業界のエージェントシステムにほとんどの時間を費やしており、そこでは、過剰な自信を持った誤った回答は、報告すべきインシデントになります。