Govdata MCP 服务器

用于govdata适配器的模型上下文协议（MCP）服务器。通过MCP工具提供对美国人口普查数据、证券交易委员会（SEC）文件、经济指标和地理数据的语义访问。

注这个服务器需要使用带有govdata适配器的Apache Calcite分支。

建筑学（或：建筑）

┌──────────────────────────────┐
│  Python MCP Server           │  ← This repo
│  - FastAPI + SSE transport   │
│  - 9 MCP tools               │
│  - API Key + JWT/OIDC auth   │
└──────────┬───────────────────┘
           │ JPype1 (JVM bridge)
           ▼
┌──────────────────────────────┐
│  Calcite Fat JAR             │  ← Built from github.com/kenstott/calcite
│  - JDBC driver               │
│  - Govdata adapter           │
│  - DuckDB sub-schema         │
└──────────────────────────────┘

先决条件

Python 3.9或更高版本
Java 17及以上版本 （Calcite JAR 所需）
MinIO 或 AWS S3 （数据存储所需）

- 服务器将Parquet文件和缓存数据存储在兼容S3的存储中 - 对于本地开发，请使用MinIO（轻量级的S3兼容服务器） - 对于生产环境，可以使用AWS S3、MinIO或其他兼容S3的服务

方解石脂肪JAR（注：这里的“JAR”可能是一个特定上下文中的术语或品牌名，直接翻译为“罐”可能不够准确，但在此保留原样以尊重原文的可能意图。如果“JAR”在特定领域有特定含义，应根据实际情况调整翻译。） - 从……开始构建 Kenstott/Calcite（注：Kenstott可能是一个人名或特定项目/组织的名称，Calcite可能指的是一个软件、库或项目名，具体含义需根据上下文确定）叉：

  git clone https://github.com/kenstott/calcite.git
  cd calcite
  ./gradlew :govdata:shadowJar
  # JAR will be at: govdata/build/libs/calcite-govdata-1.41.0-SNAPSHOT-all.jar

快速入门

0. 设置S3存储（本地开发使用MinIO）

服务器需要S3兼容的存储来存放数据。对于本地开发，请使用MinIO：

使用 Docker（推荐）：

# Start MinIO with Docker
docker run -d \
  -p 9000:9000 \
  -p 9001:9001 \
  --name minio \
  -v ~/minio/data:/data \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  quay.io/minio/minio server /data --console-address ":9001"

# Create required buckets
docker exec minio mc alias set local http://localhost:9000 minioadmin minioadmin
docker exec minio mc mb local/govdata-parquet
docker exec minio mc mb local/govdata-production-cache

或者使用 Homebrew（macOS）：

brew install minio/stable/minio
minio server ~/minio/data --console-address ":9001"

# In another terminal, create buckets:
mc alias set local http://localhost:9000 minioadmin minioadmin
mc mb local/govdata-parquet
mc mb local/govdata-production-cache

MinIO 控制台： 访问地址：http://localhost:9001（用户名：minioadmin，密码：minioadmin）

对于AWS S3： 更新 .env 使用您的AWS凭证并移除 AWS_ENDPOINT_OVERRIDE。

1. 安装依赖项

cd govdata-mcp-server
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .  # Install the package in editable mode

2. 所需的JAR文件（日志记录与DuckDB）

下载所需的JAR文件（SLF4J绑定和DuckDB JDBC驱动程序）：

./download-jars.sh

这个脚本将下载：

slf4j-reload4j-2.0.13.jar 翻译为中文是：“slf4j-reload4j 2.0.13 版本的 JAR 文件” (~11KB) - 用于 Calcite 日志记录的 SLF4J 2.x 绑定
DuckDB JDBC 驱动包 1.1.3 版本（文件名：duckdb-jdbc-1.1.3.jar） (~70MB) - 用于查询执行的DuckDB JDBC驱动程序

当服务器启动时，这些JAR文件将自动添加到Calcite JAR之前，作为类路径的一部分。

注如果JAR文件已经存在，脚本将跳过下载步骤。

3. 配置环境

复制 .env.example 到；向；朝 .env 并更新路径：

cp .env.example .env

编辑 .env 并进行以下配置：

必需 - Calcite 配置：

CALCITE_JAR_PATH=/path/to/calcite/govdata/build/libs/calcite-govdata-1.41.0-SNAPSHOT-all.jar

