Agentic MCP Example Ui

MCP演示项目

这是一个完整的端到端演示，展示了模型上下文协议（MCP），其中有三个干净分离的组件：

建筑

1. MCP服务器 (mcp-server/)-通过MCP协议公开工具
2. 代理后端 (agent-backend/)-使用MCP工具的OpenAI代理循环
3. 前端 (frontend/)-用于与代理交互的React UI

先决条件

• 支持虚拟环境的Python 3.12+
• Node.js 22+
• Docker（可选，用于容器化部署）
• OpenAI API密钥

快速开始

1.设置Python环境

python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]" openai-agents fastapi uvicorn

2.设置环境变量

cp env.example .env
# Edit .env and add your OpenAI API key

3.运行组件

选项A:Docker Compose（推荐）

docker compose up --build

然后打开http://localhost:5173

选项B：手动（开发）

终端1-MCP服务器：

source .venv/bin/activate
cd mcp-server
python server.py

终端2-代理后端：

source .venv/bin/activate
export OPENAI_API_KEY="your-key-here"
cd agent-backend
python main.py

3号航站楼-前端：

cd frontend  
npm run dev

然后打开http://localhost:5173

测试

1. 在浏览器中打开前端
2. 类型：“什么是41+1？”
3. 观看链：用户→ 代理→ MCP（添加）→ 代理→ UI

项目结构

mcp-proj/
├── mcp-server/
│   ├── server.py          # 40-line MCP server with add() tool
│   └── Dockerfile
├── agent-backend/
│   ├── main.py           # FastAPI app with OpenAI-Agents
│   └── Dockerfile  
├── frontend/
│   ├── src/
│   │   ├── App.jsx       # Simple chat interface
│   │   └── main.jsx
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml
└── README.md

发展

MCP服务器检查器

直接测试MCP服务器：

source .venv/bin/activate
mcp dev mcp-server/server.py

添加新工具

编辑 mcp-server/server.py 并添加更多 @mcp.tool() 功能：

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Return a * b"""
    return a * b

扩展代理

代理会自动发现所有MCP工具。添加新工具时不需要在后端进行更改。

港口

• MCP服务器：5000
• 代理后端：8000
• 前端：5173（开发）/4173（生产）

故障排除

1. OpenAI API密钥：确保 OPENAI_API_KEY 在您的环境中设置
2. 端口冲突：检查端口5000、8000或5173是否已在使用中
3. 码头工人：确保Docker正在运行以进行容器化部署