mcp_best_practices

# MCP 服务器最佳实践 ## 快速参考 ### 服务器命名 - **Python**: `{service}_mcp` (例如 `slack_mcp`) - **Node/TypeScript**: `{service}-mcp-server` (例如 `slack-mcp-server`) ### 工具命名 - 使用带有服务前缀的 snake_case - 格式: `{service}_{action}_{resource}` - 示例: `slack_send_message`, `github_create_issue` ### 响应格式 - 支持 JSON 和 Markdown 格式 - JSON 用于程序化处理 - Markdown 用于人类可读性 ### 分页 - 始终遵守 `limit` 参数 - 返回 `has_more`, `next_offset`, `total_count` - 默认值为 20-50 项 ### 传输 - **Streamable HTTP**: 用于远程服务器、多客户端场景 - **stdio**: 用于本地集成、命令行工具 - 避免使用 SSE（已弃用，转而支持 streamable HTTP） --- ## 服务器命名约定 遵循这些标准化的命名模式： **Python**: 使用格式 `{service}_mcp` (小写，带下划线) - 示例: `slack_mcp`, `github_mcp`, `jira_mcp` **Node/TypeScript**: 使用格式 `{service}-mcp-server` (小写，带连字符) - 示例: `slack-mcp-server`, `github-mcp-server`, `jira-mcp-server` 名称应通用、描述所集成的服务、易于从任务描述中推断，且不包含版本号。 --- ## 工具命名与设计 ### 工具命名 1. **使用 snake_case**: `search_users`, `create_project`, `get_channel_info` 2. **包含服务前缀**: 预见到您的 MCP 服务器可能会与其他 MCP 服务器一起使用 - 使用 `slack_send_message` 而不是仅仅 `send_message` - 使用 `github_create_issue` 而不是仅仅 `create_issue` 3. **面向动作**: 以动词开头 (get, list, search, create 等) 4. **具体化**: 避免可能与其他服务器冲突的通用名称 ### 工具设计 - 工具描述必须狭窄且明确地描述功能 - 描述必须与实际功能精确匹配 - 提供工具注解 (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) - 保持工具操作聚焦且原子化 ## 响应格式 所有返回数据的工具都应支持多种格式： ### JSON 格式 (`response_format="json"`) - 机器可读的结构化数据 - 包含所有可用字段和元数据 - 一致的字段名称和类型 - 用于程序化处理 ### Markdown 格式 (`response_format="markdown"`, 通常为默认) - 人类可读的格式化文本 - 使用标题、列表和格式化以清晰