# @cyanheads/socrata-mcp-server 中文文档

规范地址：https://npmcn.com/package/%40cyanheads/socrata-mcp-server/

版本：0\.7\.0
npm 元数据更新时间：2026-11-08T18:04:17.674Z
中文译文更新时间：2026-11-14T16:03:00.109Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cyanheads/socrata-mcp-server
原文对照：https://npmcn.com/package/%40cyanheads/socrata-mcp-server/?lang=original
项目主页：https://github.com/cyanheads/socrata-mcp-server#readme
源码仓库：https://github.com/cyanheads/socrata-mcp-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：578 kB，120 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：4 个
- 首次发布：2026-05-23T20:02:56.600Z
- 最新版本发布：2026-11-08T18:04:17.503Z
- 近 30 天下载量：1992（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：24（近 12 个月 24 个）

## 中文简介

通过MCP搜索并查询政府开放数据门户(Socrata SADA API). (原始内容存档于2012-10-12). STIO or Streamable HTTP.

## 安装

```sh
npm install @cyanheads/socrata-mcp-server
```

也可以使用：`pnpm add @cyanheads/socrata-mcp-server`、`yarn add @cyanheads/socrata-mcp-server`、`bun add @cyanheads/socrata-mcp-server`

## README

# @cyanheads/ socrata-mcp-服务器

**通过MCP搜索并查询政府开放数据门户(Socrata SADA API). (原始内容存档于2012-10-12). STIO or Streamable HTTP.**

• 2个数据资源

