MCP代理

Name: MCP代理
Author: dev-muhammad

作者：dev-muhammad3 星标更新：2025-10-31

安装使用来源：spider==github.com

项目介绍

MCP Agent - AI 费用追踪器

使用自定义MCP服务器实现AI代理的实际演示。

该项目展示了如何使用模型上下文协议（MCP）构建智能AI代理。通过一个实际的费用追踪应用程序，您可以看到AI代理如何通过自然对话与工具、数据库和API进行交互以执行复杂任务。

🎯 演示内容

自定义MCP服务器：使用FastAPI构建自己的MCP服务器
AI代理集成：通过MCP协议连接AI代理到工具
实际应用：实用的费用追踪用例
自然语言接口：与AI聊天以管理您的数据
工具发现：AI自动发现并使用可用工具

🏗️ 架构

graph TB
    subgraph "后端"
        API[API服务器<br/>FastAPI + SQLite<br/>端口：8002]
        MCP[MCP服务器<br/>FastAPI-MCP<br/>端口：9002]
    end

    subgraph "AI层"
        Agent[AI代理<br/>Agno框架<br/>端口：7777]
        LLM[LLM]
    end

    subgraph "客户端层"
        UI[Web UI<br/>Next.js + React<br/>端口：3000]
        Telegram[Telegram机器人<br/>Python Telegram Bot]
        AnyClient[任何MCP客户端]
    end

    subgraph "最终用户"
        User1[用户]
        User2[用户]
        User3[用户]
    end

    API -->|暴露REST API| MCP
    MCP -->|MCP协议| Agent
    MCP -.->|MCP协议| AnyClient
    Agent -->|API调用| LLM
    Agent -->|提供服务| UI
    Agent -->|提供服务| Telegram
    UI -->|交互| User1
    Telegram -->|交互| User2
    AnyClient -.->|交互| User3

    style API fill:#0066CC,color:#fff
    style MCP fill:#00AA66,color:#fff
    style Agent fill:#FF6600,color:#fff
    style LLM fill:#8B5CF6,color:#fff
    style UI fill:#06B6D4,color:#fff
    style Telegram fill:#06B6D4,color:#fff

📖 有关详细架构文档、请求流程和部署选项，请参阅 ARCHITECTURE.md

🚀 特性

AI驱动代理：使用OpenAI GPT-4进行自然语言费用追踪
SQLite数据库：所有交易的持久存储
自动初始化：自动设置数据库并填充种子数据
MCP集成：用于AI代理的可扩展工具系统
REST API：完整的CRUD操作用于费用管理
多个客户端：Web UI、Telegram机器人和直接代理界面
智能分类：自动费用分类和洞察
货币无关：干净的数值格式化，不带货币符号

📁 项目结构

MCPAgent/
├── .env.example       # 环境变量模板
├── .env               # 您的配置（从.env.example创建）
├── agent/             # 使用Agno框架的AI代理
│   ├── agent.py       # 带有系统提示的主要代理
│   └── agno.db        # 代理的SQLite数据库
├── server/            # 带有MCP服务器的FastAPI后端
│   ├── main.py        # API路由和端点
│   ├── store.py       # SQLite数据存储
│   ├── models.py      # Pydantic数据模型
│   ├── config.py      # 配置设置
│   ├── mcp_server.py  # MCP协议服务器
│   ├── start.py       # 服务器初始化及启动
│   └── expenses.db    # 交易数据库
└── client/
    ├── agent-ui/      # Next.js Web界面
    └── telegram-bot/  # Telegram机器人客户端

🏃 快速开始

1. 安装依赖

# 安装Python依赖
pip install -r server/requirements.txt
pip install agno openai python-dotenv

2. 设置环境变量

# 复制示例并添加您的API密钥
cp .env.example .env
# 编辑.env并添加您的OPENAI_API_KEY

3. 初始化并启动服务器

cd server

# 检查依赖并初始化数据库
python start.py

# 启动MCP服务器（在一个终端中）
python start.py --mcp

# 启动API服务器（在另一个终端中）
python start.py --api

4. 运行AI代理

cd agent
python agent.py

访问代理：http://localhost:7777

💬 使用示例

与AI代理聊天：

"添加50元杂货费用"
"我昨晚花了75元吃晚餐"
"这个月我在食物上花了多少钱？"
"显示我的财务总结"
"最大的支出类别是什么？"
"添加5000元工资收入"

🛠️ 技术栈

协议：模型上下文协议（MCP）- 自定义服务器实现
代理框架：Agno
AI模型：OpenAI GPT-4
MCP服务器：FastAPI-MCP（将REST API转换为MCP工具）
后端：FastAPI + SQLite
前端：Next.js + React
机器人：Python Telegram Bot

🔌 在这里MCP是如何工作的

FastAPI后端 (server/main.py) - 标准REST API，具有CRUD操作
MCP服务器 (server/mcp_server.py) - 包装API并将其作为MCP工具公开
AI代理 (agent/agent.py) - 连接到MCP服务器并自动发现工具
自然语言 - 用户与代理聊天，代理使用工具完成任务

用户输入 → AI代理 → MCP服务器 → FastAPI → SQLite
              ↓
         工具选择与执行
              ↓
         自然语言响应

📊 API端点

GET /transactions - 列出所有交易
POST /transactions - 创建新交易
PUT /transactions/{id} - 更新交易
DELETE /transactions/{id} - 删除交易
GET /transactions/search?q= - 搜索交易
GET /summary - 财务总结
GET /summary/categories - 分类分解
GET /health - 健康检查

完整API文档：http://localhost:8002/docs

🎯 服务器命令

start.py脚本管理服务器初始化和启动：

# 检查依赖并初始化数据库
python start.py

# 只启动MCP服务器
python start.py --mcp

# 只启动API服务器
python start.py --api

# 自定义端口
python start.py --api --port 8000
python start.py --mcp --port 10000

start.py做了什么：

✅ 检查所有必需的依赖项
✅ 验证环境变量
✅ 初始化SQLite数据库
✅ 种子数据库（仅首次运行时）
✅ 启动请求的服务器

🤖 代理能力

AI代理可以：

创建、读取、更新和删除费用
按关键词搜索交易
生成财务总结和洞察
分析按类别划分的消费模式
提供预算建议
按日期、类型或类别筛选交易

🔧 配置

环境变量（`.env`）

OPENAI_API_KEY=your_key_here    # AI代理所需
HOST=localhost                  # 服务器主机
PORT=8002                       # API服务器端口
MCP_HOST=localhost              # MCP服务器主机
MCP_PORT=9002                   # MCP服务器端口

服务器配置（`server/config.py`）

服务器主机/端口设置
数据库路径
MCP服务器配置

代理配置（`agent/agent.py`）

AI模型选择（默认：gpt-4.1）
系统提示定制
代理行为设置
数据库位置

🔍 故障排除

缺少依赖项？

pip install -r server/requirements.txt
pip install agno openai python-dotenv

数据库未初始化？

cd server && python start.py

端口已被占用？

python start.py --api --port 8003
python start.py --mcp --port 9003

代理无法连接到MCP？

确保MCP服务器正在运行：python start.py --mcp
检查agent/agent.py中的MCP URL（默认：http://localhost:9002/mcp）

📊 展示

此项目包括关于实际AI代理实现的展示：

🌐 在线演示

在线查看幻灯片 →

📁 本地文件

英文幻灯片：docs/en/index.html
俄文幻灯片：docs/ru/index.html

打开幻灯片以了解更多关于AI代理和MCP协议的信息。

📚 资源

此项目是基于并受到以下开源项目的启发而构建的：

模型上下文协议（MCP） - 将AI代理连接到工具的标准协议
FastAPI-MCP - FastAPI集成用于MCP服务器
Agno - 构建AI代理的现代框架
代理UI - AI代理的漂亮聊天界面

特别感谢这些项目及其维护者，使AI代理开发变得易于访问且有趣！🙏

📝 许可

MIT

使用AI代理和MCP构建，充满爱心❤️