# @tushare/mcp

> Tushare Model Context Protocol 服务器 - 为 AI 工具提供 100+ 金融数据接口

## 功能特性

- **三个核心工具**：`sdk_call`（通用调用）、`sdk_schema`（参数查询）、`sdk_search`（接口搜索）
- **MCP 资源**：`sdk:apis`（接口列表）、`sdk:api/<name>`（详细说明）
- **顺序分页**：自动处理大数据量查询（顺序分页 + 重试/退避）
- **字段预设**：`minimal`/`basic`/`full` 三档预设，减少数据传输
- **限流重试**：内置指数退避重试，遵循 Tushare API 限制
- **强类型安全**：基于 `@tushare/sdk`，严格类型检查，零 `any`

## 快速开始

### 安装

```bash
# 在 monorepo 中
pnpm install

# 构建
pnpm build
```

### 配置

设置 Tushare API Token：

```bash
export TUSHARE_TOKEN="your_tushare_token_here"
```

> 说明：也支持使用 `TUSHARE_API_TOKEN` 或 `TS_TOKEN` 作为别名环境变量。

### 运行

```bash
# 开发模式
pnpm dev

# 生产模式
tushare-mcp --stdio
```

### MCP 客户端配置

在 `~/.codeium/windsurf/mcp_config.json` 中添加：

```json
{
  "mcpServers": {
    "tushare": {
      "command": "npx",
      "args": [
        "@tushare/mcp",
        "--stdio"
      ],
      "env": {
        "TUSHARE_TOKEN": "your_token_here"
      }
    }
  }
}
```

## 工具使用

### sdk_search - 搜索接口

```json
{
  "name": "sdk_search",
  "arguments": {
    "q": "股票日线数据",
    "limit": 5
  }
}
```

### sdk_schema - 查看参数

```json
{
  "name": "sdk_schema", 
  "arguments": {
    "api_name": "daily"
  }
}
```

### sdk_call - 调用接口

```json
{
  "name": "sdk_call",
  "arguments": {
    "api_name": "daily",
    "params": {
      "ts_code": "000001.SZ",
      "start_date": "20240101",
      "end_date": "20240331"
    },
    "fields_preset": "basic"
  }
}
```

## 环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `TUSHARE_TOKEN` | - | **必填** Tushare API Token |
| `TUSHARE_MCP_POPULAR_TOOLS` | `20` | 热门工具数量（0=关闭） |
| `TUSHARE_MCP_MAX_CONCURRENCY` | `1` | 最大并发数 |
| `TUSHARE_MCP_TIMEOUT_MS` | `30000` | 请求超时（毫秒） |
| `TUSHARE_MCP_RETRY` | `3` | 最大重试次数 |
| `TUSHARE_MCP_BACKOFF_MS` | `200` | 退避基础毫秒数 |
| `TUSHARE_MCP_VERBOSE` | `false` | 详细日志 |
| `TUSHARE_MCP_STDIO` | `true` | 是否启用 STDIO 传输模式 |

## 工具详解：sdk_call

`sdk_call` 是通用调用器，对应 `src/tools/call.ts` 的 Schema。参数如下（蛇形命名）：

- `api_name`（string，必填）：接口名，例如 `stock_basic`、`daily`。
- `params`（object，必填）：入参对象；具体字段请通过 `sdk_schema` 查询。
- `fields`（string[]，可选）：返回字段列表；不传则返回所有字段。
- `fields_preset`（'minimal' | 'basic' | 'full'）：字段预设包。
- `paginate`（boolean，默认 false）：是否自动顺序分页抓取。
- `limit`（integer，默认 5000，1..5000）：单次请求条数上限。
- `offset`（integer，默认 0，>=0）：分页偏移量。
- `max_rows`（integer，默认 50000，1..100000）：分页模式下最多累计条数。
- `transform`（'object' | 'raw'，默认 'object'）：返回对象数组或原始二维表。

字段选择规则：`fields_preset` 与 `fields` 会做并集并去重；未指定则等同于“全部字段”。

示例（单次调用）：

```json
{
  "api_name": "stock_basic",
  "params": { "limit": 3 },
  "fields": ["ts_code", "name"]
}
```

示例（顺序分页，最多 1 万行）：

```json
{
  "api_name": "daily",
  "params": { "ts_code": "000001.SZ", "start_date": "20240101" },
  "paginate": true,
  "limit": 5000,
  "max_rows": 10000,
  "fields_preset": "basic",
  "transform": "object"
}
```

## 字段预设

- **minimal**：核心字段（3-5个），适合快速查看
- **basic**：常用字段（8-12个），适合大多数分析
- **full**：所有字段，等同于不指定 `fields`

## 常用 API

| 分类 | API | 说明 |
|------|-----|------|
| 股票 | `stock_basic` | 股票基础信息 |
| 股票 | `daily` | 日线数据 |
| 股票 | `daily_basic` | 每日基本面 |
| 基金 | `fund_basic` | 基金基础信息 |
| 基金 | `fund_nav` | 基金净值 |
| 财务 | `income` | 利润表 |
| 财务 | `balancesheet` | 资产负债表 |
| 指数 | `index_daily` | 指数日线 |

## 开发

### 项目结构

```
src/
├── cli.ts              # CLI 入口
├── server.ts           # MCP 服务器
├── env.ts              # 配置管理
├── types.ts            # 类型定义
├── errors.ts           # 错误处理
├── caller.ts           # SDK 调用器
├── schema.ts           # Schema 管理
├── search.ts           # 搜索引擎
├── resources.ts        # 资源处理
├── presets.ts          # 字段预设
├── rateLimit.ts        # 限流重试
└── tools/              # 工具实现
    ├── call.ts         # sdk_call
    ├── schema.ts       # sdk_schema
    └── search.ts       # sdk_search
```

### 命令

```bash
# 类型检查
pnpm typecheck

# 测试
pnpm test

# 构建
pnpm build

# 清理
pnpm clean
```

## License

MIT - 详见 [LICENSE](../../LICENSE)