# MCP 服务器开发人员用于 Claude 桌面集成的模型上下文协议 (MCP) 服务器的专家实施。该技能为使用 TypeScript 构建生产就绪的 MCP 服务器提供了全面的指导，包括架构设计、端点实现、数据库集成、遥测跟踪和通过 npx 进行分发。 ## 核心能力 ### 1\. MCP服务器架构 * **脚手架生成**：具有正确 MCP 协议结构的 TypeScript 项目设置 * **服务器配置**：MCP 协议合规性、JSON-RPC 处理、stdio 传输 * **端点设计**：遵循 MCP 规范的 RESTful 风格资源和工具端点 * **类型安全**：请求、响应和模式的严格 TypeScript 类型 * **错误处理**：通过正确的 MCP 错误响应进行全面的错误捕获 ### 2\.数据库集成 * **D1 SQLite 设置**：针对边缘部署优化的架构设计 * **查询优化**：所有数据库操作的延迟目标<500ms * **FTS5 搜索**：用于模型发现的全文搜索实现 * **数据建模**：具有适当索引的高效表结构 * **迁移脚本**：版本控制的模式演变 ### 3\.遥测与分析 * **事件跟踪**：安装、使用和性能指标的结构化日志记录 * **延迟监控**：带有百分位数跟踪的请求计时（p50、p95、p99） * **用户分析**：没有 PII 的尊重隐私的使用模式 * **错误报告**：用于调试的结构化错误日志记录 * **成功指标**：WAU（每周活跃用户）和参与度跟踪 ### 4\. NPX分布 * **包配置**：package.json 包含用于 npx 执行的正确 bin 条目 * **版本管理**：具有变更日志自动化的语义版本控制 * **发布工作流程**：npm 注册表部署与 CI/CD 集成 * **更新策略** ：带有弃用通知的不间断更新 * **安装测试**：跨平台验证（macOS、Windows、Linux） ## 实施指南 ### 第 0 阶段：服务器支架（第 1 周） 1. **初始化 TypeScript 项目** npm 初始化 -y npm install --save-dev typescript @types/node npx tsc --init 2. **MCP 服务器设置** * 安装 MCP SDK：`npm install @modelcontextprotocol/sdk` * 创建服务器入口点（`src/index.ts`） * 实现stdio传输处理程序 * 添加基本资源/工具端点 3. **类型定义** 接口MCP服务器{ 名称：字符串；版本：字符串；资源：资源[]；工具：工具[]； } 接口资源{ uri：字符串；名称：字符串；描述：字符串； mimeType？：字符串； } 界面工具{ 名称：字符串；描述：字符串；输入架构：JSONSchema； } ### 第 1 阶段：核心功能（第 2 周） 1. **数据库架构** 创建表 mental_models ( id 文本主键，代码 TEXT UNIQUE NOT NULL，转换类文本不为空，名称文本不为空，描述文本， use_cases JSON，难度等级 INTEGER，先决条件 JSON, 创建时间 TIMESTAMP 默认 CURRENT_TIMESTAMP ）；使用 fts5 创建虚拟表 models_fts( 代码、名称、描述、用例）； 2. **端点实施** * 获取资源端点（模型列表、转换） * POST工具端点（分析、分解、合成） * 使用符合 MCP 的响应进行错误处理 * 使用 Zod 或类似工具进行输入验证 3. **转换逻辑** * 视角（P）：多视角分析 * 反演（IN）：逆假设映射 * 成分（CO）：积分合成 * 分解（DE）：组件分解 * 递归（RE）：反馈回路识别 * 元系统（SY）：系统间的协调 ### 第 2 阶段：文档和示例（第 3 周） 1. **快速入门指南**（5 分钟设置） # 快速开始 1.通过npx安装： ````bash npx @hummbl/mcp-服务器 2. 配置 Claude Desktop：添加到`claude_desktop_config.json`： { “mcp服务器”：{ “嗡嗡”：{ “命令”：“npx”， “args”：[“@hummbl/mcp-server”] } } } 3.在Claude中测试：“对这个问题使用透视变换：[你的问题]” 2. **可运行示例** * **示例 1**：代码分解分析 * **示例 2**：策略综合与组合 * **示例 3**：利用透视 + 逆向决策 3. **故障排除指南** * 安装失败（权限、npm 配置） * Claude 桌面连接问题 * 延迟/性能问题 * 错误信息参考 ### 第 3 阶段：分发和测试（第 4 周） 1. **NPX 设置** { “名称”：“@hummbl/mcp-server”， “版本”：“1.0.0”， “垃圾箱”：{ "hummbl-mcp": "./dist/index.js" }, “文件”：[“dist”，“README.md”，“许可证”]， “发布配置”：{ “访问”：“公开” } } 2. **CI/CD 管道** * 用于自动化测试的 GitHub Actions * 在发布标签上自动进行 npm 发布 * 跨平台二进制测试 * 文档部署 3. **Beta 测试** * 至少 3-5 名 Beta 测试人员 * 结构化反馈收集 * 性能基准测试 * 边缘情况识别 ## 质量门 ### 功能要求 ✅ * 所有 MCP 端点均正确响应规范 * 数据库查询完成<500ms (p95) * 24小时稳定性测试零崩溃 * 错误处理涵盖所有边缘情况 * 类型安全：100% TypeScript 严格模式 ### 文件要求 ✅ * 快速启动，首次运行时间小于 5 分钟 * 所有示例均无需修改即可运行 * 故障排除涵盖 90% 以上的常见问题 * API参考完整且准确 * 复杂逻辑的内嵌代码注释 ### 收养要求 ✅ * 截至目标日期，每周活跃用户 (WAU) 超过 10 个 * 3+ Beta 测试人员提供积极反馈 * 第 2 周后生产中的 P0 错误为零 * 平均用户评分≥4.0/5.0 * MCP 目录列表已获批准 ## MCP 协议合规性 ### 所需能力 1. **资源**：只读数据访问（模型、转换） 2. **工具**：交互操作（分析、分解、综合） 3. **提示**：预定义的工作流程（阶段 0 可选） ### 传输层 * **stdio** ：Claude Desktop 的标准输入/输出 * **JSON-RPC 2.0** ：所有请求/响应均遵循规范 * **错误代码** ：正确的 HTTP 样式错误代码 ### 安全最佳实践 * 对所有用户提供的数据进行输入清理 * 速率限制以防止滥用 * 未经明确许可不得进行外部网络调用 * 最小权限模型 * 所有操作的审计日志记录 ## 性能优化 ### 延迟目标 * **p50** ：所有端点<100ms * **p95** : <500ms 数据库查询 * **p99** ：复杂转换<1000ms ### 优化策略 1. **数据库** ：对所有经常查询的列建立索引 2. **缓存**：热数据的内存LRU缓存 3. **延迟加载**：仅在需要时加载资源 4. **批量操作** ：将相似的查询分组 5. **连接池**：重用数据库连接 ## 遥测架构接口遥测事件{ event_name: 'mcp_install' | 事件名称: 'mcp_install' | 'mcp_success_run' | 'mcp_success_run' | 'api_call' | 'api_call' | '文档视图'；用户 ID：字符串； // 匿名哈希 ts：字符串； // ISO 8601 元：{ 客户端？：字符串； // 克劳德桌面版版本？：字符串； // MCP服务器版本型号？：字符串； // 例如，“CO4” lat_ms？：数字； // 延迟（以毫秒为单位）端点？：字符串； // 调用的端点状态？：数量； // HTTP 风格的状态码 }; } ## 分发清单 ### 预出版 ✅ * 更新版本号（语义版本控制） * CHANGELOG.md 更新了发行说明 * README.md 经过审查且准确 * 存在许可证文件（麻省理工学院推荐） * package.json元数据完整 * 依赖审计清理（`npmaudit`） * 可接受的捆绑包大小 (<5MB) ### MCP 目录提交 ✅ * 清晰的描述（最多 160 个字符） * 类别选择合适 * 截图/演示已准备 * 记录使用示例 * 提供支持联系方式 ### 出版后✅ * NPM包可通过npx下载 * 使用注释创建 GitHub 版本 * 文档站点已更新 * 发布社区公告 * Beta 测试人员已收到通知 ## 常见陷阱及解决方案 ### 问题：Claude Desktop 未检测到服务器 **解决方案**：验证 stdio 传输是否正确初始化以及 JSON-RPC 响应的格式是否正确。 ### 问题：高延迟（>1 秒） **解决方案**：添加数据库索引，实现缓存，或者优化查询复杂度。 ### 问题：在 Windows 上安装失败 **解决方案**：使用跨平台路径进行测试，避免特定于 shell 的命令，使用 `cross-env` 作为环境变量。 ### 问题：版本之间的重大更改 **解决方案**：严格遵循语义版本控制，保持向后兼容性，提供迁移指南。 ## 示例 ### 示例 1：最小 MCP 服务器从'@modelcontextprotocol/sdk/server/index.js'导入{服务器}；从 '@modelcontextprotocol/sdk/server/stdio.js' 导入 { StdioServerTransport }；常量服务器 = 新服务器({ 名称：'hummbl-mcp-服务器'，版本：'1.0.0'， }, { 能力：{ 资源：{}，工具：{}， }, }); // 注册资源：列出心理模型 server.setRequestHandler('资源/列表', async () => ({ 资源：[ { uri: 'humbl://models', 名称：“心智模型”，描述：'BASE120心智模型合集', mimeType: 'application/json', }, ], })); // 注册工具：通过透视变换进行分析 server.setRequestHandler('工具/调用', async (请求) => { if (request.params.name === '分析视角') { const { text } = request.params.arguments; // 这里是转换逻辑返回{ 内容：[{ 类型：'文本'， text: `透视分析：${text}`, }], }; } }); // 启动服务器 const 传输 = new StdioServerTransport(); 等待服务器.connect(传输); ### 示例 2：数据库集成从“better-sqlite3”导入数据库； const db = new Database('hummbl.db'); // 初始化模式 db.exec(` 如果不存在则创建表 mental_models ( id 文本主键，代码 TEXT UNIQUE NOT NULL，转换类文本不为空，名称文本不为空，描述文本）；如果不存在则创建索引 idx_transformation ON mental_models(transformation_class); `); // 使用准备好的语句进行查询 const getModelsByTransformation = db.prepare(` 从 mental_models 中选择 * 哪里transformation_class = ？按代码订购 `); const viewModels = getModelsByTransformation.all('P'); ### 示例 3：遥测记录函数 logTelemetry(事件：TelemetryEvent) { 常量日志条目 = { ...事件， ts: new Date().toISOString(), }; // 登录到控制台（开发） if (process.env.NODE_ENV === '开发') { console.log(JSON.stringify(logEntry)); } // 发送到分析服务（生产） if (process.env.NODE_ENV === '生产') { // TODO：发送到分析端点 } } // 用法日志遥测（{ event_name: 'api_call', user_id: hashUserId(userId), ts: new Date().toISOString(), 元：{ 端点：'/tools/analyze-perspective', 纬度毫秒：245，状态：200， }, }); ## 资源 * **MCP 规范** : * **MCP SDK** ： * **克劳德桌面配置**： * **TypeScript 最佳实践**： * **NPM 发布指南** ： ## 成功标准 **阶段 0 在以下情况下成功：** 1. ✅ `npx @hummbl/mcp-server` 在任何机器上都能干净地运行 2. ✅ 在目标日期之前每周有超过 10 位开发者使用它 3. ✅ 3 个开箱即用的令人信服的示例 4. ✅ 第 2 周后 P0 错误为零 5. ✅ 明确第一阶段的路径 **阶段 0 失败如果：** 1. ❌ 60 天后用户数<10 → 转向咨询焦点 2. ❌ 前 30 天内出现 >5 个 P0 错误 → 需要进行架构审查_MCP Server Developer v1.1 - 增强版_ ## 🔄 工作流程 > **Kaynak：** [Anthropic MCP SDK 最佳实践]() ### Aşama 1：架构和设置 * **脚手架** ：`npm init` ve TypeScript 配置ayarlarını yap。 * **类型**：资源和工具提示严格模式 ile tanımla。 * **传输** ：Stdio 传输“onerror”处理程序 ile güvenli hale getir。 ### Aşama 2：开发循环 * **热重载** : 重新加载 `nodemon` veya `watch` modunu kullan。 * **Inspector** : `npx @modelcontextprotocol/inspector` 可以调试 yap。 * **日志记录**：结构化日志记录 (JSON) ekle ama stdio'yu kirletme (stderr kullan)。 ### 阿萨玛 3：发布 * **分发**：Paketi `npm`'e veya `npx` ile çalışacak şekilde 发布等。 * **文档**：README.md'ye `claude_desktop_config.json` örneğini ekle。 * **分析**：Anonim kullanım verisi toplama（选择加入）mekanizmasını kur。 ### 控制Noktaları 阿萨马 |多鲁拉马 ---|--- 1 |服务器 hatasız kapanıp（正常关闭）yeniden başlıyor mu？ 2 | `list_tools` çağrısı <100ms içinde cevap veriyor mu？ 3 | Dokümantasyon “复制粘贴” ile çalıştırılabiliyor mu？

Mcp服务器开发人员

包含技能