基于MCP协议构建AI助手业务工具适配器：从原理到实践

1. 项目概述用MCP协议为AI助手装上“业务之眼”如果你和我一样日常开发中需要频繁地在Stripe看支付数据、在Sentry查线上错误、在Notion里翻文档、在Linear跟进任务状态那你一定懂那种在十几个浏览器标签页和不同SaaS平台间反复横跳的疲惫感。更别提当你想让AI助手比如Claude、Cursor的AI帮你分析业务数据时它只能对着你粘贴的零散截图或文本“盲猜”因为它没有直接访问这些业务系统的“眼睛”和“手”。这就是我投入大量时间构建和维护MCP Pool这个开源项目的初衷。简单来说它是一个精心挑选、统一构建的Model Context Protocol (MCP) 服务器集合。MCP是Anthropic提出的一种协议旨在为AI模型提供安全、结构化的方式来访问外部工具和数据。而MCP Pool里的每一个“服务器”本质上就是一个适配器它把某个流行SaaS如Stripe、Notion的API翻译成了AI助手能理解并安全调用的“工具”。想象一下你现在可以直接在Claude Desktop里问“我们上个月在Stripe的MRR月度经常性收入是多少环比增长如何” 或者 “把Sentry里过去24小时最高频的错误摘要发给我。” AI助手能直接调用背后的MCP服务器获取实时数据并基于这些数据进行分析和回答。这不再是科幻场景而是通过MCP Pool就能实现的日常工作流。它弥合了AI聊天界面与我们每日依赖的业务工具之间的鸿沟让自然语言提问能获得由实时数据支撑的真实答案。2. 核心设计思路为什么是“协议”“适配器”模式在深入代码之前理解我们选择MCP协议作为基石的原因至关重要。这决定了整个项目的架构走向和长期价值。2.1 为什么是Model Context Protocol (MCP)在MCP出现之前让AI使用外部工具主要有几种方式一是为特定AI产品如ChatGPT Plugins开发专用插件但这种方式被平台绑定一旦平台策略变化或你想换用其他AI模型如Claude、本地部署的Llama插件就失效了。二是通过复杂的提示词工程和函数调用Function Calling描述让AI去调用一个你预先定义好的API但这需要你在每次对话中“教”AI这个函数怎么用并且安全性和权限控制是个大难题。MCP协议优雅地解决了这些问题。它定义了一套与AI模型解耦的标准通信方式。你可以把MCP服务器想象成一个智能网关或翻译官。AI模型客户端只需要知道如何说MCP这种“通用语言”而MCP服务器则负责将通用指令翻译成具体的API调用如Stripe API的HTTP请求并将结果再翻译回通用格式返回。这样做有几个决定性优势一次开发多处使用我为Stripe写一个MCP服务器只要AI客户端如Claude Desktop、Cursor、Windsurf支持MCP它就能立即使用这个服务器无需为每个客户端重写一遍集成代码。安全边界清晰MCP服务器运行在用户指定的环境通常是本地或受信任的服务器API密钥等敏感信息永远不会离开这个环境。AI客户端只是发送指令和接收结果它本身不持有密钥。这比把密钥直接交给云端AI服务要安全得多。能力标准化MCP协议明确定义了“工具”Tools、“资源”Resources、“提示词模板”Prompts等概念。这意味着所有遵循MCP的服务器都以一种可预测的方式向AI暴露能力AI更容易学习和可靠地使用它们。因此选择基于MCP构建就是选择了一个开放、安全且具有互操作性的未来。我们的工作重心从“让某个AI能用某个API”变成了“为这个API构建一个标准的MCP适配器”。2.2 MCP Pool的架构哲学模块化与一致性有了MCP这个“协议层”我们需要决定如何组织代码。市面上已有的SaaS API成千上万如果每个MCP服务器都从零开始会存在大量重复劳动比如处理OAuth授权、错误重试、日志记录、配置加载等。因此MCP Pool采用了Monorepo单体仓库 共享核心库的架构。项目根目录是一个使用npm workspaces的Monorepo。packages/目录下包含了所有独立的MCP服务器包如stripe-mcp,notion-mcp以及一个非常关键的共享包oauth-core。这个设计体现了“一致性优先”的原则。oauth-core这是项目的“基石”。它封装了OAuth 2.0授权流程授权码模式、客户端凭证模式等和静态令牌认证的通用逻辑。当你要新增一个支持OAuth的SaaS服务如Google Workspace时绝大部分认证相关的代码都可以直接复用这个包你只需要提供该服务的特定配置如授权端点、令牌端点、作用域。这极大地降低了开发新服务器的门槛并保证了所有服务器在认证行为上的一致性和安全性。独立的服务器包每个SaaS服务对应一个独立的npm包。它们结构高度统一通常包含src/index.ts服务器入口点负责初始化MCP服务器注册工具。src/services/这里是“翻译官”的核心。我们在这里封装目标SaaS的官方SDK或直接调用其REST/GraphQL API。这一层的目的是将复杂的、面向开发的API封装成一组更简洁、更符合AI操作直觉的函数。例如将Stripe API中分页、参数复杂的list调用封装成一个简单的getAllSubscriptions函数。src/tools/这里定义MCP“工具”。每个工具对应一个AI可以调用的功能。工具定义包括名称、描述、输入参数JSON Schema和执行函数。执行函数会调用services/层封装好的方法。这里的描述description至关重要它是AI理解这个工具能做什么、该如何使用的“说明书”需要写得清晰、准确。src/common/存放类型定义、工具函数和配置加载逻辑。这种架构确保了项目的可扩展性和可维护性。想要支持新的SaaS服务基本上就是“复制-粘贴-修改”一个现有服务器包的模式然后专注于实现其特有的services和tools。3. 深度实操从零构建一个MCP服务器以Linear为例理论讲得再多不如亲手实现一个。让我们以添加对Linear一个流行的项目管理工具的支持为例走一遍完整的开发流程。我会穿插大量在开发MCP Pool过程中积累的“踩坑”经验和优化技巧。3.1 环境准备与项目初始化首先确保你的环境符合要求。项目要求Node.js 20我强烈建议使用nvm来管理Node版本项目根目录下的.nvmrc文件已经指定了版本。# 克隆项目并安装依赖 git clone https://github.com/vineethkrishnan/mcp-pool.git cd mcp-pool nvm use # 自动切换到.nvmrc指定的Node版本 npm install现在我们要创建一个新的MCP服务器包。虽然你可以手动创建文件夹和文件但最有效率的方法是复制一个现有结构清晰的包作为模板。stripe-mcp或notion-mcp都是很好的起点。# 复制stripe-mcp作为linear-mcp的模板 cp -r packages/stripe packages/linear cd packages/linear # 更新包名和描述 # 需要手动修改 package.json 里的 name, description 等字段实操心得善用模板与脚本在实际开发中我后来为项目添加了一个简单的脚手架脚本scripts/create-mcp-server.js。你只需要运行npm run create-mcp-server linear它就会自动完成创建目录、复制模板文件、更新包名和基础配置等一系列重复工作。对于需要频繁添加新服务的项目花一点时间编写这类自动化脚本能极大提升效率。3.2 核心实现Service层与Tool层这是最核心的两步。我们以Linear的GraphQL API为例。第一步实现Service层 (src/services/linearService.ts)Linear提供了官方的JavaScript SDK但为了保持项目依赖的轻量和一致性MCP Pool更倾向于直接使用fetch调用其GraphQL端点。我们需要创建一个服务类封装所有对Linear API的调用。// src/services/linearService.ts import type { Issue, Team, Project, User } from ./types; // 需要自己定义GraphQL返回的类型 export class LinearService { private apiToken: string; private graphqlEndpoint https://api.linear.app/graphql; constructor(apiToken: string) { this.apiToken apiToken; } private async fetchGraphQLT(query: string, variables?: any): PromiseT { const response await fetch(this.graphqlEndpoint, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${this.apiToken}, // Linear 推荐显式设置 API 版本 Linear-API-Version: 2024-10-15, }, body: JSON.stringify({ query, variables }), }); if (!response.ok) { const errorBody await response.text(); throw new Error(Linear API error: ${response.status} ${errorBody}); } const result await response.json(); // GraphQL 错误在 errors 字段中 if (result.errors) { throw new Error(Linear GraphQL error: ${JSON.stringify(result.errors)}); } return result.data as T; } // 封装一个获取所有Issue的工具方法 async getIssues(teamId?: string, state?: string, first: number 50): PromiseIssue[] { const query query GetIssues($teamId: String, $state: String, $first: Int) { issues(filter: { team: { id: { eq: $teamId } }, state: { name: { eq: $state } } }, first: $first) { nodes { id title description state { name } assignee { name displayName } team { name } createdAt updatedAt } } } ; const variables { teamId, state, first }; const data await this.fetchGraphQL{ issues: { nodes: Issue[] } }(query, variables); return data.issues.nodes; } // 封装一个根据ID获取特定Issue的方法 async getIssueById(issueId: string): PromiseIssue { const query query GetIssue($issueId: String!) { issue(id: $issueId) { id title description state { name } assignee { name displayName } team { name } createdAt updatedAt comments { nodes { body createdAt user { name } } } } } ; const data await this.fetchGraphQL{ issue: Issue }(query, { issueId }); return data.issue; } // 更多方法getTeams, getProjects, createIssue, updateIssueStatus... }注意事项GraphQL查询设计与分页字段选择GraphQL要求你显式指定需要返回的字段。为AI设计查询时要思考哪些字段对分析和回答问题是关键的如标题、状态、负责人、创建时间避免请求过多无用数据。分页处理Linear的GraphQL API使用基于游标cursor的分页。上面的getIssues例子只取了第一页first: 50。在生产级工具中你需要实现递归或循环来获取所有数据。一个常见的模式是提供一个getAllIssues方法内部自动处理分页但对AI暴露一个简单的“获取所有问题”的工具。这简化了AI的使用逻辑。错误处理GraphQL即使部分查询成功也可能返回errors字段。必须检查并处理这个字段而不是只检查HTTP状态码。第二步定义Tool层 (src/tools/index.ts)Service层是给开发者用的Tool层是给AI用的。我们需要把Service层的方法“包装”成MCP协议定义的Tool。// src/tools/index.ts import { LinearService } from ../services/linearService; import { z } from zod; // MCP Pool使用zod进行参数验证 export function getLinearTools(service: LinearService): ServerTool[] { return [ { name: linear_get_issues, description: 从Linear工作区获取问题Issues列表。可以按团队和状态进行筛选。适用于快速查看待办事项、进行中的任务或已完成的工作。, inputSchema: z.object({ teamId: z.string().optional().describe(Linear团队ID。如果未提供则返回所有团队的问题。), state: z.string().optional().describe(问题状态名称例如 Todo, In Progress, Done。), first: z.number().optional().default(50).describe(返回的问题数量默认50。), }), handler: async ({ teamId, state, first }) { const issues await service.getIssues(teamId, state, first); // 将数据格式化为对AI友好的文本或结构化内容 return { content: [ { type: text, text: 找到 ${issues.length} 个问题\n issues.map(issue - [#${issue.id}] ${issue.title} (状态: ${issue.state.name}, 负责人: ${issue.assignee?.displayName || 无})).join(\n), }, ], }; }, }, { name: linear_get_issue_details, description: 根据问题ID获取Linear中某个特定问题的详细信息包括描述、评论历史等。适用于深入分析某个具体任务或故障。, inputSchema: z.object({ issueId: z.string().describe(Linear问题的唯一ID。), }), handler: async ({ issueId }) { const issue await service.getIssueById(issueId); return { content: [ { type: text, text: 问题详情${issue.title}\n状态${issue.state.name}\n描述${issue.description || 无}\n最近评论${issue.comments?.nodes?.[0]?.body || 无}, }, ], }; }, }, // 可以继续添加更多工具如 linear_create_issue, linear_update_status... ]; }核心技巧Tool描述的“艺术”Tool的description字段是AI理解和使用工具的关键。写描述时要站在AI的视角说明用途这个工具是干什么的“获取问题列表”说明适用场景在什么情况下使用它“适用于快速查看待办事项...”解释参数在描述中或通过zod的.describe()方法清晰地说明每个参数的意义和格式。例如issueId需要说明是“Linear问题的唯一ID”。使用自然语言避免技术黑话用AI和最终用户都能理解的日常语言描述。 一个写得好的描述能显著提升AI调用工具的准确率和可靠性。3.3 集成与配置让服务器跑起来实现了核心逻辑后我们需要将它们集成到MCP服务器的入口点并处理配置。入口点 (src/index.ts)// src/index.ts import { Server } from modelcontextprotocol/sdk/server/index.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { LinearService } from ./services/linearService.js; import { getLinearTools } from ./tools/index.js; // 1. 读取配置。环境变量是MCP服务器的标准配置方式。 const LINEAR_API_KEY process.env.LINEAR_API_KEY; if (!LINEAR_API_KEY) { console.error(错误必须设置 LINEAR_API_KEY 环境变量); process.exit(1); } // 2. 初始化服务和工具 const linearService new LinearService(LINEAR_API_KEY); const tools getLinearTools(linearService); // 3. 创建MCP服务器实例 const server new Server( { name: linear-mcp, version: 0.1.0, }, { capabilities: { tools: {}, // 声明本服务器提供工具 }, } ); // 4. 注册工具 server.setRequestHandler(ListToolsRequestSchema, async () ({ tools: tools.map(tool ({ name: tool.name, description: tool.description, inputSchema: tool.inputSchema, })), })); server.setRequestHandler(CallToolRequestSchema, async (request) { const tool tools.find(t t.name request.params.name); if (!tool) { throw new Error(未知工具: ${request.params.name}); } return await tool.handler(request.params.arguments ?? {}); }); // 5. 启动服务器使用stdio传输这是与Claude Desktop等客户端通信的标准方式 const transport new StdioServerTransport(); await server.connect(transport); console.error(Linear MCP服务器已启动并等待连接...);配置与运行现在用户可以通过环境变量配置并使用这个服务器。以Claude Desktop为例在它的配置文件claude_desktop_config.json中添加{ mcpServers: { linear: { command: npx, args: [-y, vineethnkrishnan/linear-mcp], env: { LINEAR_API_KEY: lin_api_你的Linear密钥 } } } }重启Claude Desktop后你就可以直接问“Claude帮我看看Linear里‘In Progress’状态的任务有哪些” AI会自动识别并调用linear_get_issues工具获取数据后给你清晰的回答。4. 进阶主题安全、性能与工程化实践构建一个可用的MCP服务器是第一步但要将其纳入像MCP Pool这样的生产级集合还需要考虑更多。4.1 认证与安全不仅仅是API密钥不同的SaaS服务认证方式各异。MCP Pool通过oauth-core包抽象了最常见的几种模式静态API密钥/令牌如Stripe、Linear。最简单直接将密钥作为环境变量传入。关键点必须在服务器启动时验证密钥有效性避免启动后首次调用才失败。OAuth 2.0 (授权码模式)如Google Workspace、Notion。这涉及用户登录授权流程。oauth-core包提供了CLI助手cli/logincli/logout和令牌管理逻辑。服务器启动时会检查本地是否存在有效的刷新令牌如果没有则引导用户通过CLI完成OAuth流程。安全核心刷新令牌被安全地存储在本地如使用keytar库访问令牌在内存中短期缓存并自动刷新。多地域/多租户支持如Datadog有US、EU等站点、PagerDuty。我们在配置中引入site或region参数并在Service层根据这个参数动态构建API端点URL。安全红线在任何情况下MCP服务器的代码都绝不能硬编码或日志记录任何认证信息。所有密钥、令牌都必须通过环境变量或安全的配置管理服务传入。这是项目CI中安全扫描Trivy, CodeQL重点检查的部分。4.2 性能优化与稳健性当AI助手进行复杂分析时可能会链式调用多个工具每个工具又可能涉及多次API请求。性能与稳定性变得重要。请求节流与缓存对于频繁访问且变化不频繁的数据如团队列表、项目列表可以在Service层实现简单的内存缓存TTL缓存。同时要尊重SaaS服务的速率限制实现请求队列或退避重试机制。例如在fetchGraphQL方法中增加指数退避重试逻辑。错误处理与用户反馈API调用可能因网络、权限、参数错误等失败。Tool的handler必须包含完善的try-catch并将错误信息转化为对AI和用户友好的消息返回而不是直接抛出堆栈跟踪。例如“无法从Linear获取数据认证失败请检查API密钥是否有效且未过期。”流式响应支持MCP协议支持服务器端事件SSE可以流式传输长内容。这对于返回大量数据如所有客户列表或长时间运行的操作如导出报告非常有用。MCP Pool的路线图中已包含此特性。4.3 项目的工程化基石CI/CD与质量守护观察MCP Pool的GitHub仓库你会发现一套成熟的自动化工作流这是项目保持高质量和可协作的关键。自动化测试 (CI)每个服务器包都必须有单元测试和集成测试如果可行。根目录的npm test会运行所有包的测试。测试不仅要覆盖成功路径更要覆盖错误处理、边界情况。我们使用Jest作为测试框架。代码质量与一致性使用ESLint进行代码检查Prettier进行自动格式化。npm run lint:check和npm run format:check确保所有贡献者的代码风格一致。这减少了代码审查时的噪音。依赖安全扫描通过GitHub的Dependabot和定期的Trivy扫描及时发现并修复依赖中的安全漏洞。自动化发布使用release-please工具。当有符合Conventional Commits规范如feat:,fix:的提交合并到main分支时它会自动创建版本标签、更新CHANGELOG并触发npm发布流程。这实现了语义化版本控制和发布日志的自动化管理。文档即代码项目使用Docusaurus构建独立的文档网站。文档与代码在同一仓库任何API或功能的更改都需要同步更新文档。npm run docs:start可以本地启动文档服务器方便编写和预览。5. 常见问题与排查实录在实际开发和用户使用中会遇到一些典型问题。这里记录下最常遇到的几个及其解决方法。5.1 服务器启动失败或连接错误问题现象可能原因排查步骤与解决方案Claude Desktop提示“无法连接MCP服务器”或直接无响应。1.Node.js版本不匹配项目要求20。2.全局依赖冲突使用npx时本地或全局有损坏的包。3.命令路径错误Claude配置中的command或args不正确。1. 在项目根目录运行node --version确认版本。使用nvm use。2. 尝试清除npm缓存npm cache clean --force。直接使用本地路径测试node ./packages/linear/dist/index.js看服务器能否独立启动。3. 仔细检查claude_desktop_config.json确保args中的包名正确如果是本地开发可以用“command”: “node”, “args”: [“/绝对路径/to/your/mcp-pool/packages/linear/dist/index.js”]进行测试。服务器启动但立即退出控制台报错“Missing API Key”。环境变量未正确设置。1. 确认在Claude配置的env对象中正确设置了密钥变量如LINEAR_API_KEY。2. 变量名必须与服务器代码中读取的如process.env.LINEAR_API_KEY完全一致注意大小写。3.重启Claude Desktop。环境变量通常在启动时加载修改配置后必须重启客户端。5.2 AI无法识别或错误调用工具问题现象可能原因排查步骤与解决方案向AI提问后AI回复“我不知道如何操作”或没有调用工具的意图。1.工具描述不清晰AI无法从description理解工具的用途。2.Claude Desktop未加载新配置。1.优化Tool的description。用更自然、场景化的语言重写明确说明工具做什么、何时用。参考项目中现有优秀工具的描述。2. 重启Claude Desktop确保新配置生效。有时需要完全退出再重新打开。AI尝试调用工具但参数错误导致服务器返回错误。1.参数Schema定义太宽松或太严格。2.AI对参数的理解有偏差。1.严格定义输入Schema。使用zod的.describe()为每个参数添加清晰说明。对于枚举值如状态使用z.enum([‘Todo’, ‘In Progress’])进行限制。2. 在Tool的handler中增加更健壮的前置验证并提供更友好的错误信息反馈给AI帮助它修正参数。5.3 数据返回格式问题问题现象可能原因排查步骤与解决方案AI收到了数据但表示“无法解析”或回答混乱。从handler返回的content格式对AI不友好。可能是一大段未格式化的JSON或信息过载。精心设计返回内容。MCP支持返回text和image类型。对于列表数据不要直接返回JSON字符串。应该像前面的例子一样格式化为清晰的、带项目符号的文本摘要。对于复杂数据可以考虑返回一个简短的文本摘要同时附上一个结构化的JSON块作为text的一部分供AI需要时深入提取。原则是先给人看再给机器读。返回数据量巨大导致响应慢或AI上下文超限。查询未加限制返回了成千上万条记录。1.在工具中设置合理的默认分页如first: 50。2.提供筛选参数如state,teamId,createdAfter让AI或用户能够缩小查询范围。3. 对于“获取所有X”这类工具内部实现分页获取但返回时先给出总数和摘要并提示“如需详情请指定更精确的筛选条件”。5.4 开发与调试技巧独立测试服务器在集成到AI客户端前先独立运行你的MCP服务器进行测试。你可以写一个简单的测试脚本模拟MCP客户端发送ListToolsRequest和CallToolRequest。这能快速验证核心逻辑是否正确。启用调试日志在服务器代码中对于关键步骤如收到请求、调用API、返回结果添加console.error输出注意MCP协议中console.log输出到stdio可能会干扰通信所以用console.error是更安全的选择。这些日志会在Claude Desktop的运行日志或你独立运行服务器的终端中看到是排查问题的利器。利用TypeScript和Zod严格的类型定义和运行时验证能避免大量低级错误。确保你的Service方法返回类型准确Tool的inputSchema定义完备。这不仅能提高代码质量也能让AI在参数传递上更有“把握”。构建和维护MCP Pool的过程是一个不断在“AI的抽象世界”和“API的具体细节”之间搭建桥梁的过程。每一个新的MCP服务器都像是为AI助手解锁了一个新的专业领域。看到用户能够用一句简单的自然语言完成过去需要多次点击、查询和复制的复杂操作这种成就感是驱动项目持续迭代的最大动力。如果你也对用技术消除工具间的隔阂感兴趣非常欢迎你查看项目源码、使用现有的服务器或者按照贡献指南为你常用的工具添加一个MCP适配器。