csmar-mcp

# CSMAR MCP 面向 Agent 工作流的精简 MCP 服务器：提供 CSMAR 元数据发现、查询可行性探测，以及本地物化。 ## 对外接口 ### 工具 1. `csmar_list_databases` 确定性枚举已购买的数据库。命中元数据缓存时零 API 调用。 2. `csmar_list_tables` 确定性枚举指定数据库下的表。命中元数据缓存时零 API 调用；若持旧缓存撞上 `not_purchased` 会自动失效并重取一次。 3. `csmar_get_table_schema` 返回纯表结构与字段元数据，不返回样本行。命中元数据缓存时零 API 调用。 4. `csmar_bulk_schema` 一次性获取多个 `table_code` 的表结构（上限 20 个）。cache-first：已缓存的条目零 API 调用，只有真正的 miss 会并发（上限 4）打 CSMAR。**首选，避免重复调用 `csmar_get_table_schema`。** 5. `csmar_probe_query` 对查询进行预检，返回 `validation_id`、`query_fingerprint`、行数、少量样本、无效列，以及物化可行性。 6. `csmar_materialize_query` 按 `validation_id` 将先前预检过的查询物化为本地文件。 7. `csmar_refresh_cache` ⚠️ **危险工具** 显式失效元数据缓存（`databases` / `tables` / `schema` / `all`，可选指定 `key`）。**仅在用户明确要求刷新时调用** —— 例如用户怀疑表结构变更或新购了数据库。调用后后续元数据查询会直接打受限流的 CSMAR API，绝不可在常规探索中预调用。 ## 设计原则 - 每个工具职责单一。 - JSON 输出精简：只返回下一步所需字段。 - 面向修复的错误：`code`、`message`、`hint`，以及可选的 `retry_after_seconds`、`suggested_args_patch`。 - 日期区间只做格式与顺序校验，随后原样透传给 SDK。 - 查询的预检与物化通过 `validation_id` 串联。 - 运行时状态持久化在 SQLite 中，默认落在用户缓存目录，跨工作目录的会话天然共享同一份缓存。 ## 工具示例 ### `csmar_list_databases` ```json {} ``` ### `csmar_list_tables` ```json { "database_name": "股票市场交易" } ``` ### `csmar_get_table_schema` ```json { "table_code": "FS_Combas" } ``` ### `csmar_bulk_schema` ```json { "table_codes": ["BANK_Index", "BANK_Loan", "BANK_CreditRisks"] } ``` ### `csmar_refresh_cache` ```json { "namespace": "schema", "key": "BANK_Loan" } ``` ### `csmar_probe_query` ```json { "table_code": "FS_Combas", "columns": ["Stkcd", "Accper", "Typrep"], "condition": "Stkcd='000001'", "start_date": "2010-01-01", "end_date": "2024-12-31", "sample_rows": 2 } ``` ### `csmar_materialize_query` ```json { "validation_id": "validation_1234567890", "output_dir": "D:/tmp/csmar" } ``` ## 运行时默认值 - `lang = "0"` - `belong = "0"` - `poll_interval_seconds = 3` - `poll_timeout_seconds = 900` - `cache_ttl_minutes = 4320`（即 **3 天**，对业务查询缓存 `probes / validations / downloads` 生效） -…