内容
# Cegid Y2 MCP 服务器
**Cegid Y2 ERP 集成模型上下文协议服务器**
版本：1.0.0
作者：
许可证：MIT
## 📋 概述
一个生产就绪的模型上下文协议（MCP）服务器，提供与 Cegid Y2 ERP 系统的无缝集成。该服务器通过 MCP 资源、工具和提示，安全地使 AI 模型和应用程序能够与 ERP 数据交互。
### 主要功能
✅ **完全符合 MCP 1.0 标准**
- 资源（只读数据访问）
- 工具（可操作操作）
- 提示（AI 优化模板）
✅ **Cegid Y2 集成**
- 所有主要 API 端点
- 发票、客户、产品、订单、财务数据
- 二维码验证
- 批量操作
✅ **企业安全**
- OAuth2、API 密钥、JWT 身份验证
- 速率限制
- CORS 配置
- 输入净化
✅ **高性能**
- Redis 缓存，TTL 可配置
- 连接池
- 异步/等待架构
- 内存备用
✅ **生产就绪**
- Docker 和 Docker Compose
- 全面的日志记录
- 健康检查
- 监控端点
✅ **开发者友好**
- FastAPI 文档
- 多种身份验证选项
- 丰富的示例
- 单元测试
## 🚀 快速入门
### 前提条件
- Python 3.11+
- Docker 和 Docker Compose（推荐）
- Redis（可选，用于缓存）
- PostgreSQL（可选，用于数据存储）
### 选项 1：Docker（推荐）
```bash
# 克隆仓库
cd cegid_y2_mcp
# 复制环境文件
cp config/.env.example config/.env
# 编辑 .env 文件，添加您的凭证
nano config/.env
# 启动服务
docker-compose -f docker/docker-compose.yml up -d
# 查看日志
docker-compose logs -f mcp-server
# 测试 API
curl http://localhost:8000/health
```
### 选项 2：本地安装
```bash
# 安装依赖
pip install -r requirements.txt
# 设置环境变量
export CEGID_API_KEY="your_key_here"
export JWT_SECRET_KEY="your_secret_here"
# 运行服务器
python src/mcp_server.py
# 访问 http://localhost:8000
```
## 📚 API 文档
### 健康检查
```bash
curl http://localhost:8000/health
```
### 列出资源
```bash
curl http://localhost:8000/resources
```
### 读取资源
```bash
curl http://localhost:8000/resources/invoices/INV-001
```
### 列出工具
```bash
curl http://localhost:8000/tools
```
### 调用工具
```bash
curl -X POST http://localhost:8000/tools/list_invoices \
-H "Content-Type: application/json" \
-d '{"limit": 10, "offset": 0}'
```
### 获取提示
```bash
curl http://localhost:8000/prompts
```
## 🔧 配置
### config.json
主要配置文件，包含：
- 服务器设置
- Cegid API 凭证
- 身份验证选项
- Redis 配置
- 速率限制
- CORS 设置
- 日志记录
### .env 文件
环境变量覆盖 config.json：
- `CEGID_API_KEY` - 您的 Cegid API 密钥
- `JWT_SECRET_KEY` - JWT 签名密钥
- `REDIS_HOST` - Redis 服务器主机
- `DEFAULT_API_KEY` - 默认 API 密钥用于身份验证
## 🛠️ 可用资源
### 发票
- `cegid://invoices` - 列出所有发票
- `cegid://invoices/{id}` - 获取发票详情
### 客户
- `cegid://customers` - 列出所有客户
- `cegid://customers/{id}` - 获取客户详情
### 产品
- `cegid://products` - 列出所有产品
- `cegid://products/{id}` - 获取产品详情
### 订单
- `cegid://orders` - 列出所有订单
- `cegid://orders/{id}` - 获取订单详情
### 财务
- `cegid://financial/{period}` - 获取财务摘要
- `cegid://dashboard` - 获取仪表盘数据
## 🛠️ 可用工具
### 发票操作
- `list_invoices` - 列出发票，带过滤器
- `get_invoice_details` - 获取发票详情
- `create_invoice` - 创建新发票
- `update_invoice` - 更新现有发票
- `delete_invoice` - 删除发票
- `search_invoices` - 按关键词搜索发票
- `batch_get_invoices` - 获取多个发票
### 客户操作
- `list_customers` - 列出客户
- `get_customer_details` - 获取客户详情
- `create_customer` - 创建新客户
- `update_customer` - 更新客户
### 产品操作
- `list_products` - 列出产品
- `get_product_details` - 获取产品详情
### 订单操作
- `list_orders` - 列出订单
- `get_order_details` - 获取订单详情
### 财务操作
- `get_financial_summary` - 获取财务摘要
- `validate_qr_code` - 验证二维码
## 🤖 可用提示
### 分析发票
分析发票的异常并生成摘要
```bash
curl http://localhost:8000/prompts/analyze_invoice \
-d '{"invoice_id": "INV-001"}'
```
### 客户报告
生成综合客户报告
```bash
curl http://localhost:8000/prompts/customer_report \
-d '{"customer_id": "CUST-001", "period": "2025-01"}'
```
### 财务分析
分析财务数据和趋势
```bash
curl http://localhost:8000/prompts/financial_analysis \
-d '{"period": "2025-01"}'
```
### 欺诈检测
分析交易中的欺诈模式
```bash
curl http://localhost:8000/prompts/fraud_detection \
-d '{"threshold": 50}'
```
## 🔐 身份验证
### API 密钥身份验证
```bash
curl http://localhost:8000/tools/list_invoices \
-H "X-API-Key: your_api_key_here"
```
### JWT 令牌身份验证
```bash
# 生成令牌（内部端点）
TOKEN=$(curl -X POST http://localhost:8000/auth/token \
-d '{"user_id": "user123"}')
# 使用令牌
curl http://localhost:8000/tools/list_invoices \
-H "Authorization: Bearer $TOKEN"
```
### OAuth2（可选）
在 .env 文件中为 Cegid 提供商身份验证配置 OAuth2。
## 📊 监控和指标
### 健康检查
```bash
curl http://localhost:8000/health
```
### 服务器功能
```bash
curl http://localhost:8000/capabilities
```
### 指标
```bash
curl http://localhost:8000/metrics
```
## 🧪 测试
```bash
# 安装测试依赖
pip install pytest pytest-asyncio pytest-cov
# 运行测试
pytest tests/ -v
# 带有覆盖率
pytest tests/ --cov=src --cov-report=html
```
## 🐳 Docker 部署
### 启动服务
```bash
docker-compose -f docker/docker-compose.yml up -d
```
### 停止服务
```bash
docker-compose -f docker/docker-compose.yml down
```
### 查看日志
```bash
docker-compose -f docker/docker-compose.yml logs -f mcp-server
```
### 包含的服务
- **mcp-server**: FastAPI 应用程序
- **redis**: 缓存层
- **postgres**: 可选数据库
## 🔄 集成示例
### Python 客户端
```python
import requests
headers = {"X-API-Key": "your_api_key"}
# 列出发票
response = requests.get(
"http://localhost:8000/resources/invoices",
headers=headers
)
invoices = response.json()
```
### curl 命令
```bash
# 列出发票
curl -H "X-API-Key: your_key" \
http://localhost:8000/resources/invoices
# 创建发票
curl -X POST http://localhost:8000/tools/create_invoice \
-H "Content-Type: application/json" \
-H "X-API-Key: your_key" \
-d '{
"customer_id": "CUST-001",
"amount": 1000,
"currency": "USD"
}'
```
### JavaScript/Node.js
```javascript
const fetch = require('node-fetch');
const headers = {
'X-API-Key': 'your_api_key',
'Content-Type': 'application/json'
};
// 列出发票
const response = await fetch('http://localhost:8000/resources/invoices', {
headers
});
const invoices = await response.json();
```
## 🐛 故障排除
### Redis 连接错误
- 验证 Redis 是否正在运行：`redis-cli ping`
- 在配置中检查 Redis 主机/端口
- 自动回退到内存缓存
### Cegid API 错误
- 验证 API 密钥是否正确
- 检查 API URL 是否可访问
- 确保 API 密钥具有所需的权限
### 端口已被占用
```bash
# 更改配置中的端口或通过环境变量
docker-compose -f docker/docker-compose.yml up -d -p 8001:8000
```
### 权限被拒绝
```bash
# 修复文件权限
chmod -R 755 .
chmod 600 config/.env
```
## 📈 性能调优
### 启用 Redis 缓存
```json
{
"redis": {
"enabled": true,
"default_ttl": 300
}
}
```
### 调整速率限制
```json
{
"rate_limit": {
"requests_per_minute": 2000,
"requests_per_hour": 100000
}
}
```
### 增加工作线程
```bash
# 在 docker-compose.yml 中或本地运行时
export WORKERS=8
```
## 📚 架构
```
┌─────────────────┐
│ AI/客户端 │
└────────┬────────┘
│
┌────▼─────────────────┐
│ FastAPI MCP 服务器 │
│ ┌──────────────────┐ │
│ │ 资源 │ │
│ │ 工具 │ │
│ │ 提示 │ │
│ │ 身份验证 │ │
│ └──────────────────┘ │
└────┬────────┬────────┘
│ │
┌────▼──┐ ┌──▼────┐
│ Redis │ │ Cegid │
│ 缓存 │ │ API │
└───────┘ └───────┘
```
## 🔄 工作流程示例
1. 客户端使用 API 密钥进行身份验证
2. 客户端调用 `list_invoices` 工具
3. 服务器检查 Redis 缓存
4. 如果未缓存，则查询 Cegid API
5. 服务器缓存结果，带有 TTL
6. 返回响应给客户端
7. 在下一次请求时，从缓存中提供
8. 缓存超时后失效
## 📝 日志记录
日志写入：
- 控制台（stdout）
- 文件：`logs/mcp_server.log`
在 config.json 中配置：
```json
{
"logging": {
"level": "INFO",
"file": "logs/mcp_server.log",
"max_bytes": 10485760,
"backup_count": 10
}
}
```
## 🤝 贡献
欢迎贡献！请：
1. 分叉仓库
2. 创建功能分支
3. 添加测试
4. 提交拉取请求
## 📄 许可证
MIT 许可证 - 有关详细信息，请参见 LICENSE 文件
## 🆘 支持
电子邮件：
## 🚀 下一步
1. **配置凭证**：编辑 `config/.env` 文件，添加您的 Cegid 凭证
2. **启动服务器**：运行 Docker Compose 或 Python 服务器
3. **测试 API**：使用 curl 或 Postman
4. **集成客户端**：使用提供的 SDK 或 API
5. **监控**：检查日志和指标
## 🎯 路线图
- [ ] WebSocket 支持实时更新
- [ ] Webhook 通知
- [ ] 高级报告工具
- [ ] 用于欺诈检测的机器学习模型
- [ ] 多租户支持
- [ ] GraphQL 端点
---
**由 TIMSOFT Société 构建 **
最后更新：2026 年 1 月 14 日
