用 MCP 减少多客户端的重复集成
文章以三个 AI 客户端接入数据库、容器日志、工单和本地 Git 为例,说明如何通过 MCP 的 JSON-RPC 2.0 接口,让不同客户端发现并调用同一套工具。
AI 深度解读
给 Cursor、Claude Desktop 和内部 CLI 接同一批工具时,最容易重复写的是适配层。Anthropic 的 Model Context Protocol(MCP)把工具发现、参数描述和调用约定统一起来。团队可以把内部能力封装成 MCP 服务,再由兼容的客户端接入。
原文用一个 TypeScript 停机率计算示例串起了从握手到执行的流程。对前端和全栈开发者,最实用的是看懂客户端怎么知道「能调用什么、该传什么」,以及哪些检查仍要自己在服务端实现。
12 份集成是怎么来的
假设团队有 4 套内部系统要接入 AI 助手:用于检查表结构的预发 PostgreSQL、用于排查容器崩溃的 Kubernetes Pod 日志、用于归纳工单的 Jira,以及用于查看差异的本地 Git 工作区。前端开发用 Cursor,架构师用 Claude Desktop,运维用内部 CLI agent。按原文设定,如果每种组合都要单独写适配,就有 4 × 3 = 12 份。
MCP 把这类集成从 M × N 改成 M + N:每套内部系统接到协议的服务端一侧,每种 AI 环境接到客户端一侧。以 Git 为例,读取 diff 的实现可以集中在一个 MCP 服务里。接入新客户端时,团队主要处理客户端配置和兼容性,复用服务端已有的工具定义。
这个算式描述的是适配代码的复用。每个客户端还要连接到服务端,服务端也要拿到访问内部系统所需的权限。
客户端怎么知道工具能接收什么参数
原文用 JSON-RPC 2.0 展示客户端与服务端的消息,并列举了标准输入输出(stdio)和 Server-Sent Events(SSE)两种传输方式。下面的 initialize 请求用来交换协议版本和客户端身份。
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"clientInfo": { "name": "cursor", "version": "1.0.0" }
}
}
protocolVersion 是双方要协商的协议版本,和 clientInfo.version 表示的客户端版本各有用途。示例中的 postgres-inspector 服务端版本也是 1.0.0,它在响应里声明 tools.listChanged: true 和 resources.subscribe: true,表示支持工具列表变更通知和资源订阅。原文的小标题提到三种原语,正文实际展开了工具发现,并在握手响应里展示了资源订阅能力。
接下来,客户端用 id: 2 发出 tools/list。服务端列出 explain_query,并通过 inputSchema 声明 query 是必填字符串,工具说明写的是运行 PostgreSQL 的 EXPLAIN ANALYZE。客户端由此知道怎样组织参数。至于这条 SQL 能否安全运行,要由服务端根据语句和数据库权限判断。
一个 TypeScript 工具怎么从声明走到执行
原文用官方 @modelcontextprotocol/sdk 实现了 calculate_uptime。这段代码让同一个进程既能回答「有哪些工具」,也能接收停机分钟数并返回可用率。
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
// 1. Initialize Server Metadata
const server = new Server(
{ name: 'devscampus-system-tools', version: '1.0.0' },
{ capabilities: { tools: {} } }
);
// 2. Register Available Tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
{
name: 'calculate_uptime',
description: 'Calculates system SLA uptime percentage from incident minutes',
inputSchema: {
type: 'object',
properties: {
downtimeMinutes: { type: 'number', description: 'Minutes of outage in a 30-day month' },
},
required: ['downtimeMinutes'],
},
},
],
}));
// 3. Handle Tool Execution
server.setRequestHandler(CallToolRequestSchema, async (request) => {
if (request.params.name === 'calculate_uptime') {
const minutes = Number(request.params.arguments?.downtimeMinutes ?? 0);
const totalMinutes = 30 * 24 * 60; // 43,200 min in a month
const uptimePct = (((totalMinutes - minutes) / totalMinutes) * 100).toFixed(4);
return {
content: [
{
type: 'text',
text: `SLA Uptime: ${uptimePct}% (${minutes} minutes of downtime out of ${totalMinutes} total minutes)`,
},
],
};
}
throw new Error(`Tool not found: ${request.params.name}`);
});
// 4. Start Server on stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);
看 Number(request.params.arguments?.downtimeMinutes ?? 0) 这一行:工具定义把 downtimeMinutes 标成必填,处理函数却在缺参时按 0 分钟计算,会给出 100.0000%。示例统一按 30 天,也就是 30 * 24 * 60 得到的 43,200 分钟计算,用 toFixed(4) 保留四位小数。
最后两行把服务接到 stdio,stdout 要留给 JSON-RPC 消息。如果往里面写 console.log("Debug info"),客户端可能把调试文字当成协议数据解析。内部日志可以用 console.error() 写到 stderr。
我的判断
原文对适配成本的分析成立,尤其适合多个 AI 客户端确实要共享一批工具的团队。12 份集成是推演出来的示例,作者没有提供迁移前后的工时、故障率或跨客户端测试结果。接入能省多少事,仍是经验判断。只有一个内部 agent、工具也很少时,直接用现有框架的工具接口,可能更省配置和部署成本。
我会把这份 TypeScript 示例当作理解协议的起点。参数形状由 inputSchema 描述,业务边界还得在执行处检查。文件服务可以用 path.resolve() 处理路径,再验证目标落在获准目录内。原文也建议对 DROP TABLE、git push --force 这类操作保留人工确认。团队采用这一建议时,需要实际检查所用客户端的确认行为,并在服务端落实写权限。原文没有展示这些检查的实现。
能拿来做什么
- 如果 Cursor 和内部 CLI 都需要查看 Git diff,可以先把这一项做成只读 MCP 工具,用两个客户端分别验证发现、参数传递和结果展示,再决定是否迁移其余适配。
- 如果用 Node 和 TypeScript 复刻
calculate_uptime,在处理函数里拒绝缺参、非有限数字、负数和超过 43,200 的值,再按团队实际采用的 SLA 周期确定分母。 - 如果本地工具用
StdioServerTransport接入 AI 编辑器,把调试日志统一写到 stderr。客户端能启动进程却列不出工具时,先检查 stdout 是否混入启动日志。