[![Version](https://img.shields.io/badge/Version-0.7.0-blue.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/socrata-mcp-server/CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/socrata-mcp-server/LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/socrata-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-%5E2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/%40cyanheads%2Fsocrata-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/socrata-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-%5E7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/socrata-mcp-server/releases/latest/download/socrata-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=socrata-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvc29jcmF0YS1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22socrata-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fsocrata-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

**公共主机服务器 :** [https://socrata.caseyjhand.com/mcp 页面存档备份,存于互联网档案馆](https://socrata.caseyjhand.com/mcp)

* * *

## 概览

查询城市,县,州,联邦开放数据门户建于索克拉塔. 发现出入口和数据集,检查列计,并运行SoQL查询,或SQL在大结果集之上.

### 工具

| 工具 | 说明 |
| :-- | :-- |
| `socrata_list_portals` | 列出已知的Socrata 驱动政府开放数据门户,其中包含域名,组织名称,以及近似数据集计数 |
| `socrata_find_datasets` | 通过发现API搜索所有Socrata门户网站或范围到一个门户网站的数据集 |
| `socrata_get_dataset` | 获取完整的元数据并输入由 ID 组成的数据集的列图 —— 编写 SoQL 查询前需要 |
| `socrata_query_dataset` | 执行针对任何数据集的 SoQL 查询: 搜索、 选择、 在哪里、 何地、 组、 有、 顺序, 并带有 DataCanvas 外溢 |
| `socrata_dataframe_describe` | 在 DataCanvas 会话中列出已注册的表格—— schema, 行数, 列名 |
| `socrata_dataframe_query` | 运行 SELECT 唯一的 SQL 对 DataCanvas 表格 `socrata_query_dataset` |
| `socrata_dataframe_drop` | 丢入 DataCanvas 画布, 或其中一张表格—— 选择通过 `SOCRATA_DATAFRAME_DROP_ENABLED=true` |

### 资源

| 资源 | 说明 |
| :-- | :-- |
| `socrata://datasets/{domain}/{datasetId}` | 获取完整的元数据和列计划, 用于稳定 URI 的数据集—— 与 `socrata_get_dataset` |
| `socrata://portals` | 有组织名称和大致数据集统计的已知Socrata门户网站的分页列表 |

所有资源数据也可通过工具获取。 对代理工作流程使用相应的工具——资源是支持URI可处理数据的客户端.

### 提示

| 提示 | 说明 |
| :-- | :-- |
| `explore_open_data` | 结构分六步进行的公民数据调查流程:找到门户 发现数据集 检查计划 查询 汇总 合成 |

### 代理技能

[`socrata-guide`](https://npmcn.com/package/%40cyanheads/socrata-mcp-server/skills/socrata-guide/SKILL.md) 涵盖数据集覆盖检查,SoQL和DuckDB查询语法,以及不同阶段表格的比较. 它携带插件安装、 npm、 Docker 和 MCPB 捆绑, 可在 MCP 上提供 `skill://socrata-guide/SKILL.md`。 。 。 .

## 能力参考

### `socrata_list_portals` 工具

-   39个知名城市、县、州和联邦门户的校正目录——每个成员在发现目录中都经过核实
-   从发现API中获取的每个端口数据集数,缓存为~24小时(`0` 表示门户不向目录显示数据集资产; `null` 表示暂时无法计算)
-   在域名或组织名称上进行客户端下行过滤;页码可达每页200个并有偏移
-   返回域(通过到 `socrata_find_datasets`),组织名称和相近数据集计数;计数包括来自另一个索克拉塔租户(奥斯汀,伊利诺斯,梅萨和旧金山通过数据枢纽发布;西雅图目录由兄弟租户发布)的门户联邦数据
-   从未在上游错误上失败过——无法取到的计数,或呼叫的50秒期限被切断,保持其最后已知值,或回来 `null` 当它没有, 而列表仍然返回
-   过去端通知: 空页 `offset > 0` 页:1

* * *

### `socrata_find_datasets` 工具

-   跨数据集名称/描述的全文查询;范围 `domain`,由门户自行过滤 `categories`编号 :`tags` 限制 `only` 到资产类型(数据集、地图、文件、日历、故事)
-   `categories` 财务报告和审定财务报表 `tags` 需求 `domain`:每个出入口都指定自己的出入口,没有一台"发现"(Discovery)就把它们比作一个"Socrata"全域分类,结果从未报告. 要么没有 `domain` 失败 `domain_required` 在任何请求之前进行搜索;在门户之间搜索 `query`。空数组或空白条目读取为未设置
-   按相关性、页面浏览、创建日期或更新日期排序; `limit` 最多10 000人 `SOCRATA_CLAMP_LIMITS` ,每拨100个电话,并附上一个通知,标明继续的抵消(计划上限为100,同时取消)
-   "发现"只服务于搜索的前一万场比赛: `offset` 必须保持在一万以下 `totalCount` 以一万计停止 `totalCountCapped: true` 标记下行图
-   返回数据集ID、名称、域名、标记、更新时间戳和 `column_names` —— API 字段名称 SoQL takes (`cuisine_description`,而不是显示标签 `CUISINE DESCRIPTION`页:1 `socrata_get_dataset` 用于在写入查询前输入的图案
-   每个结果都包含 `asset_type` (单位:千美元)`dataset`, (中文(简体) ), `filter`, (中文(简体) ), `map`, (中文(简体) ), `chart`, (中文(简体) ), `story`, (中文(简体) ), `href`, ; 仅 `dataset` 财务报告和审定财务报表 `filter` 回复 `socrata_query_dataset` (有行)和 `parent_dataset_ids`,从(或从)`dfnk-7re6`芝加哥的犯罪地图 `x2n5-8w5q`); 当目录中没有列出时, 每一个都缺失
-   对空结果的恢复提示——回放应用的过滤器并提议如何拓宽;一页经过上一对的表示,并给下一页的偏移取名. 通知还包括: `limit` 低于请设员额
-   `domain` 使用一个赤裸的主机名; URL 窗体 (`https://data.cdc.gov/`)被降为宿主. 范围搜索涵盖门户所出版的每套数据,包括来自另一个索克拉塔租户的、在门户自身领域报告的数据集
-   输入错误 : `domain_required` 何时 `categories` 或者说 `tags` 抵达没有 `domain`, (中文(简体) ), `result_window_exceeded` 何时 `offset` 是1万或更多, `rate_limited` 当发现 API 返回 429 时( 可重复) , `retry_deadline_exceeded` 当电话超过50秒期限时, `unknown_domain` 当发现目录 不索引域, `invalid_domain` 当域名不是主机名时

* * *

### `socrata_get_dataset` 工具

-   返回字段名称、 Socrata 数据类型、描述、行数(与 `row_count_source` 来源、许可证和 `asset_type` (单位:千美元)`dataset`, (中文(简体) ), `filter`, (中文(简体) ), `map`,(...) 可用时 `dataset` 财务报告和审定财务报表 `filter` 回复 `socrata_query_dataset` 带行
-   `dataset_id` 总是请求的ID; 当它是一个别名时, 以另一个数据集的记录回答门户, `canonical_dataset_id` 记录身份标识的名,列仍然是请求的ID行所携带的名
-   栏 `data_type` 确定条款的语法 : `Number` - 裸体字(`year=2023`, (中文(简体) ), `Text` − 单引字符串(`year='2023'`(中文(简体) )
-   不包括计算出来的区域栏(`:@computed_region_*`)以减少噪音;包括每栏非核数(如有)
-   数据集ID是门户扫描的——通过 `domain` 从同 `socrata_find_datasets` 结果; URL- form域缩小为主机. `dataset_id` 接受两个字母大小写并发送小写; 在任何请求之前, 错误的 ID 失败参数验证
-   输入错误 : `not_found` (在被询问的域上没有这样的数据集——消息名称为ID和域名,在发现目录知道时,恢复名称为持有ID的门户), `unknown_domain` (域名不为Socrata API服务——它不解决,不是Socrata的门户,或者在别处重定向;第一次尝试失败), `invalid_domain` (不是一个主机名), `rate_limited` (可重试;尊重上游) `Retry-After`, (中文(简体) ), `retry_deadline_exceeded` (可重复;电话已过50秒期限)
-   总是在写之前打电话 `socrata_query_dataset` 何处条款

* * *

### `socrata_query_dataset` 工具

-   `search` 快速的全文检索( e)`$q`),或组合 `select`编号 :`where`编号 :`group`编号 :`having`编号 :`order` 全面分析控制——条款参考栏,按API字段名称(`field_name` 从 `socrata_get_dataset`,从不显示标签;运算符 `=`, (中文(简体) ), `!=`, (中文(简体) ), `>`, (中文(简体) ), `<`, (中文(简体) ), `LIKE`, (中文(简体) ), `IN(...)`, (中文(简体) ), `BETWEEN`, (中文(简体) ), `IS NULL`, (中文(简体) ), `starts_with()`, (中文(简体) ), `contains()`, (中文(简体) ), `AND`, (中文(简体) ), `OR`, (中文(简体) ), `NOT`
-   通过 `count(*)`, (中文(简体) ), `sum()`, (中文(简体) ), `avg()`, (中文(简体) ), `min()`, (中文(简体) ), `max()` 与 `group`编号 :`having`
-   `not_tabular` 识别没有可查询行的资产 : SODA 拒绝行访问(故事、度量、文件、外部链接), 或没有字段(地图、图表、日历、可视化)的答案, 这些答案在重新计票或进行之前失败。 无论哪一种,追回名称都是资产所依据的表格(`a7mk-8suc is a map built on t6tk-mr48; query that dataset_id on data.nj.gov.`, (中文(简体) ), `9hpx-asd8 is a story built on e52k-ymww; query that dataset_id on data.ny.gov.`),与 `dataset_id`, (中文(简体) ), `asset_type`,以及 `parent_dataset_ids` 在错误数据中; 没有列出的父数据, 请使用 `only: "datasets"`。 。 。 . `query_rejected` 当空行请求成功时, 识别拒绝查询条款的网关; 简化查询并使用 SoQL `case(condition, value, true, fallback)` 用于有条件的总和.
-   `limit` 最多50 000人 `SOCRATA_CLAMP_LIMITS` 上,但一个呼叫返回最多5000行: `limit` 以 5,000 为单位, 并附有一份通知, 指定当更多行匹配时继续使用的偏移( 关闭时, 计划上限为 5,000) 。 页为 `offset`
-   `total_count` 将查询数为已写入 —— 一组进行分组查询, 单独选定的不同值 —— 通过绑定的 SoQL `$query` 烟管计票。 当比赛比应答多站出一行,当应答维持整场比赛或计票失败或跑过15秒时,即为出场. `truncated` 仅在 `total_count` 超过 `offset + row_count`,或者当页面填充时 `limit` 而不存在计数
-   空页 `offset > 0` 获得一个指定匹配大小的过去端通知, 或当计数失败时可能发送到端通知
-   `assembled_query` 响应学习语法的 SoQL 字符串; 所有 SODA 2.1 行值都是字符串, 除了地理/ 位置列, 它们返回嵌入对象
-   当服务器有一个画布和更多的行匹配过页面时, 多达5万行匹配的行会溢出到 DataCanvas 的表格上, 不管是什么 `limit` (单位:千美元)`canvas_id`, (中文(简体) ), `table_name`, (中文(简体) ), `canvas_row_count`() 列出其列 `socrata_dataframe_describe`,然后使用 `socrata_dataframe_query`一个小的 `limit` (如:10) 分级进行大相匹配,而无大内行页. Staging 是一个 SODA 请求; 如果失败或用完时间, 呼叫仍然返回其内行, 没有 `canvas_id` 和一条通知说,什么也没有发生
-   `stage: false` 返回单页 : 没有中转请求和画布, 包含行、 计数, 并提示服务器没有画布返回 。 A 类 `canvas_id` 或者说 `table_name` 通知中标出它名称 在没有画布的服务器上, `stage` 无更改
-   `table_name` 命名已播放的表格( 默认来自 `dataset_id`,比如说. `ijzp_q8t2_rows`) (中文(简体) ). 用画布上已经标出的名字来拼接,取代了那个表,通知中报告了替换情况;通过一个明确的 `table_name` 同样的 `canvas_id` 可以同时保留一个数据集的若干过滤摘录。 当一个被命名的呼叫阶段因整个匹配符合页面,或服务器没有帆布而无所作为时,通知中说:a `limit` 页面行下方的相配点数
-   每一次电话请求 共享一个50秒的期限, 重复和退赛
-   输入错误 : `not_tabular`, (中文(简体) ), `query_rejected`, (中文(简体) ), `not_found` (名称为ID,域名被询问,以及已知时持有ID的门户),, `unknown_domain`, (中文(简体) ), `invalid_domain`, (中文(简体) ), `soql_error` (bad SoQL, 未知的列或函数, 或类型不匹配 —— 带有上游 `socrataCode` 而当上游命名它,犯罪者 `column`; 类型不匹配添加 `referenced_columns`,将查询名称及其类型,以及一个未知列 `similar_columns`,来自一个赤行请求; 恢复提示与代码相匹配:分析错误的 API 字段名称、未知标识符的相近字段名称或两处修正、列类型、引用规则和投影等 `district::number` 对于类型不匹配,未知函数的 SoQL 函数列表, `rate_limited` (可重试;尊重上游) `Retry-After`, (中文(简体) ), `retry_deadline_exceeded` (可重复;电话已过50秒期限)

* * *

### `socrata_dataframe_describe` 工具

-   要求数 `canvas_id` 从上一个 `socrata_query_dataset` 溢出 — 画布无法列出, 所以略去失败 `canvas_id_required` 而不是列出表格
-   显示每个注册表格的表格名称、行数和 DuckDB 列类型( SODA) `number` → `DOUBLE`(中文(简体) )
-   输入错误 : `canvas_id_required`, (中文(简体) ), `canvas_not_found` (已过期或未知的代号——重新运行) `socrata_query_dataset` 来演新画布)

* * *

### `socrata_dataframe_query` 工具

-   SELECT 仅限 SQL 对一 `canvas_id` 播放的表格 `socrata_query_dataset`; DDL, DML, 文件引用, 文件读取功能, 引擎设置功能 (`current_schema`, (中文(简体) ), `current_setting`),任何名称拼写为 DuckDB 元数据视图(`pg_type`, (中文(简体) ), `duckdb_tables`, (中文(简体) ), `sqlite_master`),即使作为列别名或CTE名称,也会被拒绝. 使用直接表格引用而不是 `query_table`· ; `query()` 仅接受一个 SQL 字符串文字。 认证一个命名的已上演的列 `current_schema` 及其表格`t.current_schema`) (中文(简体) ).
-   从 SODA 响应信头中打出螺旋柱: `number` 列(包括总别名)为 `DOUBLE`,因此数字比较在没有铸币的情况下有效(`year > 2020`, (中文(简体) ), `amount < 500`); 文本和时间戳栏保留 `VARCHAR` - 与 `CAST(date AS TIMESTAMP)`
-   `limit` 最多50 000人 `SOCRATA_CLAMP_LIMITS` 上(默认值 1000),但最多1万行调用返回:更大的 `limit` 服务于10,000人。 当更多的行匹配,通知给出了呼号食谱—— `ORDER BY` 唯一的一栏 `LIMIT`编号 :`OFFSET` 在SQL中。 关机后,计划最多为一万
-   `content[]` 显示 `**SQL:**` 回声作为代码或栅栏 `sql` 当 SQL 跨行时块; `structuredContent` 随身携带
-   输入错误 : `canvas_disabled` (单位:千美元)`CANVAS_PROVIDER_TYPE=none`, (中文(简体) ), `canvas_not_found`, (中文(简体) ), `table_not_found`, (中文(简体) ), `sql_rejected` (非SELECT,一个文件或系统目录引用——一个列别名或CTE,以元数据视图计数命名——或一个被拒绝的函数或操作员), `invalid_sql` (语法错误或未知的列或函数), `sql_execution_error` (一个SELECT在舞台上失败,例如失败) `CAST`(中文(简体) )
-   箱外工作——DuckDB轮船作为常规依赖,默认启用; `CANVAS_PROVIDER_TYPE=none` 关闭它

* * *

### `socrata_dataframe_drop` 工具

-   Opt- in: 从工具列表中省略直到 `SOCRATA_DATAFRAME_DROP_ENABLED=true`; 还需要 `CANVAS_PROVIDER_TYPE=duckdb`
-   无 `table_name`,将整个画布放下——它的 `canvas_id` 停止解析 `socrata_dataframe_describe` 财务报告和审定财务报表 `socrata_dataframe_query`与 `table_name`,将一张桌子放下,并将帆布和其他桌子放在原地
-   报告投放的表格及其行数和仍然在画布上的表格
-   只删除已显示的复制件—— `socrata_query_dataset` 能够再次显示数据
-   输入错误 : `canvas_disabled` (单位:千美元)`CANVAS_PROVIDER_TYPE=none`, (中文(简体) ), `canvas_not_found` (未知、已过期或已放弃), `table_not_found` (载帆布) `availableTables`(中文(简体) )

* * *

### `socrata://datasets/{domain}/{datasetId}` 资源

-   返回与 `socrata_get_dataset` ——字段名称,数据类型,说明,行数,许可证发放
-   `domain` 财务报告和审定财务报表 `datasetId` 来自 `socrata_find_datasets`· ; `datasetId` 必须匹配四相图案(如:. `kzjm-xkqj`),在两个字母中,均取出小写
-   在错误的ID上失败参数验证, 当域上不存在数据集时无法找到( 当发现目录知道时命名持有该ID的门户)

* * *

### `socrata://portals` 资源

-   39个已知的Socrata门户的校正目录,光标被涂上(`cursor` param,默认为每页50个,上限为200个)
-   返回域名、组织名称和近似数据集计数(`0` = 没有数据集资产, `null` = 暂时无法使用;计算50秒的呼叫截止时间会保持其最后已知值,或为 `null` 没有时),缓存~24小时
-   过 `domain` 改为 `socrata_find_datasets` 范围搜索到一个门户

* * *

### `explore_open_data` 提示

-   参数 : `topic` 需要; `portal` 财务报告和审定财务报表 `geography` 可选择跳过发现或范围
-   返回一个走六步流程的用户信息: 找到门户 发现数据集 检查计划 查询 汇总 合成

## 特征

建造在 [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio和可流式的 HTTP 传输器,可插接式(`none` 编号 : `jwt` 编号 : `oauth`),可互换存储(`in-memory`, (中文(简体) ), `filesystem`, (中文(简体) ), `Supabase`, (中文(简体) ), `Cloudflare KV/R2/D1`),结构化记录,可选择的OpenTeleometry tracking.

索克塔特异性:

-   Full Socrata SADA 2.1 API集成器 — SoQL 查询构建器,包含选择,地点,组,有,有,有,有,有,有,有,有搜索,有限制,有偏移
-   发现 API 用于跨端数据集搜索和每个端口数据集计数(已校验 39-端口目录,计数缓存~24h)
-   应用符号支持( A)`SOCRATA_APP_TOKEN`用于提高每个实施计划的费率限额
-   通过配置默认门户域 `SOCRATA_DEFAULT_DOMAIN`
-   DataCanvas 外溢( DuckDB, 捆绑) – 大型查询结果记录作为SQL 表格进行分析查询

方便代理输出 :

-   组合 SoQL 字符串回放于每个 `socrata_query_dataset` 反应使代理能够学习和完善语法
-   关于空结果的恢复提示——回放应用过滤器,并提出具体建议以扩大
-   截断披露—— `truncated`编号 :`shown`编号 :`cap` 字段中,当更多行与页面相匹配时,有页或提高限制的指针,当结果溢出时,命名已上演的表格和两个数据框工具
-   每个工具的打出出错误原因( E)`not_found`, (中文(简体) ), `not_tabular`, (中文(简体) ), `query_rejected`, (中文(简体) ), `unknown_domain`, (中文(简体) ), `invalid_domain`, (中文(简体) ), `soql_error`, (中文(简体) ), `rate_limited`, (中文(简体) ), `retry_deadline_exceeded`, (中文(简体) ), `result_window_exceeded`, (中文(简体) ), `canvas_id_required`, (中文(简体) ), `canvas_not_found`, (中文(简体) ), `table_not_found`, (中文(简体) ), `sql_rejected`, (中文(简体) ), `invalid_sql`, (中文(简体) ), `sql_execution_error`, (中文(简体) ), `canvas_disabled`可采取行动的追回案文

## 开始

连接到主机实例, 没有安装 :

```sh
claude mcp add --transport http socrata-mcp-server https://socrata.caseyjhand.com/mcp
```

或者在当地运行它:

```sh
claude mcp add socrata-mcp-server -- npx -y @cyanheads/socrata-mcp-server
```

对于其他客户端,请将此添加到 MCP 配置文件中 :

```json
{
  "mcpServers": {
    "socrata-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/socrata-mcp-server"]
    }
  }
}
```

可选 `SOCRATA_APP_TOKEN` 从a [索克拉塔门户网站](https://data.seattle.gov/) 提高利率限制。 对于 Docker 或源构建,请参见 [运行服务器](https://npmcn.com/package/%40cyanheads/socrata-mcp-server/#readme-running-the-server)。 。 。 .

## 配置

所有配置在启动时通过 Zod schemas 在 `src/config/server-config.ts`关键环境变量:

| 变量 | 说明 | 默认 |
| :-- | :-- | :-- |
| `SOCRATA_APP_TOKEN` | Socrata app sorder (X- App- Token header) (英语). 没有符号,请求每个源IP共享一个被节制的池. | —— 说 |
| `SOCRATA_DEFAULT_DOMAIN` | 默认门户域当 `domain` 在工具调用中省略. | `data.seattle.gov` |
| `MCP_TRANSPORT_TYPE` | 运输: `stdio` 或者说 `http`。 。 。 . | `stdio` |
| `MCP_HTTP_PORT` | HTTP 服务器端口 . | `3010` |
| `MCP_SESSION_MODE` | 会话处理 : `stateful`, (中文(简体) ), `stateless`,或 `auto` (默认值) `auto` 决意要申报。 此服务器明确设置为无国籍者. | `stateless` |
| `MCP_AUTH_MODE` | Auth 模式 : `none`, (中文(简体) ), `jwt`,或 `oauth`。 。 。 . | `none` |
| `MCP_LOG_LEVEL` | 日志级别( RFC 5424) : `debug`, (中文(简体) ), `info`, (中文(简体) ), `notice`, (中文(简体) ), `warning`, (中文(简体) ), `error`。 。 。 . | `info` |
| `SOCRATA_CLAMP_LIMITS` | 服务a `limit` a. 超过一个工具在顶部的每个调用上限,并附有注明继续使用的抵消额的通知; `false` 拒绝它,并恢复每个盖作为最大的计划. | `true` |
| `CANVAS_PROVIDER_TYPE` | 大型结果集的数据扫描; `none` 关闭它。 DuckDB 有服务器的飞船——不需要额外安装. | `duckdb` |
| `SOCRATA_DATAFRAME_DROP_ENABLED` | 设定为 `true` 启用 `socrata_dataframe_drop`中,该工具从工具列表中删除. | `false` |
| `LOGS_DIR` | 日志文件目录(只有Node.js). | `<project-root>/logs` |
| `STORAGE_PROVIDER_TYPE` | 存储后端 : `in-memory`, (中文(简体) ), `filesystem`, (中文(简体) ), `supabase`, (中文(简体) ), `cloudflare-kv/r2/d1`。 。 。 . | `in-memory` |
| `OTEL_ENABLED` | 启用 [OpenTelemet 仪器](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)。 。 。 . | `false` |
| `LOG_TOOL_FAILURE_PAYLOADS` | 记录每个失败的工具调用参数和结果( 仅记录键名编辑) . | `false` |

见 [`.env.example`](https://npmcn.com/package/%40cyanheads/socrata-mcp-server/.env.example) 用于完整可选覆盖列表.

## 运行服务器

要求数 [Bun v 1.4.4+ 车厢](https://bun.sh/) 或节点.js v24+.

```sh
git clone https://github.com/cyanheads/socrata-mcp-server.git
cd socrata-mcp-server
bun install
cp .env.example .env
# Set SOCRATA_APP_TOKEN in .env if you have one.
```

### 地方发展

-   **构建和运行 :**
    
    ```sh
    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
    ```
    
-   **运行检查和测试 :**
    
    ```sh
    bun run devcheck   # Lint, format, typecheck, security audit
    bun run test       # Vitest test suite
    ```
    

### 夹克

```sh
docker build -t socrata-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=http -p 3010:3010 socrata-mcp-server
```

Dockerfile 默认为 HTTP 传输、 无国籍会话模式和日志到 `/var/log/socrata-mcp-server`。默认情况下安装了 OpenTeleometry 端端依赖性 `--build-arg OTEL_ENABLED=false` 以略去它们.

## 项目结构

| 目录 | 目的 |
| :-- | :-- |
| `src/index.ts` | `createApp()` 进入点——登记工具、资源、提示和输入索克拉塔服务. |
| `src/config` | 服务器特定环境变量与Zod解析并验证. |
| `src/mcp-server/tools` | 工具定义`*.tool.ts`) (中文(简体) ). 涵盖门户网站列表,数据集搜索,schema获取,SOQL查询,以及DataCanvas SQL和清理的7个工具. |
| `src/mcp-server/resources` | 资源定义`*.resource.ts`) (中文(简体) ). 数据集元数据和门户网站目录资源. |
| `src/mcp-server/prompts` | 即时定义`*.prompt.ts`公民数据调查流程迅速. |
| `src/services/socrata` | Socrata服务层——SODA 2.1 API客户端,发现API,查询构建器,类型正常化. |
| `skills/` | 与服务器一起调查公民数据的特工指南发布. |
| `tests/` | 单位和综合测试镜像 `src/`。 。 。 . |

## 发展指南

见 [`CLAUDE.md`](https://npmcn.com/package/%40cyanheads/socrata-mcp-server/CLAUDE.md) 发展准则和建筑规则。 简本:

-   搬运工投掷,框架渔获量——否 `try/catch` 在工具逻辑中
-   使用 `ctx.log` 请求范围伐木, `ctx.state` 租户范围储存
-   打电话 `socrata_get_dataset` 在撰写条款之前 `field_name` 是 SoQL 引用和列 `data_type` 确定引用
-   环绕外部 API 调用: 验证 生 → 规范到域类型 → 返回输出计划; 永远不要编织缺失的字段

## 捐款

问题值得欢迎。 提交前进行检查和测试:

```sh
bun run devcheck
bun run test
```

## 许可证

阿帕奇-2.0 — 见 [自由主义](https://npmcn.com/package/%40cyanheads/socrata-mcp-server/LICENSE) 详细情况.

## 常见问题

### @cyanheads/socrata-mcp-server 是什么？

通过MCP搜索并查询政府开放数据门户\(Socrata SADA API\)\. \(原始内容存档于2012-10-12\)\. STIO or Streamable HTTP\.

### 如何安装 @cyanheads/socrata-mcp-server？

在项目目录运行 npm install @cyanheads/socrata-mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 socrata-mcp-server，可以用 npx socrata-mcp-server 直接运行。

### @cyanheads/socrata-mcp-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cyanheads/socrata-mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cyanheads/socrata-mcp-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cyanheads/socrata-mcp-server 可以商用吗？

@cyanheads/socrata-mcp-server 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cyanheads/socrata-mcp-server 的下载量有多少？

根据 npm 官方下载统计，@cyanheads/socrata-mcp-server 在 2026/10/11 – 2026/11/09 这 30 天内被下载 1,992 次，日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cyanheads/socrata-mcp-server 还在维护吗？

最新版本 0\.7\.0 发布于 2026/11/09（5 天前）；至今共发布 24 个版本，其中过去 12 个月发布了 24 个；首次发布于 2026/05/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。