🚀 Awesome-MCP-Scaffold

生产级 MCP 服务器开发脚手架 - 专为 Cursor IDE 优化的快速开发解决方案

English | 中文

🎯 项目定位

Awesome-MCP-Scaffold 是一个开箱即用的 MCP 服务器开发脚手架，让你能够：

🚀 5分钟启动：从零到运行的完整 MCP 服务器
🤖 10分钟MCP开发：内置提示词和范例，基于 Cursor IDE 一句话完成MCP Server tools开发
🏭 生产级架构：经过验证的高性能部署方案
📚 最佳实践内置：遵循官方 MCP SDK v1.11.0 规范
⭐ outputSchema 支持：所有工具默认支持结构化输出和 JSON Schema 自动生成

✨ 核心优势

🔥 专为 Cursor 优化

智能规则系统：内置用户Rules Cursor_User_Rules.md和 3 套项目 .cursor/rules 配置
AI 代码生成：一句话自动生成 Tools、Resources、Prompts，并自动生成测试用例
上下文感知：AI 助手理解 MCP 开发模式
错误自动修复：智能识别并修复常见问题

⚡ 开箱即用的完整功能

24+ 示例工具：计算器、文本处理、文件操作等，全部支持 outputSchema
结构化响应：所有工具返回 Pydantic 模型，自动生成 JSON Schema
多种资源类型：系统信息、配置数据等
提示模板：代码审查、数据分析等场景
REST API 端点：支持外挂完整的 HTTP API 支持，便于与不支持MCP的平台对接

🏗️ 生产级架构

Streamable HTTP 优先：最新传输协议，3-5倍性能提升
Docker 优化：多进程部署，智能资源管理
负载均衡：Nginx 配置，支持水平扩展
监控集成：Prometheus + Grafana 开箱即用

🚀 5分钟快速开始

1. 克隆脚手架

# 使用脚手架创建新项目
git clone https://github.com/WW-AI-Lab/Awesome-MCP-Scaffold.git my-mcp-server
cd my-mcp-server

# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

2. 启动开发服务器

# 开发模式 (stdio)
python run.py

# HTTP 模式 (推荐)
python run.py --transport streamable-http --port 8000

# 使用 FastMCP CLI
fastmcp dev run.py

3. 验证MCP服务器

# MCP协议测试 - 获取工具列表
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python run.py

# MCP协议测试 - 获取资源列表  
echo '{"jsonrpc":"2.0","id":2,"method":"resources/list"}' | python run.py

# MCP协议测试 - 调用计算器工具
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"calculator","arguments":{"expression":"2+3*4"}}}' | python run.py

# HTTP模式下的MCP端点测试
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

4. 在 Cursor 中开发

打开项目：在 Cursor 中打开项目文件夹
AI 助手激活：Cursor 自动加载 .cursor/rules 配置
开始开发：按 Cmd/Ctrl+K 输入需求，AI 自动生成代码

📁 脚手架结构

awesome-mcp-scaffold/
├── 🎯 核心架构
│   ├── server/                 # MCP 服务器核心
│   │   ├── main.py            # FastMCP 主实例
│   │   ├── config.py          # 配置管理
│   │   ├── tools/             # 工具实现 (12+ 示例)
│   │   ├── resources/         # 资源实现
│   │   ├── prompts/           # 提示模板
│   │   └── routes/            # REST API 路由
│   └── run.py                 # 启动入口
│
├── 🤖 Cursor 集成
│   └── .cursor/rules/         # AI 规则配置
│       ├── mcp-development-guide.mdc
│       ├── streamable-http-production.mdc
│       └── mcp-testing-patterns.mdc
│
├── 🏭 生产部署
│   ├── Dockerfile             # 生产级容器配置
│   ├── docker-compose.yml     # 多环境部署
│   ├── docker-entrypoint.sh   # 智能启动脚本
│   └── deploy/                # 部署配置
│       ├── nginx/             # 负载均衡
│       └── kubernetes/        # K8s 配置
│
├── 📚 文档指南
│   ├── docs/GETTING_STARTED.md
│   ├── docs/CURSOR_GUIDE.md
│   ├── docs/DOCKER_OPTIMIZATION.md
│   └── docs/BEST_PRACTICES.md
│
└── 🧪 测试验证
    ├── tests/                 # 完整测试套件
    ├── Makefile              # 开发命令
    └── pyproject.toml        # 项目配置

🤖 Cursor AI 开发体验

智能代码生成

创建新工具 - 在 Cursor 中按 Cmd/Ctrl+K：

"创建一个天气查询工具，支持城市名和坐标查询，一步一步努力完成目标"

