MCP 协议：AI Agent 的工具集成标准

// MCP 协议交互示例：初始化阶段
// 1. Host → Server: initialize
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": { "listChanged": true },
      "sampling": {}
    },
    "clientInfo": {
      "name": "claude-desktop",
      "version": "1.0.0"
    }
  }
}

// 2. Server → Host: initialize response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": { "listChanged": true },
      "resources": { "subscribe": true, "listChanged": true },
      "prompts": { "listChanged": true }
    },
    "serverInfo": {
      "name": "github-mcp-server",
      "version": "1.0.0"
    }
  }
}

// 3. Host → Server: initialized (通知)
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

// 4. Host → Server: 列出可用工具
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

// 5. Server → Host: 返回工具列表
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "create_issue",
        "description": "在 GitHub 仓库中创建 Issue",
        "inputSchema": {
          "type": "object",
          "properties": {
            "owner": { "type": "string" },
            "repo": { "type": "string" },
            "title": { "type": "string" },
            "body": { "type": "string" },
            "labels": { "type": "array", "items": { "type": "string" } }
          },
          "required": ["owner", "repo", "title"]
        }
      }
    ]
  }
}

// MCP Server 的传输层选择
// stdio 模式（本地进程）
// ┌──────────┐   stdin    ┌───────────┐
// │   Host   │ ─────────► │ MCP Server│
// │          │ ◄───────── │ (子进程)  │
// └──────────┘   stdout   └───────────┘
// 优点：零网络延迟、无需端口管理、进程级隔离
// 缺点：只能在本地运行

// HTTP + SSE 模式（远程服务）
// ┌──────────┐  HTTP POST  ┌───────────┐
// │   Host   │ ──────────► │ MCP Server│
// │          │ ◄────────── │ (远程服务) │
// └──────────┘   SSE stream └───────────┘
// 优点：跨网络、可部署到云端、支持多 Host 连接
// 缺点：网络延迟、需要认证、运维复杂

// 2026 年趋势：本地开发用 stdio，生产环境用 HTTP+SSE

// 构建自定义 MCP Server：数据库查询工具
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import { Pool } from "pg";

// 创建 MCP Server 实例
const server = new McpServer({
  name: "database-query-server",
  version: "1.0.0",
});

const db = new Pool({
  host: process.env.DB_HOST,
  port: parseInt(process.env.DB_PORT || "5432"),
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
});

// 注册工具 1: 安全 SQL 查询
server.tool(
  "query_database",
  "执行只读 SQL 查询，返回结果集",
  {
    sql: z.string().describe("SELECT 查询语句"),
    max_rows: z.number().default(100).describe("最大返回行数"),
  },
  async ({ sql, max_rows }) => {
    // 安全验证：只允许 SELECT 语句
    const normalized = sql.trim().toUpperCase();
    if (!normalized.startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "错误：只允许 SELECT 查询" }],
        isError: true,
      };
    }
    // 限制返回行数
    const safeSql = sql.endsWith(";") ? sql : sql + ";";
    const limitSql = safeSql.replace(
      /;$/,
      ` LIMIT ${Math.min(max_rows, 1000)};`
    );

    try {
      const result = await db.query(limitSql);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result.rows, null, 2),
          },
          {
            type: "text",
            text: `返回 ${result.rows.length} 行（最大 ${max_rows} 行）`,
          },
        ],
      };
    } catch (error: any) {
      return {
        content: [{ type: "text", text: `查询错误: ${error.message}` }],
        isError: true,
      };
    }
  }
);

