Files

2026-03-05 21:27:11 +08:00

3.9 KiB

Raw Blame History

name, version, description

name	version	description
mcp-builder	1.1.0	构建 MCP Server，让 LLM 通过 Tool 与外部服务交互。当需要创建 MCP 工具或封装 API 为 MCP 时使用。推荐 TypeScript + MCP SDK。

MCP Server 开发指南

触发条件

用户需要构建自定义 MCP Server 以封装 API 或服务为 LLM 可调用的 Tool。

执行流程

Phase 1：研究与规划

1.1 理解目标 API

梳理目标服务的 API 端点、认证方式、数据模型
使用 WebFetch 或 WebSearch 获取 API 文档
列出需要封装的端点，按优先级排序（最常用操作优先）

1.2 学习 MCP 协议

加载 MCP 规范：

起始页：https://modelcontextprotocol.io/sitemap.xml
获取特定页面时添加 .md 后缀获取 Markdown 格式

加载 MCP SDK 文档：

WebFetch: https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md
SDK 名称虽含 "typescript"，但完全支持纯 TypeScript 项目

1.3 设计 Tool

设计原则	说明
命名清晰	使用 `prefix_action_target` 格式，如 `github_create_issue`
描述精准	简洁说明功能 + 参数含义 + 返回值结构
错误可操作	错误信息应引导 LLM 找到解决方案
结果聚焦	返回精准、相关的数据，支持分页/过滤
API 覆盖优先	不确定时优先提供全面的 API 覆盖，而非少量高层 Workflow Tool

Phase 2：实现

推荐技术栈：

语言：TypeScript（MCP SDK 原生支持，无需编译，直接运行）
传输：远程服务用 Streamable HTTP（无状态 JSON），本地用 stdio

2.1 项目结构

mcp-server-{{name}}/
├── src/
│   ├── index.ts           # Server entry + tool registration
│   ├── client.ts          # API client with auth
│   └── tools/             # One file per tool group
│       ├── resources.ts
│       └── actions.ts
├── package.json
└── README.md

2.2 基础设施

实现共享工具：

API Client（认证、请求头、Base URL）
错误处理 Helper（统一格式，包含 actionable 信息）
响应格式化（JSON 结构化 + 文本摘要）
分页支持

2.3 Tool 实现

每个 Tool 需要：

输入 Schema（Zod）：

Zod 在纯 TypeScript 中同样可用，提供运行时参数校验
包含约束和清晰的字段描述
在 description 中添加示例值

输出 Schema（推荐定义）：

使用 outputSchema + structuredContent 返回结构化数据

Tool 注解：

readOnlyHint: 是否只读
destructiveHint: 是否有破坏性
idempotentHint: 是否幂等

Phase 3：审查与测试

3.1 代码质量检查

无重复代码（DRY）
一致的错误处理
关键函数和参数有 JSDoc 注释
清晰的 Tool 描述

3.2 测试

# 直接运行验证语法
node src/index.ts

# 使用 MCP Inspector 交互式测试
npx @modelcontextprotocol/inspector

Phase 4：集成到项目

将构建好的 MCP Server 注册到 .cursor/mcp.json：

{
  "mcpServers": {
    "{{name}}": {
      "command": "node",
      "args": ["path/to/mcp-server-{{name}}/src/index.ts"],
      "env": {
        "API_KEY": "{{env_var}}"
      }
    }
  }
}

验证

node src/index.ts 启动无错误
MCP Inspector 可以列出所有 Tool
每个 Tool 的输入 Schema 有 Zod 校验
每个 Tool 的 description 清晰、包含参数说明
错误信息包含具体的修复建议（actionable）
需要分页的 Tool 支持 cursor/limit 参数
环境变量用于凭证/密钥，不硬编码
.cursor/mcp.json 注册正确

Tier 3 参考资料（按需读取）

references/mcp_best_practices.md — MCP 最佳实践指南
references/node_mcp_server.md — TypeScript/Node.js 实现详细指南

3.9 KiB Raw Blame History Unescape Escape