mcp-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

MCP Server Development Guide

MCP Server 开发指南

Build high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services.

构建高质量的MCP（Model Context Protocol）服务器，使LLM能够与外部服务进行交互。

Core Design Principles

核心设计原则

Build for Workflows, Not Just APIs

为工作流而非单纯API构建

Principle	Why
Consolidate operations	Single tool for complete tasks
Return high-signal data	Agents have limited context
Provide format options	"concise" vs "detailed" modes
Use human-readable IDs	Not technical codes
Make errors actionable	Guide toward correct usage

Key concept: Don't just wrap API endpoints. Design tools that enable complete workflows agents actually need.

原则	原因
整合操作	单个工具完成完整任务
返回高信号数据	Agent的上下文有限
提供格式选项	"简洁"与"详细"模式
使用人类可读ID	而非技术编码
提供可操作的错误信息	引导正确使用方式

核心概念：不要仅仅封装API端点。要设计能支持Agent实际所需完整工作流的工具。

Development Phases

开发阶段

Phase 1: Research

第一阶段：调研

Step	Action
Study MCP Protocol	Read `modelcontextprotocol.io/llms-full.txt`
Study SDK docs	Python or TypeScript SDK README
Study target API	Read ALL available documentation
Create implementation plan	Before writing code

步骤	操作
学习MCP协议	阅读 `modelcontextprotocol.io/llms-full.txt`
学习SDK文档	Python或TypeScript SDK的README
研究目标API	阅读所有可用文档
创建实现计划	编写代码前完成

Phase 2: Design

第二阶段：设计

Decision	Options
Language	Python (FastMCP) or TypeScript
Tool granularity	Atomic vs workflow-oriented
Response format	JSON, Markdown, or both
Error handling	What errors can occur, how to recover

决策项	选项
开发语言	Python（FastMCP）或TypeScript
工具粒度	原子化 vs 面向工作流
响应格式	JSON、Markdown或两者兼具
错误处理	可能出现的错误及恢复方式

Phase 3: Implementation

第三阶段：实现

Component	Purpose
Input validation	Pydantic (Python) or Zod (TypeScript)
Tool descriptions	Clear, with examples
Error messages	Include suggested next steps
Response formatting	Consistent across tools

组件	用途
输入验证	使用Pydantic（Python）或Zod（TypeScript）
工具描述	清晰且附带示例
错误信息	包含建议的下一步操作
响应格式化	所有工具保持一致

Phase 4: Testing

第四阶段：测试

Critical: MCP servers are long-running processes. Never run directly in main process.

Approach	How
Evaluation harness	Recommended
tmux session	Run server separately
Timeout wrapper	`timeout 5s python server.py`
MCP Inspector	Official debugging tool

重点提示：MCP服务器是长期运行的进程。切勿直接在主进程中运行。

方法	操作方式
评估工具集	推荐使用
tmux会话	单独运行服务器
超时包装器	`timeout 5s python server.py`
MCP Inspector	官方调试工具

Tool Annotations

工具注解

Annotation	Meaning	Default
readOnlyHint	Doesn't modify state	false
destructiveHint	Can cause damage	true
idempotentHint	Repeated calls safe	false
openWorldHint	Interacts externally	true

Key concept: Annotations help the LLM decide when and how safely to use tools.

注解	含义	默认值
readOnlyHint	不修改状态	false
destructiveHint	可能造成损坏	true
idempotentHint	重复调用安全	false
openWorldHint	与外部交互	true

核心概念：注解帮助LLM判断何时以及如何安全使用工具。

Input Design

输入设计

Validation Patterns

验证模式

Pattern	Use Case
Required fields	Core parameters
Optional with defaults	Convenience parameters
Enums	Limited valid values
Min/max constraints	Numeric bounds
Pattern matching	Format validation (email, URL)

模式	使用场景
必填字段	核心参数
带默认值的可选字段	便捷参数
枚举类型	有限的有效值
最小/最大值约束	数值范围
模式匹配	格式验证（邮箱、URL）

Parameter Naming

参数命名

Good	Bad	Why
`user_email`	`e`	Self-documenting
`limit`	`max_results_to_return`	Concise but clear
`include_archived`	`ia`	Descriptive boolean

良好示例	不良示例	原因
`user_email`	`e`	自文档化
`limit`	`max_results_to_return`	简洁且清晰
`include_archived`	`ia`	描述性布尔值

Response Design

响应设计

Format Options

格式选项

Format	Use Case
JSON	Programmatic use, structured data
Markdown	Human readability, reports
Hybrid	JSON in markdown code blocks

格式	使用场景
JSON	程序化使用、结构化数据
Markdown	人类可读性、报告
混合格式	Markdown代码块中的JSON

Response Guidelines

响应指南

Guideline	Why
~25,000 token limit	Context constraints
Truncate with indicator	Don't silently cut
Support pagination	`limit` and `offset` params
Include metadata	Total count, has_more

指南	原因
~25,000 tokens限制	上下文约束
截断时添加标识	不要静默截断
支持分页	`limit` 和 `offset` 参数
包含元数据	总数、是否还有更多数据

Error Handling

错误处理

Error Message Structure

错误消息结构

Element	Purpose
What failed	Clear description
Why it failed	Root cause if known
How to fix	Suggested next action
Example	Correct usage

Key concept: Error messages should guide the agent toward correct usage, not just diagnose problems.

元素	用途
失败内容	清晰描述
失败原因	已知的根本原因
修复方式	建议的下一步操作
示例	正确用法

核心概念：错误消息应引导Agent正确使用，而非仅仅诊断问题。

Quality Checklist

质量检查表

Code Quality

代码质量

Check	Description
No duplicated code	Extract shared logic
Consistent formats	Similar ops return similar structure
Full error handling	All external calls wrapped
Type coverage	All inputs/outputs typed
Comprehensive docstrings	Every tool documented

检查项	描述
无重复代码	提取共享逻辑
格式一致	类似操作返回相似结构
完整错误处理	所有外部调用均被包装
类型覆盖	所有输入/输出均已类型化
全面的文档字符串	每个工具都有文档

Tool Quality

工具质量

Check	Description
Clear descriptions	Model knows when to use
Good examples	In docstring
Sensible defaults	Reduce required params
Consistent naming	Group related with prefixes

检查项	描述
清晰的描述	模型知晓何时使用
优质示例	包含在文档字符串中
合理的默认值	减少所需参数
一致的命名	使用前缀分组相关工具

Best Practices

最佳实践

Practice	Why
One tool = one purpose	Clear mental model
Comprehensive descriptions	LLM selection accuracy
Include examples in docstrings	Show expected usage
Return actionable errors	Enable self-correction
Test with actual LLM	Real-world validation
Version your server	Track compatibility

实践	原因
一个工具对应一个用途	清晰的心智模型
全面的描述	提升LLM选择准确性
在文档字符串中包含示例	展示预期用法
返回可操作的错误	支持自我修正
使用实际LLM测试	真实场景验证
为服务器版本化	跟踪兼容性

Resources

资源

MCP Protocol: https://modelcontextprotocol.io/
Python SDK: https://github.com/modelcontextprotocol/python-sdk
TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk

MCP协议：https://modelcontextprotocol.io/
Python SDK：https://github.com/modelcontextprotocol/python-sdk
TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk