@apocdata/mcp-server

MCP-сервер (Model Context Protocol) проекта 天启至数 ApocData. Он упаковывает 46 интерфейсов данных A-акций без аутентификации в MCP-инструменты, которые можно напрямую вызывать в любом MCP-клиенте: Claude Desktop / Cursor / Cline / Continue и других.

• Источник данных: https://data.tianqis.com/api/blade-dataplatform/open/data/*

• API Key и регистрация не требуются (шлюз настроен на /open/** без аутентификации)

• Автоматически пробрасываются мета-заголовки X-Tdc-* (остаток лимита / флаг усечения / код ошибки / политика кэширования)

• 46 инструментов охватывают: котировки, оценку, финансы, акционеров, потоки средств, лимиты роста/падения, секторы, объявления, макроэкономику, факторы, комплексный профиль

Установка

Способ A: npx (рекомендуется, без установки)

В конфигурации клиента просто укажите npx -y @apocdata/mcp-server — ручная установка не нужна.

Способ B: Глобальная установка

npm install -g @apocdata/mcp-server
apocdata-mcp   # 可执行命令

Related MCP server: sfc-data-mcp

Примеры конфигурации клиента

Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "apocdata": {
      "command": "npx",
      "args": ["-y", "@apocdata/mcp-server"]
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "apocdata": {
      "command": "npx",
      "args": ["-y", "@apocdata/mcp-server"]
    }
  }
}

Cline / Continue / другие stdio-клиенты MCP

Аналогично: передайте command=npx, args=["-y","@apocdata/mcp-server"].

Флаги CLI

apocdata-mcp --version    # 打印版本号
apocdata-mcp --help       # 显示完整用法

Сигналы

• SIGTERM / SIGINT: корректное завершение. Дождаться завершения выполняющихся запросов (максимум 5 секунд), затем закрыть transport и выйти.

Режим отладки

Переменная окружения APOCDATA_DEBUG=1 выводит path/status/meta каждого HTTP-вызова в stderr:

{
  "mcpServers": {
    "apocdata": {
      "command": "npx",
      "args": ["-y", "@apocdata/mcp-server"],
      "env": { "APOCDATA_DEBUG": "1" }
    }
  }
}

Настраиваемый BASE URL

Переменная окружения APOCDATA_BASE_URL может указывать на внутреннюю сеть / частное развертывание:

"env": { "APOCDATA_BASE_URL": "https://intranet.example.com/api/blade-dataplatform/open/data" }

Тайм-аут и повторы

4xx не повторяются (повторять бизнес-ошибки бессмысленно). После исчерпания повторов возвращается последний 5xx-ответ или выбрасывается NetworkError (сетевая ошибка).

Список инструментов (46)

Входные/выходные параметры и значения по умолчанию каждого инструмента описываются на уровне протокола MCP через JSON Schema, и клиент отображает их автоматически.

MCP-ресурсы

Помимо инструментов предоставляются 3 markdown-документа; агент получает их через resources/list и resources/read:

Пример использования (просто спросите в Claude)

> 帮我看下贵州茅台最近 5 天行情
（Claude 调用 daily(symbol="600519", limit=5)）

> 现在涨幅榜前 10 是哪些股票？
（Claude 调用 ranking(type="gainers", limit=10)）

> 整理一下平安银行的综合画像
（Claude 调用 profile-full(symbol="000001")）

> CPI 最近一次数据是多少？
（Claude 调用 macro-latest(type="cpi")）

Производительность и лимиты

• Лимит на один IP: 60 req/min (оставшаяся квота пробрасывается в заголовке ответа X-Tdc-RateLimit-Remaining)

• Политика кэширования: внутридневные данные — 5 с, дневные обновления после закрытия — 5 мин, метаданные — 1 ч (заголовок Cache-Control добавляется автоматически)

• Верхний предел параметра limit — 50, при превышении — тихое усечение (см. заголовок ответа X-Tdc-Truncated)

• Для больших объёмов данных рекомендуется колоночный вывод format=compact — экономия 60–70% токенов

• У интерфейсов с большим числом полей (например, financial, announcements) поддерживается сокращение через fields=...

Подробное поведение описано в основном SKILL-документе: https://github.com/ApocData/ApocData-skill

Разработка

git clone https://github.com/ApocData/ApocData-skill.git
cd ApocData-skill/mcp-server
npm install
npm run build
npm start

Структура исходного кода:

src/
  index.ts     # MCP server 入口，stdio transport
  client.ts    # HTTP client，BASE_URL 调用 + meta 头提取
  tools.ts     # 46 个工具的配置表（声明式）

Чтобы добавить новый интерфейс: добавьте ToolDef в соответствующую группу в tools.ts и пересоберите — другой код менять не нужно.

Тестирование

npm test                 # build + 6 类测试全跑（需在 tianqi-mcp 目录执行）
npm run test:unit        # client 单测：超时/重试/URL 构造，不打外网
npm run test:contract    # 46 工具逐个真实 HTTP 调用（happy path）
npm run test:errors      # 错误路径：非法参数 / 不存在 symbol / 日期格式
npm run test:coverage    # 限流头/截断头/所有枚举值遍历
npm run test:e2e         # MCP 协议层：stdio JSON-RPC + isError + compact
npm run test:integration # 集成：mock HTTP + 子进程 server，验证 retries / timeout / --version / SIGTERM

Шесть скриптов соответствуют шести видам проверок:

Частное развертывание: APOCDATA_BASE_URL=http://your.host/path npm test

Известные LAG (ожидают релиза на проде)

Следующие возможности уже реализованы в коде (дорожная карта §2.1 / §5.1 / §5.3), но в текущей развёрнутой версии data.tianqis.com ещё не действуют. После повторного развёртывания бэкенда менять MCP-сервер не нужно — поведение восстановится автоматически:

• Валидация недопустимых enum для ranking / macro / macro/latest / macro/definition / sector-flow / hot-rank / margin

• Заголовок ответа X-Tdc-Error-Code

• Заголовок ответа X-Tdc-RateLimit-Remaining (оставшаяся квота лимита)

• Заголовок ответа X-Tdc-Truncated (уведомление о превышении limit; обратите внимание: само усечение через safeLimit в контроллере уже работает, просто нет уведомляющего заголовка)

• Колоночный вывод format=compact

• Сами эндпоинты /profile/full и /factor-categories

Лицензия

Apache-2.0