socrata-mcp-server

---

概览

查询基于 Socrata 构建的市、县、州和联邦开放数据门户。发现门户和数据集、查看列架构，并运行 SoQL 查询；也可以对大型结果集运行 SQL。

工具

工具	描述
socrata_list_portals	列出已知的 Socrata 政府开放数据门户，包括域名、组织名称和数据集估算数量
socrata_find_datasets	通过 Discovery API 搜索所有 Socrata 门户中的数据集，或限定在单个门户内搜索
socrata_get_dataset	按 ID 获取数据集的完整元数据和类型化列架构——编写 SoQL 查询前必须先调用
socrata_query_dataset	对任意数据集执行 SoQL 查询：搜索、选择、筛选、分组、分组筛选、排序，并支持 DataCanvas 溢出
socrata_dataframe_describe	列出 DataCanvas 会话中已注册的表——架构、行数和列名
socrata_dataframe_query	对由 socrata_query_dataset 填充的 DataCanvas 表运行仅限 SELECT 的 SQL
socrata_dataframe_drop	删除 DataCanvas 画布或其中的一张表——需通过 SOCRATA_DATAFRAME_DROP_ENABLED=true 选择启用

资源

资源	描述
socrata://datasets/{domain}/{datasetId}	按稳定 URI 获取数据集的完整元数据和列架构——与 socrata_get_dataset 返回的数据相同
socrata://portals	分页列出已知的 Socrata 门户，包括组织名称和数据集估算数量

所有资源数据也可通过工具访问。对于 Agent 工作流，请使用相应工具；资源适用于支持通过 URI 访问数据的客户端。

提示词

提示词	描述
explore_open_data	结构化的六步公民数据调查工作流：查找门户 → 发现数据集 → 检查架构 → 查询 → 汇总 → 综合分析

功能参考

socrata_list_portals _工具

• 精选了 39 个知名的市、县、州和联邦门户 — 目录中的每个门户都已在 Discovery 目录中验证为可访问
• 通过 Discovery API 实时获取各门户的数据集数量，并缓存约 24 小时（0 表示该门户未向目录公开任何数据集资产；null 表示暂时无法获取数量）
• 可在客户端按域名或组织名称进行子串筛选；支持分页，每页最多 200 条，并可指定偏移量
• 返回域名（传递给 socrata_find_datasets）、组织名称和数据集的大致数量；数量包含门户从其他 Socrata 租户联合提供的数据集（Austin、Illinois、Mesa 和 San Francisco 通过数据中心发布；Seattle 在同级租户下编入目录）
• 上游发生错误时不会失败 — 无法获取的数量会返回 null，但列表仍会正常返回

---

socrata_find_datasets _工具

• 对数据集名称和描述进行全文查询；使用 domain 指定范围，按 categories/tags 筛选，使用 only 限定资产类型（数据集、地图、文件、日历、故事）
• 可按相关性、页面浏览量、创建日期或更新日期排序；支持分页，每页最多 100 条，并可指定偏移量
• 返回数据集 ID、名称、域名、标签、更新时间戳和 column_names — 即 SoQL 接受的 API 字段名称（cuisine_description，而非显示标签 CUISINE DESCRIPTION）；已剔除计算区域列 — 编写查询前请调用 socrata_get_dataset 获取类型化架构
• 无结果时提供恢复提示 — 回显已应用的筛选条件，并建议如何放宽条件
• domain 接受不带路径的主机名；URL 形式（https://data.cdc.gov/）会被转换为主机名。指定范围的搜索会覆盖该门户发布的所有数据集，包括从其他 Socrata 租户联合提供的数据集；这些数据集会以该门户自己的域名报告
• 类型化错误：Discovery API 返回 429 时为 rate_limited（可重试）；Discovery 目录未索引该域名时为 unknown_domain；域名不是主机名时为 invalid_domain

---

socrata_get_dataset _工具

• 返回字段名称、Socrata 数据类型、描述、行数（含 row_count_source 来源信息），以及可用时的许可信息
• 列的 data_type 决定 WHERE 子句语法：Number → 不带引号的字面值（year=2023），Text → 单引号括起的字符串（year='2023'）
• 排除计算区域列（:@computed_region_*）以减少干扰；可用时包含每列的非空值计数
• 数据集 ID 的作用范围限定于门户 — 传递同一条 socrata_find_datasets 结果中的 domain；URL 形式的域名会被转换为主机名
• 类型化错误：invalid_id（四位四位格式的 ID 不合法）、not_found（所查询的域名上没有该数据集 — 消息会指出 ID 和域名；如果 Discovery 目录知道该 ID 所属的门户，恢复提示会指出该门户）、unknown_domain（该域名未提供 Socrata API — 域名无法解析、不是 Socrata 门户，或重定向到其他位置；首次尝试时即失败）、invalid_domain（不是主机名）、rate_limited（可重试；遵循上游的 Retry-After）
• 编写 socrata_query_dataset WHERE 子句前，务必先调用

