mcp_test by hiddenguy1 - MCP Server

MCP 智能代理项目

本项目演示 Model Context Protocol (MCP) 的智能代理在实际应用中的使用，如 AI 聊天机器人和 Agentic Loop。

项目核心特点

强大 Agentic Loop - 智能循环最多10次迭代自动规划执行任务
并行工具调用支持 - 可同时并发调用多个工具提高效率
集成多种实用工具 - 包括网络搜索、天气查询、文件读写、计算器等功能
完善错误重试机制 - 检测到工具调用格式错误可自动重试
流式输出友好展示 - 支持实时流式输出工具调用结果与 AI 回复
灵活编码支持 - 自动处理多种文件编码（UTF-8, GBK, GB2312等）

可用工具列表

工具	功能	参数
`query_weather`	查询天气	`city` (城市代码)
`search_web`	网络搜索	`query` (搜索关键词)
`calculate`	计算器	`expression` (计算表达式)
`read_file`	读取文件内容	`file_path` (文件路径)
`write_file`	写入或创建文件	`file_path`, `content`
`list_files`	列出目录文件	`directory_path`, `recursive`
`mark_task_complete`	标记任务完成	`summary` (任务总结)

项目文件结构

mcp-client/
├── client.py                             # 主客户端代理（带工具调用）
├── server.py                             # MCP 服务端（7种工具）
├── example.py                            # 完整示例演示
├── client_chat_only.py                   # 纯对话客户端
├── client_template.py                    # MCP 模板客户端
├── main.py                               # 快速启动入口
├── pyproject.toml                        # 项目依赖配置
├── INTEGRATION_GUIDE.md                  # 集成使用指南
└── README.md                             # 项目说明

快速开始指南

1. 安装依赖

## 安装 uv 包管理器
pip install uv

## 初始化项目文件夹 
uv init mcp-client

## 创建虚拟环境
uv venv

## 激活环境（Windows）
.venv\Scripts\activate 

## 激活环境（Linux/Mac）
# source .venv/bin/activate

## 安装 MCP SDK
uv add mcp

## 安装其他必需依赖
uv add httpx openai python-dotenv tavily-python

2. 配置 .env 文件

在项目根目录创建 .env 文件：

# OpenAI API 配置
OPENAI_API_KEY=your_openai_api_key_here
BASE_URL=https://api.openai.com/v1
MODEL=gpt-4

# Tavily API 密钥（用于网络搜索）
TAVILY_API_KEY=your_tavily_api_key_here

# 如果使用国产 API 可替换为 SiliconFlow：
# BASE_URL=https://api.siliconflow.cn/v1
# MODEL=your_model_name

运行示例

启动带工具调用的智能代理

python client.py server.py

启动纯对话客户端

python client_chat_only.py

使用示例

示例1：多工具并行调用

提问: 搜索 MCP 协议的相关信息，计算 4454+322-32/3，并把搜索结果创建到文件 mcp_info.txt

开始 Agent 迭代 1/10
规划 Agent 决定使用 3 个工具
[调用工具 search_web，参数 {"query": "MCP 协议相关信息"}]
[调用工具 calculate，参数 {"expression": "4454+322-32/3"}]
[调用工具 write_file，参数 {"file_path": "mcp_info.txt", "content": "..."}]

来自 OpenAI: 任务已完成！搜索到了关于MCP协议的详细信息，计算结果为4765.33，已成功保存至mcp_info.txt 文件中。

示例2：文件读写操作

提问: 列出当前目录的文件，并读取 README.md

开始 Agent 迭代 1/10
规划 Agent 决定使用 2 个工具
[调用工具 list_files，参数 {"directory_path": "."}]
[调用工具 read_file，参数 {"file_path": "README.md"}]

来自 OpenAI: 当前目录共有以下文件：
文件夹: __pycache__/
文件: client.py (5.2KB), server.py (8.3KB), README.md (1.5KB)...

示例3：天气查询

提问: 查询北京的天气

开始 Agent 迭代 1/10
规划 Agent 决定使用 1 个工具
[调用工具 query_weather，参数 {"city": "110101"}]

来自 OpenAI: 北京天气如下：
城市: 北京
当前气温: 15°C
湿度: 45%
风力: 东南风
风力等级: 3级
天气: 晴

技术实现要点

异步并发设计

性能优化 - 基于 asyncio 的异步并发设计
工具并发调用** - 使用 asyncio.gather() 并发调用多个工具
流式输出友好 - 支持实时输出，使用 flush=True
编码支持 - 自动处理多种文件编码（UTF-8, GBK, GB2312等）
容错性 - 完善的异常处理和错误重试

Agentic Loop 要点

智能循环 - 最多10次迭代自动规划并执行任务
工具选择智能 - AI 自动选择并组合需要的工具调用
工具并行调用 - 可同时并发调用多个工具
任务完成检测 - 智能判断任务已完成并自动停止，避免无意义迭代

文件读写操作要点

编码支持 - 自动处理多种文件编码格式
路径规范化 - 支持路径规范化确保跨平台兼容
文件大小格式化 - 友好显示文件大小（B/KB/MB）
容错性 - 错误处理、文件不存在等异常情况

依赖包说明

依赖包	版本	用途
`httpx`	>=0.28.1	HTTP 客户端，用于 API 调用
`mcp`	>=1.14.1	MCP 协议框架
`openai`	>=1.109.1	OpenAI API 客户端
`python-dotenv`	>=1.1.1	环境变量配置管理
`tavily-python`	>=0.5.0	网络搜索 API

扩展自定义指南

添加新工具

在 server.py 中添加新工具函数定义
使用 @mcp.tool() 装饰器
客户端会自动检测并识别新工具

@mcp.tool()
async def new_tool(param: str) -> str:
    """
    新工具描述
    :param param: 参数说明
    :return: 返回值描述
    """
    # 工具逻辑
    return "结果"

调整配置

修改 max_iterations 参数控制最大迭代次数
修改超时重试机制保护 AI 反应
添加新的环境变量配置支持

常见问题解答

问题排查

编码错误 - 确保文件编码格式正确
API 调用失败 - 检查 .env 文件中的 API Key
工具响应为空 - 确认服务端是否正常运行
迭代次数过多 - 在超时重试机制中确认任务描述清晰

调试模式

通过以下方式启用详细的并发调用日志：

查看迭代轮次
规划工具调用
查看工具返回结果
最终 AI 输出

许可证

本项目采用 MIT 许可证。

贡献指南

欢迎通过 Issue 和 Pull Request 来改进这个项目！

注意: 本项目仅为演示 AI 工具调用的最佳实践和 API 的使用方法，请勿用于生产环境。