MCP代理教育项目
这是一个教育性的、最小的项目，它用三种不同类型的服务器演示了模型上下文协议（MCP）：
- 代码服务器 -文件操作和代码执行
- 数据库服务器 -SQLite数据库操作
- 文档服务器 -文档管理和搜索
什么是MCP？
模型上下文协议（MCP）是一种标准化的协议，允许AI代理与各种服务和工具进行交互。它为以下内容提供了一个通用接口：
- 工具：代理可以调用以执行操作的函数
- 资源：代理可以访问的数据
- 提示：可重复使用的提示模板
项目结构
.
├── servers/
│ ├── code_server.py # Code server implementation
│ ├── database_server.py # Database server implementation
│ └── document_server.py # Document server implementation
├── notebooks/
│ ├── mcp_client_demo.ipynb # Jupyter notebook with basic MCP demos
│ └── mcp_llm_agent.ipynb # Jupyter notebook with LLM integration
├── requirements.txt # Python dependencies
└── README.md # This file设置
- 安装依赖项：
pip install -r requirements.txt- 使服务器脚本可执行（可选）：
chmod +x servers/*.py运行演示
- 启动Jupyter笔记本：
jupyter notebook- 打开演示笔记本（按顺序）：
- 从这里开始: notebooks/mcp_client_demo.ipynb -基本MCP演示 - 运行单元格 一次一个 - 等待每个单元格完成，然后运行下一个单元格 - 那就试试: notebooks/mcp_llm_agent.ipynb -高级LLM集成 - 首先需要了解基本演示
- 重要提示：
- 按顺序运行单元格：不要同时运行所有单元格 - 等待完成：寻找 [1], [2], [3] （单元格编号） - **[*] 意味着跑步：等待它完成 - await 在Jupyter中工作：不需要 asyncio.run() - 服务器自动启动**：无需手动启动它们
- 故障排除：
- 如果执行编号未显示：请参阅 NOTEBOOK_TROUBLESHOOTING.md - 如果单元格挂起：按 Ctrl+C （或 Cmd+C)中断，然后重新启动内核 - 如果连接错误：请参阅 GETTING_STARTED.md 获取详细帮助
LLM集成
该项目包括LLM集成，以创建能够理解自然语言并使用MCP工具的智能代理。支持两种方法：
方法1：Ollama（局部模型）
在没有API密钥的情况下本地运行LLM：
- 安装Ollama：从下载 https://ollama.ai
- 拉一个模型:
ollama pull llama3（或任何其他型号） - 启动Ollama服务:
ollama serve - 在笔记本电脑中使用：The
mcp_llm_agent.ipynb笔记本电脑将自动检测并使用Ollama
方法2：基于API的模型（OpenAI和Gemini）
使用基于云的LLM API：
- 获取API密钥:
- 开放人工智能：从 https://platform.openai.com/api-keys - 双子座：从 https://aistudio.google.com/app/apikey
- 设置API密钥 （使用.env文件）：
- 创建 .env 文件 在项目根目录中：
cp .env.example .env- 编辑 .env 文件 并添加您的密钥：
OPENAI_API_KEY=your-openai-key-here
GEMINI_API_KEY=your-gemini-key-here- 备注：您只需为要使用的提供商设置密钥 - 这 .env 出于安全考虑，文件被忽略
- 在笔记本电脑中使用：打开
mcp_llm_agent.ipynb-密钥将从自动加载.env
LLM代理使用示例
# Using Ollama (local)
result = await intelligent_agent(
"List all users in the database",
provider="ollama",
model="llama3"
)
# Using OpenAI
result = await intelligent_agent(
"Create a document with database statistics",
provider="openai",
model="gpt-4o-mini"
)
# Using Gemini
result = await intelligent_agent(
"Write a Python function to calculate factorial",
provider="gemini"
)服务器详细信息
代码服务器(code_server.py)
提供以下工具：
read_file：读取文件内容write_file：将内容写入文件execute_code：执行Python代码save_code_snippet：保存代码片段以供以后使用list_code_snippets：列出所有已保存的代码段
资源：
- 存储在内存中的代码片段（可通过以下方式访问
code://URI）
数据库服务器(database_server.py)
提供以下工具：
execute_query：执行SQL查询（SELECT、INSERT、UPDATE、DELETE）list_tables：列出所有数据库表describe_table：获取表的架构信息insert_user：插入新用户（方便方法）get_user：通过电子邮件联系用户（便捷方式）
资源：
- 数据库架构(
db://schema) - 表格列表(
db://tables)
注： 服务器自动创建SQLite数据库(example.db)第一次运行时使用样本数据。
文档服务器(document_server.py)
提供以下工具：
create_document：创建新的文本文档read_document：读取文档内容list_documents：列出所有可用文件search_documents：在所有文档中搜索文本append_to_document：将文本附加到现有文档delete_document：删除文档
资源：
- 文件存储在
documents/目录（可通过以下方式访问doc://URI）
MCP的工作原理
传输机制
MCP支持多种传输机制：
- 标准输入/输出 -用于此项目
- ✅ 简单：无需网络配置 - ✅ 安全：无暴露端口 - ✅ 进程管理：客户端生成服务器 - ❌ 仅限本地：无法连接到远程服务器 - ❌ 每台服务器一个客户端：每个客户端生成自己的进程
- HTTP/SSE（服务器发送事件） -备选方案
- ✅ 远程访问：连接到不同机器上的服务器 - ✅ 可扩展：多个客户端可以共享一台服务器 - ✅ Web集成：可以从浏览器访问 - ❌ 更复杂：需要web服务器框架 - ❌ 安全性：需要身份验证/授权
为什么选择stdio参与这个项目？
- 教育重点：更易于理解和设置
- 本地开发：非常适合学习和测试
- MCP标准：MCP规范中的主要传输机制
- 无依赖性：开箱即用
何时改用HTTP：
- 生产部署
- 远程服务器访问
- 多个客户端共享一台服务器
- Web浏览器集成
看 TRANSPORT_COMPARISON.md 以进行详细比较。
通信流
- 服务器：MCP服务器通过stdio（或HTTP）公开工具和资源
- 客户端：MCP客户端连接到服务器，可以：
- 列出可用工具 - 调用带有参数的工具 - 列出可用资源 - 按URI访问资源
- 沟通：通过stdio（或HTTP/SSE）使用JSON-RPC进行通信
示例用法
基本MCP演示(mcp_client_demo.ipynb)
基本笔记本演示：
- 连接到每台服务器
- 列出可用工具
- 调用具有不同参数的工具
- 访问资源
- 在工作流中组合多个服务器
LLM代理演示(mcp_llm_agent.ipynb)
LLM代理笔记本演示了：
- 使用Ollama进行局部LLM推理
- 使用OpenAI API进行基于云的LLM
- 使用Google Gemini API
- 与MCP服务器的自然语言交互
- 智能刀具选择和执行
- 多步骤工作流自动化
教育价值
本项目说明：
- 如何创建MCP服务器
- 如何实施工具和资源
- 如何将客户端连接到服务器
- 如何同时使用多台服务器
- 如何将LLM与MCP服务器集成
- 如何创建理解自然语言的智能代理
- 代理应用程序的真实模式
运输选项
当前实施：stdio
此项目中的服务器使用 stdio传输，即：
- 设置简单
- 安全（无网络端口）
- 非常适合当地发展
- 标准MCP传输
添加HTTP支持
要改用HTTP传输，请执行以下操作：
- 安装HTTP依赖项 （可选）：
pip install fastapi uvicorn- 将服务器作为HTTP服务运行:
python servers/code_server_http.py- 通过HTTP连接客户端:
from mcp.client.sse import sse_client
# Use HTTP client instead of stdio_client看 TRANSPORT_COMPARISON.md 有关stdio与HTTP的详细比较。
扩展项目
您可以通过以下方式扩展此项目：
- 向现有服务器添加更多工具
- 创建新服务器（例如，API服务器、文件系统服务器）
- 实现远程访问的HTTP传输
- 添加身份验证和授权
- 实施更复杂的工作流程
- 添加错误处理和验证
- 为服务器创建web界面
资源
许可证
这是一个教育项目。您可以根据需要自由使用和修改。