MCP深挖 · 11问

const gw = new MCPServer("enterprise-gateway");

// 包装内部 REST API
gw.addTool({
  name: "get_customer",
  description: "获取客户详情，已知 customer_id 时使用...",
  handler: async ({ customer_id }) => {
    return await fetch(`http://crm/api/customers/${customer_id}`);
  }
});

// 包装内部 gRPC
gw.addTool({
  name: "get_orders",
  description: "获取客户订单列表...",
  handler: async ({ customer_id }) => {
    return await orderGrpcClient.ListOrders({ customer_id });
  }
});

// Gateway 核心价值：聚合多服务（AI看到1个Tool，背后是3个服务）
gw.addTool({
  name: "get_full_profile",
  description: "获取客户完整画像，含订单和风控评分...",
  handler: async ({ customer_id }) => {
    const [customer, orders, risk] = await Promise.all([
      crmFetch(customer_id),
      orderGrpc.list(customer_id),
      riskGrpc.score(customer_id)
    ]);
    return { customer, orders, risk_score: risk.score };
  }
});

const groups = {
  "客户查询": ["search_customer", "get_customer", "list_contacts"],
  "支付退款": ["get_order", "verify_refund", "issue_refund"],
  "报表分析": ["generate_report", "export_data"],
};

async function getTools(userMsg) {
  const intent = await classifyIntent(userMsg);
  return groups[intent] ?? defaultTools;
}

// 每轮对话前动态设置
mcpClient.setAvailableTools(await getTools(userInput));

用户："上海今天天气怎么样？"
         │
         ▼
【你的代码】把 用户消息 + Tool定义 发给 AI 模型
         │
         ▼
【AI 模型】分析后输出结构化 JSON（只是"表达意图"，不是执行）:
  {
    "type": "tool_use",
    "name": "get_weather",
    "input": { "city": "上海" }
  }
         │
         ▼  ← ✋ AI 在此停止，等待结果
【你的代码】读取 JSON，执行真实操作:
  result = weather_api.query("上海")
  → 返回: { temp: 22, weather: "晴" }
         │
         ▼
【你的代码】把结果传回给 AI（作为 tool_result）
         │
         ▼
【AI 模型】生成最终自然语言回答:
  "上海今天晴天，气温 22°C，适合出行。"

{
  // 部分 1：自然语言 description（AI 的核心强项）
  "name": "search_customer",
  "description": "当用户需要按姓名/邮件查找客户时使用。
    [何时不用] 如果已知 customer_id，用 get_customer 更精确、更快。
    [副作用] 只读，不修改任何数据。
    [失败处理] 无匹配结果时返回空数组，而非报错。",

  // 部分 2：JSON Schema（AI 训练数据中大量出现的规范格式）
  "parameters": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "搜索关键词，支持姓名/邮件/手机号，最少2个字符"
      },
      "limit": {
        "type": "integer",
        "default": 20,
        "maximum": 100
      }
    },
    "required": ["query"]   // AI 知道这意味着"必须提供"
  }
}

POST /v1/cust/src
{ "q": "张三", "pg": 1 }

AI 看到这个会想：
→ "cust" 是 customer 吗？"src" 是 search 还是 source？
→ "q" 是 query 吗？"pg" 是 page 吗？
→ 这个接口有副作用吗？会修改数据吗？
→ 什么时候应该调这个而不是另一个接口？

全部是猜测，无法确定。语义在文档里、在开发者脑子里，不在接口本身。