Cmmv Mcp

Contract-Model-Model-View（CMMV）
使用契约构建可扩展的模块化应用。

文档 • 报告问题

描述

@cmmv/mcp 模块为 CMMV 应用实现了模型上下文协议（MCP），支持大模型与应用之间进行标准化交互。MCP 提供了结构化接口，用于以标准格式定义 AI 模型可使用的工具。

功能

• 大模型集成：支持应用与语言模型之间的双向通信。
• 灵活的传输方式：支持通过 HTTP（StreamableHTTP）、SSE 或标准 I/O 传输。
• 基于 API 装饰器：使用 @MCPTool 等直观的装饰器注册工具。
• 使用 Zod 进行验证：使用 Zod 验证输入架构。
• 连接管理：提供可靠的实现，以处理多个并发连接。
• 现代 SDK：使用最新的 @modelcontextprotocol/sdk 和 StreamableHTTPServerTransport。
• HTTP 服务集成：可集成到现有的 CMMV HTTP 服务中，也可独立运行。
• 兼容旧版 SSE：保持与 SSE 端点（/sse、/messages）的兼容性。
• 会话管理：支持多个并发 MCP 会话，并跟踪会话 ID。
• 运行状况监控：内置运行状况检查（/mcp/health）和工具列表（/mcp/tools）端点。
• CORS 支持：可配置跨域请求的 CORS。
• DNS 重绑定防护：提供可配置的 DNS 重绑定防护功能，增强安全性。
• 钩子集成：可通过 CMMV 的钩子系统无缝集成。
• TypeScript：提供完整的 TypeScript 支持和增强的类型安全性。
• 错误处理：全面处理错误，并返回适当的 HTTP 状态码。

安装

通过 pnpm 安装 @cmmv/mcp：

$ pnpm add @cmmv/mcp

配置

在 .cmmv.config.cjs 中配置 MCP 模块，或使用 ConfigSchema：

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 装饰器注册可供大模型调用的工具：

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 架构明确定义每个工具的参数。
• 提供有意义的响应：为大模型返回结构化且有帮助的响应。
• 妥善处理错误：在处理程序中实现健壮的错误处理。
• 安全第一：考虑在公共端点使用 JWT。
• 性能：使用超时，并确保处理程序轻量、快速。