mcp-server-design

MCP 服务设计

概述

本技能介绍设计 MCP（Model Context Protocol）服务的最佳实践，让它们能够与大模型 Agent 高效协作。核心要点：为 Agent 而非自动化设计。大模型像人一样思考，而不是 API 的调用方。

核心理念

为 Agent 而非自动化设计

传统 API 设计会通过细粒度端点来优化程序化访问。MCP 工具设计则应根据大模型的思考和推理方式进行优化：

• 大模型像人一样思考：它们能够理解意图、上下文和目的
• 工具应面向任务，而非端点：围绕用户想要完成的目标来设计工具
• 减轻认知负担：少量、更有目的性的工具胜过大量细粒度工具

三大支柱

1. 提供所需的一切：提供完整、可执行的信息
2. 减少工作量：尽可能减少完成任务所需的步骤
3. 减少路径：限制大模型需要探索的决策分支

工具设计原则

1. 优先采用专用工具，而非通用封装

反模式：将每个 API 端点都封装为工具

// Bad: Generic database tools
// src/tools/run-sql.ts
// src/tools/list-tables.ts
// src/tools/describe-table.ts

最佳实践：围绕用户任务设计工具

// Good: Task-oriented tools
// src/tools/prepare-database-migration.ts
import { z } from "zod";
import type { ToolMetadata } from "xmcp";

export const schema = {
  description: z.string().describe("What database changes are needed"),
};

export const metadata: ToolMetadata = {
  name: "prepare-database-migration",
  description: "Design a database change with safety checks and reviewed migration plan",
};

// src/tools/analyze-slow-queries.ts
// src/tools/create-backup.ts

2. 尽量减少工具数量

大模型难以处理很长的工具列表。每增加一个工具：

• 都会增加选择时的困惑
• 会为每个请求增加 token
• 会削弱每个工具的用途

指南：

• 从 5-10 个核心工具开始
• 仅在评估表明确有需要时添加工具
• 在合理的情况下合并相关操作

3. 按用途而非实现方式命名工具

工具名称会引导大模型的行为。名称应描述任务，而非实现机制。

不要使用……	使用……
post-slack-message	notify-team
run-sql-query	analyze-data
call-api-endpoint	check-service-status

4. 按任务塑造工具

对于复杂流程，一个任务对应一个工具，胜过一个步骤对应一个工具。

反模式：将部署拆分为原子操作

// Bad: Too many granular tools
// src/tools/create-branch.ts
// src/tools/commit-changes.ts
// src/tools/push-branch.ts
// src/tools/create-pr.ts
// src/tools/run-tests.ts
// src/tools/merge-pr.ts

最佳实践：用单个工具完成整个任务

// src/tools/deploy-changes.ts
import { z } from "zod";
import type { ToolMetadata } from "xmcp";

export const schema = {
  description: z.string().describe("What changes are being deployed"),
  runTests: z.boolean().default(true).describe("Run test suite first"),
  autoMerge: z.boolean().default(false).describe("Auto-merge after tests pass"),
};

export const metadata: ToolMetadata = {
  name: "deploy-changes",
  description: "Deploy current changes through the complete workflow",
};

export default function deployChanges({ description, runTests, autoMerge }) {
  // Handles: branch creation, commit, push, PR, tests, merge
}

决策框架

何时创建新工具

在以下情况下创建新工具：

• 用户经常请求这项特定能力
• 任务的边界和目的明确
• 现有工具无法顺畅完成任务
• 评估表明大模型会为此任务选择错误的工具

在以下情况下不要创建新工具：

• 现有工具只需稍微调整参数就能处理
• 新工具会重复现有功能（应合并）
• 这是罕见的边缘情况（使用现有工具并提供指导来处理）

何时合并操作

在以下情况下，将多个操作合并为一个工具：

• 它们几乎总是一起使用
• 中间结果单独使用时没有价值
• 拆分它们会造成不必要的决策点

在以下情况下，保持操作独立：

• 用户需要精细控制
• 中间结果本身具有独立价值
• 合并后会导致工具过于复杂

平衡粒度

细粒度工具	合并后的工具
灵活性更高	心智模型更简单
选择负担更重	意图更明确
存在误用风险	可定制性较低

快速参考

工具设计检查清单

• 根据用途命名，而非实现方式
• 说明何时使用该工具
• 参数说明清晰
• 响应中包含后续步骤或上下文
• 使用实际的大模型请求进行测试

警示信号

• 单个服务中有超过 15 个工具
• 工具名称采用 HTTP 方法或端点名称
• 声称“无所不能”的通用工具
• 完成单个任务需要多次调用的工具

资源

references/

• design-principles.md - 扩展示例、反模式和真实案例研究

如需深入了解这些概念，请阅读设计原则参考文档。