@apocdata/mcp-server

天启至数 ApocData의 MCP(Model Context Protocol) Server입니다. 46개의 인증이 필요 없는 A주 데이터 인터페이스를 MCP tools로 감싸서 Claude Desktop / Cursor / Cline / Continue 등 모든 MCP client에서 직접 호출할 수 있습니다.

• 데이터 소스: https://data.tianqis.com/api/blade-dataplatform/open/data/*

• API Key 불필요, 등록 불필요 (게이트웨이에서 /open/** 인증 면제로 구성됨)

• X-Tdc-* 메타 정보 헤더 자동 전달(한도 잔여/잘림 플래그/오류 코드/캐시 정책)

• 46개 도구: 시세, 밸류에이션, 재무, 주주, 자금 흐름, 상하한가, 섹터, 공시, 매크로, 팩터, 종합 프로필

설치

방법 A: npx (권장, 제로 설치)

client 설정에 npx -y @apocdata/mcp-server라고 직접 작성하면 되며, 수동 설치가 필요 없습니다.

방법 B: 전역 설치

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

Related MCP server: sfc-data-mcp

Client 설정 예시

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 client

위와 동일하게 command=npx, args=["-y","@apocdata/mcp-server"]를 전달하면 됩니다.

CLI flags

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

시그널

• SIGTERM / SIGINT: 정상 종료. 진행 중인 요청이 완료될 때까지(최대 5초) 기다린 다음 transport를 닫고 종료합니다.

디버그 모드

환경 변수 APOCDATA_DEBUG=1을 설정하면 매 HTTP 호출의 path/status/meta가 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개)

각 tool의 입력/출력/기본값은 MCP 프로토콜 계층에서 JSON Schema로 노출되며, client가 자동으로 표시합니다.

MCP Resources

도구 외에도 3개의 markdown 문서를 노출하며, Agent는 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이 남은 할당량 전달)

• 캐시 정책: 장중 실시간 데이터 5s, 장후 일별 갱신 5min, 메타데이터 1h (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 个工具的配置表（声明式）

새 인터페이스를 추가하려면 tools.ts의 해당 그룹에 ToolDef 하나를 추가하고 다시 build하면 되며, 다른 코드는 수정할 필요가 없습니다.

테스트

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

6개의 스크립트는 6가지 검증에 해당합니다:

프라이빗 배포: APOCDATA_BASE_URL=http://your.host/path npm test

알려진 LAG (라이브 대기 배포)

다음 기능은 소스 코드에 이미 구현되어 있지만(로드맵 §2.1 / §5.1 / §5.3), data.tianqis.com에 현재 배포된 버전에서는 아직 적용되지 않았습니다. 백엔드 redeploy 후 MCP server를 수정할 필요 없이 동작이 자동으로 복구됩니다:

• ranking / macro / macro/latest / macro/definition / sector-flow / hot-rank / margin의 잘못된 enum 검증

• X-Tdc-Error-Code 응답 헤더

• X-Tdc-RateLimit-Remaining 응답 헤더(율 제한 남은 할당량)

• X-Tdc-Truncated 응답 헤더(limit 상한 초과 알림; 컨트롤러 내 safeLimit 잘림 자체는 이미 적용되었으며, 헤더 알림만 없는 점에 유의)

• format=compact 열 형식 출력

• /profile/full 및 /factor-categories 두 엔드포인트 자체

License

Apache-2.0