// 注册工具 2: 表结构查询
server.tool(
  "describe_table",
  "查询表的结构信息（列名、类型、约束）",
  {
    table_name: z.string().describe("表名"),
  },
  async ({ table_name }) => {
    // SQL 注入防护：只允许字母数字和下划线
    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table_name)) {
      return {
        content: [{ type: "text", text: "错误：无效的表名" }],
        isError: true,
      };
    }

    const query = `
      SELECT column_name, data_type, is_nullable, column_default
      FROM information_schema.columns
      WHERE table_name = $1
      ORDER BY ordinal_position
    `;

    try {
      const result = await db.query(query, [table_name]);
      if (result.rows.length === 0) {
        return {
          content: [{ type: "text", text: `表 "${table_name}" 不存在` }],
          isError: true,
        };
      }
      return {
        content: [
          { type: "text", text: JSON.stringify(result.rows, null, 2) },
        ],
      };
    } catch (error: any) {
      return {
        content: [{ type: "text", text: error.message }],
        isError: true,
      };
    }
  }
);

// 注册资源：数据库连接状态
server.resource(
  "db_status",
  "db://status",
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify({
          connected: true,
          host: process.env.DB_HOST,
          database: process.env.DB_NAME,
          timestamp: new Date().toISOString(),
        }),
      },
    ],
  })
);

// 启动 Server
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Database MCP Server running on stdio");
}

main().catch(console.error);

// MCP Server 配置（claude_desktop_config.json 示例）
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/xueshuai/projects"],
      "env": {}
    },
    "database": {
      "command": "node",
      "args": ["/path/to/database-mcp-server.js"],
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "myapp",
        "DB_USER": "app_user",
        "DB_PASSWORD": "secret"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "BSA_xxx"
      }
    }
  }
}
// 以上配置让 Claude Desktop 同时拥有：
// - GitHub 仓库管理能力
// - 本地文件系统访问能力
// - 数据库查询能力
// - 网络搜索能力

// MCP Gateway 架构：集中式路由与流量控制
import express from "express";
import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

interface McpGatewayConfig {
  servers: Record<string, {
    url: string;
    auth?: { type: "bearer"; token: string };
    rateLimit?: { requestsPerMinute: number };
    timeout?: number;
  }>;
}

class McpGateway {
  private clients: Map<string, McpClient> = new Map();
  private rateLimiters: Map<string, { count: number; resetAt: number }> = new Map();
  private app = express();

  constructor(private config: McpGatewayConfig) {}

  async initialize() {
    // 连接到所有 MCP Server
    for (const [name, serverConfig] of Object.entries(this.config.servers)) {
      const client = new McpClient({
        name: "mcp-gateway",
        version: "1.0.0",
      });
      const transport = new StreamableHTTPClientTransport(
        new URL(serverConfig.url),
        {
          requestInit: serverConfig.auth
            ? { headers: { Authorization: `Bearer ${serverConfig.auth.token}` } }
            : undefined,
        }
      );
      await client.connect(transport);
      this.clients.set(name, client);
      this.rateLimiters.set(name, { count: 0, resetAt: Date.now() + 60000 });
    }
  }

  // 路由 MCP 工具调用请求
  async handleToolCall(serverName: string, toolName: string, args: any) {
    // 1. 速率限制检查
    const limiter = this.rateLimiters.get(serverName);
    if (!limiter) throw new Error(`Unknown server: ${serverName}`);

    if (Date.now() > limiter.resetAt) {
      limiter.count = 0;
      limiter.resetAt = Date.now() + 60000;
    }
    const serverConfig = this.config.servers[serverName];
    if (serverConfig.rateLimit && limiter.count >= serverConfig.rateLimit.requestsPerMinute) {
      throw new Error(`Rate limit exceeded for ${serverName}`);
    }
    limiter.count++;

    // 2. 工具调用
    const client = this.clients.get(serverName);
    if (!client) throw new Error(`Client not connected: ${serverName}`);

    const startTime = Date.now();
    try {
      const result = await client.callTool(toolName, args, {
        timeout: serverConfig.timeout || 30000,
      });
      const latency = Date.now() - startTime;

      // 3. 记录指标
      console.log(JSON.stringify({
        event: "mcp_tool_call",
        server: serverName,
        tool: toolName,
        latency,
        success: true,
        timestamp: new Date().toISOString(),
      }));

      return result;
    } catch (error: any) {
      console.error(JSON.stringify({
        event: "mcp_tool_call",
        server: serverName,
        tool: toolName,
        error: error.message,
        latency: Date.now() - startTime,
        success: false,
      }));
      throw error;
    }
  }
}

