@apocdata-info/mcp-server 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to `@apocdata/mcp-server` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **后端 §5.5 数据 SLA 标注**：响应头 `X-Tdc-Freshness-Tier` + `X-Tdc-Freshness-Detail` 透传数据时效分类（intraday / post-close / t0-morning / quarterly / metadata / aggregated 共 6 档）。MCP server 已通过 `x-tdc-` 前缀自动透传，guide resource 加了 6 档说明 + 典型用法
+- **后端 §6.3 OpenAPI @Operation 文案调优**：12 个易混淆工具（quote / stock / daily / ranking / announcements / news / concepts / ths-boards / hot-money / hot-money-detail / macro / factors / profile-full / factor-categories）的 description 加"何时用 / 不该用"对照，Java 侧文档对齐 MCP server tools.ts
+- **后端 §2.6 fields 全局扩展**：所有 47 个 `/open/data/*` 接口都支持 `?fields=col1,col2`（之前只有 financial / announcements）。MCP resources 的 `apocdata://limits` 段相应更新说明全局可用
+- **后端 announcements 加过滤参数**：解决用户实测痛点"只能拿最近 5 条无任何过滤"。新增 `startDate` / `endDate` / `category` / `q` / `includeContent` 参数；limit 上限从 5 提到 30。MCP tool schema 同步更新，对应字段同步进 SKILL.md
+- **后端 news 加过滤参数**：与 announcements 同款思路。新增 `startDate` / `endDate` / `category` / `q` / `sentiment`（bullish/neutral/bearish）/ `importance`（high/medium/low）；limit 上限从 10 提到 30；时间过滤优先级 startDate+endDate > hours
+- **后端 calendar 加 `?detail=true`**：路线图差异登记"pretrade_date 可由相邻交易日计算"项落地。默认返回 List<String> 向后兼容；detail=true 返回 List<{trade_date, pretrade_date}>
+- **MCP resources**：暴露 3 个 markdown 文档（`apocdata://guide` 接入指南 / `apocdata://scenarios` 场景速查 / `apocdata://limits` limit-fields-compact 速查表），Agent 一连上即可读到全局上下文
+- **工具 description 调优**：易混淆的工具组（quote vs profile-full、daily vs ranking、news vs announcements、concepts vs ths-boards、hot-money vs hot-money-detail、macro 三件套）加入"何时用 / 不该用"提示，提升 Agent 选择准确率
+- **GitHub Actions**：
+  - `test.yml`：push / PR 触发，矩阵 Node 18/20/22 × Ubuntu/macOS，跑 unit + integration（不打外网）
+  - `publish.yml`：GitHub Release 触发自动 `npm publish --access public --provenance`；支持 workflow_dispatch dry-run
+- **CHANGELOG.md**：Keep-a-Changelog 格式
+- **发包脚本**：`npm run publish:dry`、`npm run version:patch|minor|major`、`prepublishOnly` 自动跑 test:ci
+
+### Changed
+
+- e2e 测试用例从 11 涨到 16（加 resources/list、resources/read、未知 URI 错误响应）
+
+## [0.1.0] - 2026-05-27
+
+### Added
+
+- 初始版本，覆盖 ApocData `/open/data/*` 全部 47 个免鉴权接口
+- MCP server（stdio transport），自动透传 `X-Tdc-*` 元信息头与 `Cache-Control`
+- HTTP client：30s 超时（AbortController）、5xx/网络异常指数 backoff 重试 ×2、4xx 不重试、错误归一化为 `NetworkError`
+- 优雅退出：SIGTERM/SIGINT 等 in-flight 请求结束（最多 5s）后再退
+- CLI：`--version` / `--help`，环境变量 `APOCDATA_BASE_URL` / `APOCDATA_DEBUG` / `APOCDATA_TIMEOUT_MS` / `APOCDATA_MAX_RETRIES`
+- 测试套件 6 套：unit / contract / errors / coverage / e2e / integration，总计 125 PROD case
+
+### Known limitations
+
+后端服务 `data.tianqis.com` 当前部署版本滞后于源码，以下能力 MCP 客户端代码已就绪，需后端 redeploy 才会生效：
+
+- `profile/full` 与 `factor-categories` 端点（404）
+- 多接口非法 enum 校验（`ranking` direction / `macro` type / `sector-flow` type / `hot-rank` type / `margin` exchange / `macro-latest|definition` type）
+- `X-Tdc-Error-Code` / `X-Tdc-RateLimit-Remaining` / `X-Tdc-Truncated` 响应头
+- `format=compact` 列式输出
+
+[Unreleased]: https://github.com/ApocData/ApocData-skill/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ApocData/ApocData-skill/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,191 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and
+distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities
+that control, are controlled by, or are under common control with that entity.
+For the purposes of this definition, "control" means (i) the power, direct or
+indirect, to cause the direction or management of such entity, whether by
+contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including
+but not limited to software source code, documentation source, and configuration
+files.
+
+"Object" form shall mean any form resulting from mechanical transformation or
+translation of a Source form, including but not limited to compiled object code,
+generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made
+available under the License, as indicated by a copyright notice that is included
+in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that
+is based on (or derived from) the Work and for which the editorial revisions,
+annotations, elaborations, or other modifications represent, as a whole, an
+original work of authorship. For the purposes of this License, Derivative Works
+shall not include works that remain separable from, or merely link (or bind by
+name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version
+of the Work and any modifications or additions to that Work or Derivative Works
+thereof, that is intentionally submitted to Licensor for inclusion in the Work
+by the copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems, and
+issue tracking systems that are managed by, or on behalf of, the Licensor for
+the purpose of discussing and improving the Work, but excluding communication
+that is conspicuously marked or otherwise designated in writing by the copyright
+owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
+of whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the Work and such
+Derivative Works in Source or Object form.
+
+3. Grant of Patent License.
+
+Subject to the terms and conditions of this License, each Contributor hereby
+grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
+irrevocable (except as stated in this section) patent license to make, have
+made, use, offer to sell, sell, import, and otherwise transfer the Work, where
+such license applies only to those patent claims licensable by such Contributor
+that are necessarily infringed by their Contribution(s) alone or by combination
+of their Contribution(s) with the Work to which such Contribution(s) was
+submitted. If You institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+Contribution incorporated within the Work constitutes direct or contributory
+patent infringement, then any patent licenses granted to You under this License
+for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution.
+
+You may reproduce and distribute copies of the Work or Derivative Works thereof
+in any medium, with or without modifications, and in Source or Object form,
+provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of
+this License; and
+You must cause any modified files to carry prominent notices stating that You
+changed the files; and
+You must retain, in the Source form of any Derivative Works that You distribute,
+all copyright, patent, trademark, and attribution notices from the Source form
+of the Work, excluding those notices that do not pertain to any part of the
+Derivative Works; and
+If the Work includes a "NOTICE" text file as part of its distribution, then any
+Derivative Works that You distribute must include a readable copy of the
+attribution notices contained within such NOTICE file, excluding those notices
+that do not pertain to any part of the Derivative Works, in at least one of the
+following places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation, if provided along
+with the Derivative Works; or, within a display generated by the Derivative
+Works, if and wherever such third-party notices normally appear. The contents of
+the NOTICE file are for informational purposes only and do not modify the
+License. You may add Your own attribution notices within Derivative Works that
+You distribute, alongside or as an addendum to the NOTICE text from the Work,
+provided that such additional attribution notices cannot be construed as
+modifying the License.
+You may add Your own copyright statement to Your modifications and may provide
+additional or different license terms and conditions for use, reproduction, or
+distribution of Your modifications, or for any such Derivative Works as a whole,
+provided Your use, reproduction, and distribution of the Work otherwise complies
+with the conditions stated in this License.
+
+5. Submission of Contributions.
+
+Unless You explicitly state otherwise, any Contribution intentionally submitted
+for inclusion in the Work by You to the Licensor shall be under the terms and
+conditions of this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify the terms of
+any separate license agreement you may have executed with Licensor regarding
+such Contributions.
+
+6. Trademarks.
+
+This License does not grant permission to use the trade names, trademarks,
+service marks, or product names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty.
+
+Unless required by applicable law or agreed to in writing, Licensor provides the
+Work (and each Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,
+including, without limitation, any warranties or conditions of TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are
+solely responsible for determining the appropriateness of using or
+redistributing the Work and assume any risks associated with Your exercise of
+permissions under this License.
+
+8. Limitation of Liability.
+
+In no event and under no legal theory, whether in tort (including negligence),
+contract, or otherwise, unless required by applicable law (such as deliberate
+and grossly negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special, incidental,
+or consequential damages of any character arising as a result of this License or
+out of the use or inability to use the Work (including but not limited to
+damages for loss of goodwill, work stoppage, computer failure or malfunction, or
+any and all other commercial damages or losses), even if such Contributor has
+been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability.
+
+While redistributing the Work or Derivative Works thereof, You may choose to
+offer, and charge a fee for, acceptance of support, warranty, indemnity, or
+other liability obligations and/or rights consistent with this License. However,
+in accepting such obligations, You may act only on Your own behalf and on Your
+sole responsibility, not on behalf of any other Contributor, and only if You
+agree to indemnify, defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason of your
+accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "{}" replaced with your own
+identifying information. (Don't include the brackets!) The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification within
+third-party archives.
+
+   Copyright 2023 BladeX (https://bladex.cn)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,230 @@
+# @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`，无需手动 install。
+
+### 方式 B：全局安装
+
+```bash
+npm install -g @apocdata/mcp-server
+apocdata-mcp   # 可执行命令
+```
+
+---
+
+## Client 配置示例
+
+### Claude Desktop
+
+编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
+
+```json
+{
+  "mcpServers": {
+    "apocdata": {
+      "command": "npx",
+      "args": ["-y", "@apocdata/mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor
+
+`~/.cursor/mcp.json`：
+
+```json
+{
+  "mcpServers": {
+    "apocdata": {
+      "command": "npx",
+      "args": ["-y", "@apocdata/mcp-server"]
+    }
+  }
+}
+```
+
+### Cline / Continue / 其它 stdio MCP client
+
+同上，传 `command=npx, args=["-y","@apocdata/mcp-server"]` 即可。
+
+### CLI flags
+
+```bash
+apocdata-mcp --version    # 打印版本号
+apocdata-mcp --help       # 显示完整用法
+```
+
+### 信号
+
+- `SIGTERM` / `SIGINT`：优雅退出。等正在进行的请求完成（最多 5 秒），再关闭 transport 退出。
+
+### 调试模式
+
+环境变量 `APOCDATA_DEBUG=1` 会把每次 HTTP 调用的 path/status/meta 打到 stderr：
+
+```json
+{
+  "mcpServers": {
+    "apocdata": {
+      "command": "npx",
+      "args": ["-y", "@apocdata/mcp-server"],
+      "env": { "APOCDATA_DEBUG": "1" }
+    }
+  }
+}
+```
+
+### 自定义 BASE URL
+
+环境变量 `APOCDATA_BASE_URL` 可指向内网/私有部署：
+
+```json
+"env": { "APOCDATA_BASE_URL": "https://intranet.example.com/api/blade-dataplatform/open/data" }
+```
+
+### 超时与重试
+
+| 环境变量 | 默认 | 说明 |
+| --- | --- | --- |
+| `APOCDATA_TIMEOUT_MS` | `30000` | 单次请求超时（毫秒），到时间 AbortController 中断 |
+| `APOCDATA_MAX_RETRIES` | `2` | 5xx 或网络错误重试次数（不含首次），指数 backoff 500→1000→2000ms |
+
+4xx 不重试（业务错误重试无意义）。重试用尽后返回最后一次的 5xx 响应，或抛 `NetworkError`（网络异常）。
+
+---
+
+## 工具清单（46 个）
+
+| 类别 | 工具 |
+| --- | --- |
+| **A. 行情与估值（10）** | `quote` `quotes` `daily` `stock` `stocks` `st` `ranking` `indexes` `index-daily` `hot-rank` |
+| **B. 财务与股东（8）** | `financial` `express` `dividend` `holders` `holder-number` `share-float` `repurchase` `block-trade` |
+| **C. 资金流向（8）** | `moneyflow` `hsgt` `hk-hold` `hk-daily` `margin` `dragon-tiger` `hot-money` `hot-money-detail` |
+| **D. 涨跌停与板块（4）** | `limit-list` `limit-step` `sector-flow` `cyq-perf` |
+| **E. 公告/调研（2）** | `announcements` `survey` |
+| **F. 板块成分（4）** | `concepts` `concept-stocks` `ths-boards` `ths-board-stocks` |
+| **G. 可转债（2）** | `convertible-bonds` `cb-price-chg` |
+| **H. 因子（2）** | `factors` `tech-factor` |
+| **I. 宏观（3）** | `macro` `macro-latest` `macro-definition` |
+| **J. 日历（1）** | `calendar` |
+| **K. 综合（2）** | `profile-full` `factor-categories` |
+
+每个 tool 的入参/出参/默认值在 MCP 协议层用 JSON Schema 暴露，client 会自动展示。
+
+## MCP Resources
+
+除工具外还暴露 3 个 markdown 文档，Agent 通过 `resources/list` 和 `resources/read` 拉取：
+
+| URI | 内容 |
+| --- | --- |
+| `apocdata://guide` | 全局接入指南：46 工具分组、symbol 格式、延迟/限流/错误协议、元信息头说明 |
+| `apocdata://scenarios` | 场景速查：常见用户意图到工具组合的映射 + 反模式（避免串调 8 个接口） |
+| `apocdata://limits` | limit/fields/compact 速查表：每个工具的默认值/上限/字段裁剪支持情况 |
+
+---
+
+## 用法示例（在 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% token
+- 字段较多的接口（如 financial、announcements）支持 `fields=...` 裁剪
+
+详细行为参考主 SKILL 文档：<https://github.com/ApocData/ApocData-skill>
+
+---
+
+## 开发
+
+```bash
+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 即可，无需改其它代码。
+
+## 测试
+
+```bash
+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
+```
+
+六个脚本对应六种验证：
+
+| 脚本 | 验证 |
+| --- | --- |
+| `client-unit-test.mjs` | client 4xx 不重试、5xx 重试到成功/用尽、超时归一化、meta 头提取、URL 构造（mock fetch） |
+| `contract-test.mjs` | 所有 46 端点参数名/必填和后端 `@RequestParam` 一致；happy path 全部 200 |
+| `error-path-test.mjs` | 业务错误用 HTTP 200 + `success=false` 表达；标记 PROD（已部署）/ LAG（源码已写、线上待发版）|
+| `coverage-test.mjs` | 限流头 / 截断头透传；所有 enum 工具（ranking / limit-list / sector-flow / hot-rank / margin / macro）的合法值全部遍历 |
+| `mcp-e2e-test.mjs` | MCP 协议正确：tools/list 46 个、isError 在 HTTP 4xx 和 `success=false` 都正确标记、compact 模式列式输出 |
+| `integration-test.mjs` | 真实 backoff 耗时验证；真实 timeout 触发；`--version` / `--help` CLI；SIGTERM 空闲即时退出；SIGTERM in-flight 等待完成后退出 |
+
+私有部署：`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 超上限通知；注意 controller 内的 `safeLimit` 截断本身已生效，只是没有头通知）
+- `format=compact` 列式输出
+- `/profile/full` 和 `/factor-categories` 两个端点本身
+
+---
+
+## License
+
+Apache-2.0

package/dist/cache.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2018-2099, Chill Zhuang 庄骞 (bladejava@qq.com).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * @author Chill
+ */
+/**
+ * 缓存包装:命中直接返,未命中调 factory 并缓存。
+ * @param key 缓存键
+ * @param ttlMs 本次缓存 TTL(毫秒);若 undefined 用默认 5min
+ * @param factory 数据源工厂
+ */
+export declare function withCache<T>(key: string, ttlMs: number | undefined, factory: () => Promise<T>): Promise<T>;
+/**
+ * 测试用:清空缓存。
+ */
+export declare function clearCache(): void;

package/dist/cache.js

@@ -0,0 +1,51 @@
+/**
+ * Copyright (c) 2018-2099, Chill Zhuang 庄骞 (bladejava@qq.com).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * @author Chill
+ */
+import { LRUCache } from "lru-cache";
+/**
+ * MCP 端进程内 LRU 缓存。
+ * - 容量 1000 条
+ * - 默认 TTL 5min(若 factory 未指定)
+ * - key 形如 "tool:get_stock_quote:000001"
+ */
+const cache = new LRUCache({
+    max: 1000,
+    ttl: 5 * 60 * 1000,
+});
+/**
+ * 缓存包装:命中直接返,未命中调 factory 并缓存。
+ * @param key 缓存键
+ * @param ttlMs 本次缓存 TTL(毫秒);若 undefined 用默认 5min
+ * @param factory 数据源工厂
+ */
+export async function withCache(key, ttlMs, factory) {
+    const hit = cache.get(key);
+    if (hit !== undefined)
+        return hit;
+    const value = await factory();
+    if (ttlMs !== undefined) {
+        cache.set(key, value, { ttl: ttlMs });
+    }
+    else {
+        cache.set(key, value);
+    }
+    return value;
+}
+/**
+ * 测试用:清空缓存。
+ */
+export function clearCache() {
+    cache.clear();
+}

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;;;;GAKG;AACH,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAc;IACtC,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI;CACnB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,GAAW,EACX,KAAyB,EACzB,OAAyB;IAEzB,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAkB,CAAC;IAC5C,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAClC,MAAM,KAAK,GAAG,MAAM,OAAO,EAAE,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU;IACxB,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC"}

package/dist/client.js

@@ -0,0 +1,113 @@
+/**
+ * 通用 HTTP client，封装 ApocData /open/data/* 调用。
+ *
+ * - GET only，参数序列化为 query string
+ * - 自动透传 X-Tdc-* 元信息头（限流/截断/错误码/缓存）
+ * - 超时控制（AbortController）和 5xx 自动重试（指数 backoff）
+ * - 错误归一化为 NetworkError，保留 HTTP 状态和原始消息
+ */
+const META_HEADER_PREFIX = 'x-tdc-';
+const CACHE_CONTROL_HEADER = 'cache-control';
+export class ApocDataClient {
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    retryBackoffMs;
+    constructor(baseUrl, options = {}) {
+        this.baseUrl = baseUrl;
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxRetries = options.maxRetries ?? 2;
+        this.retryBackoffMs = options.retryBackoffMs ?? 500;
+    }
+    async call(path, params) {
+        const url = this.buildUrl(path, params);
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            try {
+                const result = await this.fetchOnce(url);
+                // 5xx 触发重试；4xx 直接返回（业务问题，不该重试）
+                if (result.status >= 500 && attempt < this.maxRetries) {
+                    await this.sleep(this.backoff(attempt));
+                    continue;
+                }
+                return result;
+            }
+            catch (err) {
+                lastError = err;
+                // AbortError 或网络错误：重试
+                if (attempt < this.maxRetries) {
+                    await this.sleep(this.backoff(attempt));
+                    continue;
+                }
+            }
+        }
+        // 重试用尽，抛规范化错误
+        throw new NetworkError(this.formatError(lastError), lastError);
+    }
+    async fetchOnce(url) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(url, {
+                method: 'GET',
+                signal: ctrl.signal,
+                headers: {
+                    'User-Agent': 'apocdata-mcp-server/0.1.0',
+                    Accept: 'application/json',
+                },
+            });
+            const meta = {};
+            for (const [key, value] of res.headers) {
+                const lower = key.toLowerCase();
+                if (lower.startsWith(META_HEADER_PREFIX) || lower === CACHE_CONTROL_HEADER) {
+                    meta[key] = value;
+                }
+            }
+            const text = await res.text();
+            let body;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch {
+                body = { raw: text };
+            }
+            return { body, meta, status: res.status };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    buildUrl(path, params) {
+        const trimmed = path.replace(/^\/+/, '');
+        const url = new URL(`${this.baseUrl.replace(/\/+$/, '')}/${trimmed}`);
+        for (const [k, v] of Object.entries(params)) {
+            if (v === undefined || v === null || v === '')
+                continue;
+            url.searchParams.append(k, String(v));
+        }
+        return url.toString();
+    }
+    backoff(attempt) {
+        // attempt 从 0 开始：500ms, 1000ms, 2000ms ...
+        return this.retryBackoffMs * Math.pow(2, attempt);
+    }
+    sleep(ms) {
+        return new Promise((r) => setTimeout(r, ms));
+    }
+    formatError(err) {
+        if (err instanceof Error) {
+            if (err.name === 'AbortError')
+                return `Request timed out after ${this.timeoutMs}ms`;
+            return err.message;
+        }
+        return String(err);
+    }
+}
+export class NetworkError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'NetworkError';
+    }
+}