---

socrata_query_dataset _工具

• 使用 search 进行快速全文查找（$q），或组合使用 select/where/group/having/order 以实现完整的分析控制——子句通过 API 字段名（socrata_get_dataset 中的 field_name）引用列，而非显示标签；运算符包括 =、!=、>、<、LIKE、IN(...)、BETWEEN、IS NULL、starts_with()、contains()、AND、OR、NOT
• 通过 count(*)、sum()、avg()、min()、max() 配合 group/having 进行聚合
• not_tabular 表示该资源没有可查询的行；使用 only: "datasets" 进行搜索。query_rejected 表示网关拒绝了查询子句，但不带子句的行请求成功；请简化查询，并使用 SoQL case(condition, value, true, fallback) 进行条件聚合。
• 每次调用最多返回 5000 行，支持偏移分页；普通行查询被截断时会返回 total_count（分组／聚合查询不返回该字段）
• assembled_query 会回显 SoQL 字符串，便于了解语法；除地理／位置列会返回嵌套对象外，所有 SODA 2.1 行值均为字符串
• 当 CANVAS_PROVIDER_TYPE=duckdb 且页面填满 limit 时，无论 limit 为何，最多 50,000 条匹配行会写入 DataCanvas 表（canvas_id、table_name、canvas_row_count）——使用 socrata_dataframe_describe 列出其列，然后使用 socrata_dataframe_query 运行 SQL。较小的 limit（例如 10）可在不返回大量内联数据的情况下暂存大量匹配行
• 类型化错误：not_tabular、query_rejected、invalid_id、not_found（列出 ID、查询的域名，以及已知时持有该 ID 的门户）、unknown_domain、invalid_domain、soql_error（SoQL 错误、未知列或类型不匹配——包含上游的 socrataCode，以及上游提供时的出错 column；恢复提示与错误代码相匹配：解析错误时提示使用 API 字段名，标识符未知时提供两种修复方法，类型不匹配时提供引用规则）、rate_limited（可重试；遵循上游的 Retry-After）

---

socrata_dataframe_describe _工具

• 需要提供先前 socrata_query_dataset 写入数据时返回的 canvas_id——画布无法枚举，因此省略该参数会报错 canvas_id_required，而不是列出表
• 显示每个已注册表的表名、行数和 DuckDB 列类型（SODA number → DOUBLE）
• 仅在设置了 CANVAS_PROVIDER_TYPE=duckdb 时有意义
• 类型化错误：canvas_id_required、canvas_not_found（令牌已过期或未知——重新运行 socrata_query_dataset 以暂存新画布）

---

socrata_dataframe_query _工具

• 仅支持针对由 socrata_query_dataset 暂存的 canvas_id 表执行 SELECT-only SQL；DDL、DML、文件引用、文件读取函数和引擎设置函数（current_schema、current_setting）均会被拒绝。请直接引用表，而不要使用 query_table；query() 只接受单个 SQL 字符串字面量。若暂存列名为 current_schema，请使用表名限定该列（t.current_schema）。
• 暂存列的类型根据 SODA 响应头确定：number 列（包括聚合别名）为 DOUBLE，因此无需转换类型即可进行数值比较（year > 2020、amount < 500）；文本和时间戳列保持为 VARCHAR——使用 CAST(date AS TIMESTAMP) 比较时间
• 每次调用最多返回 10,000 行，默认值为 1000
• 类型化错误：canvas_disabled（CANVAS_PROVIDER_TYPE=none）、canvas_not_found、table_not_found、sql_rejected（非 SELECT、访问系统目录或使用被拒绝的函数）
• 开箱即用——DuckDB 是常规依赖项，且默认启用；CANVAS_PROVIDER_TYPE=none 可将其禁用

---

socrata_dataframe_drop _工具

• 选择启用：在设置 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 格式错误时验证失败；若该数据集在此域名下不存在，则返回未找到错误（如果 Discovery 目录知道该 ID 所属的门户，还会注明该门户）

---

socrata://portals _资源