# 生产环境 MCP 部署配置（docker-compose.yml）
version: "3.8"

services:
  # MCP Gateway —— 集中式路由
  mcp-gateway:
    build: ./gateway
    ports:
      - "3000:3000"
    environment:
      - GITHUB_MCP_URL=http://github-mcp:8080
      - DB_MCP_URL=http://db-mcp:8080
      - REDIS_URL=redis://redis:6379
    depends_on:
      - github-mcp
      - db-mcp
      - redis

  # GitHub MCP Server
  github-mcp:
    image: ghcr.io/modelcontextprotocol/servers/github:latest
    environment:
      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN}
    restart: unless-stopped

  # 数据库 MCP Server
  db-mcp:
    build: ./mcp-servers/database
    environment:
      - DB_HOST=postgres
      DB_NAME: app_db
      - DB_USER=readonly_user
      - DB_PASSWORD=${DB_PASSWORD}
    depends_on:
      - postgres

  # Redis 用于速率限制和缓存
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

  # PostgreSQL 数据库
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: app_db
      - POSTGRES_USER=app_admin
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

// MCP 安全中间件：输入验证 + 权限控制 + 审计
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

interface SecurityContext {
  userId: string;
  role: "admin" | "developer" | "viewer";
  allowedTools: string[];
  rateLimit: { maxCalls: number; windowMs: number };
}

// 安全审计日志
function auditLog(ctx: SecurityContext, tool: string, args: any, result: any) {
  console.log(JSON.stringify({
    timestamp: new Date().toISOString(),
    userId: ctx.userId,
    role: ctx.role,
    tool,
    args: sanitizeArgs(args), // 脱敏处理
    success: !result.isError,
    resultSize: JSON.stringify(result).length,
  }));
}

// 参数脱敏
function sanitizeArgs(args: any): any {
  const sensitive = ["password", "token", "secret", "api_key"];
  const sanitized = { ...args };
  for (const key of sensitive) {
    if (key in sanitized) {
      sanitized[key] = "*REDACTED*";
    }
  }
  return sanitized;
}

// 权限检查装饰器
function requireRole(allowed: SecurityContext["role"][]) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    descriptor.value = async function (ctx: SecurityContext, ...args: any[]) {
      if (!allowed.includes(ctx.role)) {
        auditLog(ctx, propertyKey, args, { isError: true });
        return {
          content: [{ type: "text", text: "权限不足" }],
          isError: true,
        };
      }
      return original.call(this, ctx, ...args);
    };
    return descriptor;
  };
}

// 速率限制装饰器
function rateLimit(maxCalls: number, windowMs: number) {
  const calls = new Map<string, { count: number; resetAt: number }>();
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    descriptor.value = async function (ctx: SecurityContext, ...args: any[]) {
      const key = ctx.userId;
      const now = Date.now();
      const limiter = calls.get(key) || { count: 0, resetAt: now + windowMs };

      if (now > limiter.resetAt) {
        limiter.count = 0;
        limiter.resetAt = now + windowMs;
      }
      limiter.count++;
      calls.set(key, limiter);

      if (limiter.count > maxCalls) {
        return {
          content: [{ type: "text", text: "速率限制：请稍后重试" }],
          isError: true,
        };
      }
      return original.call(this, ctx, ...args);
    };
    return descriptor;
  };
}

// 防止提示词注入的工具包装器
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

class SecureToolWrapper {
  private server: McpServer;
  // 常见的提示词注入模式
  private injectionPatterns = [
    /ignores+(previous|all)s+(instructions|rules)/i,
    /systems*:s*/i,
    /yous+ares+now/i,
    /news+instructions/i,
    /disregard/i,
    /override/i,
    /forgets+your/i,
  ];

