> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reportify.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Reportify MCP 介绍和快速开始指南

## 概述

Reportify MCP 是一个基于 MCP (Model Context Protocol) 协议的金融数据服务，提供文档搜索、公司财务数据、股票行情等丰富的金融信息查询工具。通过 MCP 协议，您可以：

* 搜索和获取金融文档内容
* 查询公司财务数据和基本信息
* 获取实时股票行情和历史数据
* 与智能体进行对话交互

## 架构设计

服务采用 **Gateway + 多 MCP 服务器** 架构，按功能分类提供 4 个独立的 MCP 端点：

```
MCP Gateway (https://mcp.reportify.cn)
├── /search/mcp    - 文档搜索类工具
├── /stock/mcp     - 股票数据类工具
├── /agent/mcp     - Agent 对话类工具
└── /following/mcp - 账号关注/频道/时间线/关注组工具
```

每个端点都是独立的 MCP 服务器，客户端可以按需选择连接。

<CardGroup cols={2}>
  <Card title="Search MCP" icon="magnifying-glass" color="#0072ff">
    文档搜索类工具

    * 综合文档搜索（财报、研报、公告等）
    * 语义搜索和内容块检索
    * 文档列表和详情获取
    * 知识库搜索
  </Card>

  <Card title="Stock MCP" icon="chart-candlestick" color="#0072ff">
    股票数据类工具

    * 公司基本信息和财务报表
    * 实时行情和历史股价
    * 指数和行业数据
    * 量化分析工具
  </Card>

  <Card title="Agent MCP" icon="robot" color="#0072ff">
    Agent 对话类工具

    * 创建和管理对话会话
    * 发送消息并接收响应
    * 获取对话历史和生成文件
  </Card>

  <Card title="Following MCP" icon="rss" color="#0072ff">
    账号关注 / 频道 / 时间线 / 关注组 工具

    * 公司关注（关注/取关/已关注列表）
    * 频道搜索与订阅管理
    * 公司/话题/机构/媒体时间线
    * 关注组管理
  </Card>
</CardGroup>

## 接入配置

### MCP 服务端点

| 服务            | 端点 URL                                   | 说明                |
| ------------- | ---------------------------------------- | ----------------- |
| Search MCP    | `https://mcp.reportify.cn/search/mcp`    | 文档搜索类工具           |
| Stock MCP     | `https://mcp.reportify.cn/stock/mcp`     | 股票数据类工具           |
| Agent MCP     | `https://mcp.reportify.cn/agent/mcp`     | Agent 对话类工具       |
| Following MCP | `https://mcp.reportify.cn/following/mcp` | 账号关注/频道/时间线/关注组工具 |

### 客户端配置

