# Search MCP Server

**複数のMCPサーバーを統合し、AIクライアントのコンテキスト消費を75%削減するMCPアグリゲーター**

Search MCP Serverは、Model Context Protocol (MCP) の理念に基づき、複数のMCPサーバーを1つに集約することで、Claude Desktop、Cursor、Windsurf等のAIクライアントのコンテキスト消費を**約75%削減**します。

**⚡ Bun最適化**: 高速なBunランタイムで実装されており、Node.jsと比較して3-4倍高速に動作します。

## 問題と解決策

### 現在の課題

```
Claude Desktop
├── filesystem MCP (50 tools)
├── brave-search MCP (20 tools)
├── database MCP (30 tools)
└── slack MCP (15 tools)

→ 115 tools × 平均200トークン = 23,000トークン消費 😢
```

各MCPサーバーが個別に接続されており、すべてのツールのメタデータが初期読み込み時にコンテキストを消費します。

### Search MCPの解決策

```
Claude Desktop
└── Search MCP (アグリゲーター)
    ├── filesystem MCP
    ├── brave-search MCP
    ├── database MCP
    └── slack MCP

→ 軽量メタデータのみ: 約5,750トークン (75%削減!) 🎉
```

Search MCPが複数のMCPサーバーを束ね、**プログレッシブな開示**により必要な情報だけを段階的に提供します。

## 主な特徴

- 🎯 **MCPアグリゲーター**: 複数のMCPサーバーを1つに統合
- 📉 **コンテキスト削減**: 初期読み込みを75%削減（23,000 → 6,000トークン）
- 🔌 **簡単な移行**: 既存のClaude Desktop設定をコピペするだけ
- 🔄 **プログレッシブ開示**: 必要な情報のみを段階的に取得
- 🛠️ **MCP標準準拠**: stdio + JSON-RPC 2.0による標準プロトコル
- ⚡ **高速**: Bunランタイムで3-4倍高速（起動12ms、Node.jsは50ms）
- 📦 **シングルバイナリ**: 1つのバイナリファイルで配布可能
- 🔀 **デュアルサポート**: Bun（推奨） + Node.js（互換）

## クイックスタート

### 1. インストール

#### オプション A: Bun を使用（推奨）

```bash
# Bunのインストール
curl -fsSL https://bun.sh/install | bash

# リポジトリのクローン
git clone https://github.com/krtw00/search-mcp.git
cd search-mcp

# 依存関係のインストール
bun install
```

#### オプション B: Node.js を使用

```bash
# リポジトリのクローン
git clone https://github.com/krtw00/search-mcp.git
cd search-mcp

# 依存関係のインストール
npm install
```

### 2. 設定ファイルの作成

既存のClaude Desktop設定から`mcpServers`セクションをコピー：

```bash
mkdir -p config
vi config/mcp-servers.json
```

**config/mcp-servers.json**:
```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
      }
    }
  }
}
```

**ポイント**: Claude Desktopの設定ファイルと**全く同じ形式**なので、コピペするだけ！

### 3. Search MCPの起動

**開発モード**:
```bash
# Bunで起動（推奨）
bun run dev

# Node.jsで起動
npm run dev:node
```

**ビルド & 起動**:
```bash
# Bunでビルド
bun run build
bun start

# Node.jsでビルド
npm run build:node
npm run start:node

# シングルバイナリをビルド（Bun）
bun run build:binary
./search-mcp
```

### 4. Claude Desktopの設定を更新