# For quick testing (downloads in ~5-10 minutes):
CALCITE_MODEL_PATH=/path/to/govdata-mcp-server/govdata-model-sample.json

# For full data (downloads in 1-2 days):
# CALCITE_MODEL_PATH=/path/to/govdata-mcp-server/govdata-model.json

模型文件对比：

模型	数据来源	下载时间	使用场景
`govdata-model-sample.json`	1家公司（苹果），2023-2024年，基础FRED数据系列	约5-10分钟	测试，开始吧
`govdata-model.json`	30家道琼斯工业指数（DJIA）成分股公司，2010-2025年，完整数据源	1-2天	生产，全面分析

建议： 以……开始 govdata-model-sample.json 验证一切正常后，如有需要再切换到完整模型。

必需 - MCP 服务器认证：

API_KEYS=your-api-key-here

必需 - AWS/S3 配置（适用于 MinIO 或 AWS S3）：

AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_ENDPOINT_OVERRIDE=http://0.0.0.0:9000
GOVDATA_PARQUET_DIR=s3://govdata-parquet
GOVDATA_CACHE_DIR=s3://govdata-production-cache

必填 - 政府数据API密钥：

Calcite 政府数据适配器需要各种政府数据源的API密钥。请免费注册：

FRED API (https://fred.stlouisfed.org/docs/api/api_key.html) 翻译为中文是：（圣路易斯联邦储备银行文档：API密钥页面）
BLS API (https://www.bls.gov/developers/api_signature_v2.html) 翻译为中文是：（美国劳工统计局开发者页面 - API签名v2）
BEA API 根据上面的信息，执行如下指令：
人口普查API (https://api.census.gov/data/注册密钥页面.html) （注：实际翻译时，“注册密钥页面”可能根据具体语境调整为“密钥申请页面”或“密钥获取页面”等，以更贴合中文表达习惯。）

把这些加到 .env：

FRED_API_KEY=your-fred-api-key
BLS_API_KEY=your-bls-api-key
BEA_API_KEY=your-bea-api-key
CENSUS_API_KEY=your-census-api-key

见 .env.example 如需额外的可选API密钥（FBI、NHTSA、FEMA、HUD等）。

可选 - 执行引擎

默认情况下，您可以将DuckDB用作查询处理的执行引擎。在您的（配置文件/环境中）进行配置 .env：

CALCITE_EXECUTION_ENGINE=DUCKDB

如果使用DuckDB，请确保DuckDB JDBC JAR文件已存在（参见所需的JAR文件）。您还可以控制长时间运行的下载任务：

GOVDATA_DOWNLOAD_TIMEOUT_MINUTES=2147483647

4. 运行服务器

推荐 - 使用启动脚本（含前提条件检查）：

# Development mode (with auto-reload)
./start-server.sh

# Production mode
./start-server.sh prod

# With debug logging
LOG_LEVEL=DEBUG ./start-server.sh

备选方案 - 直接命令：

# Using Python module
python -m govdata_mcp.server

# Using installed command
govdata-mcp

# Using uvicorn directly (production)
uvicorn govdata_mcp.server:app --host 0.0.0.0 --port 8080

服务器将在 http://0.0.0.0:8080 （可通过.env文件中的SERVER_HOST和SERVER_PORT进行配置）

5. 使用健康检查进行测试

curl http://0.0.0.0:8080/health

可用的MCP工具

服务器提供了9个MCP工具：

发现工具

列出模式（或架构） - 列出所有数据库模式
列出表（或：显示表列表） - 列出模式中的表
描述表 - 获取表的列详细信息

查询工具

查询数据 - 执行SQL查询
样本表 - 从表中抽取样本行

分析工具

配置文件表 - 统计分析配置文件（行数统计、不同值计数、最小值/最大值、空值统计）
搜索元数据 - 跨所有元数据的语义搜索

向量搜索工具

语义搜索 - 嵌入数据上的向量相似度搜索
列出向量源 - 列出多源向量的源表

认证

服务器支持两种认证方法：

API密钥（简单）

在请求中添加头部信息：

curl -H "X-API-Key: dev-key-12345" http://0.0.0.0:8080/messages

在其中进行配置 .env：

API_KEYS=key1,key2,key3

JWT/OAuth2（高级）

在请求中添加承载令牌：

curl -H "Authorization: Bearer " http://0.0.0.0:8080/messages

你有两个选择：

本地签名的JWT（简单，非提供商支持）

# .env
JWT_SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256

OIDC 提供商令牌（Azure AD、Google 等）

启用OIDC验证以接受由外部身份提供商颁发的令牌。在（相关配置界面/系统中）进行配置 .env：

# Enable OIDC/OAuth2 token validation
OIDC_ENABLED=true

# Issuer URL:
#  - Azure AD: https://login.microsoftonline.com//v2.0
#  - Google:   https://accounts.google.com
OIDC_ISSUER_URL=https://login.microsoftonline.com//v2.0

# Audience expected in tokens:
#  - Azure AD: your Application (client) ID or api://
#  - Google:   your OAuth client ID
OIDC_AUDIENCE=

# Optional overrides
# OIDC_JWKS_URL=  # normally discovered automatically from the issuer
# OIDC_CACHE_TTL_SECONDS=3600

# Security: when OIDC is enabled, local HS256 JWT fallback is DISABLED by default
# Set AUTH_ALLOW_LOCAL_JWT_FALLBACK=true only if you intentionally need to accept
# both provider-issued tokens and locally-signed JWTs.
# AUTH_ALLOW_LOCAL_JWT_FALLBACK=false

注：

确保您使用 OIDC_ISSUER_URL（而非 OIDC_ISSUER）并设置 OIDC_ENABLED=true。
启用OIDC后，默认情况下会拒绝本地签名的JWT；您可以通过设置AUTH_ALLOW_LOCAL_JWT_FALLBACK=true来启用回退机制。
你无需删除 JWT\_\* 变量；除非启用了本地回退，否则它们会被忽略。为了更高的安全性，你可以将它们移除。

示例：

Azure AD（单租户）：

- OIDC_ISSUER_URL=https://login.microsoftonline.com/ 翻译为中文是：OIDC颁发者URL=https://login.microsoftonline.com//v2.0（第二版/版本2.0） - OIDC_AUDIENCE=（此字段通常用于指定OIDC（OpenID Connect）的受众，即接收令牌的目标客户端或服务，此处为空表示未设置具体值）

谷歌

- OIDC_ISSUER_URL=https://accounts.google.com - OIDC_AUDIENCE=（此处表示OIDC受众参数未指定或留空）

注释：

仅执行验证（签名、过期时间、颁发者、受众）。此服务器不托管登录界面；请从您的提供商处获取令牌（例如，在客户端中使用OAuth授权码流程），并在Authorization头中呈现这些令牌。
API密钥仍将继续受到支持，并且可以与OIDC共存。

常见问题解答：使用私有JWT/OIDC服务器时，“客户端ID”（受众）是什么？

服务器将呈现的令牌中的aud声明与OIDC_AUDIENCE进行验证。在许多提供者中，此值被称为您要保护的资源（此MCP服务器）的客户端ID或API标识符。
在实际操作中，请将OIDC_AUDIENCE设置为在您的身份提供商中为此API配置的标识符。示例：

- Keycloak（开放身份联合，OIDC）： - OIDC_ISSUER_URL=https:///领地/ - OIDC_AUDIENCE=（此处表示OIDC受众参数未指定或留空） - 注：令牌可能包含多个受众。确保颁发令牌的客户端在aud中包含此API的客户端ID（通常通过启用“包含客户端受众”或将此API作为受众/范围来完成）。 - Auth0： - OIDC_ISSUER_URL=https://.auth0.com/ - OIDC_AUDIENCE=https://api.your-company.internal 或您在“应用程序”→“API”下配置的类似 UUID 的 API 标识符。 - 注：在Auth0中，API具有一个标识符，该标识符将成为aud声明。在此处使用该值（除非您已将应用程序的client_id配置为API标识符，否则不要使用）。 - Azure AD（私有租户）： - OIDC_ISSUER_URL=https://login.microsoftonline.com//v2.0 - OIDC_AUDIENCE=\ 或 api:// 根据你如何配置公开API而定。 - Google身份平台 / Firebase认证（OIDC模式）： - OIDC_ISSUER_URL=https://accounts.google.com（或您的联合身份提供者） - OIDC_AUDIENCE=（此处表示OIDC受众设置为空或未指定） - 使用您自己的JWKS自定义OIDC： - OIDC_ISSUER_URL=https://auth.您的域名.com - OIDC_AUDIENCE=（此处为等号后未给出具体值，若要完整表达，可译为“OIDC_AUDIENCE=（未指定）”或根据上下文补充具体值） - 如果发现服务不是标准的，可选地设置 OIDC_JWKS_URL=https://auth.your-domain.com/.well-known/jwks.json。

如果我有一个非OIDC的私有JWT服务器，该怎么办？

如果您无法公开标准的OIDC发现文档和JWKS，您可以选择以下两种方式之一：

- 通过配置JWT_SECRET_KEY和JWT_ALGORITHM=HS256，使用本地签名的JWT（采用HS256算法）。在此模式下，无需设置OIDC\_\*相关配置，且服务器不会强制要求aud（受众）参数。 - 或者实现一个兼容OIDC的JWKS（JSON Web Key Set）端点。然后设置OIDC_ENABLED=true，将OIDC_ISSUER_URL设置为您的颁发者URL，并且如果发现服务不可用，还可以选择性地设置OIDC_JWKS_URL为您的JWKS URL。

经验法则：

访问令牌中客户端呈现的aud声明中的任何值都应与.env文件中的OIDC_AUDIENCE相匹配。该值通常是您在身份提供商中为此MCP服务器创建的API/资源标识符。

安全注意事项

永远不要将真实的API密钥、JWT密钥或令牌提交到版本控制系统中。请使用 .env 在本地进行处理，并且只保留经过清理的示例 .env.example。
如果曾经泄露过任何秘密，请立即进行轮换（或更改）。
在生产中，设定一个强大的（标准/目标/体系等，具体根据上下文确定） API_KEYS 使用强密钥的JWT（JSON Web Token）来存储值或进行使用 JWT_SECRET_KEY并限制网络访问仅限于受信任的客户端。
建议在HTTPS（反向代理）后运行，并监控日志以检测未经授权的访问尝试。

MCP客户端配置

注除非您使用的是Claude at Work，否则浏览器版本的Claude不支持远程MCP服务器。

Claude Desktop - 选项1：stdio模式（本地使用最简单）

对于本地开发，直接将服务器作为stdio进程运行。这是 最简单的方法 - 无需单独的服务器进程。

更新 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "govdata": {
      "command": "python3",
      "args": [
        "-m",
        "govdata_mcp.server"
      ],
      "env": {
        "CALCITE_JAR_PATH": "/path/to/calcite/govdata/build/libs/calcite-govdata-1.41.0-SNAPSHOT-all.jar",
        "CALCITE_MODEL_PATH": "/path/to/govdata-mcp-server/govdata-model.json",
        "FRED_API_KEY": "your-fred-key",
        "BLS_API_KEY": "your-bls-key",
        "BEA_API_KEY": "your-bea-key",
        "CENSUS_API_KEY": "your-census-key",
        "AWS_ACCESS_KEY_ID": "minioadmin",
        "AWS_SECRET_ACCESS_KEY": "minioadmin",
        "AWS_ENDPOINT_OVERRIDE": "http://localhost:9000",
        "GOVDATA_PARQUET_DIR": "s3://govdata-parquet",
        "GOVDATA_CACHE_DIR": "s3://govdata-production-cache"
      }
    }
  }
}

重要提示：

请将路径和API密钥替换为您的实际值
确保MinIO正在运行（参见快速入门中的步骤0）
服务器自动检测stdio模式并运行，无需HTTP/SSE
编辑配置后重启Claude桌面版
日志出现在Claude Desktop的开发者控制台中

优点：

最简单的设置——无需单独的服务器进程
无需API密钥认证
非常适合本地开发和测试

Claude Desktop - 选项2：使用mcp-remote的HTTP/SSE

将服务器作为独立的HTTP服务运行（在多个客户端共享或调试时非常有用）：

单独启动服务器：

   ./start-server.sh

配置Claude桌面版：

{
  "mcpServers": {
    "govdata": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8080/messages/",
        "--header",
        "X-API-KEY: your-api-key-here",
        "--debug",
        "--allow-http"
      ]
    }
  }
}

重要提示：

替换 your-api-key-here 用其中的一把钥匙 API_KEYS 在你的 .env
该 --allow-http 本地开发（非HTTPS）需要标志
这个（或“该”） --debug 该标志提供详细日志记录以用于故障排除
编辑配置文件后重启Claude桌面版

优点：

服务器独立运行 - 可供多个客户端共享
更易于使用（某工具/方法）进行监控 LOG_LEVEL=DEBUG 在终端（或命令行界面）中
可以使用curl/HTTP工具进行测试

本地开发工作流程

要在本地运行MCP服务器并与Claude桌面端连接：

启动服务器：

   ./start-server.sh
   # Or with debug logging:
   LOG_LEVEL=DEBUG ./start-server.sh

配置Claude桌面版 使用上述配置（使用 http://127.0.0.1:8080/messages/）

重启Claude桌面版 加载新配置

测试连接 通过询问Claude：“列出govdata MCP服务器上可用的工具”

重要提示 - 初始数据下载：

⚠️ 首次启动服务器时，它会下载政府数据：

使用 govdata-model-sample.json （建议用于测试）5-10分钟

- 1家公司（苹果）的2023-2024年数据 - 基本的FRED经济数据系列 - 非常适合入门和测试

使用 govdata-model.json （完整的生产数据）1-2天

