FinSage 🚀

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

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 股、做分析、做对比」
• 🗣️ 自然语言接口：分析贵州茅台的毛利率和ROE、筛选低估值高ROE的股票
• 🧩 双层可插拔架构：数据层（mock / akshare）、LLM 层（mock / OpenAI 兼容）
• 📴 零依赖即可跑通：默认 mock 模式离线可用，无需 API key、无需联网
• 🐳 一键部署：Docker / docker-compose 就绪，附带 GitHub Actions CI
• 📚 自带 OpenAPI 文档：REST 模式启动后访问 /docs

---

🏗️ 架构

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
REST API	POST /api/v1/analyze / /screen / /report / /compare + GET /health

---

🚀 快速开始

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

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

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

Claude Desktop 配置（claude_desktop_config.json）：

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

本地调试（MCP Inspector）：

npx @modelcontextprotocol/inspector python -m finsage

2. REST API 模式

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

3. Docker

docker compose up --build

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

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"])

REST：

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"]}'

---

🧪 测试

pip install pytest pytest-asyncio
pytest -q

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

---

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

• [x] MCP Server 形态（analyze / screen / report / compare 四工具）
• [x] 多标的对比（/compare + compare_stocks）
• [ ] 新闻/公告情绪分析接入
• [ ] 技术指标（MACD/KDJ）计算层
• [ ] Streaming 流式选股过程
• [ ] 前端演示页（带图表，最利于传播）

---

📄 License

MIT