# FA-MCP

**Repository Path**: carllee34/fa-mcp

## Basic Information

- **Project Name**: FA-MCP
- **Description**: 这是一个基于 FastMCP 框架构建的企业级金融数据服务系统，集成了 Akshare 数据同步服务和 API 网关。系统提供完整的中国金融市场数据获取、存储、缓存和 API 服务功能。
- **Primary Language**: Python
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-06-30
- **Last Updated**: 2025-08-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 金融数据 MCP 服务系统

## 项目概述

这是一个基于 FastMCP 框架构建的企业级金融数据服务系统，集成了 Akshare 数据同步服务和 API 网关。系统提供完整的中国金融市场数据获取、存储、缓存和 API 服务功能。

### 核心特性

- 🚀 **高性能异步架构**: 基于 FastAPI + SQLAlchemy 异步 ORM
- 📊 **全面数据覆盖**: 股票、指数、基金、债券等金融数据
- 🔄 **智能数据同步**: 实时、日频、低频三级同步策略
- 💾 **多级缓存系统**: 内存缓存 + Redis 缓存 + 智能缓存管理
- 📅 **任务调度系统**: 基于 Cron 表达式的灵活任务调度
- 🛡️ **企业级安全**: API 密钥验证、速率限制、CORS 支持
- 📈 **数据质量保证**: 五维度数据质量检查和监控
- 🐳 **容器化部署**: Docker + Docker Compose 一键部署
- 📖 **完整 API 文档**: 自动生成的 OpenAPI 文档

## 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   API网关       │    │  数据同步服务    │    │  任务调度器     │
│  (FastAPI)      │    │  (Akshare)      │    │  (AsyncIO)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
         ┌─────────────────────────────────────────────────┐
         │              统一服务管理器                      │
         │           (FinancialMCPServer)                  │
         └─────────────────────────────────────────────────┘
                                 │
         ┌─────────────────────────────────────────────────┐
         │                数据存储层                        │
         │  PostgreSQL + Redis + 多级缓存系统              │
         └─────────────────────────────────────────────────┘
```

## 快速开始

### 环境要求

- Python 3.11+
- PostgreSQL 13+
- Redis 6+
- Docker & Docker Compose (可选)

### 1. 克隆项目

```bash
git clone <repository-url>
cd financial-mcp-service
```

### 2. 环境配置

```bash
# 复制环境配置文件
cp .env.example .env

# 编辑配置文件
vim .env
```

### 3. 安装依赖

```bash
# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate     # Windows

# 安装依赖
pip install -r requirements.txt
```

### 4. 数据库初始化

```bash
# 启动PostgreSQL和Redis (如果使用Docker)
docker-compose up -d postgres redis

# 运行数据库迁移
python -c "
from src.core.database import DatabaseManager
import asyncio
async def init_db():
    db = DatabaseManager()
    await db.initialize()
    await db.create_tables()
asyncio.run(init_db())
"
```

### 5. 启动服务

#### 方式一：直接启动

```bash
python src/main_server.py
```

#### 方式二：Docker Compose 启动

```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f financial_service
```

### 6. 验证服务

```bash
# 健康检查
curl http://localhost:8000/health

# API文档
open http://localhost:8000/docs
```

## 服务端口

| 服务       | 端口 | 描述              |
| ---------- | ---- | ----------------- |
| API 网关   | 8000 | 主要 API 服务端口 |
| MCP 服务   | 8001 | MCP 协议服务端口  |
| PostgreSQL | 5432 | 数据库服务端口    |
| Redis      | 6379 | 缓存服务端口      |

## API 接口文档

### 核心接口

#### 1. 健康检查

```http
GET /health
```

#### 2. 股票数据

```http
GET /api/v1/stocks?symbol=000001&limit=100&offset=0
GET /api/v1/stocks/{symbol}
```

#### 3. 指数数据

```http
GET /api/v1/indices?symbol=000001&limit=100&offset=0
GET /api/v1/indices/{symbol}
```

#### 4. 基金数据

```http
GET /api/v1/funds?symbol=000001&limit=100&offset=0
GET /api/v1/funds/{symbol}
```

#### 5. 债券数据

```http
GET /api/v1/bonds?symbol=000001&limit=100&offset=0
GET /api/v1/bonds/{symbol}
```

#### 6. 数据同步管理

```http
GET /api/v1/sync/status
POST /api/v1/sync/trigger
GET /api/v1/sync/tasks
```

#### 7. 系统统计

```http
GET /api/v1/stats/overview
GET /api/v1/stats/performance
```

### 查询参数

| 参数       | 类型    | 描述                  | 默认值     |
| ---------- | ------- | --------------------- | ---------- |
| symbol     | string  | 股票/基金/债券代码    | -          |
| limit      | integer | 返回记录数量          | 100        |
| offset     | integer | 偏移量                | 0          |
| start_date | string  | 开始日期 (YYYY-MM-DD) | -          |
| end_date   | string  | 结束日期 (YYYY-MM-DD) | -          |
| sort_by    | string  | 排序字段              | trade_date |
| sort_order | string  | 排序方向 (asc/desc)   | desc       |

## 配置说明

### 数据库配置

```env
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/dbname
DATABASE_POOL_SIZE=20
DATABASE_MAX_OVERFLOW=30
```

### Redis 配置

```env
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_POOL_SIZE=20
```

### 数据同步配置

```env
SYNC_BATCH_SIZE=1000
SYNC_MAX_WORKERS=10
SYNC_RETRY_ATTEMPTS=3
```

### 任务调度配置

```env
SYNC_STOCK_CRON=0 */1 * * * *    # 每分钟同步股票数据
SYNC_INDEX_CRON=0 */5 * * * *    # 每5分钟同步指数数据
SYNC_FUND_CRON=0 0 */1 * * *     # 每小时同步基金数据
SYNC_BOND_CRON=0 0 */6 * * *     # 每6小时同步债券数据
```

## 数据同步策略

### 同步频率

| 数据类型 | 同步频率  | Cron 表达式     | 说明         |
| -------- | --------- | --------------- | ------------ |
| 股票数据 | 每分钟    | `0 */1 * * * *` | 实时价格数据 |
| 指数数据 | 每 5 分钟 | `0 */5 * * * *` | 市场指数数据 |
| 基金数据 | 每小时    | `0 0 */1 * * *` | 基金净值数据 |
| 债券数据 | 每 6 小时 | `0 0 */6 * * *` | 债券价格数据 |

### 数据质量检查

系统实施五维度数据质量检查：

1. **完整性检查**: 验证必填字段和数据完整性
2. **准确性检查**: 验证数据格式和数值范围
3. **一致性检查**: 验证数据逻辑一致性
4. **及时性检查**: 验证数据更新时间
5. **有效性检查**: 验证数据业务有效性

## 缓存策略

### 多级缓存架构

```
请求 → L1缓存(内存) → L2缓存(Redis) → 数据库
```

### 缓存配置

| 缓存类型   | TTL    | 最大大小  | 清理间隔 |
| ---------- | ------ | --------- | -------- |
| 内存缓存   | 1 小时 | 10,000 条 | 5 分钟   |
| Redis 缓存 | 6 小时 | 无限制    | 自动     |

## 监控和日志

### 日志配置

```env
LOG_LEVEL=INFO
LOG_FORMAT=json
LOG_FILE_PATH=logs/financial_service.log
```

### 监控指标

- API 请求响应时间
- 数据同步成功率
- 缓存命中率
- 数据库连接池状态
- 任务执行状态

## 部署指南

### Docker 部署

```bash
# 构建镜像
docker build -t financial-service .