- 包含2010-2025年数据（数十GB）的30家道琼斯工业平均指数（DJIA）成分股公司 - 所有经济数据来源（FRED、BLS、BEA、财政部） - 人口普查和地理数据

生产配置小贴士：

从样本模型开始验证设置
编辑 govdata-model.json 调整年份范围、公司识别码（CIKs）和数据来源
设定；套装；一套 autoDownload: false 在模型中手动控制下载内容
使用MinIO或S3在实例之间共享下载的数据

监控下载进度：

服务器日志显示每个数据源的下载进度
与 LOG_LEVEL=DEBUG，您将看到证券交易委员会（SEC）文件提交的详细进展
数据被缓存于 .aperio/ （本地）和 s3://govdata-parquet (S3/MinIO)
后续启动速度很快（约1-2秒），因为使用了缓存数据

克劳德在工作（远程部署）

如果你有 《克劳德在工作》，您可以配置直接的HTTP/SSE连接到一个远程（公开可访问的）实例：

要求：

服务器必须托管在公共URL上（而非localhost）
必须配置OIDC认证（请参阅上文的“认证”部分）
强烈建议在生产环境中使用HTTPS

示例配置：

{
  "mcpServers": {
    "govdata": {
      "command": "true",
      "url": "https://your-mcp-server.example.com/messages",
      "headers": {
        "Authorization": "Bearer your-oidc-token"
      }
    }
  }
}

