Masterclass MCP Agent

启用MCP的AI代理

该项目是一个AI聊天机器人代理，具有模型上下文协议（MCP）客户端功能。通过基于FastAPI的Web UI与用户交互，并通过JSON配置文件动态管理和联动MCP服务器。

主要功能

• 基于FastAPI的Web服务器：使用异步Web框架FastAPI提供Web UI和后端逻辑。
• Web套接字通信：使用Web套接字进行客户端和服务器之间的实时双向通信。
• OpenAI GPT-4o연동：利用OpenAI的GPT-4o模型回答用户的问题并使用工具。
• MCP（模型上下文协议）클라이언트：通过MCP与外部工具服务器通信，扩展代理的功能。
• 动态服务器管理: mcp_servers.json 通过配置文件动态加载多台MCP服务器并管理进程。
• 通过UI查看状态：您可以在Web UI中查看当前连接的MCP服务器的列表和每个服务器提供的工具。
• 可靠的依赖性管理：Python虚拟环境（venv）隔离和管理项目依赖性。

项目结构

.
├── .env                  # API 키 등 환경 변수 설정 파일
├── mcp_servers.json      # MCP 서버 설정 파일
├── openai_mcp_agent.py   # MCP 클라이언트 기능이 포함된 주 AI 에이전트 로직
├── static/               # 웹 프론트엔드 파일
│   ├── index.html
│   └── script.js
├── venv/                 # Python 가상 환경
├── weather_server.py     # 날씨 정보 API를 MCP로 제공하는 예제 서버
├── web_server.py         # FastAPI 웹 서버 및 웹소켓 로직
└── Readme.md             # 프로젝트 설명 파일

如何安装和运行

前提条件：必须安装Python 3.10或更高版本。

1. 创建和激活虚拟环境

   # Python 3.10 버전을 명시하여 가상환경 생성
   python3.10 -m venv venv

   # 가상환경 활성화 (macOS/Linux)
   source venv/bin/activate

   # 가상환경 활성화 (Windows)
   .\venv\Scripts\activate

1. 设置环境变量

.env.example 复制文件 .env 创建文件，并在文件中输入自己的API密钥和端点。

   cp .env.example .env
   # nano, vim 등 편집기로 .env 파일 수정

1. 选择代理类型（可选）

.env 在文件中 AGENT_TYPE 您可以通过添加变量来选择要使用的LLM服务。默认值为 AZURE。

   # 사용하려는 에이전트 타입을 'AZURE' 또는 'STANDARD'로 설정
   AGENT_TYPE="AZURE" 

