# FinSage 🚀

> 给 AI Agent 装上「A 股眼睛」——一个专注 A 股的金融分析 **MCP Server**。
> 用自然语言分析个股、按条件选股、生成公司简报；数据默认离线 mock，填入 key 即接真实 A 股与 LLM。

🔗 **Live Demo**：https://a7c068bdc039499baa6defa9a85d7cce.gz3.agentos-app.net （交互式体验四个核心能力，默认展示离线演示数据）

FinSage 把「大语言模型的理解能力」与「金融数据」桥接起来：你（或你的 AI Agent）用中文提问，它先让 LLM 解析意图与参数，再调用数据层拉取行情/财务，最后由 LLM 合成可读的分析结论。既可作为 **MCP Server** 被任意支持 MCP 的客户端（Claude Desktop、Cursor、各类 Agent 框架）调用，也可作为 **REST API** 独立部署。

**差异化定位**：专注 **A 股 + 免费数据源（akshare）+ 可插拔 LLM**。大多数开源金融 AI 工具盯着美股，A 股场景明显供给不足——这是天然的护城河；而 MCP 形态让它刚好卡在 2026 年「Agent / 工具调用」的流量入口上。

---

## ✨ 特性

- 🤝 **MCP 原生**：四个核心 tools + 一个**组合工具**直接接入任意 MCP 客户端，让你的 Agent 能「查 A 股、做分析、做对比、出研报」
- 🔗 **组合工具 `research_company`**：一句话完成「分析 + 简报 + 同业对比」，专为 Agent 编排设计，无需多次往返
- 🌐 **Remote MCP**：默认 stdio（本地），设 `FINSAGE_MCP_TRANSPORT=sse` 即可云端暴露，被远程 Agent 通过 MCP 协议调用
- 🗣️ **自然语言接口**：`分析贵州茅台的毛利率和ROE`、`筛选低估值高ROE的股票`
- 🧩 **双层可插拔架构**：数据层（mock / akshare）、LLM 层（mock / OpenAI 兼容）
- 📴 **零依赖即可跑通**：默认 `mock` 模式离线可用，无需 API key、无需联网
- 🐳 **一键部署**：Docker / docker-compose 就绪，附带 GitHub Actions CI
- 📚 **自带 OpenAPI 文档**：REST 模式启动后访问 `/docs`

---

## 🏗️ 架构

```mermaid
flowchart LR
    C[MCP 客户端\nClaude/Cursor/Agent] -->|自然语言| MCP[FinSage MCP Server]
    API[FastAPI /api/v1] -->|自然语言| SVC[编排层 services]
    MCP --> SVC
    SVC --> LLM[LLM 层\n解析意图+合成]
    SVC --> DATA[数据层\n行情/财务]
    LLM -. mock / OpenAI兼容 .-> LLMIMPL[(LLMProvider)]
    DATA -. mock / akshare .-> DATAIMPL[(DataProvider)]
    SVC --> RESP[结构化 JSON 响应]
```

两种入口共享同一套编排与数据/LLM 层：

| 入口 | 能力 |
| --- | --- |
| MCP tools | `analyze_stock` / `screen_stocks` / `stock_report` / `compare_stocks` / **`research_company`** |
| REST API | `POST /api/v1/analyze` / `/screen` / `/report` / `/compare` / **`/research`** + `GET /health` |

---

## 🚀 快速开始

### 1. MCP 模式（推荐，零配置）

```bash
pip install -r requirements.txt
python -m finsage            # 或: finsage-mcp
```

默认以 **stdio** 方式启动 MCP Server。把它接入支持 MCP 的客户端即可。

**远程传输（Remote MCP）**：若要让云端部署的 FinSage 被**远程** Agent 通过 MCP 协议调用，设置环境变量以 SSE 模式启动：

```bash
FINSAGE_MCP_TRANSPORT=sse python -m finsage
```

> SSE 端点默认监听 `127.0.0.1:8000`（可用 `FASTMCP_SERVER_HOST` / `FASTMCP_SERVER_PORT` 调整）。远程客户端（或网关）即可用 MCP-over-SSE 连上来——这正是「给任意 Agent 装 A 股眼睛」的云端形态。