  constructor(server: McpServer) {
    this.server = server;
  }

  checkForInjection(input: string): { safe: boolean; risk: string } {
    for (const pattern of this.injectionPatterns) {
      if (pattern.test(input)) {
        return { safe: false, risk: `检测到注入模式: ${pattern.source}` };
      }
    }
    return { safe: true, risk: "" };
  }

  // 安全调用工具：先检查注入，再执行
  async safeCallTool(
    toolName: string,
    args: Record<string, string>
  ): Promise<any> {
    // 检查所有字符串参数
    for (const [key, value] of Object.entries(args)) {
      if (typeof value === "string") {
        const check = this.checkForInjection(value);
        if (!check.safe) {
          console.warn(`[SECURITY] ${toolName}.${key}: ${check.risk}`);
          return {
            content: [
              {
                type: "text",
                text: "请求被安全系统拦截，请检查输入内容",
              },
            ],
            isError: true,
          };
        }
      }
    }
    // 通过检查，正常调用
    return this.server.callTool(toolName, args);
  }
}

// MCP Apps：在 Agent 界面中渲染交互式 UI
// 这是 2026 年 MCP 最令人兴奋的新特性

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

const server = new McpServer({
  name: "dashboard-mcp",
  version: "1.0.0",
});

// 返回交互式仪表盘而非纯文本
server.tool(
  "show_metrics_dashboard",
  "显示系统性能仪表板",
  {
    timeRange: z.enum(["1h", "24h", "7d", "30d"]).default("24h"),
  },
  async ({ timeRange }) => {
    const metrics = await fetchMetrics(timeRange);

    // MCP 2026 新特性：返回交互式 UI 组件
    return {
      content: [
        {
          type: "resource",
          resource: {
            uri: "mcp://dashboard/metrics",
            mimeType: "application/vnd.mcp.app+json",
            text: JSON.stringify({
              type: "dashboard",
              title: "系统性能指标",
              timeRange,
              widgets: [
                {
                  type: "line_chart",
                  title: "CPU 使用率",
                  data: metrics.cpu,
                  unit: "%",
                },
                {
                  type: "bar_chart",
                  title: "API 请求量",
                  data: metrics.requests,
                  unit: "req/s",
                },
                {
                  type: "gauge",
                  title: "内存使用",
                  value: metrics.memory,
                  unit: "%",
                  thresholds: { warning: 70, critical: 90 },
                },
                {
                  type: "table",
                  title: "服务状态",
                  columns: ["服务", "状态", "延迟", "错误率"],
                  rows: metrics.services.map((s: any) => [
                    s.name,
                    s.healthy ? "✅" : "❌",
                    `${s.latency}ms`,
                    `${s.errorRate}%`,
                  ]),
                },
              ],
            }),
          },
        },
      ],
    };
  }
);

// MCP Apps 让 Agent 从"聊天机器人"进化为"交互式应用平台"
// 用户不再只是阅读文本，而是可以与数据直接交互

// 2026 年 MCP 生态概览
{
  "official_servers": [
    "@modelcontextprotocol/server-github",
    "@modelcontextprotocol/server-filesystem",
    "@modelcontextprotocol/server-postgres",
    "@modelcontextprotocol/server-brave-search",
    "@modelcontextprotocol/server-puppeteer",
    "@modelcontextprotocol/server-slack",
    "@modelcontextprotocol/server-google-drive",
    "@modelcontextprotocol/server-git"
  ],
  "community_highlights": {
    "total_servers": 1000,
    "categories": {
      "databases": ["mysql", "mongodb", "redis", "elasticsearch"],
      "apis": ["stripe", "salesforce", "hubspot", "jira", "notion"],
      "tools": ["docker", "kubectl", "terraform", "ansible"],
      "media": ["spotify", "youtube", "s3", "cloudinary"]
    }
  },
  "platform_support": {
    "anthropic_claude": "原生支持 (2024.11)",
    "openai": "Responses API MCP 支持 (2026.01)",
    "google_gemini": "Workspace MCP 集成 (2026.02)",
    "microsoft_copilot": "Windows Agentic MCP (2026.01)",
    "amazon_q": "AWS MCP 连接器 (2026.02)"
  },
  "governance": {
    "owner": "Linux Foundation Agentic AI Foundation",
    "donated": "2025-12",
    "w3c_status": "Community Group (标准制定中)",
    "expected_standard": "2026-2027"
  }
}

