claude-for-financial-services-cn

# CLAUDE.md — China Financial Services Plugins

China-market equivalent of the main `financial-services` repo. All data sourced from Chinese financial data providers (Wind 万得 / iFind 同花顺 / AkShare / china-news). Wind is the Tier-0 paid source; iFind is the Tier-1 paid source; AkShare is the Tier-2 free fallback.

## Source of truth

- **Skills** are authored in `vertical-plugins/china-finance/skills/`.
- **Agent system prompts** are at `agent-plugins/<slug>/agents/<slug>.md`.
- Agent plugins bundle vendored copies of their skills. **Never edit bundled copies directly.**

## Core data layer

Four MCP servers (multi-tier architecture):

```bash
# Start the Wind data server (万得, paid — requires WIND_API_KEY)
python3 mcp-servers/wind-mcp/server.py

# Start the AkShare data server (A-share market data, free)
python3 mcp-servers/akshare-mcp/server.py

# Start the iFind data server (同花顺, paid — requires IFIND_AUTH_TOKEN)
python3 mcp-servers/ifind-mcp/server.py

# Start the China news server (free)
python3 mcp-servers/china-news-mcp/server.py
```

All default to stdio transport. For deployment, use `--transport sse --port <PORT>`.

**Data source priority:**
1. **Wind MCP** (Tier-0 paid, v2.0) — 44 tools across 8 domains: stock_data (10), global_stock_data (10), fund_data (10), index_data (6), bond_data (4), financial_docs (2), economic_data (1), analytics_data (1)
2. **iFind MCP** (Tier-1 paid) — precise financials, macro/EDB, bonds, HK/US stocks, ESG
3. **AkShare MCP** (Tier-2 free) — basic quotes, industry classification, indices
4. **china-news MCP** (Tier-3 free) — news and announcements

iFind requires an auth token: set `IFIND_AUTH_TOKEN` env var or write to `mcp-servers/ifind-mcp/mcp_config.json`.
Get your key at https://mcp.51ifind.com/ (MCP官网 → 个人中心 → 密钥).

Wind requires an API key: set `WIND_API_KEY` env var or write to `mcp-servers/wind-mcp/mcp_config.json`.
Key starts with `ak_`. Get your key at https://aifinmarket.wind.com.cn/#/home.

AkShare documentation: https://akshare.akfamily.xyz/

## Commands

```bash
# Validate everything before push
python3 scripts/check-china.py

# Test cookbook structure (dry-run deployment)
bash scripts/test-china-cookbooks.sh

# Deploy a cookbook (dry-run or live)
bash scripts/deploy-managed-agent.sh <slug> [--dry-run]

# After editing a skill in vertical-plugins/, propagate to all agents that bundle it
python3 scripts/sync-china-skills.py

# Cross-agent handoff orchestration (reference implementation)
python3 scripts/orchestrate.py

# Validate worker output against a JSON schema
python3 scripts/validate.py <output.json> <schema.json|schema.yaml>
```

## Key conventions

- Agent frontmatter: every `agents/*.md` must have YAML `---` with `name` + `description`.
- Tool references in agent frontmatter use `mcp__akshare__*`, `mcp__ifind__*`, `mcp__wind__*`, and `mcp__china-news__*` syntax.
- Stock codes follow A-share conventions: 6-digit codes, no exchange prefix (e.g., "600519", "000001").

## Agents (4 China-market)

- `china-pitch-agent` — A-share pitch book (comps, DCF, LBO, deck)
- `china-market-researcher` — A-share sector research
- `china-earnings-reviewer` — A-share earnings analysis
- `china-model-builder` — DCF, LBO, 3-statement for Chinese equities

## Dependencies

Install per-server:
```bash
pip install -r mcp-servers/akshare-mcp/requirements.txt
pip install -r mcp-servers/ifind-mcp/requirements.txt
pip install -r mcp-servers/wind-mcp/requirements.txt
pip install -r mcp-servers/china-news-mcp/requirements.txt
```


## Data source mode switch

`IFIND_DATA_SOURCE_MODE` env var controls data source behavior:

| Mode | Value | Behavior |
|------|-------|----------|
| **iFind strict** | `ifind-only` | iFind only, error on failure, no AkShare fallback |
| **iFind priority (default)** | `ifind-fallback` | iFind first, fallback to AkShare |
| **AkShare only** | `akshare-only` | Skip iFind, use AkShare only |
| **Wind strict** | `wind-only` | Wind only, error on failure, no fallback |
| **Wind priority** | `wind-fallback` | Wind first, fallback to iFind → AkShare |

Set in config: `export IFIND_DATA_SOURCE_MODE=ifind-only`