BLS MCP Server

BLS MCP服务器

用于劳工统计局（BLS）数据的独立MCP（模型上下文协议）服务器，旨在通过本地和远程连接与多个LLM客户端一起工作。

特性

• 官方MCP SDK：与官方合作建造 mcp 用于完全协议控制的Python SDK
• 先模拟数据：使用逼真的模拟BLS数据进行快速开发和测试
• 多个传输：支持stdio（本地）和SSE（通过ngrok远程）
• 多LLM兼容：使用Claude、GPT-4和其他MCP兼容客户端进行测试
• 模块化设计：工具、资源和数据提供者之间的清晰分离

快速开始

安装

选项1：使用紫外线（推荐-快10倍！）

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Navigate to project
cd bls_mcp

# Sync dependencies (creates .venv automatically)
uv sync

# Run the server
./scripts/uv_start_server.sh

# Test the server
./scripts/uv_test_client.sh

看 UV_USAGE.md 用于全面的UV文档。

选项2：使用pip（传统）

# Clone the repository
cd bls_mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

# Or install with dev dependencies
pip install -e ".[dev]"

运行服务器（本地）

# With UV (recommended)
./scripts/uv_start_server.sh

# Or with traditional Python
python scripts/start_server.py

MCP检验员测试

# Install MCP inspector (if not already installed)
npm install -g @modelcontextprotocol/inspector

# Run inspector
mcp-inspector python scripts/start_server.py

项目状态

电流相位：第2阶段-增强工具（开始可视化）

第一阶段-基础✅ 完成

• \[x\] 已创建项目结构
• \[x\] 配置文件设置
• \[x\] 已实施模拟数据系统（8个CPI系列，114个数据点）
• \[x\] 使用stdio传输实现的核心MCP服务器
• \[x\] 已实现的基本工具（get_series、list_series、get_series_info）
• \[x\] 编写了17个单元测试（全部通过）
• \[x\] UV包管理器集成
• \[x\] SSE运输+ngrok支持（奖金！）
• \[x\] Claude桌面集成指南

第2阶段-增强工具（进行中）

• \[x\] 简单的可视化工具（静态图）- plot_series 工具
• \[\]高级分析工具
• \[\]数据比较工具

可用工具

第一阶段工具-数据访问

get_series

通过ID获取BLS数据系列，并可选择日期范围过滤。

参数：

• series_id （字符串，必填）：BLS系列ID（例如“CUUR0000SA0”）
• start_year （整数，可选）：数据范围的起始年份
• end_year （整数，可选）：数据范围的结束年份

例子：

{
  "name": "get_series",
  "arguments": {
    "series_id": "CUUR0000SA0",
    "start_year": 2020,
    "end_year": 2024
  }
}

list_series

列出具有可选过滤功能的可用BLS系列。

参数：

• category （字符串，可选）：按类别筛选（例如，“CPI”、“就业”）
• limit （整数，可选）：最大结果数（默认值：50）

get_series_info

获取特定BLS系列的详细元数据。

参数：

• series_id （字符串，必填）：BLS系列ID

第2阶段工具-可视化数据格式

plot_series

获取为客户端绘图格式化的CPI所有项目（CUUR0000SA0）数据。

特征：

• 返回准备绘制的结构化时间序列数据
• 无需参数-硬编码到CPI所有项目
• 包括统计数据（最小值、最大值、平均值）
• 按时间顺序排序的数据
• 绘制客户端渲染说明

参数：

• 无需

退货：

• data：｛date、value、year、month、period｝对象的数组
• statistics：{计数、最小值、最大值、平均值}
• date_range：{开始，结束}
• plot_instructions：建议的图表设置
• series_title：完整系列名称

例子：

{
  "name": "plot_series",
  "arguments": {}
}

示例响应：