# 启动服务
docker-compose up -d

# 扩容服务
docker-compose up -d --scale financial_service=3
```

### 生产环境配置

```env
ENVIRONMENT=production
DEBUG=false
LOG_LEVEL=WARNING
MCP_WORKERS=8
DATABASE_POOL_SIZE=50
API_KEY_REQUIRED=true
RATE_LIMIT_REQUESTS=500
```

## 开发指南

### 项目结构

```
financial-mcp-service/
├── src/
│   ├── core/                 # 核心模块
│   │   ├── config.py        # 配置管理
│   │   ├── database.py      # 数据库管理
│   │   ├── cache.py         # 缓存管理
│   │   └── exceptions.py    # 异常定义
│   ├── models/              # 数据模型
│   │   ├── base.py         # 基础模型
│   │   ├── stock.py        # 股票模型
│   │   ├── index.py        # 指数模型
│   │   ├── fund.py         # 基金模型
│   │   └── bond.py         # 债券模型
│   ├── data_sync_service.py # 数据同步服务
│   ├── api_gateway.py       # API网关
│   ├── scheduler_service.py # 任务调度器
│   └── main_server.py       # 主服务器
├── docker-compose.yml       # Docker编排
├── Dockerfile              # Docker镜像
├── requirements.txt        # Python依赖
├── .env.example           # 环境配置示例
└── README.md              # 项目文档
```

### 添加新的数据源

1. 在 `src/models/` 中定义数据模型
2. 在 `src/data_sync_service.py` 中添加同步逻辑
3. 在 `src/api_gateway.py` 中添加 API 接口
4. 在 `src/scheduler_service.py` 中配置调度任务

### 代码规范

```bash
# 代码格式化
black src/
isort src/

# 代码检查
flake8 src/
mypy src/

# 运行测试
pytest tests/
```

## 故障排除

### 常见问题

#### 1. 数据库连接失败

```bash
# 检查数据库状态
docker-compose ps postgres

# 查看数据库日志
docker-compose logs postgres
```

#### 2. Redis 连接失败

```bash
# 检查Redis状态
docker-compose ps redis

# 测试Redis连接
redis-cli ping
```

#### 3. 数据同步失败

```bash
# 查看同步日志
docker-compose logs financial_service | grep sync

# 手动触发同步
curl -X POST http://localhost:8000/api/v1/sync/trigger
```

#### 4. API 响应慢

```bash
# 检查缓存状态
curl http://localhost:8000/api/v1/stats/performance

# 清理缓存
curl -X POST http://localhost:8000/api/v1/cache/clear
```

### 性能优化

1. **数据库优化**

   - 增加连接池大小
   - 添加适当索引
   - 启用查询缓存

2. **缓存优化**

   - 调整缓存 TTL
   - 增加缓存容量
   - 优化缓存策略

3. **同步优化**
   - 调整批处理大小
   - 增加工作线程数
   - 优化同步频率

## 安全考虑

### API 安全

- API 密钥验证
- 速率限制
- CORS 配置
- JWT 令牌认证

### 数据安全

- 数据库连接加密
- 敏感信息环境变量存储
- 定期数据备份
- 访问日志记录

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 贡献指南

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 支持

如有问题或建议，请通过以下方式联系：

- 提交 Issue
- 发送邮件至 lixin_ff@126.com

---

**注意**: 本系统仅供学习和研究使用，请遵守相关法律法规和数据提供商的使用条款。