注：

这个 "command": "true" “workaround enables remote-only servers in Claude at Work” 可以翻译为：“通过变通方法，Claude at Work 支持仅远程服务器”
您必须实现OIDC认证（在.env文件中设置OIDC_ENABLED=true，OIDC_ISSUER_URL，OIDC_AUDIENCE）
仅凭API密钥不足以在Claude at Work中使用 - 请使用有效的OIDC令牌

其他MCP客户端

服务器通过HTTP实现MCP（机器通信协议）并使用服务器发送事件（SSE），应能与任何支持HTTP/SSE传输的MCP兼容客户端正常工作。

注虽然该服务器遵循MCP（多客户端协议）规范，理论上应能与其他客户端兼容，但主要是在与Claude Desktop进行测试。欢迎就与其他MCP客户端的兼容性提供反馈。

终点（或结果指标）：

主要的，重要的 http://0.0.0.0:8080/messages
别名： http://0.0.0.0:8080/sse （相同行为；为清晰起见而列出）

用法：

使用 GET 方法打开 SSE 读取流。
向已宣布的终端点发送POST请求（包括 session_id) 在写入通道上发送数据。
兼容性：POST 初始化到基础路径（无需 session_id) 返回 200 OK，因此某些客户端（例如 mcp-remote）不会将服务器标记为故障。

传输与认证：

交通SSE（服务器发送事件）
认证：X-API-Key 头部或 Authorization: Bearer 令牌

直接模式快速测试（curl）：

无会话ID的初始化（兼容路径）：

- curl -s -H "X-API-Key: "-H \\"Content-Type: application/json\\"" 翻译成中文是：“-H \\"内容类型: application/json\\"” 或者更自然的表达可以是：“-H \\"设置内容类型为 application/json\\"”。不过，在实际使用中，通常直接保留原样，因为这是HTTP头设置的常见格式 \ -d '{"jsonrpc":"2.0","id":0,"method":"initialize","params":{}}' 翻译成中文是：使用-d选项传递JSON-RPC请求，内容为初始化方法，无参数 \ http://127.0.0.1:8080/messages | jq . 翻译成中文是：“访问本地主机的8080端口上的/messages接口，并使用jq工具解析其输出”。

