Open Census MCP Server

关键词

统计上下文服务工具集成Census 数据接入Pragmatics 渲染MCP 服务器实现

使用说明（Markdown 格式）

项目简介

  • 本项目实现了一个基于 Model Context Protocol (MCP) 的后端服务器，面向 LLM 客户端提供结构化的上下文服务。核心能力包括资源管理、工具注册与执行、以及 Prompt 模板的定义与渲染，全部通过标准化的 MCP 协议进行通信。

主要功能点

  • MCP 核心协议实现：提供服务器端的工具注册、调用以及资源访问能力，遵循 MCP 的请求/响应模式。
  • 资源与资源包（Resources / Packs）：通过 PackLoader 加载与管理多个数据包，提供上下文数据源给 LLM 客户端。
  • 工具注册与执行（Tools）：实现三个核心工具，分别是 get_methodology_guidance、get_census_data（含对 get_acs_data 的向后兼容）以及 explore_variables，支持工具调用和结果回传。
  • Prompt 定义与渲染（Prompts）：实现 Pragmatics Retriever 与相关模块，提供 grounding 的上下文并将检索到的片段整合进系统提示，支撑不同交互模式（控制、RAG、Pragmatics）。
  • JSON-RPC 风格通信：通过 MCP 库实现的 JSON-RPC 栈进行请求/响应和通知传输（含工具调用、资源读取等）。
  • 会话与能力声明：实现对会话状态、能力清单以及多模态传输的支持，确保可扩展性与安全性。
  • 多传输支持雏形：当前实现以 StdIO 为传输，未来可扩展至 SSE/WebSocket 等传输协议。
  • 兼容性与测试用例：内含若干集成测试用例与示例，确保服务端逻辑的有效性。

安装与运行

  • 运行前提：确保 Python3 及相关依赖已就绪（项目内包含的 Python 模块及依赖在运行环境中安装完成）。
  • 启动服务器：直接运行入口入口点 python -m census_mcp.server。该入口会在当前进程中启动 MCP 服务器并进入事件循环，等待 JSON-RPC 请求。
  • 注意事项：
    • 服务器默认从 PACKS_DIR（"packs"）加载资源包并初始化必要组件（如 PackLoader、PragmaticsRetriever、CensusClient）。
    • 若需要对 Census API Key 进行绑定，请在环境变量中设置 CENSUS_API_KEY，或在 .env 文件中配置以供加载。
    • 服务器默认使用 stdio 传输模式（适合嵌入式调用或本地开发环境），如需网络传输，需要使用 MCP 框架支持的其他传输适配器。

服务器配置（MCP 客户端连接所需） 以下为示例配置JSON格式，描述服务器启动命令及必要参数，供 MCP 客户端连接使用。请将该配置用于客户端阶段在连接 MCP 服务器时的初始引导信息；具体字段含义如下：

  • server_name: MCP 服务器名称，应与服务端配置一致（本项目默认名为 census-mcp）。
  • command: 启动服务器的命令（不包含具体参数以便跨平台移植性）。
  • args: 启动命令的参数列表（如需要工作目录、网络端口等，可在此传递）。
  • env: 服务器运行时环境变量（如 PACKS_DIR、CENSUS_API_KEY 等）。

{ "server_name": "census-mcp", "command": "python", "args": ["-m", "census_mcp.server"], "env": { "PACKS_DIR": "packs", "CENSUS_API_KEY": "<你的 Census API Key（可选，若环境变量未设置）>" } }

使用示例

  • 启动并连接：在客户端环境下按照 MCP 客户端的接入文档提供的流程，通过上述配置启动并建立 JSON-RPC 连接。
  • 功能调用：通过 MCP 客户端调用工具 get_methodology_guidance、get_census_data、explore_variables 等，服务器将返回结构化的 JSON-RPC 响应或带有上下文的结果。

基本使用方法

  • 启动方式：运行 python -m census_mcp.server，即可启动 MCP 服务器。
  • 常见操作流程：客户端发送请求，服务器根据请求类型分发给对应的工具实现，返回 MCP 格式的响应并携带必要的上下文（如 pragmatics 指引、数据源等）。
  • 扩展性：服务器具备资源管理、工具调用、Prompts 渲染等功能，支持在投产环境中对资源源、工具集、Prompt 模板进行扩展与升级。

注意事项与风险

  • 当前实现以 StdIO 传输为主，若需要网络化暴露，请参考 MCP 框架的传输适配器实现，确保安全性（鉴权、日志、审计等）。
  • 鼓励在生产环境中对资源包进行版本管理与签名验证，确保模型对上下文的一致性和可追溯性。

服务器信息

访问项目