代理MCP代码执行PoC
概念证明，演示了使用模型上下文协议（MCP）执行代码，以实现高效的AI代理，并增强了 天气API 和 基于FAISS的RAG 能力。
天气API集成
- 使用OpenWeatherMap的实时天气数据
- 具有时区感知的5天天气预报
- 灵活的位置搜索（城市名称或邮政编码）
- 集成为MCP工具 -代理可以生成代码来使用天气数据
- 基于 langchain天气工具调用
基于FAISS的RAG系统
- 使用向量嵌入进行文档索引
- 快速语义相似度搜索
- 多种嵌入选项（HuggingFace或OpenAI）
- 文本文档的文件上传支持
- 集成为MCP工具 -Agent可以存储和检索知识
- 具有源跟踪功能的持久存储
MCP工具集成
天气和RAG都暴露在 MCP工具 代理可以通过生成Python代码来使用：
- 代理接收用户请求
- LLM生成调用MCP工具的代码
- 代码在具有工具访问权限的沙盒中执行
- 处理和总结结果
概述
本PoC实现了Anthropic关于 使用MCP执行代码，演示了代理如何使用代码执行更有效地与MCP服务器交互。
关键利益
- 渐进呈现：按需加载工具定义，而不是预先加载
- 上下文高效：在传递给LLM之前，在代码中过滤和转换数据
- 强大的控制流：在代码中使用循环和条件语句，而不是链接工具调用
- 隐私保护：中间结果留在执行环境中
- 状态持久性：保存结果和技能以供重用
建筑
User Request → FastAPI → LangChain Orchestrator → Code Generator (LLM)
↓
Generated Python Code
↓
Code Executor (Sandbox)
↓
MCP Client → MCP Tool Servers
↓
Results → Workspace Files
↓
Summary → User快速开始
先决条件
- Python 3.12+
- OpenAI API密钥
- OpenWeatherMap API密钥（可选，用于天气功能）
- PostgreSQL数据库（可选，用于postgres-mcp功能）
快速开始
# 1. Clone and setup
git clone
cd mcp-code-exec
make setup
# 2. Configure environment
cp .env.example .env
# Edit .env with your API keys
# 3. Generate MCP tool wrappers
make wrappers
# 4. Start the server
make startPostgreSQL MCP服务器
此项目现在使用 postgres mcp （从 crystaldba/postgres mcp)作为MCP服务器，提供：
- 架构检查：浏览数据库、表、视图和序列
- 安全查询执行：只读和无限制模式，带验证
- 解释计划：使用假设索引分析查询性能
- 索引调整：用于查询优化的人工智能索引建议
- 数据库运行状况：监控连接、真空、复制等
- 热门查询：识别慢速和资源密集型查询
代理可以按照MCP模式生成使用这些工具的代码。
设置PostgreSQL数据库
您有几个选择：
选项1:Docker（推荐）
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres --name postgres-mcp postgres:14
uv run python scripts/setup_pg.py # Creates sample database选项2：本地PostgreSQL
# Ubuntu/Debian
sudo apt-get install postgresql
# macOS
brew install postgresql@14
# Then create sample database
uv run python scripts/setup_pg.py选项3：使用现有数据库 刚刚设置 DATABASE_URL 在 .env 到您现有的PostgreSQL实例。
特性
- 代码执行：用于代理生成代码的安全Python沙盒
- MCP集成：天气API和FAISS RAG作为MCP工具
- PostgreSQL MCP：通过postgres mcp进行高级数据库操作
- 渐进呈现：按需加载工具
- 上下文效率：执行环境中的数据过滤
- 状态持久性：保存结果和可重复使用的技能
包含内容
setup命令会自动执行：
- 安装
uv如果尚未安装 - 安装所有Python依赖项（包括postgres-mcp）
- 创造
.env模板文件 - 创建所需的目录（工作区、日志、数据）
- 使用示例文档设置RAG索引
- 为PostgreSQL设置提供指导
手动设置（替代）
如果你喜欢手动设置或没有Docker：
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Install dependencies
uv sync
# Copy environment template
cp .env.example .env
# Edit .env with your API keys
# Create directories
mkdir -p workspace logs data/rag data/invoices
# Setup RAG
uv run python scripts/setup_rag.py
# Setup PostgreSQL (if you have it installed)
uv run python scripts/setup_pg.pyPostgreSQL MCP服务器
此项目现在使用 postgres mcp （从 crystaldba/postgres mcp)作为MCP服务器，提供：
- 架构检查：浏览数据库、表、视图和序列
- 安全查询执行：只读和无限制模式，带验证
- 解释计划：使用假设索引分析查询性能
- 索引调整：用于查询优化的人工智能索引建议
- 数据库运行状况：监控连接、真空、复制等
- 热门查询：识别慢速和资源密集型查询
代理可以按照MCP模式生成使用这些工具的代码。
设置PostgreSQL数据库
您有几个选择：
选项1:Docker（推荐）
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=postgres --name postgres-mcp postgres:14
uv run python scripts/setup_pg.py # Creates sample database选项2：本地PostgreSQL
# Ubuntu/Debian
sudo apt-get install postgresql
# macOS
brew install postgresql@14
# Then create sample database
uv run python scripts/setup_pg.py选项3：使用现有数据库 刚刚设置 DATABASE_URL 在 .env 到您现有的PostgreSQL实例。
配置
创建 .env 文件（或复制自 .env.example):
# OpenAI Configuration
OPENAI_API_KEY=your-openai-key-here
OPENAI_MODEL=gpt-4o
# Weather API (get key from https://openweathermap.org/api)
OPEN_WEATHER_API_KEY=your-openweather-key-here
# RAG Configuration
RAG_INDEX_PATH=data/rag_index
# PostgreSQL Configuration (for postgres-mcp MCP server)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/mcp_demo
# Paths
WORKSPACE_PATH=/workspaces/mcp-code-exec/agent-mcp-codeexec-poc/workspace
LOGS_PATH=/workspaces/mcp-code-exec/agent-mcp-codeexec-poc/logs运行应用程序
选项1：开始一切（推荐）
# Start both FastAPI server and Streamlit UI
make start这将启动：
- FastAPI服务器 在端口8000上（API端点和文档）
- 流线型UI 在端口8501上（交互式web界面）
在 GitHub代码空间，两个端口都会自动转发：
- API
https://-8000.preview.app.github.dev - UI：
https://-8501.preview.app.github.dev
当地：
- API
http://localhost:8000（文件在/docs) - UI：
http://localhost:8501
选项2：仅限流线型UI🎨
MCP代码执行POC的交互式web界面
# Quick start
make ui
# Or manually with uv
uv run streamlit run ui/app.py --server.port=8501 --server.address=0.0.0.0
# Or using the launch script
./ui/run.sh特性:
- 仪表盘：实时MCP状态、服务器概述、执行历史
- 操场：带有预构建示例的交互式代码编辑器
- 监视器：分析、服务器详细信息、执行日志
- 文档：API参考、示例、资源
选项3：脚本执行工具（CLI）
使用MCP工具执行独立的Python脚本：
# Basic usage
python -m app.runtime.script_harness
# Example: Test lazy loading
python -m app.runtime.script_harness workspace/test_lazy_loading.py
# Example: Test signal handling
python -m app.runtime.script_harness workspace/test_signal_handling.py特性:
- 延迟加载：服务器仅在调用工具时连接
- 信号处理：SIGINT/SIGTERM用于优雅关机
- 自动清理：出口时关闭MCP连接
- 持久事件循环：正确的异步操作处理
选项4：仅API服务器（Web服务）
# Start the FastAPI server
make start服务器将在以下时间启动 http://localhost:8000 与：
- 交互式API文档：
http://localhost:8000/docs - OpenAPI架构：
http://localhost:8000/openapi.json
停止服务
# Stop both API server and Streamlit UI
make stop
# Stop only Streamlit UI
make stop-ui
# Clean everything (stop + clear cache)
make clean启动FastAPI服务器
开始
The server will start at `http://localhost:8000` with:
- Interactive API docs: `http://localhost:8000/docs`
- OpenAPI schema: `http://localhost:8000/openapi.json`
### Available Make Commands
make help # Show available commands make setup # Complete project setup (uv, deps, env, databases) make start # Start both FastAPI server and Streamlit UI make ui # Start only Streamlit UI make stop # Stop both server and UI make stop-ui # Stop only Streamlit UI make restart # Restart all services make clean # Stop services and clear cache make wrappers # Generate MCP tool wrappers
## 用法
### 快速演示-MCP代理与天气和RAG
通过MCP使用Weather和RAG工具测试代理：
Start the server first
uv run fastapi dev app/main.py
In another terminal, run the agent test
python examples/test_agent_mcp_tools.py
此交互式测试演示了代理生成代码以：
- 获取任何城市的当前天气
- 获取天气预报
- 将文档添加到RAG知识库
- 使用语义查询搜索RAG
- 在单一工作流程中结合天气+RAG
- 上传文件并查询
- 获取RAG统计数据
### MCP代理示例
**天气查询：**
curl -X POST http://127.0.0.1:8000/api/v1/agent \ -H "Content-Type: application/json" \ -d '{ "request": "Get current weather for Tokyo, Japan and tell me the temperature" }'
**RAG知识库：**
curl -X POST http://127.0.0.1:8000/api/v1/agent \ -H "Content-Type: application/json" \ -d '{ "request": "Add this to knowledge base: Python is a programming language. Then search for Python." }'
**综合天气+RAG：**
curl -X POST http://127.0.0.1:8000/api/v1/agent \ -H "Content-Type: application/json" \ -d '{ "request": "Get weather for London, store it in RAG, then search for London weather" }'
### API直接示例（非代理）
**获取当前天气：**
curl -X POST http://127.0.0.1:8000/api/v1/weather/current \ -H "Content-Type: application/json" \ -d '{"city_name": "London", "country_name": "UK"}'
**获取天气预报：**
curl -X POST http://127.0.0.1:8000/api/v1/weather/forecast \ -H "Content-Type: application/json" \ -d '{"city_name": "Tokyo", "country_name": "Japan", "days": 2, "hour": 14}'
**将文档添加到RAG：**
curl -X POST http://127.0.0.1:8000/api/v1/rag/documents/add \ -H "Content-Type: application/json" \ -d '{ "texts": ["Python is a programming language."], "source": "my-docs" }'
**搜索文档：**
curl -X POST http://127.0.0.1:8000/api/v1/rag/search \ -H "Content-Type: application/json" \ -d '{"query": "What is Python?", "k": 3}'
### 代理示例请求
curl -X POST http://127.0.0.1:8000/api/v1/agent \ -H "Content-Type: application/json" \ -d '{ "request": "Fetch invoice data, find duplicates and anomalies, then summarize the findings", "parameters": { "month": "last_month" } }'
### 示例响应
{ "status": "success", "summary": "Found 12 duplicate invoices and 5 anomalies. Details saved to workspace.", "output_file": "workspace/invoice_analysis_2025-11-08_14-30-22.csv", "metrics": { "tokens_used": 1250, "model_name": "gpt-4o", "tool_calls_count": 1, "code_exec_time_ms": 450, "total_time_ms": 2100 } }
## 项目结构
agent-mcp-codeexec-poc/ ├── README.md # This file ├── pyproject.toml # Project metadata and dependencies ├── uv.lock # Locked dependencies ├── .env # Environment variables ├── .env.example # Example environment file ├── logs/ # Execution logs and metrics ├── workspace/ # Output files from agent ├── rag_index/ # FAISS vector index storage ├── examples/ │ ├── weather_and_rag_demo.py # Direct API demo │ └── test_agent_mcp_tools.py # MCP agent tests ├── app/ │ ├── main.py # FastAPI entry point │ ├── config.py # Configuration │ ├── api/ │ │ └── v1/ │ │ ├── agent.py # Agent endpoint │ │ ├── weather.py # Weather API endpoints │ │ └── rag.py # RAG API endpoints │ ├── agent_core/ │ │ ├── orchestrator.py # Main agent orchestration │ │ ├── code_executor.py # Sandboxed code execution │ │ └── monitoring.py # Metrics collection │ ├── mcp_client/ │ │ ├── client.py # MCP client wrapper │ │ └── tools/ │ │ ├── invoice_tool.py # Example invoice tool │ │ ├── weather_tool.py # Weather API tool (MCP) │ │ └── rag_tool.py # RAG tool (MCP) │ ├── rag/ │ │ └── document_store.py # FAISS-based RAG system │ └── prompts/ │ └── agent_prompt.py # LLM prompt templates
## 运作原理
### 1.请求处理
FastAPI端点接收用户请求并将其传递给LangChain编排器。
### 2.代码生成
代理没有预先加载所有工具定义，而是：
- 分析请求
- 仅按需加载相关工具定义
- 使用LLM生成Python代码，该代码：
- 通过客户端包装器调用MCP工具
- 在本地处理数据（过滤、聚合等）
- 将结果写入工作区
- 返回摘要
### 3.代码执行
生成的代码在沙盒环境中执行，其中：
- 限制导入（仅允许库）
- 超时保护
- 资源限制
- 捕获的stdout/stderr
### 4.监测
每次执行都会记录以下内容：
- 时间戳
- 使用的代币
- 工具调用
- 执行时间
- 成功/失败状态
- 错误消息（如有）
## 示例工具
### 气象工具（MCP）
作为MCP工具公开，用于生成代理代码：
- `get_current_weather(city_name, country_name)` -获取当前天气
- `get_forecast(city_name, country_name, days, hour)` -获取天气预报
- `get_geo_data(city_name, zip_code, country_name)` -获取地理坐标
**代理使用：**
Generated code example
from mcp_client_wrapper import mcp_client
weather = mcp_client.call_tool('get_current_weather', { 'city_name': 'Tokyo', 'country_name': 'Japan' }) print(f"Temperature: {weather['main']['temp']}°F")
### RAG系统（MCP）
作为知识管理的MCP工具公开：
- `add_documents(texts, source)` -索引文件
- `search_documents(query, k)` -语义相似度搜索
- `get_context(query, k)` -获取LLM的格式化上下文
- `add_file(file_path, source)` -将文件添加到索引
- `get_rag_stats()` -获取索引统计信息
**代理使用：**
Generated code example
from mcp_client_wrapper import mcp_client
Add to knowledge base
mcp_client.call_tool('add_documents', { 'texts': ['Python is a programming language'], 'source': 'facts' })
Search
results = mcp_client.call_tool('search_documents', { 'query': 'What is Python?', 'k': 2 })
### 发票工具（MCP）
PoC包括一个模拟发票工具，该工具模拟：
- `fetch_invoices(month)` -获取发票数据
- `update_anomaly_log(anomalies)` -日志检测到异常
## 测试
Run all tests
uv run pytest
Run specific test
uv run pytest tests/test_agent_flow.py
With coverage
uv run pytest --cov=app tests/
## 监控
指标保存到 `logs/run_.json`:
{ "timestamp": "2025-11-08T14:30:22Z", "request": "Fetch invoice data...", "model_name": "gpt-4o", "tokens_used": 1250, "tool_calls_count": 1, "code_exec_time_ms": 450, "total_time_ms": 2100, "status": "success", "output_file": "workspace/invoice_analysis.csv" }
## 未来的增强功能
- \[\]添加Streamlit UI用于交互式代理交互
- \[\]实施更多MCP工具服务器
- \[\]添加Docker容器化
- \[\]实现技能持久性（保存可重用函数）
- \[\]添加更复杂的沙盒
- \[\]多租户支持
- \[\]身份验证和授权
- \[\]将Weather API与代理编排器集成
- \[\]将RAG驱动的上下文添加到代理响应中
- \[\]实现混合搜索（关键字+语义）
## 参考文献
- [Anthropic：使用MCP执行代码](https://www.anthropic.com/engineering/code-execution-with-mcp)
- [模型上下文协议规范](https://modelcontextprotocol.io)
- [LangChain文档](https://python.langchain.com)
- [FastAPI文档](https://fastapi.tiangolo.com)
- [OpenWeatherMap API](https://openweathermap.org/api)
## 许可证
麻省理工学院