{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_rzaugmhrem7s","handle":"csmar-mcp","url":"https://wellknown.network/agents/csmar-mcp","links":{"self":"https://wellknown.network/agents/csmar-mcp/record.json","html":"https://wellknown.network/agents/csmar-mcp","markdown":"https://wellknown.network/agents/csmar-mcp/record.md","api":"https://wellknown.network/api/v1/agents/csmar-mcp","status":"https://wellknown.network/api/v1/agents/csmar-mcp/status","claim":"https://wellknown.network/agents/csmar-mcp/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/csmar-mcp/claim.json","badge":"https://wellknown.network/agents/csmar-mcp/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/csmar-mcp/history","tools":"https://wellknown.network/api/v1/agents/csmar-mcp/tools"},"ard":{"identifier":"urn:air::server:csmar-mcp","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"csmar-mcp","summary":"MCP server for querying CSMAR metadata and materializing downloads","description":"# CSMAR MCP\n\n面向 Agent 工作流的精简 MCP 服务器：提供 CSMAR 元数据发现、查询可行性探测，以及本地物化。\n\n## 对外接口\n\n### 工具\n\n1. `csmar_list_databases`\n   确定性枚举已购买的数据库。命中元数据缓存时零 API 调用。\n\n2. `csmar_list_tables`\n   确定性枚举指定数据库下的表。命中元数据缓存时零 API 调用；若持旧缓存撞上 `not_purchased` 会自动失效并重取一次。\n\n3. `csmar_get_table_schema`\n   返回纯表结构与字段元数据，不返回样本行。命中元数据缓存时零 API 调用。\n\n4. `csmar_bulk_schema`\n   一次性获取多个 `table_code` 的表结构（上限 20 个）。cache-first：已缓存的条目零 API 调用，只有真正的 miss 会并发（上限 4）打 CSMAR。**首选，避免重复调用 `csmar_get_table_schema`。**\n\n5. `csmar_probe_query`\n   对查询进行预检，返回 `validation_id`、`query_fingerprint`、行数、少量样本、无效列，以及物化可行性。\n\n6. `csmar_materialize_query`\n   按 `validation_id` 将先前预检过的查询物化为本地文件。\n\n7. `csmar_refresh_cache` ⚠️ **危险工具**\n   显式失效元数据缓存（`databases` / `tables` / `schema` / `all`，可选指定 `key`）。**仅在用户明确要求刷新时调用** —— 例如用户怀疑表结构变更或新购了数据库。调用后后续元数据查询会直接打受限流的 CSMAR API，绝不可在常规探索中预调用。\n\n## 设计原则\n\n- 每个工具职责单一。\n- JSON 输出精简：只返回下一步所需字段。\n- 面向修复的错误：`code`、`message`、`hint`，以及可选的 `retry_after_seconds`、`suggested_args_patch`。\n- 日期区间只做格式与顺序校验，随后原样透传给 SDK。\n- 查询的预检与物化通过 `validation_id` 串联。\n- 运行时状态持久化在 SQLite 中，默认落在用户缓存目录，跨工作目录的会话天然共享同一份缓存。\n\n## 工具示例\n\n### `csmar_list_databases`\n\n```json\n{}\n```\n\n### `csmar_list_tables`\n\n```json\n{\n  \"database_name\": \"股票市场交易\"\n}\n```\n\n### `csmar_get_table_schema`\n\n```json\n{\n  \"table_code\": \"FS_Combas\"\n}\n```\n\n### `csmar_bulk_schema`\n\n```json\n{\n  \"table_codes\": [\"BANK_Index\", \"BANK_Loan\", \"BANK_CreditRisks\"]\n}\n```\n\n### `csmar_refresh_cache`\n\n```json\n{\n  \"namespace\": \"schema\",\n  \"key\": \"BANK_Loan\"\n}\n```\n\n### `csmar_probe_query`\n\n```json\n{\n  \"table_code\": \"FS_Combas\",\n  \"columns\": [\"Stkcd\", \"Accper\", \"Typrep\"],\n  \"condition\": \"Stkcd='000001'\",\n  \"start_date\": \"2010-01-01\",\n  \"end_date\": \"2024-12-31\",\n  \"sample_rows\": 2\n}\n```\n\n### `csmar_materialize_query`\n\n```json\n{\n  \"validation_id\": \"validation_1234567890\",\n  \"output_dir\": \"D:/tmp/csmar\"\n}\n```\n\n## 运行时默认值\n\n- `lang = \"0\"`\n- `belong = \"0\"`\n- `poll_interval_seconds = 3`\n- `poll_timeout_seconds = 900`\n- `cache_ttl_minutes = 4320`（即 **3 天**，对业务查询缓存 `probes / validations / downloads` 生效）\n-…","publisher":{"name":"CSMAR MCP maintainers","url":null},"homepage":"https://github.com/JinYuKiKK0/CSMAR-Data-MCP","repository":"https://github.com/JinYuKiKK0/CSMAR-Data-MCP","version":"0.1.0","license":"License not declared","protocols":["mcp"],"tags":["csmar","mcp","model-context-protocol"],"pricing":null,"endpoints":[{"url":"pypi:csmar-mcp","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","license":"pypi","repoUrl":"pypi","summary":"pypi","version":"pypi","description":"pypi","homepageUrl":"pypi","publisherName":"pypi"}},"derived":{"capabilities":[{"slug":"data.database","name":"Databases","confidence":1,"provenance":"derived"}],"categories":["data"],"language":"en"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"csmar-mcp","registry":"pypi","observedAt":"2026-11-09T02:26:06.085Z","publishedAt":"2026-06-16T06:51:55.687045Z","latestVersion":"0.1.0"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"csmar-mcp","url":"https://pypi.org/project/csmar-mcp/","firstSeenAt":"2026-09-09T13:20:56.902Z","fetchedAt":"2026-11-09T02:25:10.919Z","normalizedAt":"2026-11-09T02:25:10.919Z"}]},"firstSeenAt":"2026-09-09T13:20:56.902Z","updatedAt":"2026-11-09T02:26:06.085Z"}