加拿大统计局网络数据服务 MCP 服务器

<div align="center"> <img src="./assets/StatCan-Header.png" alt="加拿大统计局 Logo" width="600"/> </div>

一个 MCP (模型上下文协议) 服务器，提供对加拿大统计局网络数据服务 (Web Data Service) 的访问，使 AI 助手能够通过自然语言发现、探索、分析和引用加拿大统计数据。

项目概述

该服务器解决了访问加拿大统计局网络数据服务 (WDS) API 的几个技术挑战：

1. API 格式要求: 确定了加拿大统计局 WDS API 端点的正确格式，以解决 406 错误
2. 弹性数据访问: 实现了多层缓存和回退，以应对 API 限制
3. 增强的元数据: 为统计解释和正确引用提供丰富的上下文
4. 分析能力: 包括统计分析、可视化和预测功能
5. MCP 集成: 与其他 MCP 服务器连接以扩展功能

特性

• 🔍 数据集发现: 按关键词、主题或地理位置搜索和浏览加拿大统计局数据集
• 📊 数据检索: 提取时间序列数据，并为关键向量提供正确的格式
• 📝 元数据探索: 访问有关数据集结构和内容的详细信息
• 💾 持久存储: 使用 SQLite 后端存储数据集以供将来使用
• 📊 高级分析: 执行全面的统计分析、趋势检测、季节性分析和预测
• 📈 可视化: 通过与 Vega-Lite 的集成生成数据可视化
• 📑 引用: 为加拿大统计局数据生成格式正确的引用
• 🖼️ 图表引用: 跟踪和引用从加拿大统计局数据创建的图表
• 🔄 API 弹性: 强大的错误处理，并为 API 限制提供回退

当前限制

加拿大统计局 WDS API 有几个限制，此服务器解决了这些限制：

• 数据检索约束: 尽管格式正确，但某些 API 端点仍然存在问题
• 格式敏感性: 向量 ID 必须是数字，没有 'v' 前缀，并且有效负载必须是数组格式
• 坐标访问: 基于向量的查询比基于坐标的查询更可靠
• 性能问题: 对于大型请求或高峰时段，某些 API 调用可能会超时
• 速率限制: 大量查询可能会受到加拿大统计局 WDS API 的限制

当前的实现使用以下策略来解决这些限制：

• 元数据、向量和立方体级别的多层缓存系统
• 常见统计指标的本地回退
• 自动格式调整和指数退避重试
• 当 API 端点失败时，优雅地降级到缓存数据

有关详细信息，请参见 docs/implementation_status.md 和 docs/api_connection_guide.md。

快速开始

# 克隆存储库
git clone https://github.com/yourusername/mcp-statcan.git
cd mcp-statcan

# 创建一个虚拟环境
python -m venv venv
source venv/bin/activate  # 在 Windows 上: venv\Scripts\activate

# 安装依赖
pip install -e .

# 启动 MCP 服务器
python -m src

依赖

pip install sqlitedict aiohttp mcp pydantic python-dotenv pandas numpy

与 Claude 一起使用

1. 打开 Claude 桌面应用程序
2. 转到设置 > MCP 服务器
3. 添加一个新服务器，配置如下：
   • 名称：StatCan Data
   • 命令：path/to/venv/bin/python -m src
4. 开始与 Claude 聊天，询问有关加拿大统计数据的问题！

可用的示例查询

以下是一些在当前实现中可靠工作的查询：

基本数据发现

• "查找有关加拿大消费者价格的数据集"
• "你们有哪些关于就业的数据集？"
• "显示最新的 CPI 数据"

基于向量的数据检索

• "获取 CPI 向量 41690973 的数据"
• "从向量 21581063 检索 GDP 数据"
• "获取就业向量 111955426 的最新值"

分析和可视化

• "生成过去 5 年 CPI 数据的折线图"
• "分析过去 10 个季度的 GDP 趋势"
• "创建失业率变化的图表"

引用

• "为消费者价格指数数据集生成引用"
• "我应该如何以 APA 格式引用加拿大统计局的 GDP 数据？"
• "为劳动力调查创建一个参考"

测试

要验证 API 客户端是否正常工作：

python -m tests.api.api_connection_steps

这将运行以下步骤的逐步测试：

• API 连接性
• 元数据检索
• 向量数据访问
• 格式要求

项目结构

• /src - 核心服务器实现
• /docs - 文档和指南
• /tests - API 和功能的测试套件
• /docs/references - API 规范和代码集

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参见 LICENSE 文件。

致谢

该项目使用来自 加拿大统计局 的数据，通过他们的 网络数据服务 API 访问。 它不隶属于加拿大统计局，也没有得到加拿大统计局的认可。

加拿大统计局的徽标仅用于提供信息，以指示数据来源。