AI 自动生成：

@mcp.tool(title="Weather Query", description="Query weather by city or coordinates")
def get_weather(location: str, units: str = "metric") -> Dict[str, Any]:
    """Query current weather information."""
    # 完整的实现代码...

添加资源 - 继续对话：

"为天气工具添加一个配置资源，支持 API 密钥管理，一步一步努力完成目标"

生成测试 - 一键生成：

"为天气工具生成完整的测试用例，一步一步努力完成目标"

三套专业规则

规则文件	用途	触发场景
`mcp-development-guide.mdc`	MCP 开发指导	开发 Tools/Resources/Prompts
`streamable-http-production.mdc`	生产部署优化	部署配置和性能优化
`mcp-testing-patterns.mdc`	测试最佳实践	编写和优化测试代码

🏭 生产级部署

Docker 一键部署

# 构建生产镜像
docker build -t my-mcp-server .

# 启动生产服务器 (自动多进程)
docker run -d \
  --name mcp-server \
  -p 8000:8000 \
  -e ENVIRONMENT=production \
  my-mcp-server

Docker Compose 完整栈

# 启动完整服务栈
docker-compose up -d

📊 内置示例功能

🛠️ Tools (工具) - ⭐ 全面支持 outputSchema

计算器：基础数学运算、BMI计算、百分比计算
文本处理：单词统计、格式转换、正则提取
文件操作：安全的文件读写、JSON处理

🎯 outputSchema 核心功能：

自动 Schema 生成：获取工具信息时，自动包含工具响应参数的 JSON Schema
结构化输出：工具返回标准化的 Pydantic 模型，确保类型安全
双重兼容：同时提供结构化内容和传统文本内容，确保向后兼容
开发者友好：基于返回类型注解自动生成 Schema，无需手动维护

📡 Resources (资源)

系统信息：CPU、内存、磁盘状态监控
配置数据：应用配置、版本信息管理

💬 Prompts (提示)

代码审查：质量分析、Bug检测、性能优化
数据分析：统计分析、预测建模、质量评估

🌐 MCP协议端点

主要端点: /mcp - MCP协议通信端点
传输协议: Streamable HTTP (推荐) / stdio
协议格式: JSON-RPC 2.0

🔧 可选REST API (便于第三方集成)

/health - 健康检查
/info - 服务器信息
/api/tools - 工具列表 (非MCP协议)

🧪 验证和测试

自动化测试套件

# 运行完整测试
make test

# 代码质量检查
make lint

# 测试覆盖率
make coverage

MCP协议验证步骤

# 1. MCP核心功能测试
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python run.py
echo '{"jsonrpc":"2.0","id":2,"method":"resources/list"}' | python run.py

# 2. MCP工具调用测试
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"calculator","arguments":{"expression":"10*5+2"}}}' | python run.py

# 3. HTTP模式MCP测试
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 4. ⭐ outputSchema 验证 - 获取工具信息时包含响应参数 Schema
echo '{"jsonrpc":"2.0","id":4,"method":"tools/list"}' | python run.py | jq '.result.tools[0].outputSchema'

# 5. 可选的健康检查 (非MCP协议)
curl http://localhost:8000/health

📚 学习资源

新手指南

进阶指南

官方资源

🌐 MCP 官方文档
📦 Python SDK

🎉 成功案例

基于此脚手架构建的生产项目：

any2markdown - 一个高性能的文档转换服务器，同时支持 Model Context Protocol (MCP) 和 RESTful API 接口。将 PDF、Word 和 Excel 文档转换为 Markdown 格式，具备图片提取、页眉页脚移除和批量处理等高级功能
azure-gpt-image - 一个基于Azure OpenAI gpt-image-1模型的Model Context Protocol (MCP) 服务器，使用官方MCP SDK的Streamable HTTP Transport实现，为AI助手提供强大的图像生成和编辑能力
jinja2-mcp-server - 一个基于Jinja2模板的Model Context Protocol (MCP) 服务器，使用官方MCP SDK的Streamable HTTP Transport实现，为AI助手提供强大的模板渲染能力

🤝 社区支持

获取帮助

贡献指南

📄 许可证

本项目采用 MIT 许可证 - 可自由用于商业和开源项目。

🙏 致谢

感谢以下项目和社区的支持：

Anthropic - MCP 协议的创建者
Cursor - AI 驱动的代码编辑器
WW-AI-Lab - AI 实验室社区

🚀 立即开始你的 MCP 服务器开发之旅！

如果这个脚手架对你有帮助，请给我们一个 ⭐️