- 蓝天：使用Azure OpenAI服务。 (AZURE_OPENAI_API_KEY 等需要） - 标准：使用标准OpenAI API。 (OPENAI_API_KEY 需要）

1. 设置MCP服务器路径

mcp_servers.json 打开文件 weather_server的 command包括 weather_server.py的路径 用户环境的绝对路径必须修改为。

1. 安装所需的库

在创建的虚拟环境中安装所需的库。

   pip install -r requirements.txt

1. 运行Web服务器

   python web_server.py

1. 服务连接

打开Web浏览器 http://127.0.0.1:8000 连接到地址。

开发过程摘要

该项目从解决简单AI代理代码中的错误开始，经过了逐步扩展和稳定功能的过程。

1. 初始调试: await 表达式错误和 openai-agents 解决了库中的结果对象属性问题，提高了对异步处理和库结构的理解。

1. MCP客户端集成：将MCP客户端功能集成到代理中，基于FastAPI的Web服务器（web_server.py）和Web插座已从CLI环境切换到Web UI环境。

1. 解决环境和依赖性问题: ModuleNotFoundError为了解决重复出现的问题，请使用Python执行环境和 pip 发现原因是安装路径不一致。 mcp 确认软件包要求使用Python3.10或更高版本。 venv通过使用构建基于Python3.10的虚拟环境，解决了所有依赖性问题。这是项目稳定性的最重要阶段。

1. 动态服务器加载和UI增强：在单服务器连接中 mcp_servers.json 改进了读取配置文件以动态加载和管理多台MCP服务器的方式。此外，我们还实现了API端点和前端UI，以便根据用户的要求在UI中查看连接的服务器和工具列表。

1. 解决最终连接问题: mcp_servers.json将在中设置的服务器运行路径无效导致的错误修改为绝对路径，最终解决了问题。

通过这一过程，我们从一个简单的AI代理开始，完成了一个稳定的系统，可以与外部工具动态协作，并通过Web方便地进行交互。

🏗️ 体系结构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Browser   │    │  OpenAI Agents  │    │  MCP Servers    │
│   (Frontend)    │◄──►│  SDK + MCP Ext  │◄──►│  (Weather,      │
│                 │    │                 │    │   Example, etc) │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              ▲
                              │
                         ┌────▼────┐
                         │ Azure   │
                         │ OpenAI  │
                         └─────────┘

🎯 主要功能

• OpenAI代理SDK：使用最新的OpenAI Agents SDK
• MCP扩展：自动连接Model Context Protocol服务器
• Azure OpenAI：完全支持Azure OpenAI服务
• Web界面：提供实时聊天UI
• 自动工具发现：自动发现和使用MCP服务器上的工具
• 流式处理：支持实时响应流式处理

📁 文件结构

📦 OpenAI MCP Agent
├── 🤖 openai_mcp_agent.py      # 핵심 OpenAI MCP Agent
├── 🌐 web_server.py            # FastAPI 웹 서버
├── 🌤️  weather_server.py        # 날씨 MCP Server
├── 📊 example_server.py        # 예제 MCP Server
├── ⚙️  mcp_agent.config.yaml   # MCP 서버 설정
├── 🔑 mcp_agent.secrets.yaml   # API 키 등 비밀 정보
├── 📋 requirements.txt         # Python 의존성
├── 📖 README.md               # 프로젝트 문서
└── 🎨 static/                 # 웹 프론트엔드
    ├── index.html             # 메인 HTML
    ├── style.css             # 스타일시트
    └── script.js             # JavaScript 클라이언트

🚀 安装和设置

1.安装依赖性

pip install -r requirements.txt

2.设置API密钥

mcp_agent.secrets.yaml 修改文件以设置API密钥：

# Azure OpenAI 설정 (권장)
AZURE_OPENAI_API_KEY: "your_azure_openai_api_key_here"
AZURE_OPENAI_ENDPOINT: "https://your-resource-name.openai.azure.com"
AZURE_OPENAI_API_VERSION: "2024-10-21"
AZURE_OPENAI_DEPLOYMENT_NAME: "gpt-4o-mini"  # 또는 사용하는 모델

# 또는 일반 OpenAI 설정
OPENAI_API_KEY: "your_openai_api_key_here"

# 날씨 서버용
OPENWEATHER_API_KEY: "your_openweather_api_key_here"

3.发放API密钥

• Azure OpenAI: Azure门户 →创建OpenAI资源
• OpenAI: OpenAI平台
• 开放天气: OpenWeatherMap

🎮 使用方法

使用Web界面

1. 启动Web服务器:

python web_server.py

1. 从浏览器连接:

- 主界面：http://localhost:8000 - API文档：http://localhost:8000/docs

1. 连接MCP服务器:

- Weather服务器： weather_server.py - Example服务器： example_server.py

在命令行中使用

# 대화형 모드
python openai_mcp_agent.py

# 단일 쿼리 실행
python openai_mcp_agent.py --query "서울의 3일 날씨 예보를 알려줘"

# 스트리밍 모드
python openai_mcp_agent.py --query "인공지능에 대해 설명해줘" --stream

交互式模式命令

>>> 서울의 날씨가 어때?          # 일반 질문
>>> /tools                    # 사용 가능한 도구 목록
>>> /memory                   # 메모리 상태 확인
>>> /clear                    # 메모리 지우기
>>> /stream on                # 스트리밍 모드 켜기
>>> /help                     # 도움말
>>> /quit                     # 종료

🌤️ 气象MCP服务器

您开发的Weather Server功能：

“工具”（Tools）

• get_forecast：查看各城市的天气预报

资源（Resources）

• weather://Seoul/current：首尔目前天气

使用示例

>>> 서울의 내일 날씨는 어때?
>>> 부산 3일 예보 알려줘
>>> 뉴욕과 도쿄의 날씨를 비교해줘

📊 MCP服务器示例

测试服务器的功能：

“工具”（Tools）

• get_user_info：查看用户信息
• get_product_info：查看产品信息
• calculate：计算器
• get_current_time：当前时间

提示符（Prompts）

• analyze_data：数据分析模板

使用示例

>>> 계산해줘: 15 * 7 + 23
>>> 사용자 1번 정보 알려줘
>>> 현재 시간이 몇 시야?

🌐 Web API端点

📡 WebSocket事件

// 연결
const ws = new WebSocket('ws://localhost:8000/ws');

// 메시지 전송
ws.send(JSON.stringify({
    type: "query",
    content: "안녕하세요!",
    stream: false
}));

// 응답 수신
ws.onmessage = (event) => {
    const data = JSON.parse(event.data);
    console.log('Type:', data.type);
    console.log('Message:', data.message);
};

配置MCP

mcp_agent.config.yaml

$schema: "https://raw.githubusercontent.com/lastmile-ai/mcp-agent/main/schema/mcp-agent.config.schema.json"

mcp:
  servers:
    weather:
      command: "python"
      args: ["weather_server.py"]
      env:
        OPENWEATHER_API_KEY: "${OPENWEATHER_API_KEY}"
    
    example:
      command: "python"
      args: ["example_server.py"]

添加新的MCP服务器

1. 服务器开发:

from mcp.server import Server
from mcp.types import Tool, TextContent

app = Server("my-server")

@app.list_tools()
async def list_tools():
    return [Tool(name="my_tool", description="My tool")]

@app.call_tool()
async def call_tool(name: str, arguments):
    return [TextContent(type="text", text="Result")]

1. 添加到配置文件:

mcp:
  servers:
    my_server:
      command: "python"
      args: ["my_server.py"]

1. 由Agent使用:

agent = Agent(
    name="My Agent",
    instructions="...",
    mcp_servers=["weather", "example", "my_server"]
)

🔧 高级设置

更改Azure OpenAI模型

在环境变量或secrets文件中：

AZURE_OPENAI_DEPLOYMENT_NAME: "gpt-4"  # 또는 사용하려는 모델

流响应

# 코드에서
response = await agent.query("질문", stream=True)

# API에서
POST /api/query
{
    "message": "질문",
    "stream": true
}

内存管理

# 메모리에 추가
await agent._add_to_memory("중요한 정보", "work")

# 메모리 조회
memory = agent.get_memory()

# 메모리 지우기  
agent.clear_memory()

🛠️ 故障排除

常见问题

1. “OpenAI MCP Agent未初始化”

- 验证API密钥： mcp_agent.secrets.yaml - 验证Azure OpenAI资源和部署

1. MCP服务器连接失败

- 验证服务器文件路径 - 检查您的Python环境 - 验证服务器文件的执行权限

1. 天气API错误

- OPENWEATHER_API_KEY 确认 - 验证API密钥的有效性和使用限制

1. Azure OpenAI오류

- 检查端点URL - 验证已部署的型号名称 - 验证API版本

检查日志

# 웹 서버 로그
python web_server.py

# Agent 로그  
python openai_mcp_agent.py

调试模式

# 상세 로그로 실행
OPENAI_LOG=debug python openai_mcp_agent.py

🤝 贡献

1. Fork项目
2. 创建特征分支
3. 提交更改
4. 拉取请求제출

📄 许可证

在MIT许可下分发。

📚 参考文档

• OpenAI代理SDK
• OpenAI代理MCP확장
• 模型上下文协议
• Azure OpenAI文档

🤝 贡献

1. Fork项目
2. 创建特征分支
3. 提交更改
4. 拉取请求제출

📄 许可证

在MIT许可下分发。

______________________________________________________________________

体验Azure OpenAI+MCP的强大功能！ 🚀