打开SSE流（观察端点事件）：

- curl -N -H "X-API-Key: "http://127.0.0.1:8080/messages 翻译为中文是：“http://127.0.0.1:8080/消息（或信息）”。不过，通常我们会直接保留网址的原样，因为网址本身是一种特定的格式和标识，不需要翻译。所以，更常见的表达方式是直接使用原网址：“http://127.0.0.1:8080/messages”

常见问题解答：Streamable HTTP 使用 /messages，而 SSE 使用 /sse？

无需进行硬性拆分。此服务器为两者使用同一个ASGI处理器，并为方便起见暴露了两个路径：

- /messages 是通过HTTP/SSE进行的MCP（多通道协议）的主要终点。 - /sse 是一个行为完全相同的别名。

两者都支持：

- SSE GET 用于建立读取流（您将收到一个 endpoint 与……一起的活动 ?session_id=...）。 - 向已公布的终端点发送POST请求（包括 session_id) 用于写入通道。 - 一个兼容路径，其中通过基础路径进行POST操作 { "method": "initialize" } 收到200 OK响应，以确保旧版客户端不会快速失败。

建议：引导客户至 /messages 除非你对政策或工具有所偏好 /sse在这台服务器上，两者是等效的。

示例查询

列出可用模式

# Via MCP tool call
{
  "tool": "list_schemas",
  "arguments": {}
}

查询人口普查数据

{
  "tool": "query_data",
  "arguments": {
    "sql": "SELECT state_fips, population_estimate FROM census.population_estimates WHERE year = 2020 LIMIT 10",
    "limit": 100
  }
}

“Profile a Table”可以翻译为“描述一个表格”或“表格概览”。具体翻译取决于上下文，但通常指的是对表格的结构、内容或特征进行简要说明或概述

{
  "tool": "profile_table",
  "arguments": {
    "schema": "census",
    "table": "acs_income",
    "columns": ["median_household_income", "poverty_rate"]
  }
}

在没有MCP服务器的情况下工作（无需Java/Calcite）

如果您无法访问Calcite govdata MCP服务器，或者暂时不想运行Java，您仍然可以直接使用随附的示例脚本来获取公共就业数据。

你现在可以做的

按州查询美国人口普查局美国社区调查（ACS）就业概况指标（DP03）
查询BLS时间序列数据（例如，非农就业总人数）
无需JVM或Calcite JAR文件

先决条件

已安装Python依赖项：使用pip安装requirements.txt文件中的依赖（requests已包含在内）
请将您的API密钥放入.env文件中（至少需要CENSOR_API_KEY和/或BLS_API_KEY）
在运行脚本时，将它们导出到您的环境中，例如：

- 导出$(使用grep命令从.env文件中查找以'CENSUS_API_KEY'或'BLS_API_KEY='开头的行，并通过xargs传递参数)

运行示例

人口普查（ACS 1年DP03概况——就业情况）：

- 运行 Python 脚本 examples/census_employment_example.py，参数为：使用人口普查数据，州为加州（CA），年份为2022年，限制返回结果数量为10条 - 省略--state将返回所有州。请使用两位字母的州代码或FIPS代码。

BLS（当前就业统计系列）：

- 运行 Python 脚本，执行 \examples/census_employment_example.py\，指定 BLS（美国劳工统计局）数据源，系列代码为 \CES0000000001\，起始时间为 2024 年 1 月，结束时间为 2024 年 12 月

注释

该脚本将JSON输出到标准输出，因此您可以根据需要将其通过管道传递给jq。
根据上述信息，以下是原文内容的翻译：存在速率限制；详情请参阅人口普查和BLS API文档。
当你准备好使用配备更丰富工具和SQL的Claude/其他MCP客户端时，请按照快速入门指南中的设置运行MCP服务器，然后使用下面的验证检查清单。

发展

项目结构

