AI MCP Agent

“#AI MCP代理

具有MCP集成的AI Agent-面向企业的产品管理架构

  

📋 项目描述

集成MCP（Model Context Protocol）的全功能AI代理：

• 使用Langgraph定制工具
• 连接到MCP服务器以管理产品数据
• 处理用户的自然语言查询
• 为集成提供REST API
• 通过Docker Compose启动

🏗️ 建筑

┌─────────────────────────────────────────────────────────┐
│                  Docker Container                       │
│  ┌───────────────────────────────────────────────────┐  │
│  │              FastAPI Application                  │  │
│  │          POST /api/v1/agent/query                 │  │
│  │       (Получает запросы пользователя)             │  │
│  └─────────────────────┬─────────────────────────────┘  │
│                        │                                │
│                        ▼                                │
│  ┌───────────────────────────────────────────────────┐  │
│  │              LangGraph Agent                      │  │
│  │  • Анализирует запрос пользователя                │  │
│  │  • Выбирает подходящие tools                      │  │
│  │  • Вызывает tools и обрабатывает результаты       │  │
│  │  • Формирует ответ                                │  │
│  └───┬──────────────────────────────┬────────────────┘  │
│      │                              │                   │
│      ▼                              ▼                   │
│  ┌──────────────┐         ┌──────────────────────────┐  │
│  │ Custom Tools │         │   MCP Server             │  │
│  │              │         │  (stdio transport)       │  │
│  │ • Calculator │         │                          │  │
│  │ • Formatter  │         │ Tools:                   │  │
│  └──────────────┘         │ • list_products          │  │
│                           │ • get_product            │  │
│                           │ • add_product            │  │
│                           │ • get_statistics         │  │
│                           │                          │  │
│                           │ Storage:                 │  │
│                           │ • JSON file              │  │
│                           └──────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

🚀 快速启动

选项1：Docker Compose（推荐）

要求：

• Docker引擎20.10+
• Docker Compose 2.0+

启动：

# 1. Клонируйте репозиторий (если нужно)
git clone 
cd ai-mcp-agent

# 2. Запустите приложение
docker-compose up -d

# 3. Проверьте статус
docker-compose ps

# 4. Откройте API документацию
# http://localhost:8000/docs

停止：

docker-compose down

选项2：本地（无Docker）

要求：

• Python 3.11+
• pipили诗歌

依赖关系设置：

# Создайте виртуальное окружение
python -m venv venv

# Активируйте его
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Установите зависимости
pip install -r requirements.txt

启动MCP服务器：

# В отдельном терминале
python -m mcp_server.mcp_server

启动Fastapi应用程序：

# В основном терминале
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

API文档：

• Swagger用户界面：http://localhost:8000/docs
• 重新记录：http://localhost:8000/redoc

📡 API终点

健康检查

GET /health

答复：

{
  "status": "healthy",
  "message": "API is running"
}

查询代理

POST /api/v1/agent/query
Content-Type: application/json

{
  "query": "Покажи все продукты в категории Электроника"
}

答复：

{
  "query": "Покажи все продукты в категории Электроника",
  "response": "Products in Электроника: {...}",
  "status": "success"
}

例子

GET /api/v1/examples

答复：

{
  "examples": [
    {
      "query": "Покажи все продукты",
      "description": "Get all products"
    },
    ...
  ]
}

💬 使用示例

例1：获取所有产品

curl -X POST http://localhost:8000/api/v1/agent/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Покажи все продукты"}'

例2：按类别获取产品

curl -X POST http://localhost:8000/api/v1/agent/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Покажи все продукты в категории Электроника"}'

例3：获取统计数据

curl -X POST http://localhost:8000/api/v1/agent/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Какая средняя цена продуктов?"}'

例4：计算折扣

curl -X POST http://localhost:8000/api/v1/agent/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Посчитай скидку 15% на товар с ID 1"}'

例5：通过ID查找产品

curl -X POST http://localhost:8000/api/v1/agent/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Найди товар с ID 1"}'

🧪 测试

运行测试

# Запустите все тесты
pytest tests/ -v

# Запустите с покрытием
pytest tests/ --cov=app --cov=mcp_server

# Запустите конкретный тест
pytest tests/test_api.py::TestHealthEndpoint::test_health_check -v

可用测试

test_agent.py：

• TestCalculatorTool -计算器测试（3个测试）
• TestFormatterTool -格式化测试（4个测试）
• TestAgentProcessing -查询处理测试（4个测试）
• TestAgentIntegration 集成测试（3个测试）

test_api.py：

• TestHealthEndpoint 健康检查（2个测试）
• TestQueryEndpoint Query Endpoint（6个测试）
• TestExamplesEndpoint Examples Endpoint（2个测试）
• TestErrorHandling 错误处理测试（2个测试）
• TestEndpoints 一般Endpoints测试（1个测试）

共计：27+测试

测试结果示例

tests/test_agent.py::TestCalculatorTool::test_percentage_calculation PASSED
tests/test_agent.py::TestCalculatorTool::test_simple_arithmetic PASSED
tests/test_agent.py::TestFormatterTool::test_json_formatting PASSED
tests/test_api.py::TestHealthEndpoint::test_health_check PASSED
tests/test_api.py::TestQueryEndpoint::test_query_endpoint_basic PASSED
...

📦 项目结构

ai-mcp-agent/
├── app/                          # FastAPI приложение
│   ├── __init__.py
│   ├── main.py                  # FastAPI endpoints
│   └── agent.py                 # LangGraph агент
├── mcp_server/                   # MCP сервер
│   ├── __init__.py
│   └── mcp_server.py            # MCP сервер с FastMCP
├── tests/                        # Тесты
│   ├── __init__.py
│   ├── test_agent.py            # Тесты агента
│   └── test_api.py              # Тесты API
├── data/                         # Данные
│   └── products.json            # Данные о продуктах
├── .gitignore                    # Git ignore файл
├── requirements.txt              # Python зависимости
├── Dockerfile                    # Docker конфигурация
├── docker-compose.yml            # Docker Compose конфигурация
└── README.md                     # Этот файл

🔧 系统组件

MCP服务器(mcp_server/mcp_server.py)

使用： FastMCP，JSON存储

工具（Tools）：

1. list_products -获取产品列表（可选类别）
2. get_product 通过ID获取产品
3. add_product -添加新产品
4. get_statistics -获取产品统计数据

特点：

• ✅ 通过STDIO运输工作
• ✅ Type Hints适用于所有参数
• ✅ 描述
• ✅ 错误处理（valueerror）
• ✅ JSON数据序列化

LangGraph代理(app/agent.py)

使用： LangGraph，LangChain，模拟法学硕士

自定义工具：

1. calculator -表达式和折扣的计算
2. formatter 文本格式化（JSON，Uppercase，Lowercase）

特点：

• ✅ 与MCP服务器集成
• ✅ 自然语言处理
• ✅ 路由请求到正确的工具
• ✅ Mock LLM没有真正的API密钥

FastAPI应用程序(app/main.py)

终点：

1. GET /health -健康检查
2. POST /api/v1/agent/query -请求代理
3. GET /api/v1/examples 查询示例

特点：

• ✅ Pydantic型号的安全型
• ✅ CORS支持
• ✅ 记录
• ✅ 错误处理
• ✅ swagger/redoc文档

🐳 码头工人

DockerFile功能

• 多阶段构建 -优化图像大小
• 健康检查 -自动集装箱健康检查
• 薄型基础图像 -最小大小（从120MB开始）

Docker Compose服务

1. 应用程序编程接口 -端口8000上的Fastapi应用程序
2. mcp服务器 端口 3001 上的 MCP 服务器

体积：

• ./data -持久数据
• ./app -应用程序代码
• ./mcp_server -服务器MCP代码

📊 支持的查询类型

类型，例子，结果。 |-----|--------|----------| 产品列表–“显示所有产品”–完整列表。 ÐÐÐÐÐÐÐÐÐÐÐÐÐ “平均价格是多少？”统计。 –ID–“查找ID 1的产品”–特定产品–。 “计算15%的折扣”–计算结果→

🔐 安全

实施的措施：

• ✅ 类型验证сPydantic
• ✅ 错误处理和日志记录
• ✅ CORS保护
• ✅ 添加数据时的验证

关于Production的建议：

• 添加身份验证（JWT，OAuth2）
• 使用HTTPS
• 添加速度限制
• 配置防火墙规则

🛠️ 开发

添加新工具

在MCP服务器上：

@server.tool()
def my_tool(param: str) -> dict:
    """Tool description."""
    return {"result": "value"}

在代理：

@tool
def my_custom_tool(param: str) -> str:
    """Custom tool description."""
    return f"Result: {param}"

添加新的Endpoint

@app.post("/api/v1/my-endpoint")
async def my_endpoint(request: MyRequest) -> MyResponse:
    """Endpoint description."""
    # Implementation
    return response

🐛 故障排除

Проблема：端口已在使用中

# Освободите порт
# Windows:
netstat -ano | findstr :8000
taskkill /PID 
 /F

# Linux/Mac:
lsof -i :8000
kill -9 

问题： ModuleNotFoundError

# Убедитесь что виртуальное окружение активировано
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Переустановите зависимости
pip install -r requirements.txt

问题：Docker映像不可用

# Очистите Docker кэш
docker-compose down -v
docker system prune -a

# Пересоберите
docker-compose build --no-cache

📚 追加资源

• FastMCP文档
• LangGraph文档
• FastAPI文档

📄 许可证

MIT许可证-免费用于教育目的

______________________________________________________________________

版本： 1.0.0"