MCP Server Boilerplate
MCP 服务器样板
一个最小化、文档齐全的 MCP (Model Context Protocol) 服务器实现,旨在作为构建自定义 MCP 服务器的可重用基准。
什么是 MCP?
模型上下文协议 (MCP) 是一种标准化协议,使 AI 助手能够与外部服务器进行交互。MCP 服务器可以提供:
工具 (Tools):AI 可以调用以执行操作的函数
资源 (Resources):AI 可以读取的静态或动态数据
提示词 (Prompts):用于一致性 AI 交互的可重用提示词模板
Related MCP server: MCP Mingdao
特性
此样板提供:
最小化结构:易于扩展的简洁基准
详尽文档:内联注释和独立的文档文件
架构图:展示组件交互的 Mermaid 图表
扩展指南:服务器增长的最佳实践
类型提示:完整的类型注解,以获得更好的 IDE 支持
Async/await:用于并发操作的非阻塞 I/O
可重用提示词模板
提示词是可重用的模板,允许您定义带有占位符的结构化提示词。它们支持:
一致性:在不同 AI 交互中标准化提示词格式
参数化:通过参数进行动态内容插入
可重用性:定义一次,使用多次,并传入不同输入
类型安全:定义带有验证的参数模式
提示词模板包含:
名称:提示词的唯一标识符
描述:提示词的功能说明
参数:使用提示词时可以填充的可选参数
示例用例:
具有可配置严重级别的代码审查模板
具有可自定义语气的文档生成
具有不同关注领域的分析提示词
具有不同输出格式的报告生成
项目结构
windsurf-project-3/
├── mcp_server.py # Main server implementation with extensive comments
├── pyproject.toml # Project configuration for uv
├── ARCHITECTURE.md # Architecture documentation with Mermaid diagrams
├── SCALING_GUIDE.md # Scaling patterns and best practices
├── README.md # This file
├── tools/ # Placeholder for tool modules (create as needed)
├── resources/ # Placeholder for resource modules (create as needed)
├── prompts/ # Placeholder for prompt modules (create as needed)
└── utils/ # Placeholder for utility modules (create as needed)安装
本项目使用 uv 进行快速 Python 包管理。
安装 Python 3.10 或更高版本
安装 uv(如果尚未安装):
curl -LsSf https://astral.sh/uv/install.sh | sh安装依赖项:
uv sync快速入门
1. 添加您的第一个工具
编辑 mcp_server.py 并在 list_tools() 函数中添加一个工具:
@app.list_tools()
async def list_tools() -> list[Tool]:
return [
Tool(
name="echo",
description="Echo back the input text",
inputSchema={
"type": "object",
"properties": {
"text": {"type": "string", "description": "Text to echo"}
},
"required": ["text"]
}
)
]2. 实现工具处理程序
在 call_tool() 函数中添加工具逻辑:
@app.call_tool()
async def call_tool(name: str, arguments: Any) -> str:
if name == "echo":
text = arguments.get("text", "")
return f"Echo: {text}"
raise ValueError(f"Unknown tool: {name}")3. 添加提示词(可选)
在 list_prompts() 函数中添加一个提示词:
@app.list_prompts()
async def list_prompts() -> list[Prompt]:
return [
Prompt(
name="example_prompt",
description="An example prompt template",
arguments=[
PromptArgument(
name="topic",
description="The topic to write about",
required=True
)
]
)
]然后在 get_prompt() 中实现处理程序:
@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str] | None) -> str:
if name == "example_prompt":
topic = arguments.get("topic") if arguments else None
if not topic:
raise ValueError("Argument 'topic' is required")
return f"Write a detailed explanation about {topic}."
raise ValueError(f"Unknown prompt: {name}")3. 运行服务器
uv run python mcp_server.py4. 配置您的 MCP 客户端
将此内容添加到您的 MCP 客户端配置中:
{
"mcpServers": {
"your-server-name": {
"command": "uv",
"args": ["run", "python", "/path/to/mcp_server.py"]
}
}
}文档
ARCHITECTURE.md:详细的架构文档,包含展示以下内容的 Mermaid 图表:
Python 模块及其用途
组件交互
请求流(工具调用、资源读取)
使用的设计模式
SCALING_GUIDE.md:扩展服务器的最佳实践:
模块化模式
状态管理策略
错误处理模式
日志记录和监控
配置管理
测试策略
性能优化
安全注意事项
代码结构
主服务器文件 (mcp_server.py) 分为以下几个部分:
服务器初始化:创建 MCP 服务器实例
工具注册:定义可用工具
工具处理程序:实现工具执行逻辑
资源注册:定义可用资源
资源处理程序:实现资源读取逻辑
入口点:通过 stdio 通信启动服务器
每个部分都包含详尽的内联注释,解释每个组件的用途和用法。
扩展点
添加工具
在
list_tools()中定义工具及其模式在
call_tool()中实现处理程序对于大型项目,移动到
tools/目录下的独立模块中
添加提示词
在
list_prompts()中定义带有参数的提示词在
get_prompt()中实现处理程序对于大型项目,移动到
prompts/目录下的独立模块中
添加资源
在
list_resources()中定义带有元数据的资源在
read_resource()中实现处理程序对于大型项目,移动到
resources/目录下的独立模块中
添加实用工具
将共享代码提取到 utils/ 目录中:
验证函数
日志记录助手
配置管理
错误处理实用程序
作为基准使用
此样板旨在被复制并修改以用于新项目:
复制整个项目目录
在
pyproject.toml中重命名项目在
mcp_server.py中更新服务器名称添加您的工具、资源和提示词
根据需要自定义文档
使用的 Python 模块
mcp.server.Server:主 MCP 服务器类mcp.types.Tool:工具类型定义mcp.types.Resource:资源类型定义mcp.types.Prompt:提示词类型定义mcp.types.PromptArgument:提示词参数类型定义mcp.server.stdio:Stdio 通信流asyncio:用于并发操作的 Async/awaittyping:用于代码清晰度的类型提示
有关每个模块的详细说明,请参阅 ARCHITECTURE.md。
开发
运行测试
# Run with pytest (add tests first)
uv run pytest代码风格
本项目使用 Python 类型提示并遵循 PEP 8 规范。建议使用:
ruff进行代码检查mypy进行类型检查
添加依赖项
uv add <package-name>故障排除
导入错误:运行
uv sync安装依赖项服务器无响应:检查 MCP 客户端配置
类型错误:确保已安装 Python 3.10+
找不到 uv 命令:从 https://github.com/astral-sh/uv 安装 uv
资源
许可证
此样板按“原样”提供,仅供教育和开发使用。请随意将其用于您的项目并进行修改。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Maintenance
Related MCP Connectors
A MCP server built for developers enabling Git based project management with project and personal…
MCP server for developer documentation, generated by doc2mcp.
MCP server for developers documentation, generated by doc2mcp.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA basic MCP server template that provides a foundation for building custom tools, resources, and prompts. Serves as a starting point for developers to create their own MCP server functionality.-

MCP Mingdaoofficial
AlicenseNot gradedqualityDmaintenanceA minimal MCP server template demonstrating basic tools, resources, and prompts functionality built with Smithery SDK.ISC- FlicenseNot gradedqualityDmaintenanceA template/starter project for building MCP servers with structured directories for tools, prompts, and resources that are automatically discovered and registered.5-
- FlicenseNot gradedqualityDmaintenanceA boilerplate template for developing Model Context Protocol (MCP) servers, providing a structured framework for defining tools, resources, and prompts.-