govdata-mcp-server/
├── src/govdata_mcp/
│   ├── __init__.py
│   ├── server.py          # Main MCP server
│   ├── config.py          # Configuration management
│   ├── jdbc.py            # JDBC connection via JPype
│   ├── auth.py            # Authentication middleware
│   └── tools/
│       ├── discovery.py   # Schema/table discovery
│       ├── query.py       # SQL execution
│       ├── profile.py     # Table profiling
│       ├── metadata.py    # Metadata search
│       └── vector.py      # Vector similarity search
├── tests/
├── .env                   # Environment configuration
├── .env.example           # Environment template
├── log4j.properties       # JVM logging configuration
├── pyproject.toml
├── requirements.txt
└── README.md

运行测试

pytest tests/

代码格式化

black src/
ruff check src/
mypy src/

Docker 部署

构建镜像

docker build -t govdata-mcp-server .

使用 Docker Compose 运行

docker-compose up

日志配置

服务器使用log4j进行JVM端的日志记录（Calcite、AWS SDK），并使用Python的标准日志记录功能为MCP服务器记录日志。

JVM 日志记录（log4j.properties）

配置Java日志记录 log4j.properties：

# Root logger
log4j.rootLogger=INFO, stdout

# Reduce AWS SDK verbosity
log4j.logger.com.amazonaws=WARN

# Calcite logging
log4j.logger.org.apache.calcite=INFO

# Govdata adapter - DEBUG shows detailed operations (data loading, queries, etc.)
log4j.logger.org.apache.calcite.adapter.govdata=DEBUG

注govdata适配器的日志级别也由JVM系统属性控制 -Dorg.apache.calcite.adapter.govdata.level=DEBUG 设定于 jdbc.py两者都必须配置为详细记录模式。

Python 日志记录

设置日志级别为 .env:

LOG_LEVEL=INFO  # Options: DEBUG, INFO, WARN, ERROR

启动警告

在启动过程中，您可能会看到 SLF4J 的警告信息：

SLF4J(W): No SLF4J providers were found.
SLF4J(W): Defaulting to no-operation (NOP) logger implementation

这些警告无害，可以安全地忽略。它们出现是因为 Calcite JAR 包中包含了 SLF4J 绑定但没有提供者。日志记录实际上是由 log4j 处理的。

故障排除

JVM 无法启动

确保已安装 Java 17 或更高版本： java -version
检查 Calcite JAR 文件路径是否正确
验证JAR文件是否存在且可读
检查JVM内存设置 jdbc.py （默认：最大8GB，初始2GB）

连接错误

检查Calcite模型JSON路径
确保MinIO正在运行（如果使用S3后端）
验证环境变量在 .env
启用调试日志记录：设置 log4j.logger.org.apache.calcite.adapter.govdata=DEBUG 在 log4j.properties

身份验证失败

检查API密钥是否匹配 .env 配置
对于JWT，验证密钥和算法
确保头部名称正确（X-API-Key 或者 Authorization）

性能注意事项

JVM 启动首次连接时约1-2秒
查询速度预热后的原生JDBC性能
内存Python进程 + JVM（为Java分配约2GB内存）

许可证

Apache许可证2.0

贡献

为仓库创建分支
创建一个特性分支
做出你的更改
添加测试
提交一个拉取请求

支持

对于以下相关问题：

MCP服务器此仓库中的未解决问题
Calcite/JDBC悬而未决的问题 kenstott/calcite（可译为“肯斯托特/卡尔西特”，但具体翻译可能需根据上下文调整，因为“kenstott”和“calcite”可能是特定名称或项目名）仓库
数据来源查阅govdata适配器的文档 kenstott/calcite（可译为“肯斯托特/卡尔西特”，但具体翻译可能需根据上下文或品牌含义调整）仓库

MCP客户端（Claude）验证检查清单

在Claude桌面版中使用这些提示来确认它实际上是在使用这台服务器。保持这台服务器持续运行 LOG_LEVEL=DEBUG 这样你就可以观察请求了。

先决条件

Claude Desktop配置包括：

