Cmmv Mcp

Contract-Model-Model-View（CMMV）
コントラクトを使用して、スケーラブルでモジュール化されたアプリケーションを構築します。

ドキュメント • 問題を報告

説明

@cmmv/mcp モジュールは、CMMV アプリケーション向けに Model Context Protocol（MCP）を実装し、LLM（大規模言語モデル）とアプリケーション間の標準化されたやり取りを可能にします。MCP は、AI モデルが標準形式で使用できるツールを定義するための構造化インターフェイスを提供します。

特徴

• LLM 連携：アプリケーションと大規模言語モデル間の双方向通信を可能にします。
• 柔軟なトランスポート：HTTP（StreamableHTTP）、SSE、または標準入出力によるトランスポートをサポートします。
• API デコレーター方式：@MCPTool などの直感的なデコレーターを使用してツールを登録できます。
• Zod による検証：Zod を使用して入力スキーマを検証します。
• 接続管理：複数の同時接続を処理する堅牢な実装です。
• 最新の SDK：StreamableHTTPServerTransport を備えた最新の @modelcontextprotocol/sdk を使用します。
• HTTP サーバーとの連携：既存の CMMV HTTP サーバーと連携することも、単独で実行することもできます。
• レガシー SSE のサポート：SSE エンドポイント（/sse、/messages）との互換性を維持します。
• セッション管理：セッション ID の追跡により、複数の MCP セッションを同時にサポートします。
• ヘルスモニタリング：ヘルスチェック（/mcp/health）とツール一覧（/mcp/tools）のエンドポイントを標準で備えています。
• CORS のサポート：クロスオリジンリクエスト向けに CORS を設定できます。
• DNS リバインディング保護：セキュリティ対策として DNS リバインディング保護を設定できます。
• フック連携：CMMV のフックシステムを使用してシームレスに連携します。
• TypeScript：型安全性を強化した、完全な TypeScript サポートを提供します。
• エラー処理：適切な HTTP ステータスコードを使用した包括的なエラー処理を行います。

インストール

pnpm を使用して @cmmv/mcp をインストールします。

$ pnpm add @cmmv/mcp

設定

.cmmv.config.cjs または ConfigSchema を使用して MCP モジュールを設定します。

import { ConfigSchema } from '@cmmv/core';

export const MCPConfig: ConfigSchema = {
  mcp: {
    name: {
      type: 'string',
      required: true,
      default: 'mcp',
    },
    version: {
      type: 'string',
      required: true,
      default: '0.0.1',
    },
    port: {
      type: 'number',
      required: true,
      default: 8765,
    },
    transport: {
      type: 'string',
      required: true,
      default: 'http', // 'http', 'sse' or 'stdio'
    },
    integrateWithHttp: {
      type: 'boolean',
      required: false,
      default: false, // Integrate with existing HTTP server
    },
    jwtSecret: {
      type: 'string',
      required: true,
      default: 'your-secret-key',
    },
    pingInterval: {
      type: 'number',
      required: true,
      default: 30000,
    },
    connectionTimeout: {
      type: 'number',
      required: true,
      default: 300000,
    },
  },
};

アプリケーションの設定

スタンドアロンモード（デフォルト）

メインファイルで MCPModule をインクルードし、アプリケーションを設定します。

import { Application, Config } from '@cmmv/core';
import { DefaultAdapter, DefaultHTTPModule } from '@cmmv/http';
import { MCPModule } from '@cmmv/mcp';
import { MCPHandlers } from './mcp-handlers';

Config.assign({
    mcp: {
        port: 8766,
        transport: 'http',
        name: 'cmmv-mcp-server',
        version: '1.0.0',
        integrateWithHttp: false, // Standalone mode
    },
});

Application.create({
    httpAdapter: DefaultAdapter,
    modules: [MCPModule],
    providers: [MCPHandlers],
});

統合モード（HTTP サーバーと同じポート）

MCP を既存の HTTP サーバーと統合するには、次のようにします。

import { Application, Config } from '@cmmv/core';
import { DefaultAdapter, DefaultHTTPModule } from '@cmmv/http';
import { MCPModule } from '@cmmv/mcp';
import { MCPHandlers } from './mcp-handlers';

Config.assign({
    mcp: {
        port: 3000, // Same port as your HTTP server
        transport: 'http',
        name: 'cmmv-mcp-server',
        version: '1.0.0',
        integrateWithHttp: true, // Integrate with existing HTTP server
    },
});

Application.create({
    httpAdapter: DefaultAdapter,
    modules: [MCPModule],
    providers: [MCPHandlers],
});

integrateWithHttp: true の場合、MCP のルートが既存の HTTP サーバーに追加されます。

• POST /mcp - StreamableHTTP トランスポート
• GET /mcp - SSE トランスポート（レガシー）
• POST /messages - メッセージエンドポイント（レガシー）
• GET /mcp/health - ヘルスチェック
• GET /mcp/tools - 使用可能なツールの一覧

MCP ツールハンドラーの作成

@MCPTool デコレーターを使用して、LLM が呼び出せるツールを登録します。

import { MCPTool, z } from '@cmmv/mcp';

export class MCPHandlers {
    @MCPTool('greet', {
        name: z.string(),
        age: z.number(),
    })
    public async greet({ name, age }: { name: string; age: number }) {
        return {
            content: `Hello \${name}, you are \${age} years old`,
        };
    }
}

MCP クライアントの使用

MCP クライアントは HTTP エンドポイントを使用してサーバーに接続できます。

curl -X POST http://localhost:8765/mcp \\
  -H "Content-Type: application/json" \\
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "greet",
      "arguments": {
        "name": "John",
        "age": 30
      }
    }
  }'

ヘルスチェック

サーバーのヘルス状態を確認できます。

curl http://localhost:8765/health

使用可能なツールの一覧

使用可能なすべてのツールを一覧表示できます。

curl http://localhost:8765/tools

デコレーター

@MCPTool(name: string, schema: Record<string, z.ZodSchema>)

メソッドを、名前と検証スキーマを持つ MCP ツールとして登録します。

ベストプラクティス

• スキーマを明確に定義する：Zod スキーマを使用して、各ツールのパラメーターを明確に定義します。
• 有用な応答を提供する：LLM にとって構造化された有用な応答を返します。
• エラーを適切に処理する：ハンドラーに堅牢なエラー処理を実装します。
• セキュリティを最優先する：公開エンドポイントでは JWT の使用を検討します。
• パフォーマンス：タイムアウトを設定し、ハンドラーを軽量かつ高速に保ちます。