• 精选目录，包含 39 个已知的 Socrata 门户，采用游标分页（cursor 参数；每页默认 50 个，最多 200 个）
• 返回域名、组织名称和数据集的大致数量（0 = 没有数据集资源，null = 暂时不可用），缓存约 24 小时
• 将 domain 传给 socrata_find_datasets，可将搜索范围限定为一个门户

---

explore_open_data _提示词

• 参数：必需的 topic；可选的 portal 和 geography，用于跳过发现步骤或限定 WHERE 子句的范围
• 返回一条用户消息，引导完成六步工作流：查找门户 → 发现数据集 → 检查架构 → 查询 → 聚合 → 综合

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可切换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及结构化日志和可选的 OpenTelemetry 跟踪。

Socrata 专属功能：

• 完整集成 Socrata SODA 2.1 API——SoQL 查询构建器支持 select、where、group、having、order、search、limit、offset
• Discovery API 支持跨门户数据集搜索和按门户统计数据集数量（精选的 39 个门户目录，数量缓存约 24 小时）
• 支持 App token（SOCRATA_APP_TOKEN），以提高每个 IP 的速率限制
• 通过 SOCRATA_DEFAULT_DOMAIN 配置默认门户域名
• DataCanvas 溢出（内置 DuckDB）——大型查询结果会注册为 SQL 表，以便进行分析查询

便于 Agent 使用的输出：

• 每个 socrata_query_dataset 响应都会回显组装后的 SoQL 字符串，帮助 Agent 学习并优化语法
• 对空结果提供恢复提示——回显已应用的筛选条件，并给出具体的放宽建议
• 显示截断信息——行数达到上限时提供 truncated/shown/cap 字段，并建议翻页或提高上限；若结果已溢出暂存，还会指出暂存表以及两个 DataFrame 工具
• 所有工具都提供类型化错误原因（invalid_id、not_found、not_tabular、query_rejected、unknown_domain、invalid_domain、soql_error、rate_limited、canvas_id_required、canvas_not_found、table_not_found、sql_rejected、canvas_disabled），并附有可执行的恢复说明

开始使用

将以下内容添加到 MCP 客户端配置文件中。

公共托管实例

可使用公共实例 https://socrata.caseyjhand.com/mcp，无需安装。该实例使用 Streamable HTTP；每个客户端的配置格式各不相同。

对于 Claude Code：

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

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "streamableHttp",
      "url": "https://socrata.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "socrata-mcp-server": {
      "url": "https://socrata.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/socrata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 npx（无需 Bun）：

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/socrata-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "socrata-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/socrata-mcp-server:latest"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 可选：Socrata 应用令牌——在任意门户免费注册（例如 data.seattle.gov）即可获取更高的速率限制（每个令牌 10 req/s；不使用令牌时则共享受限流量池）。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/socrata-mcp-server.git

2. 进入目录：

cd socrata-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set SOCRATA_APP_TOKEN if you have one

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。主要环境变量：

变量	描述	默认值
SOCRATA_APP_TOKEN	Socrata 应用令牌（X-App-Token 标头）。不使用令牌时，请求会按来源 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 会解析为 stateful）。此服务将其显式设置为 stateless。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）：debug、info、notice、warning、error。	info
CANVAS_PROVIDER_TYPE	为大型结果集提供 DataCanvas 溢出存储；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	启用 OpenTelemetry 插桩。	false
LOG_TOOL_FAILURE_PAYLOADS	记录每次失败的工具调用参数和结果（仅对键名进行脱敏）。	false

请参阅 .env.example 查看完整的可选覆盖项列表。

运行服务

本地开发

• 构建并运行：

  # 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

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。默认会安装 OpenTelemetry 对等依赖项；如需省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 构建。

项目结构

目录	用途
src/index.ts	createApp() 入口点——注册工具、资源和提示词，并初始化 Socrata 服务。
src/config	使用 Zod 解析和验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。七个工具涵盖门户列表、数据集搜索、架构获取、SoQL 查询，以及 DataCanvas SQL 和清理操作。
src/mcp-server/resources	资源定义（*.resource.ts）。数据集元数据和门户目录资源。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。用于公民数据调查工作流的提示词。
src/services/socrata	Socrata 服务层——SODA 2.1 API 客户端、Discovery API、查询构建器、类型规范化。
tests/	与 src/ 目录结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理程序抛出异常，由框架捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 存储租户级数据
• 编写 WHERE 子句前先调用 socrata_get_dataset——SoQL 引用的是 field_name，而列的 data_type 决定是否需要加引号
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；切勿编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。