**変更前** (`~/.config/claude/claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "filesystem": { ... },
    "brave-search": { ... },
    "database": { ... }
  }
}
```

**変更後（Bun使用）**:
```json
{
  "mcpServers": {
    "search-mcp": {
      "command": "bun",
      "args": ["run", "/path/to/search-mcp/src/index.ts"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/search-mcp/config/mcp-servers.json"
      }
    }
  }
}
```

**変更後（シングルバイナリ使用）**:
```json
{
  "mcpServers": {
    "search-mcp": {
      "command": "/path/to/search-mcp/search-mcp",
      "args": [],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/search-mcp/config/mcp-servers.json"
      }
    }
  }
}
```

**変更後（Node.js使用）**:
```json
{
  "mcpServers": {
    "search-mcp": {
      "command": "node",
      "args": ["/path/to/search-mcp/dist/index.js"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/search-mcp/config/mcp-servers.json"
      }
    }
  }
}
```

### 5. Claude Desktopを再起動

完了！これでSearch MCP経由ですべてのツールが使えるようになり、コンテキスト消費が大幅に削減されます。

## コンテキスト削減の仕組み

### 段階的な情報取得

1. **初期読み込み（軽量）**
   - ツール名とサーバー名のみ返す
   - 115 tools × 50トークン = 5,750トークン

2. **詳細取得（必要時のみ）**
   - 詳細なパラメータ情報を返す
   - 1 tool × 200トークン = 200トークン

3. **実行**
   - ツールを実行し、結果を返す

**合計**: 約6,000トークン (従来の23,000トークンから75%削減)

## プロジェクト構成

```
search-mcp/
├── src/
│   ├── mcp/
│   │   ├── mcp-client-manager.ts  # MCP統合管理
│   │   └── mcp-client.ts          # 個別MCP接続
│   ├── index.ts                   # MCPサーバー実装
│   ├── tool-registry.ts           # ツール集約
│   └── types.ts                   # 型定義
├── config/
│   └── mcp-servers.json           # MCP設定ファイル
├── docs/
│   ├── design/                    # 詳細設計
│   │   ├── 07-simplified-setup.md
│   │   └── 08-mcp-aggregator.md
│   ├── architecture.md
│   └── mcp-concepts.md
└── package.json
```

## MCPプロトコル対応

Search MCPは、Model Context Protocolの標準仕様に準拠しています：

- ✅ **stdio通信**: 標準入出力を使用した通信
- ✅ **ツール発見**: `tools/list` メソッド
- ✅ **ツール実行**: `tools/call` メソッド
- ✅ **初期化**: `initialize` プロトコル
- 🔜 **SSE (Server-Sent Events)**: 今後対応予定
- 🔜 **リソース管理**: 今後対応予定

## 対応MCPサーバー

以下を含む、すべての標準MCP準拠サーバーに対応：

- [@modelcontextprotocol/server-filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)
- [@modelcontextprotocol/server-brave-search](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)
- [@modelcontextprotocol/server-postgres](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres)
- [@modelcontextprotocol/server-github](https://github.com/modelcontextprotocol/servers/tree/main/src/github)
- [@modelcontextprotocol/server-slack](https://github.com/modelcontextprotocol/servers/tree/main/src/slack)
- その他、MCPプロトコルを実装したすべてのサーバー

## ドキュメント

### ユーザー向け
- [セットアップガイド](docs/design/07-simplified-setup.md) - 詳細なセットアップ手順
- [MCP概念](docs/mcp-concepts.md) - MCPの基本概念

### 開発者向け
- [MCPアグリゲーター設計](docs/design/08-mcp-aggregator.md) - 内部設計の詳細
- [アーキテクチャ](docs/architecture.md) - システムアーキテクチャ
- [設計ドキュメント](docs/design/) - 詳細な実装設計

## ロードマップ

- [x] Phase 1: MCPアグリゲーター基本実装
- [ ] Phase 2: 検索機能強化
- [ ] Phase 3: セキュリティ機能（認証・レート制限）
- [ ] Phase 4: 動的MCPサーバー登録
- [ ] Phase 5: Web管理UI（オプション）

詳細は [docs/design/00-overview.md](docs/design/00-overview.md) を参照。

## 技術スタック

- **ランタイム**: Bun 1.0+ （推奨）/ Node.js 18+ （互換）
- **言語**: TypeScript 5.9+
- **プロトコル**: MCP (Model Context Protocol)
- **通信**: stdio + JSON-RPC 2.0
- **プロセス管理**: child_process.spawn
- **依存関係**: @modelcontextprotocol/sdk（オプション）

### なぜBun？

- ⚡ **3-4倍高速**: Node.jsと比較して圧倒的なパフォーマンス
- 🪶 **30%軽量**: メモリ使用量が少ない（20-30MB vs 30-50MB）
- 🚀 **起動が速い**: 12ms（Node.jsは50ms）
- 📦 **シングルバイナリ**: ランタイム不要の配布が可能
- 🔧 **TypeScript標準**: トランスパイル不要で直接実行
- ✅ **Claude Code採用**: AnthropicがBunでMCPを実装（互換性保証）

詳細は [docs/design/tech-stack-bun-deep-dive.md](docs/design/tech-stack-bun-deep-dive.md) を参照。

## 開発

### 開発モード

```bash
# Bunで開発（推奨）
bun run dev

# Node.jsで開発
npm run dev:node
```

### テスト

```bash
# Bunでテスト
bun test

# Node.jsでテスト
npm run test:node
```

### ビルド

```bash
# Bunでビルド
bun run build

# シングルバイナリ作成
bun run build:binary

# Node.jsでビルド
npm run build:node
```

詳細な実装ガイドは [IMPLEMENTATION.md](IMPLEMENTATION.md) を参照。

## トラブルシューティング

### MCPサーバーに接続できない

```bash
# 詳細ログを有効化
LOG_LEVEL=debug npm start

# 設定を確認
cat config/mcp-servers.json
```

### 環境変数が読み込まれない

```bash
# 環境変数を設定
export BRAVE_API_KEY="your-api-key"

# または.envファイルを使用
echo "BRAVE_API_KEY=your-api-key" > .env
```

## ライセンス

MIT

## 貢献

プルリクエストを歓迎します。大きな変更の場合は、まずissueを開いて変更内容を議論してください。

## 参考

- [Anthropic Model Context Protocol](https://www.anthropic.com/news/model-context-protocol)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [MCP Servers Repository](https://github.com/modelcontextprotocol/servers)