参考MCP服务器
使用FastMCP的远程HTTP MCP服务器的干净、最少的参考实现。这个项目展示了使用现代Python工具构建MCP服务器是多么简单。
ˇ突破
整个MCP服务器基本上是 10行代码:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("Reference Server", stateless_http=True)
@mcp.tool()
def hello_world(message: str) -> str:
"""Say hello to the world"""
return f"Hello, {message}!"
if __name__ == "__main__":
mcp.run(transport="streamable-http")That's it! FastMCP handles HTTP server setup, MCP protocol implementation, routing, error handlingeverything.
=€ Quick Start
Prerequisites
- Python 3.11+
- uv (recommended) or pip
Installation
# Clone or create the project
git clone
cd reference-mcp-server
# Install dependencies with uv (recommended)
uv sync
# Or with pip
pip install -e .Running the Server
# Default: streamable-http transport on localhost:8000
uv run python -m reference_mcp.server
# Or use the installed script
uv run reference-mcp-server
# Use SSE transport instead
MCP_TRANSPORT=sse uv run reference-mcp-server=运输方式
此参考服务器支持以下两种MCP传输类型：
流式HTTP（默认）
- 现代化、高效的交通
- 新实现的默认选项
- 在流媒体中使用HTTP/1.1
- 更好的性能和可靠性
# Explicit streamable-http
MCP_TRANSPORT=streamable-http uv run reference-mcp-server服务器发送事件（SSE）
- 回退传输以实现兼容性
- 对服务器发送的事件使用HTTP
- 更广泛的客户支持
# Use SSE transport
MCP_TRANSPORT=sse uv run reference-mcp-server='配置
服务器使用环境变量进行配置：
| 变量 | 默认值 | 描述 |
|---|---|---|
MCP_TRANSPORT | streamable-http | 运输类型： sse 或 streamable-http |
MCP_HOST | localhost | 服务器主机（用于文档） |
MCP_PORT | 8000 | 服务器端口（用于文档） |
创建一个 .env 示例中的文件：
cp .env.example .env
# Edit .env with your preferences=集成示例
克劳德桌面
添加到您的Claude Desktop配置中：
{
"mcpServers": {
"reference-server": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/reference-mcp-server",
"reference-mcp-server"
]
}
}
}使用mcp远程适配器
真正的功能来自mcp远程适配器，它处理兼容性：
{
"mcpServers": {
"reference-server": {
"command": "mcp-remote",
"args": ["http://localhost:8000"]
}
}
}码头工人
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install uv && uv sync
EXPOSE 8000
CMD ["uv", "run", "reference-mcp-server"]="开发
项目结构
reference-mcp-server/
�� pyproject.toml # Modern Python packaging
�� README.md # This file
�� .env.example # Environment template
�� src/
�� reference_mcp/
�� __init__.py
�� server.py # Main server (the magic 10 lines!)
�� config.py # Configuration handling
�� examples/
�� configuration/ # Integration examples添加新工具
只需添加更多 @mcp.tool() 装饰功能：
@mcp.tool()
def greet_user(name: str, greeting: str = "Hello") -> str:
"""Greet a user with a custom greeting"""
return f"{greeting}, {name}! Welcome to our MCP server!"
@mcp.tool()
def calculate_sum(numbers: list[int]) -> int:
"""Calculate the sum of a list of numbers"""
return sum(numbers)FastMCP自动处理：
- 使用Pydantic进行类型验证
- 用于工具发现的JSON模式生成
- 错误处理和响应
- HTTP路由和MCP协议
运行测试
# Start the server
uv run reference-mcp-server &
# Test the hello_world tool (example with curl)
curl -X POST http://localhost:8000/tools/call \
-H "Content-Type: application/json" \
-d '{"tool": "hello_world", "arguments": {"message": "World"}}'关键设计决策
为什么选择FastMCP？
- 零样板：无需手动设置HTTP服务器
- 完全符合MCP：自动处理协议
- 类型安全性：内置Pydantic验证
- 双重运输：SSE和可流式传输的http支持
- 生产就绪：Uvicorn驱动的HTTP服务器
为什么是无状态HTTP？
- 简洁：不需要会话管理
- 可扩展性：易于负载平衡和缩放
- 可靠性：没有要丢失的连接状态
- mcp远程兼容性：与适配器完美配合
为什么两种运输方式？
- 流式HTTP：现代、高效、首选
- SSE: Fallback for broader compatibility
- Future-proof: Supports both current and legacy clients
=Ú What This Demonstrates
This reference implementation proves that building MCP servers can be:
- Stupidly Simple: 10 lines for a complete server
- Well-Architected: Modern tooling, clean structure
- Production Ready: Real HTTP server, proper error handling
- Highly Compatible: Works with all MCP client implementations
=. Next Steps
Use this as a template for:
- Custom MCP servers: Add your domain-specific tools
- Learning MCP: Understand the protocol without complexity
- Prototyping: Quick proof-of-concepts for new tools
- Production services: Scale up with additional tools and logic
The revolution is that MCP servers are no longer complex infrastructure projectsthey're just Python functions with decorators.
\<× Architecture Notes
This server leverages:
- FastMCP: Complete MCP server framework
- Uvicorn: Production ASGI server
- Pydantic: Automatic validation and schemas
- mcp-remote compatibility: Works with adapter out of the box
The combination means you get enterprise-grade MCP servers with toy-project simplicity.
______________________________________________________________________
*Built with d as part of Project Alpha*