toy-mcp-server

MCPが実際にどう動くのかを学ぶためにゼロから作った、最小限のModel Context Protocol (MCP)サーバーです。ボイラープレート生成ツールもテンプレートも使わず、素のSDKだけを使います。

最初の実践的なMCPプロジェクトとして、2つのツールと1つのリソースをstdio経由でClaude Desktopに組み込みました。

何ができるのか

MCPを使うと、LLMクライアント（Claude Desktopなど）は、トレーニングデータからテキストを生成するだけでなく、自分のマシン上で実行されている関数を呼び出せます。このサーバーが公開しているものは次のとおりです。

ツール（Claudeが呼び出せる関数）:

• roll_dice — 面数を設定できるサイコロをN個振る

• flip_coin — コインをN回投げる

リソース（Claudeが取得できる読み取り専用データ）:

• server-info — サーバーの基本メタデータ（名前、目的、開始時刻）

なぜこれを作ったのか

LLMは自分のトレーニングデータの外側にはアクセスできず、デフォルトでは何も実行できません。ただテキストを生成するだけです。MCPはモデルに次のものを与える標準的な方法です。

• 能力 — 単体では持っていない機能（例：真の乱数性。LLMは自分でランダムな数字を選ぶのが非常に苦手）

• アクセス — 知る術のないライブデータや非公開データへのアクセス

このプロジェクトは、MCPサーバーを本番環境（データベースや認証付きAPIなど）に接続する前に、そのアイデア本番で試すための小さくて安全なサンドボックスです。

技術スタック

• TypeScript

• @modelcontextprotocol/sdk — 公式MCP SDK

• zod — ツール引数のランタイムスキーマ検証

• stdioトランスポート（Claude Desktopとのローカルサブプロセス通信）

プロジェクト構成

toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md

セットアップ

1. 依存関係のインストール

npm install

2. ビルド

npm run build

3. Claude Desktopに接続する

Claude Desktopの設定ファイルを探します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: 通常は %LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json にあります。正確なパスはインストール方法（Microsoft Storeなのか直接インストーラーなのか）によって異なる場合があります。確実な見つけ方は、Claude Desktopを開いて 設定 → 開発者 → ローカルMCPサーバー → 設定を編集 を開くことです。これでアプリが実際に読み込んでいる正確なファイルが開きます。

このサーバーを mcpServers の下に追加します（既存のファイルを上書きせず、マージしてください）:

{
  "mcpServers": {
    "toy-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/toy-mcp-server/build/index.js"]
    }
  }
}

パスは、お使いのマシン上の build/index.js の実際の絶対パスに置き換えてください。Windowsでは、JSON文字列内のバックスラッシュを \\ のようにエスケープしてください。

4. Claude Desktopを再起動する

ウィンドウを閉じるだけではなく、完全に終了してから開き直します。設定 → 開発者 → ローカルMCPサーバー で toy-mcp-server が接続済みと表示されていることを確認してください。

5. 試してみる

チャットで次のように尋ねてみます。

• 「6面サイコロを3個振って」

• 「コインを10回投げて」

応答の上に小さなツール呼び出しインジケーター（例：「Roll Dice」）が表示されていれば、Claudeが答えを推測するのではなく、実際に関数を呼び出したことを確認できます。

簡単に仕組みを説明すると

• McpServer — 接続してくるクライアントに対してサーバーの機能を宣言するオブジェクトです。

• registerTool(name, config, handler) — 呼び出し可能な関数を登録します。config.inputSchemaは、ハンドラーが実行される前にモデルが送ってきた引数をZodで検証します。

• registerResource(uri, config, handler) — URIで指定できる読み取り専用データを登録します。引数なしで取得されます。

• StdioServerTransport — 通信プロトコルの役割を担います。Claude Desktopはこのファイルをサブプロセスとして起動し、JSON-RPCを使いstdin/stdoutで通信します。ここではconsole.logをログに使いません。stdoutは実際のプロトコルの通信路だからです。代わりにconsole.error（stderr）を使ってログを出します。

次のステップ

• おもちゃのツールを、実際のデータベース（Prisma経由のPostgres）を操作する本番ツールに置き換える

• GitHubバックエンドのツール（例：list_open_prs）を追加して、トークン認証を試す

• ローカルで動かすのではなくリモートでホストするために、Streamable HTTPトランスポートを試す

ライセンス

MIT