MCP代理AI入门套件
学习如何使用模型上下文协议（MCP）服务器构建代理AI应用程序的实用指南和工具包。此存储库包含教程、示例和示例数据集，以帮助您了解MCP服务器如何使AI代理与外部工具和数据源交互。
🎯 你将学到
- MCP服务器的工作原理及其用途
- 为不同用例构建自定义MCP服务器
- 将AI代理连接到数据库、API和文件系统
- 实用的代理工作流程（研究、数据分析、任务自动化）
- 使用工具进行快速工程设计的最佳实践
🚀 快速开始
先决条件
- Python 3.10+或Node.js 18+
- Claude Desktop应用程序（用于测试MCP服务器）
- 对AI/LLMs的基本理解
安装
# Clone the repository
git clone https://github.com/your-username/mcp-agentic-starter.git
cd mcp-agentic-starter
# Install UV (fast Python package manager)
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Install all dependencies
uv sync
# Optional: Install PostgreSQL support
uv sync --extra postgres
# Optional: Install FastAPI/mock API support
uv sync --extra api
# Optional: Install visualization tools
uv sync --extra viz
# Optional: Install development tools (ruff, black, pytest)
uv sync --extra dev
# Install all extras at once
uv sync --all-extras📚 存储库结构
mcp-agentic-starter/
├── tutorials/ # Step-by-step learning guides
│ ├── 01-mcp-basics.md
│ ├── 02-first-server.md
│ ├── 03-agentic-patterns.md
│ ├── 04-advanced-workflows.md
│ └── 05-testing-mcp-servers.md
├── examples/ # Working MCP server examples
│ ├── file-system/ # File operations server
│ ├── data-analysis/ # CSV/JSON data processing
│ ├── database/ # SQL database server (SQLite/PostgreSQL)
│ ├── web-api/ # REST API integration with mock server
│ ├── task-manager/ # Persistent task list server
│ └── data-pipeline/ # Multi-stage data processing pipeline
├── datasets/ # Synthetic datasets for practicing
│ ├── sales/ # E-commerce transactions, customers, products
│ └── customer-support/ # Support tickets with categories and sentiment
├── tests/ # Unit test suite (80 tests across all servers)
├── prompts/ # Effective prompts for agentic tasks
└── projects/ # Complete project templates🛠️ 示例用例
1. 个人知识库 （初级）
构建一个MCP服务器，让AI代理从您的个人笔记、文档和书签中搜索和检索信息。
你将学到：文件系统操作、文本搜索、上下文管理
2. 数据分析助理 （中级）
创建一个可以查询数据库、生成可视化和从业务数据生成报告的代理。
你将学到：SQL集成、数据处理、多步骤工作流
3. 研究自动化 （中级）
开发一个代理，搜索学术论文，提取关键发现，并综合研究总结。
你将学到：API集成、内容提取、结构化输出
4. 任务管理系统 （高级）
构建一个完整的系统，代理可以在多个平台（GitHub、Jira等）上创建、跟踪和管理任务。
你将学到：多工具协调、状态管理、错误处理
🔧 包含MCP服务器
- 文件系统服务器 -读取、写入、搜索和管理本地文件
- 数据分析服务器 -使用聚合分析CSV和JSON数据集
- 数据库服务器 -查询SQL数据库（SQLite本地，PostgreSQL云）
- Web API服务器 -与RESTAPI集成（包括用于测试的模拟API）
- 任务管理器服务器 -具有创建、完成和删除功能的持久任务列表
- 数据管道服务器 -具有状态持久性的多级处理流水线
所有服务器都包含全面的文档和工作，无需支付API帐户。
📊 示例数据集
包括用于练习的真实合成数据集：
- 电子商务 (
datasets/sales/)：1万笔交易，1千名客户，5个类别的44种产品 - 客户支持 (
datasets/customer-support/)：1K支持票，包括类别、优先级、情绪评分和解决时间
所有数据集都是用固定的随机种子生成的，以实现可重复性，并且可以免费用于学习。
🎓 教程
教程1:MCP基础（30分钟）
了解MCP是什么，它是如何工作的，以及为什么它对AI代理有用。
教程2：你的第一台MCP服务器（45分钟）
构建一个简单的计算器服务器并将其连接到Claude。
教程3：代理模式（60分钟）
发现使用工具构建有效AI代理的常见模式。
教程4：高级工作流（90分钟）
通过错误处理和状态管理创建复杂的多步骤工作流。
教程5：测试MCP服务器（60分钟）
使用pytest为MCP服务器编写一个单元测试套件——异步测试、模拟和隔离模式。
🌟 现实世界项目
每个项目包括：
- 完整的源代码
- 分步指南
- 样本数据
- 有效提示
- 常见陷阱和解决方案
包括项目创意
- 个人研究助理 -帮助您研究主题并汇编研究结果
- 代码文档生成器 -分析代码库并生成文档
- 会议笔记分析器 -提取行动项目和决定
- 内容再利用工具 -在不同格式之间转换内容
- 数据质量检查器 -验证和清理数据集
🧪 测试套件
该项目包括80个单元测试，涵盖所有示例服务器：
uv sync --extra dev
uv run pytest tests/ -v测试直接涵盖业务逻辑（不需要MCP框架模拟），并在2秒内运行。看 教程5 了解测试方法的完整演练。
🤝 贡献
欢迎投稿！无论是：
- 新教程部分
- 其他MCP服务器示例
- 更多样本数据集
- Bug修复或改进
看 贡献.md 作为指导方针。
📖 其他资源
📝 许可证
麻省理工学院许可证-可自由用于学习和商业项目。
🙏 致谢
基于MCP社区的灵感和构建代理AI应用程序的实践经验而构建。
______________________________________________________________________
准备好开始了吗？ 前往 教程/01-mcp-basics.md 开始你的旅程！