{ "mcpServers": { "govdata": { "command": "npx",， "args": \[ “mcp-remote”， "http://127.0.0.1:8080/messages/" 翻译成中文可以是：“http://127.0.0.1:8080/消息/” 或者更自然一点的说法是：“本地主机的8080端口上的消息页面”。不过，通常网址在中文语境下直接保留原样，因为网址本身是一种国际通用的标识，不需要翻译。所以，直接使用“http://127.0.0.1:8080/messages/”即可，头球 “X-API-KEY: "， "--debug"， "--allow-http" 翻译成中文是：“--允许HTTP” \] } } }

编辑完配置后，重启Claude桌面版。

向克劳德提问什么（复制/粘贴）

初始化与工具

“列出govdata MCP服务器提供的可用工具。”
“govdata服务器上提供了哪些MCP工具？”

预期日志在此： /messages GET/POST，一种（方法/请求方式） initialize 信息传递，以及工具发现。

强制调用一个简单工具

“使用govdata MCP服务器，调用‘list_schemas’工具，并向我展示结果。”

预期日志： call_tool name=list_schemas 以及一个JSON数组响应。

列出模式中的表

“从govdata MCP服务器运行list_tables命令，指定schema为census。”

预期日志： call_tool name=list_tables arguments={"schema":"census"}。

描述一张桌子

“使用govdata的MCP工具describe_table，针对schema=census和table=acs_income进行描述。”

预期日志： call_tool name=describe_table ... 在响应中包含列的详细信息。

最小查询

“使用govdata MCP服务器，调用query_data方法，设置sql='SELECT 1 AS one'且limit=1。”

预期日志： call_tool name=query_data （数据/表格等）占一行 { "one": 1 }.

真实数据冒烟测试

“使用govdata MCP服务器，调用sample_table，设置schema为census，table为population_estimates，限制返回条数为5。”

预期日志： call_tool name=sample_table ... 并返回了几行数据。

错误路径检查

“使用 list_tables 命令，设置 schema=not_a_schema，并显示结果。”

预期结果：服务器对该工具调用记录一条错误日志；Claude 返回错误载荷/解释。

身份验证确认

在首次连接时，寻找以下其中之一：

Auth: OIDC enabled (issuer=..., audience=..., ...) 或
Auth: OIDC disabled. Accepting API keys and local JWT (...)

同时，每次请求时也： [SSE] /messages auth succeeded ... mode=API Key|Bearer.

SSE 握手正确性

克劳德连接后： Sent endpoint event: /messages?session_id=... 以及定期发送ping信号。
如果你曾经看到一个 POST /messages 没有 session_id服务器返回400状态码并附带指导信息（表明客户端路由错误），但Claude Desktop应自动向会话URL发送请求。

如果克劳德不使用服务器来回答自然语言问题

询问：“使用govdata MCP服务器，在人口普查模式中查找5个与就业相关的表名。”
如果日志中未出现工具调用，请强制使用：“您必须使用govdata MCP工具来回答。首先调用list_schemas。”

故障排除

配置名称必须匹配（govdata）并且该URL可以从Claude访问。
Claude中的API密钥必须匹配 API_KEYS。
尝试 http://127.0.0.1:8080/messages/ 如果出现回环问题。
保持 LOG_LEVEL=DEBUG 看见 [SSE] 和 call_tool 线条。

Govdata MCP Server

快速接入

详细介绍

Govdata MCP 服务器

建筑学（或：建筑）

先决条件

快速入门

0. 设置S3存储（本地开发使用MinIO）

1. 安装依赖项

2. 所需的JAR文件（日志记录与DuckDB）

3. 配置环境

可选 - 执行引擎

4. 运行服务器

5. 使用健康检查进行测试

可用的MCP工具

发现工具

查询工具

分析工具

向量搜索工具

认证

API密钥（简单）

JWT/OAuth2（高级）

安全注意事项

MCP客户端配置

Claude Desktop - 选项1：stdio模式（本地使用最简单）

Claude Desktop - 选项2：使用mcp-remote的HTTP/SSE

本地开发工作流程

克劳德在工作（远程部署）

其他MCP客户端

示例查询

列出可用模式

查询人口普查数据

“Profile a Table”可以翻译为“描述一个表格”或“表格概览”。具体翻译取决于上下文，但通常指的是对表格的结构、内容或特征进行简要说明或概述

在没有MCP服务器的情况下工作（无需Java/Calcite）

发展

项目结构

运行测试

代码格式化

Docker 部署

构建镜像

使用 Docker Compose 运行

日志配置

JVM 日志记录（log4j.properties）

Python 日志记录

启动警告

故障排除

JVM 无法启动

连接错误

身份验证失败

性能注意事项

许可证

贡献

支持

相关仓库

MCP客户端（Claude）验证检查清单

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP