# minimal-mcp-server

MCP（Model Context Protocol）を学ぶための最小構成のサーバー実装です。
Claude Desktop と接続して、チャットからツールを呼び出すことができます。

## 提供ツール

| ツール名 | 説明 | 引数 |
|----------|------|------|
| `echo` | 入力されたメッセージをそのまま返す | `message` (string) |
| `get-current-time` | サーバーの現在日時を返す | なし |
| `search-wikipedia` | 日本語Wikipediaで記事の要約を検索する（外部API連携） | `query` (string) |

## セットアップ

### 必要環境

- Node.js v18 以上（`fetch` API を使用するため）
- npm

### インストール

```bash
git clone <repository-url>
cd minimal-mcp-server
npm install
```

### ビルド

```bash
npm run build
```

`src/index.ts` が `build/index.js` にコンパイルされます。

### 動作確認

```bash
npm start
```

stdio で待ち受け状態になれば成功です（Ctrl+C で終了）。

## Claude Desktop との接続

### 1. 設定ファイルを編集

macOS の場合:

```bash
~/Library/Application Support/Claude/claude_desktop_config.json
```

以下を `mcpServers` に追加します:

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

> `/path/to/` は実際のパスに置き換えてください。

### 2. Claude Desktop を再起動

再起動後、チャット入力欄のハンマーアイコンをクリックすると、登録されたツールが一覧に表示されます。

### 3. ログの確認

MCPサーバーのログは以下に出力されます:

```bash
tail -f ~/Library/Logs/Claude/mcp-server-minimal-mcp-server.log
```

> stdio トランスポートでは `console.log`（stdout）は MCP 通信と干渉するため、ログには必ず `console.error`（stderr）を使用してください。

## 使い方（Claude Desktop での質問例）

ツールは自然言語で質問するだけで、Claude が自動的に適切なツールを選んで実行します。

### echo

```
「Hello World」とエコーして
```

### get-current-time

```
今何時？
```

### search-wikipedia

```
東京タワーについて教えて
富士山のWikipedia情報を調べて
```

## 開発ガイド

### プロジェクト構成

```
minimal-mcp-server/
├── src/
│   └── index.ts          # サーバー本体（ツール定義含む）
├── build/                 # コンパイル出力（git管理外）
├── package.json
└── tsconfig.json
```

### ツールの追加方法

`src/index.ts` に `server.registerTool()` を追加します:

```ts
server.registerTool(
  "tool-name",             // ツール名（ケバブケース推奨）
  {
    description: "ツールの説明（Claudeがツール選択の判断に使う）",
    inputSchema: {         // 引数定義（Zodスキーマ）省略可
      param1: z.string().describe("引数の説明"),
      param2: z.number().describe("引数の説明"),
    },
  },
  async ({ param1, param2 }) => {
    // ツールの処理
    return {
      content: [
        { type: "text", text: "結果のテキスト" },
      ],
    };
  },
);
```

#### ポイント

- **description** は重要です。Claude はこの説明文を見てどのツールを使うか判断します。具体的に書くほど正確に呼び出されます
- **inputSchema** は Zod で定義し、自動的に JSON Schema に変換されてクライアントに公開されます
- 引数なしのツールは `inputSchema` を省略できます
- 戻り値は `content` 配列で、`type: "text"` のオブジェクトを返します

### 外部 API 連携の例（search-wikipedia）

```ts
server.registerTool(
  "search-wikipedia",
  {
    description: "日本語Wikipediaでキーワードを検索し、記事の要約を返すツール",
    inputSchema: {
      query: z.string().describe("検索キーワード（例: 東京タワー）"),
    },
  },
  async ({ query }) => {
    const url = `https://ja.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(query)}`;
    const res = await fetch(url);
    if (!res.ok) {
      return {
        content: [
          { type: "text", text: `「${query}」に該当する記事が見つかりませんでした。` },
        ],
      };
    }
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `【${data.title}】\n${data.extract}\n\nURL: ${data.content_urls?.desktop?.page ?? "N/A"}`,
        },
      ],
    };
  },
);
```

### 技術スタック

| 技術 | 用途 |
|------|------|
| [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) (`@modelcontextprotocol/sdk`) | MCP サーバーフレームワーク |
| [Zod](https://github.com/colinhacks/zod) | 引数のスキーマ定義・バリデーション |
| TypeScript | 型安全な開発 |
| StdioServerTransport | Claude Desktop との通信（stdin/stdout） |

### トランスポートについて

このサーバーは **stdio トランスポート** を使用しています。Claude Desktop はこの方式でMCPサーバーと通信します。

```
Claude Desktop → stdin → StdioServerTransport → McpServer → ツール実行
                                                                 ↓
Claude Desktop ← stdout ← StdioServerTransport ← McpServer ← 結果返却
```

Web アプリとして公開する場合は `StreamableHTTPServerTransport` を使用します（別途実装が必要）。