星战科技xingzhan.cloud
返回市场
极客-MCP-框架

极客-MCP-框架

作者：WW-AI-Lab24 星标更新：2025-07-11
安装使用来源：spider==github.com

项目介绍

🚀 Awesome-MCP-Scaffold

生产级别的MCP服务器开发框架 - 优化用于光标IDE的快速开发解决方案

English 中文

License Python MCP outputSchema Streamable HTTP Docker

🎯 项目定位

Awesome-MCP-Scaffold 是一个可立即使用的MCP服务器开发框架，允许您：

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

✨ 核心优势

🔥 特别优化用于光标

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

⚡ 即开即用全功能

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

🏗️ 生产级别架构

  • 流式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. 在光标中开发

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

📁 框架结构

awesome-mcp-scaffold/
├── 🎯 核心架构
│   ├── server/                 # MCP服务器核心
│   │   ├── main.py            # FastMCP主实例
│   │   ├── config.py          # 配置管理
│   │   ├── tools/             # 工具实现 (12+示例)
│   │   ├── resources/         # 资源实现
│   │   ├── prompts/           # 提示模板
│   │   └── routes/            # REST API路由
│   └── run.py                 # 启动入口
│
├── 🤖 光标集成
│   └── .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        # 项目配置

🤖 光标AI开发体验

智能代码生成

创建一个新的工具 - 在光标中按 Cmd/Ctrl+K：

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

AI自动生成：

@mcp.tool(title="Weather Query", description="通过城市或坐标查询天气")
def get_weather(location: str, units: str = "metric") -> Dict[str, Any]:
    """查询当前天气信息。"""
    # 完整的实现代码...

添加资源 - 继续对话：

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

生成测试 - 一键生成：

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

三组专业规则

规则文件目的触发场景
mcp-development-guide.mdcMCP开发指南开发工具/资源/提示
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

📊 内置示例功能

🛠️ 工具 - ⭐ 完全支持OutputSchema

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

🎯 OutputSchema的核心功能：

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

📡 资源

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

💬 提示

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

🌐 MCP协议端点

  • 主要端点：/mcp - MCP协议通信端点
  • 传输协议流式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. ⭐ 输出模式验证 - 获取工具信息时包含响应参数模式
echo '{"jsonrpc":"2.0","id":4,"method":"tools/list"}' | python run.py | jq '.result.tools[0].outputSchema'

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

📚 学习资源

初学者指南

高级指南

官方资源

🎉 成功案例

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

  • 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的流式HTTP传输实现，为AI助手提供强大的图像生成和编辑能力。
  • jinja2-mcp-server - 基于Jinja2模板的Model Context Protocol (MCP) 服务器，使用官方MCP SDK的流式HTTP传输实现，为AI助手提供强大的模板渲染能力。

🤝 社区支持

获取帮助

贡献指南

📄 许可证

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

🙏 致谢

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

🚀 现在开始您的MCP服务器开发之旅！

如果这个框架对您有帮助，请给我们一个 ⭐ ️