{
  "status": "success",
  "series_id": "CUUR0000SA0",
  "series_title": "Consumer Price Index for All Urban Consumers: All Items",
  "data": [
    {"date": "2020-01", "value": 257.971, "year": "2020", "month": "01", "period": "M01"},
    ...
  ],
  "statistics": {
    "count": 60,
    "min": 257.971,
    "max": 314.540,
    "average": 285.234
  },
  "date_range": {
    "start": "2020-01",
    "end": "2024-12"
  },
  "plot_instructions": {
    "chart_type": "line",
    "x_axis": "date",
    "y_axis": "value",
    "title": "Consumer Price Index for All Urban Consumers: All Items",
    "x_label": "Date",
    "y_label": "Index Value"
  }
}

注： 此工具返回用于客户端绘图的数据，而不是预渲染图像。客户端（ChatGPT、Claude等）可以使用这些数据在自己的环境中创建图表。

建筑

目录结构

bls_mcp/
├── src/bls_mcp/
│   ├── server.py              # Main MCP server
│   ├── transports/
│   │   ├── stdio.py          # stdio transport (local)
│   │   └── sse.py            # SSE transport (remote - Phase 2)
│   ├── tools/
│   │   ├── base.py           # Base tool class
│   │   ├── get_series.py     # Get series tool
│   │   ├── list_series.py    # List series tool
│   │   └── get_series_info.py # Get series info tool
│   ├── data/
│   │   ├── mock_data.py      # Mock data provider
│   │   └── fixtures/         # JSON data fixtures
│   └── utils/
│       ├── logger.py         # Logging configuration
│       └── validators.py     # Input validation
├── tests/                     # Test suite
├── scripts/                   # Utility scripts
└── docs/                      # Documentation

数据流

1. 客户请求 → MCP协议（JSON-RPC）
2. 传输层 → stdio或SSE
3. 服务器路由器 → 通往合适工具的路线
4. 工具执行 → 从提供程序获取数据
5. 数据提供者 → 模拟或真实数据源
6. 响应 → JSON格式的响应

模拟数据

服务器使用符合实际BLS API结构的真实模拟BLS数据：

• CPI系列：各类消费者价格指数数据
• 时间范围：2020-2024年每月数据点
• 覆盖：多个类别（所有项目、食品、能源、住房等）
• 现实价值观：基于实际的BLS数据模式

发展

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=bls_mcp

# Run specific test file
pytest tests/test_tools.py

代码质量

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

添加新工具

1. 在中创建工具文件 src/bls_mcp/tools/
2. 按照基本模式实现工具类
3. 在中注册工具 server.py
4. 在中添加测试 tests/test_tools.py
5. 更新文档

路线图

第一阶段：基础✅ 完成

• \[x\] 项目设置和配置
• \[x\] 模拟数据系统
• \[x\] 带stdio传输的核心MCP服务器
• \[x\] 基本工具（get_series、list_series、get_series_info）
• \[x\] 单元测试（17项测试，全部通过）
• \[x\] UV包管理器集成
• \[x\] SSE运输实施（奖金！）
• \[x\] ngrok集成（奖金！）
• \[x\] Claude桌面集成指南

第2阶段：增强工具（进行中）

• \[\]可视化工具（简单的静态图）
• \[\]数据比较和分析工具
• \[\]多LLM客户端测试
• \[\]增强的错误处理和验证

第三阶段：高级功能

• \[\]MCP资源（目录、文档）
• \[\]预构建的分析提示
• \[\]高级可视化（交互式图表）
• \[\]迁移到真实BLS数据的路径

配置

创建一个 .env 文件（复制自 .env.example):

MCP_SERVER_PORT=3000
MCP_SERVER_HOST=localhost
LOG_LEVEL=INFO
DATA_PROVIDER=mock

贡献

这是一个个人项目，但欢迎提出建议和反馈！

许可证

MIT许可证-有关详细信息，请参阅许可证文件

相关项目

• bls_data -BLS综合数据工具包（母项目）
• 模型上下文协议 -MCP规范和文件

支持

有关问题或疑问，请参阅 docs/ 目录或查看PLAN.md文件以了解开发详细信息。