基于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请求），并将结果再翻译回通用格式返回。这样做有几个决定性优势：

1. 一次开发，多处使用：我为Stripe写一个MCP服务器，只要AI客户端（如Claude Desktop、Cursor、Windsurf）支持MCP，它就能立即使用这个服务器，无需为每个客户端重写一遍集成代码。
2. 安全边界清晰：MCP服务器运行在用户指定的环境（通常是本地或受信任的服务器），API密钥等敏感信息永远不会离开这个环境。AI客户端只是发送指令和接收结果，它本身不持有密钥。这比把密钥直接交给云端AI服务要安全得多。
3. 能力标准化：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 fetchGraphQL<T>(query: string, variables?: any): Promise<T> { 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): Promise<Issue[]> { 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): Promise<Issue> { 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查询设计与分页

1. 字段选择：GraphQL要求你显式指定需要返回的字段。为AI设计查询时，要思考哪些字段对分析和回答问题是关键的（如标题、状态、负责人、创建时间），避免请求过多无用数据。
2. 分页处理：Linear的GraphQL API使用基于游标（cursor）的分页。上面的getIssues例子只取了第一页（first: 50）。在生产级工具中，你需要实现递归或循环来获取所有数据。一个常见的模式是提供一个getAllIssues方法，内部自动处理分页，但对AI暴露一个简单的“获取所有问题”的工具。这简化了AI的使用逻辑。
3. 错误处理：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的视角：

1. 说明用途：这个工具是干什么的？（“获取问题列表”）
2. 说明适用场景：在什么情况下使用它？（“适用于快速查看待办事项...”）
3. 解释参数：在描述中或通过zod的.describe()方法，清晰地说明每个参数的意义和格式。例如，issueId需要说明是“Linear问题的唯一ID”。
4. 使用自然语言：避免技术黑话，用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包抽象了最常见的几种模式：

1. 静态API密钥/令牌：如Stripe、Linear。最简单，直接将密钥作为环境变量传入。关键点：必须在服务器启动时验证密钥有效性，避免启动后首次调用才失败。
2. OAuth 2.0 (授权码模式)：如Google Workspace、Notion。这涉及用户登录授权流程。oauth-core包提供了CLI助手（cli/login，cli/logout）和令牌管理逻辑。服务器启动时，会检查本地是否存在有效的刷新令牌，如果没有，则引导用户通过CLI完成OAuth流程。安全核心：刷新令牌被安全地存储在本地（如使用keytar库），访问令牌在内存中短期缓存并自动刷新。
3. 多地域/多租户支持：如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 服务器启动失败或连接错误

5.2 AI无法识别或错误调用工具

5.3 数据返回格式问题

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适配器。