MCP 2.0 协议深度解析：AI Agent 互联互通的「USB-C 接口」

/**
 * MCP 2.0 Server 实现示例
 * 展示动态工具发现、安全沙箱、多模态支持
 */
import { McpServer, ToolDefinition, ResourceDefinition } from '@anthropic/mcp-sdk';

// 创建 MCP Server
const server = new McpServer({
  name: "github-enhanced",
  version: "2.0.0",
  capabilities: {
    tools: { listChanged: true },  // 支持动态工具发现
    resources: { subscribe: true }, // 支持资源订阅
    prompts: {},
  },
});

// 定义工具（带权限声明）
server.tool({
  name: "create_issue",
  description: "在 GitHub 仓库中创建 Issue",
  inputSchema: {
    type: "object",
    properties: {
      owner: { type: "string", description: "仓库所有者" },
      repo: { type: "string", description: "仓库名称" },
      title: { type: "string", description: "Issue 标题" },
      body: { type: "string", description: "Issue 内容" },
      labels: { type: "array", items: { type: "string" } },
    },
    required: ["owner", "repo", "title"],
  },
  // MCP 2.0: 权限声明
  permissions: {
    level: "read-write",
    scope: ["github:issues:write"],
    requiresConfirmation: true,  // 需要用户确认
  },
  // MCP 2.0: 安全沙箱配置
  sandbox: {
    networkAllow: ["api.github.com"],
    timeout: 30000,  // 30秒超时
    maxRetries: 2,
  },
  handler: async (params, context) => {
    const { owner, repo, title, body, labels } = params;

    // 执行 GitHub API 调用
    const result = await context.github.issues.create({
      owner, repo, title, body, labels,
    });

    return {
      content: [
        { type: "text", text: `Issue #${result.data.number} created: ${result.data.html_url}` },
      ],
      // MCP 2.0: 结构化元数据
      metadata: {
        issueNumber: result.data.number,
        url: result.data.html_url,
        createdAt: result.data.created_at,
      },
    };
  },
});

// 定义资源（可订阅的数据源）
server.resource({
  name: "repository_info",
  uri: "github://repo/{owner}/{repo}/info",
  description: "获取仓库的基本信息",
  mimeType: "application/json",
  handler: async (uri, params) => {
    const { owner, repo } = params;
    const info = await fetch(`https://api.github.com/repos/${owner}/${repo}`);
    return {
      contents: [{ uri: uri.toString(), mimeType: "application/json", text: JSON.stringify(info) }],
    };
  },
});

// MCP 2.0: 动态工具注册（运行时添加新工具）
server.onInitialized(async () => {
  // 根据配置动态注册工具
  const enabledFeatures = await getEnabledFeatures();
  for (const feature of enabledFeatures) {
    server.registerTool(createToolForFeature(feature));
  }
  // 通知所有连接的 Client 工具列表已变化
  server.notifyToolsListChanged();
});

// 启动 Server
server.start({ transport: "stdio" });

/**
 * 完整的 MCP 2.0 Server 示例
 * 功能：安全的数据库查询（只读）、表结构发现、数据可视化
 */
import { McpServer } from '@anthropic/mcp-sdk';
import { Pool } from 'pg';

const dbPool = new Pool({
  host: process.env.DB_HOST,
  database: process.env.DB_NAME,
  user: process.env.DB_USER,
  password: process.env.DB_PASSWORD,
  max: 5,  // 限制连接数
  idleTimeoutMillis: 30000,
});

const server = new McpServer({
  name: "postgres-analytics",
  version: "1.0.0",
  capabilities: {
    tools: {},
    resources: { subscribe: true },
  },
});

// 工具 1: 执行只读 SQL 查询
server.tool({
  name: "query",
  description: "执行只读 SQL 查询，返回结果表格",
  inputSchema: {
    type: "object",
    properties: {
      sql: { type: "string", description: "SELECT 查询语句" },
      params: { type: "array", items: { type: "string" }, description: "参数化查询参数" },
      limit: { type: "number", description: "最大返回行数 (默认 100)" },
    },
    required: ["sql"],
  },
  permissions: { level: "read-only", scope: ["db:select"] },
  sandbox: {
    networkAllow: [process.env.DB_HOST!],
    timeout: 10000,
  },
  handler: async ({ sql, params, limit = 100 }) => {
    // 安全检查：只允许 SELECT
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return { content: [{ type: "text", text: "❌ 只允许 SELECT 查询" }], isError: true };
    }

    const result = await dbPool.query(sql, params);
    const rows = result.rows.slice(0, limit);

    // 返回表格格式
    const headers = Object.keys(rows[0] || {});
    const table = [
      headers.join(" | "),
      headers.map(() => "---").join(" | "),
      ...rows.map(row => headers.map(h => String(row[h])).join(" | ")),
    ].join("\n");

    return {
      content: [
        { type: "text", text: `查询结果 (${result.rowCount} 行):\n\n${table}` },
      ],
      metadata: { rowCount: result.rowCount, columns: headers },
    };
  },
});

// 工具 2: 获取表结构
server.tool({
  name: "describe_table",
  description: "获取数据库表的结构信息",
  inputSchema: {
    type: "object",
    properties: {
      table: { type: "string", description: "表名" },
    },
    required: ["table"],
  },
  permissions: { level: "read-only", scope: ["db:metadata"] },
  handler: async ({ table }) => {
    const result = await dbPool.query(`
      SELECT column_name, data_type, is_nullable, column_default
      FROM information_schema.columns
      WHERE table_name = $1 ORDER BY ordinal_position
    `, [table]);

    return {
      content: [{
        type: "text",
        text: `表 ${table} 的结构:\n${JSON.stringify(result.rows, null, 2)}`,
      }],
    };
  },
});

// 资源: 可订阅的数据库统计信息
server.resource({
  name: "db_stats",
  uri: "postgres://stats",
  description: "数据库实时统计信息（活跃连接、查询速率等）",
  mimeType: "application/json",
  handler: async () => {
    const stats = await dbPool.query("SELECT count(*), state FROM pg_stat_activity GROUP BY state");
    return {
      contents: [{
        uri: "postgres://stats",
        mimeType: "application/json",
        text: JSON.stringify({ connections: stats.rows, timestamp: new Date().toISOString() }),
      }],
    };
  },
});

server.start({ transport: "stdio" });