**Claude Desktop 配置**（`claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "finsage": {
      "command": "python",
      "args": ["-m", "finsage"],
      "env": {
        "FINSAGE_DATA_PROVIDER": "mock",
        "FINSAGE_LLM_PROVIDER": "mock"
      }
    }
  }
}
```

**本地调试（MCP Inspector）**：

```bash
npx @modelcontextprotocol/inspector python -m finsage
```

### 2. REST API 模式

```bash
pip install -r requirements.txt
uvicorn finsage.main:app --reload --port 8000
# 打开 http://localhost:8000/docs
```

### 3. Docker

```bash
docker compose up --build
```

### 4. 真实模式（A 股数据 + 真实 LLM）

```bash
pip install ".[real]"        # 安装 akshare + openai
cp .env.example .env
# 编辑 .env:
#   FINSAGE_DATA_PROVIDER=akshare
#   FINSAGE_LLM_PROVIDER=openai
#   FINSAGE_LLM_API_KEY=sk-xxx
python -m finsage            # 或 uvicorn finsage.main:app --port 8000
```

> 支持任意 OpenAI 兼容端点（如 DeepSeek）：把 `FINSAGE_LLM_BASE_URL` 改成对应地址即可。

---

## 📡 调用示例

**MCP**（任意客户端中自然语言即可）：

```
用户: 分析贵州茅台的毛利率和ROE
→ analyze_stock(query="分析贵州茅台的毛利率和ROE", symbol="600519")

用户: 筛选低估值高ROE的白酒股
→ screen_stocks(query="低估值高ROE的白酒股", top_n=10)

用户: 给我 600519 的公司简报
→ stock_report(symbol="600519", include_risk=true)

用户: 对比贵州茅台和五粮液
→ compare_stocks(symbols=["600519","000858"])

用户: 给我一份贵州茅台的综合研究，顺便和五粮液比一下
→ research_company(symbol="600519", compare_with=["000858"])
```

**REST**：

```bash
# 综合研究（分析 + 简报 + 同业对比，一步到位）
curl -X POST http://localhost:8000/api/v1/research \
  -H 'Content-Type: application/json' \
  -d '{"symbol":"600519","compare_with":["000858"]}'
```

**REST**：

```bash
curl -X POST http://localhost:8000/api/v1/analyze \
  -H 'Content-Type: application/json' \
  -d '{"query":"分析贵州茅台的毛利率和ROE","symbol":"600519"}'

# 对比多标的
curl -X POST http://localhost:8000/api/v1/compare \
  -H 'Content-Type: application/json' \
  -d '{"symbols":["600519","000858"]}'
```

---

## 🖥️ 交互式演示页

仓库内含一个零依赖的静态演示页 `demo/index.html`，可直接体验四个核心能力（个股分析 / 条件选股 / 公司简报 / 多标的对比），对比页带 Chart.js 图表。

- **在线体验**：https://a7c068bdc039499baa6defa9a85d7cce.gz3.agentos-app.net
- **本地运行**：用任意静态服务器打开目录即可，例如 `python -m http.server` 后访问 `demo/index.html`
- 演示页默认展示**离线 mock 演示数据**；在页面顶部填入你运行中的后端地址（默认 `http://localhost:8000`）并点「测试连接」，即可切换为实时数据

---

## 🧪 测试

```bash
pip install pytest pytest-asyncio
pytest -q
```

测试全部基于 `mock` provider，**无需网络与 API key 即可通过**。

---

## 🗺️ 路线图（中等打磨阶段）

- [x] MCP Server 形态（analyze / screen / report / compare 四工具）
- [x] 多标的对比（`/compare` + `compare_stocks`）
- [x] 组合工具 `research_company`（分析+简报+同业对比，Agent 编排落地）
- [x] Remote MCP（SSE 传输，云端可被远程 Agent 调用）
- [x] 交互式演示页 `demo/`（带图表，最利于传播）
- [ ] 新闻/公告情绪分析接入
- [ ] 技术指标（MACD/KDJ）计算层
- [ ] Streaming 流式选股过程

---

## 📄 License

MIT