Dynamic MCP Server Framework

Dynamic MCP Server Framework

最新の API キー認証、ユーザー管理、動的なツール共有に対応した、Model Context Protocol（MCP）サーバーを構築するための柔軟で拡張性の高いフレームワークです。

---

🚀 概要

Dynamic MCP Server は、安全でユーザーを認識し、拡張可能な AI ツールサーバーを実現します。以下をサポートしています。

• API キーによる認証（シンプルで、すべての MCP クライアントと互換性があります）
• ユーザー管理と認可（MongoDB を使用）
• セッション単位、ユーザーごとのツール読み込み
• ツール共有ときめ細かなアクセス制御
• 後続プロジェクト向けの拡張可能な HTTP およびデータベースレイヤー

---

🌟 主な機能

• 動的なツール管理：実行時にツールを作成、削除、認可できます。ツールは起動時やコード内の静的な定義に限定されません。これにより、実行時の真の拡張性が実現し、ほとんどの他の MCP サーバーとの主な差別化要因となっています。
• ユーザー管理：ユーザーの追加、更新、削除、一覧表示、管理者の初期設定、ロールベースのアクセス制御が可能です。
• ツール共有：他のユーザーとのツール共有、アクセスレベルの管理、リアルタイム更新の受信が可能です。
• 最新の認証：シンプルな API キー認証と、認可用の MongoDB に対応しています。
• 拡張性：後続プロジェクトにカスタム HTTP ルートや MongoDB コレクションを追加できます。
• セッション単位のツール読み込み：ツールは全体ではなく、ユーザーセッションごとに読み込まれます。

---

🔑 認証（API キー）

• 各ユーザーには一意の apiKey が割り当てられます（ユーザー作成時に自動生成されます）。
• 認証するには、クライアントはクエリパラメーターまたはヘッダーで apiKey を指定する必要があります。
  • クエリパラメーター：?apiKey=your-key または ?apikey=your-key
  • ヘッダー：x-apikey: your-key または apikey: your-key
• Streamable HTTP Transport（最新）：/mcp?apiKey=... またはヘッダーを指定して /mcp
• サーバーはデータベース内の apiKey を検索し、ユーザーを認証します。

---

🚀 トランスポートプロトコル

Dynamic MCP Server は、従来の MCP トランスポートプロトコルと最新の MCP トランスポートプロトコルの両方をサポートしています。

Streamable HTTP Transport

• プロトコルバージョン：2025-03-26
• エンドポイント：/mcp
• 機能：最新かつ効率的な単一エンドポイント設計
• 認証：クエリパラメーター ?apiKey=your-key またはヘッダー x-apikey: your-key
• 用途：新しい連携での使用を推奨します

---

� ドキュメント

• はじめに
• トランスポートプロトコル
• ユーザー管理
• ツール管理と共有
• 認証と認可
• サーバーの拡張（HTTP と DB）
• API リファレンス
• 使用例
• サーバーの拡張：ハンドラーパッケージとツールパッケージの作成
• テストパターンとモック戦略

ツールの表示モデル： すべてのツールは、デフォルトですべてのユーザーに表示されます。ユーザーは hide-tool および unhide-tool アクションを使って、自分の表示からツールを非表示にできます。詳細は、ユーザー管理とツール管理と共有を参照してください。

---

🛠️ クイックスタート

インストール方法と基本的な使い方については、はじめにを参照してください。

---

📝 コントリビューション

コントリビューションを歓迎します。詳細はドキュメントを参照してください。

📄 ライセンス

MIT

---

🧩 ハンドラーとツールの登録（新しいパターン）

ツールは現在、ハンドラーパッケージを使って登録します。各ハンドラーパッケージは、関連するツールをまとめ、ツール実行用のハンドラー関数を提供します。これは、拡張性と保守性を高めるために推奨されるパターンです。

例：

const myHandlerPackage = {
  name: "my-domain",
  tools: [
    {
      name: "my-tool",
      description: "A custom tool",
      inputSchema: {
        /* ... */
      },
      handler: { type: "my-domain", config: {} },
      rolesPermitted: ["user", "admin"],
    },
    // ...more tools...
  ],
  handler: async (args, context, config, toolName) => {
    // Dispatch logic based on toolName, if needed
  },
};

const server = new DynamicMcpServer({ name: "my-mcp", version: "1.0.0" });
await server.start();
await server.registerHandler(myHandlerPackage);

詳細は、はじめにと使用例を参照してください。

---

🧩 ツール引数のマッピング（config.args）

ツールを定義する際に、config.args フィールドを使用して、ユーザーが指定したツールオプション（inputSchema から）をアクションハンドラーが想定する引数にマッピングできます。このマッピングでは、次の要素をサポートしています。

• リテラル値（例："country": "US"）
• テンプレート変数（例："city": "{{location}}"）
• ネストされたオブジェクトと配列（すべてのテンプレートが再帰的に解決されます）

例：

handler: {
  type: "weather-tools",
  config: {
    url: "https://api.openweathermap.org/data/2.5/weather",
    args: {
      queryParams: {
        appid: "{{OPENWEATHER_API_KEY}}",
        q: "{{location}}",
        units: "{{units}}"
      }
    }
  }
}

ツールが呼び出されると、システムはツールの入力と環境変数を使って、config.args 内のすべての {{...}} テンプレートを自動的に解決します。ハンドラーはマージされ、解決済みの引数を受け取るため、手動でマッピングする必要はありません。

詳細と例については、ツールの作成を参照してください。

---