概览

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

工具

资源

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

提示

代理技能

socrata-guide 涵盖数据集覆盖检查,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: 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可采取行动的追回案文

开始

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

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

或者在当地运行它:

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

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

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

可选 SOCRATA_APP_TOKEN 从a 索克拉塔门户网站 提高利率限制。 对于 Docker 或源构建,请参见 运行服务器。 。 。 .

配置

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

见 .env.example 用于完整可选覆盖列表.

运行服务器

要求数 Bun v 1.4.4+ 车厢 或节点.js v24+.

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.

地方发展

• 构建和运行 :

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试 :

  bun run devcheck   # Lint, format, typecheck, security audit
  bun run test       # Vitest test suite
  

夹克

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 以略去它们.

项目结构

发展指南

见 CLAUDE.md 发展准则和建筑规则。 简本:

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

捐款

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

bun run devcheck
bun run test

许可证

阿帕奇-2.0 — 见 自由主义 详细情况.