<Tabs>
  <Tab title="Cursor">
    在 Cursor 的 MCP 配置文件中添加以下配置（可按需选择部分或全部服务）：

    ```json theme={null}
    {
      "mcpServers": {
        "reportify-search": {
          "url": "https://mcp.reportify.cn/search/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        },
        "reportify-stock": {
          "url": "https://mcp.reportify.cn/stock/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        },
        "reportify-agent": {
          "url": "https://mcp.reportify.cn/agent/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        },
        "reportify-following": {
          "url": "https://mcp.reportify.cn/following/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    在 Claude Desktop 的配置文件中添加：

    ```json theme={null}
    {
      "mcpServers": {
        "reportify-search": {
          "command": "mcp-client",
          "args": ["https://mcp.reportify.cn/search/mcp"],
          "env": {
            "AUTHORIZATION": "Bearer YOUR_API_KEY"
          }
        },
        "reportify-stock": {
          "command": "mcp-client",
          "args": ["https://mcp.reportify.cn/stock/mcp"],
          "env": {
            "AUTHORIZATION": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Warning>
  必须在配置中包含 `Authorization` 字段，否则请求将无法通过认证
</Warning>

## 认证

所有 MCP 请求都需要在 HTTP 请求头中包含 Bearer Token：

```
Authorization: Bearer YOUR_API_KEY
```

<Info>
  **获取 API Key**

  * 将 `YOUR_API_KEY` 替换为您的实际 API Key
  * 注意 `Bearer` 后面有一个空格
  * API Key 可以在 [Reportify 控制台](https://reportify.cn/developer) 获取
</Info>

## Tools 参考

### Search MCP (`/search/mcp`)

文档与搜索相关工具。

<Info>
  股票代码使用 `market:ticker` 格式，如 `US:AAPL`、`HK:00700`、`SH:600519`
</Info>

<AccordionGroup>
  <Accordion title="搜索工具" icon="magnifying-glass" defaultOpen>
    | 工具名                    | 功能描述                                                                                                                               |
    | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
    | `comprehensive_search` | 综合搜索金融投资文档                                                                                                                         |
    | `earnings_search`      | Search for earnings-related documents submitted to exchanges (query optional, sorted by date desc or relevance)                    |
    | `conferences_search`   | Search for earnings-related conference call transcripts and presentation slides (query optional, sorted by date desc or relevance) |
    | `minutes_search`       | 搜索电话会议和 IR 会议                                                                                                                      |
    | `reports_search`       | 搜索机构研究报告                                                                                                                           |
    | `filings_search`       | 搜索公司公告                                                                                                                             |
    | `news_search`          | 搜索金融新闻                                                                                                                             |
    | `socials_search`       | 搜索社交媒体内容                                                                                                                           |
    | `webpage_search`       | 搜索网页内容                                                                                                                             |
    | `kb_search`            | 搜索知识库                                                                                                                              |

    **公共参数**：

    | 参数               | 类型        | 必填 | 说明                         |
    | ---------------- | --------- | -- | -------------------------- |
    | `query`          | string    | 是  | 搜索关键词                      |
    | `num`            | integer   | 否  | 返回结果数量，默认 10               |
    | `symbols`        | string\[] | 否  | 股票代码列表（格式：`market:ticker`） |
    | `start_datetime` | string    | 否  | 开始时间                       |
    | `end_datetime`   | string    | 否  | 结束时间                       |
  </Accordion>

  <Accordion title="文档工具" icon="file">
    | 工具名                    | 功能描述      |
    | ---------------------- | --------- |
    | `docs_list`            | 文档列表查询    |
    | `docs_by_symbols`      | 按股票代码查询文档 |
    | `docs_by_tags`         | 按标签查询文档   |
    | `document_fetch`       | 获取文档详情    |
    | `document_raw_content` | 获取文档原始内容  |
    | `document_summary`     | 获取文档摘要    |
    | `docs_upload`          | 上传文档      |
    | `docs_delete`          | 删除文档      |
    | `folder_create`        | 创建文件夹     |
    | `folder_delete`        | 删除文件夹     |
  </Accordion>
</AccordionGroup>

***

### Stock MCP (`/stock/mcp`)

股票数据、概念板块和量化分析工具。

<Info>
  股票代码直接使用 ticker，不带市场前缀，如 `AAPL`、`00700`、`600519`
</Info>

<AccordionGroup>
  <Accordion title="公司数据" icon="building" defaultOpen>
    | 工具名                    | 功能描述      |
    | ---------------------- | --------- |
    | `company_overview`     | 获取公司基本面信息 |
    | `company_shareholders` | 获取股东信息    |
    | `income_statement`     | 获取利润表     |
    | `balance_sheet`        | 获取资产负债表   |
    | `cashflow_statement`   | 获取现金流量表   |
    | `revenue_breakdown`    | 获取营收构成    |

    **公共参数**：

    | 参数       | 类型      | 必填 | 说明                     |
    | -------- | ------- | -- | ---------------------- |
    | `symbol` | string  | 是  | 股票代码（不带市场前缀）           |
    | `period` | string  | 否  | 报告周期（annual/quarterly） |
    | `limit`  | integer | 否  | 返回记录数量                 |
  </Accordion>

  <Accordion title="行情数据" icon="chart-candlestick">
    | 工具名                 | 功能描述      |
    | ------------------- | --------- |
    | `stock_quote`       | 获取股票行情    |
    | `index_quote`       | 获取指数行情    |
    | `earnings_calendar` | 财报日历      |
    | `ipo_calendar_hk`   | 港股 IPO 日历 |
  </Accordion>

  <Accordion title="指数和行业" icon="chart-pie">
    | 工具名                     | 功能描述          |
    | ----------------------- | ------------- |
    | `index_constituents`    | 获取指数成分股       |
    | `index_tracking_funds`  | 获取指数跟踪基金（ETF） |
    | `industry_constituents` | 获取行业成分股       |
    | `concepts_today`        | 今日概念板块        |
    | `concepts_latest`       | 最新概念动态        |
    | `followed_companies`    | 用户关注的公司       |
  </Accordion>

  <Accordion title="量化分析" icon="calculator">
    | 工具名               | 功能描述                                       |
    | ----------------- | ------------------------------------------ |
    | `factors`         | 获取可用因子列表（含变量、函数、技术指标、基本面因子）                |
    | `factors_compute` | 计算因子值（RSI, MACD, KDJ, BOLL, ATR 等技术指标也在其中） |
    | `factors_screen`  | 因子筛选选股                                     |
    | `ohlcv`           | 获取单只股票 OHLCV 数据                            |
    | `ohlcv_batch`     | 批量获取多只股票 OHLCV 数据                          |
    | `kline`           | 获取 K 线数据（支持 1M/5M/15M/30M/60M/1D/1W/1MO）   |
    | `kline_batch`     | 批量获取多只股票 K 线                               |
    | `backtest`        | 策略回测                                       |

    **支持的因子类型**：

    * 技术因子：`RSI(14)`, `MACD()`, `BOLL(20,2)`, `KDJ()`, `ATR(14)` 等
    * 基本面因子：`PE()`, `PE_TTM()`, `PB()`, `ROE()`, `ROA()`, `EPS()` 等
    * 财务报表：`INCOME.net_profit`, `BALANCESHEET.total_assets` 等
    * 组合筛选：`(PE() < 20) & (RSI(14) < 40)`
  </Accordion>
</AccordionGroup>

***

### Agent MCP (`/agent/mcp`)

Agent 对话相关工具。

<Accordion title="对话工具" icon="robot" defaultOpen>
  | 工具名                   | 功能描述           |
  | --------------------- | -------------- |
  | `create_conversation` | 创建新对话          |
  | `agent_chat`          | 与 Agent 对话     |
  | `get_conversation`    | 获取对话详情         |
  | `list_messages`       | 列出对话消息         |
  | `get_message_events`  | 获取消息事件         |
  | `cancel_execution`    | 取消 Agent 执行    |
  | `get_agent_file`      | 获取 Agent 生成的文件 |

  **使用流程**：

  1. 调用 `create_conversation` 创建对话，获取 `conversation_id`
  2. 调用 `agent_chat` 发送消息，传入 `conversation_id` 和 `message`
  3. 调用 `get_message_events` 获取响应内容
  4. 如需要，调用 `get_agent_file` 获取生成的文件
</Accordion>

***

### Following MCP (`/following/mcp`)

账号关注 / 频道 / 时间线 / 关注组 工具。

<AccordionGroup>
  <Accordion title="账号关注工具" icon="user-plus" defaultOpen>
    | 工具名                  | 功能描述    |
    | -------------------- | ------- |
    | `followed_companies` | 获取已关注公司 |
    | `follow_company`     | 关注公司    |
    | `unfollow_company`   | 取消关注公司  |
  </Accordion>

  <Accordion title="频道工具" icon="rss">
    | 工具名                  | 功能描述    |
    | -------------------- | ------- |
    | `channels_search`    | 搜索频道    |
    | `following_channels` | 获取已关注频道 |
    | `channel_follow`     | 关注频道    |
    | `channel_unfollow`   | 取消关注频道  |
    | `channel_docs`       | 获取频道文档  |
  </Accordion>

  <Accordion title="时间线工具" icon="clock">
    | 工具名                     | 功能描述    |
    | ----------------------- | ------- |
    | `timeline_companies`    | 公司时间线   |
    | `timeline_topics`       | 话题时间线   |
    | `timeline_institutes`   | 机构时间线   |
    | `timeline_public_media` | 公共媒体时间线 |
    | `timeline_social_media` | 社交媒体时间线 |
  </Accordion>

  <Accordion title="关注组工具" icon="users">
    | 工具名                           | 功能描述          |
    | ----------------------------- | ------------- |
    | `follow_group_create`         | 创建关注组         |
    | `follow_group_list`           | 获取关注组列表       |
    | `follow_group_get`            | 获取关注组详情       |
    | `follow_group_update`         | 更新关注组         |
    | `follow_group_delete`         | 删除关注组         |
    | `follow_group_add_follows`    | 关注组添加关注       |
    | `follow_group_remove_follows` | 关注组移除关注       |
    | `follow_group_set_follows`    | 关注组设置关注（全量替换） |
    | `follow_group_docs`           | 获取关注组文档       |
  </Accordion>
</AccordionGroup>

## 快速开始

<Tabs>
  <Tab title="搜索财报">
    使用 Search MCP 搜索苹果公司最近的财报相关文档：

    ```json theme={null}
    {
      "tool": "earnings_search",
      "parameters": {
        "query": "revenue growth",
        "symbols": ["US:AAPL"],
        "num": 5
      }
    }
    ```
  </Tab>

  <Tab title="获取公司数据">
    使用 Stock MCP 获取特斯拉公司的基本信息：

    ```json theme={null}
    {
      "tool": "company_overview",
      "parameters": {
        "symbols": "TSLA"
      }
    }
    ```
  </Tab>

  <Tab title="获取股票行情">
    使用 Stock MCP 获取股票行情：

    ```json theme={null}
    {
      "tool": "stock_quote",
      "parameters": {
        "symbol": "AAPL"
      }
    }
    ```
  </Tab>

  <Tab title="搜索研报">
    使用 Search MCP 搜索 AI 行业相关的研究报告：

    ```json theme={null}
    {
      "tool": "reports_search",
      "parameters": {
        "query": "artificial intelligence market analysis",
        "num": 10,
        "start_datetime": "2025-01-01 00:00:00"
      }
    }
    ```
  </Tab>

  <Tab title="因子选股">
    使用 Stock MCP 筛选低市盈率且 ROE 高的股票：

    ```json theme={null}
    {
      "tool": "factors_screen",
      "parameters": {
        "market": "cn",
        "formula": "(PE() < 20) & (ROE() > 0.15)"
      }
    }
    ```
  </Tab>

  <Tab title="计算指标">
    使用 Stock MCP 计算 RSI 指标：

    ```json theme={null}
    {
      "tool": "factors_compute",
      "parameters": {
        "market": "cn",
        "symbols": ["000001", "600519"],
        "formula": "RSI(14)",
        "start_date": "2025-01-01"
      }
    }
    ```
  </Tab>
</Tabs>

## 股票代码格式

<Warning>
  **注意**：Search MCP 和 Stock MCP 使用不同的股票代码格式
</Warning>

### Search MCP（搜索和文档）

使用 `market:ticker` 格式：

| 市场 | 格式      | 示例                               |
| -- | ------- | -------------------------------- |
| 美股 | `US:代码` | `US:AAPL`, `US:GOOGL`, `US:TSLA` |
| 港股 | `HK:代码` | `HK:00700`, `HK:09988`           |
| 沪市 | `SH:代码` | `SH:600519`, `SH:601398`         |
| 深市 | `SZ:代码` | `SZ:000001`, `SZ:000858`         |

### Stock MCP（股票数据）

直接使用股票代码，不带市场前缀：

| 市场 | 格式     | 示例                      |
| -- | ------ | ----------------------- |
| 美股 | 直接使用代码 | `AAPL`, `GOOGL`, `TSLA` |
| 港股 | 直接使用代码 | `00700`, `09988`        |
| A股 | 直接使用代码 | `600519`, `000001`      |

## 错误处理

MCP 调用使用标准的 HTTP 状态码：

* `200` - 请求成功
* `400` - 请求参数错误
* `401` - 认证失败（API Key 无效或未提供）
* `404` - 请求的资源不存在
* `429` - 请求频率超限
* `500` - 服务器内部错误

错误响应示例：

```json theme={null}
{
  "error": "Invalid symbol format"
}
```

## 最佳实践

<Warning>
  **保护 API Key**

  请妥善保管您的 API Key，避免在公开场所泄露：

  * 不要将 API Key 提交到代码仓库
  * 使用环境变量或配置文件管理
  * 定期轮换 API Key
</Warning>

<Tip>
  **按需选择 MCP 服务**

  根据实际需求选择连接的 MCP 服务：

  * 只需搜索功能：连接 Search MCP
  * 只需股票数据：连接 Stock MCP
  * 需要完整功能：连接全部 4 个服务
</Tip>

<Tip>
  **合理使用参数**

  优化查询性能和结果质量：

  * 使用时间范围缩小搜索范围
  * 通过股票代码精确筛选
  * 合理设置返回结果数量
</Tip>

<Note>
  **时间格式规范**

  时间参数使用统一格式：

  * 日期时间：`YYYY-MM-DD HH:mm:ss`（如 `2025-01-01 00:00:00`）
  * 仅日期：`YYYY-MM-DD`（如 `2025-01-01`）
</Note>