// MCP + LangGraph 集成示例
import { createReactAgent } from "@langchain/langgraph/preloaded_agent";
import { ChatAnthropic } from "@langchain/anthropic";
import { McpClient } from "@modelcontextprotocol/sdk/client/mcp.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { tool } from "@langchain/core/tools";

async function buildMcpAgent() {
  // 1. 连接 MCP Server
  const transport = new StdioClientTransport({
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-github"],
    env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN! },
  });
  const mcpClient = new McpClient({
    name: "github-agent",
    version: "1.0.0",
  });
  await mcpClient.connect(transport);

  // 2. 将 MCP 工具转换为 LangChain 工具
  const toolsList = await mcpClient.listTools();
  const langchainTools = toolsList.tools.map((t) =>
    tool(
      async (input) => {
        const result = await mcpClient.callTool(t.name, JSON.parse(input));
        return JSON.stringify(result.content);
      },
      {
        name: t.name,
        description: t.description,
        schema: t.inputSchema,
      }
    )
  );

  // 3. 创建 Agent
  const model = new ChatAnthropic({
    model: "claude-sonnet-4-20250514",
    temperature: 0,
  });

  const agent = createReactAgent({
    llm: model,
    tools: langchainTools,
    promptTemplate: "你是一个 GitHub 助手，可以帮助用户管理仓库。",
  });

  return agent;
}

// 使用
// const agent = await buildMcpAgent();
// const result = await agent.invoke({
//   input: "帮我查看 openclaw 仓库最近的 Issue",
// });

// MCP 故障排查检查清单
interface McpHealthCheck {
  serverName: string;
  checks: HealthCheck[];
}

interface HealthCheck {
  name: string;
  fn: () => Promise<{ pass: boolean; detail: string }>;
}

async function runHealthChecks(
  config: McpHealthCheck
): Promise<HealthReport> {
  const report: HealthReport = { server: config.serverName, results: [] };

  for (const check of config.checks) {
    try {
      const result = await check.fn();
      report.results.push({ check: check.name, ...result });
    } catch (error: any) {
      report.results.push({
        check: check.name,
        pass: false,
        detail: error.message,
      });
    }
  }

  return report;
}

interface HealthReport {
  server: string;
  results: { check: string; pass: boolean; detail: string }[];
}

// 使用示例
const report = await runHealthChecks({
  server: "github-mcp",
  checks: [
    {
      name: "进程运行中",
      fn: async () => ({
        pass: await isProcessRunning("github-mcp"),
        detail: "PID 检查",
      }),
    },
    {
      name: "协议初始化",
      fn: async () => {
        const resp = await mcpClient.initialize();
        return {
          pass: resp.protocolVersion === "2024-11-05",
          detail: `协议版本: ${resp.protocolVersion}`,
        };
      },
    },
    {
      name: "工具列表可获取",
      fn: async () => {
        const tools = await mcpClient.listTools();
        return {
          pass: tools.tools.length > 0,
          detail: `发现 ${tools.tools.length} 个工具`,
        };
      },
    },
    {
      name: "工具调用正常",
      fn: async () => {
        const result = await mcpClient.callTool("get_user_profile", {});
        return {
          pass: !result.isError,
          detail: result.isError ? "调用失败" : "调用成功",
        };
      },
    },
  ],
});

console.log(`MCP 健康报告: ${report.server}`);
for (const r of report.results) {
  console.log(`  ${r.pass ? "✅" : "❌"} ${r.check}: ${r.detail}`);
}