# BLS MCP Server

A standalone MCP (Model Context Protocol) server for Bureau of Labor Statistics (BLS) data, designed to work with multiple LLM clients through both local and remote connections.

## Features

- **Official MCP SDK**: Built with the official `mcp` Python SDK for full protocol control
- **Mock Data First**: Uses realistic mock BLS data for rapid development and testing
- **Multiple Transports**: Supports both stdio (local) and SSE (remote via ngrok)
- **Multi-LLM Compatible**: Test with Claude, GPT-4, and other MCP-compatible clients
- **Modular Design**: Clean separation between tools, resources, and data providers

## Quick Start

### Installation

#### Option 1: Using UV (Recommended - 10x faster!)

```bash
# 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
```

See [UV_USAGE.md](docs/UV_USAGE.md) for comprehensive UV documentation.

#### Option 2: Using pip (Traditional)

```bash
# 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]"
```

### Running the Server (Local)

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

# Or with traditional Python
python scripts/start_server.py
```

### Testing with MCP Inspector

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

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

## Project Status

**Current Phase**: Phase 2 - Enhanced Tools (Starting Visualization)

### Phase 1 - Foundation ✅ COMPLETE
- [x] Project structure created
- [x] Configuration files set up
- [x] Mock data system implemented (8 CPI series, 114 data points)
- [x] Core MCP server implemented with stdio transport
- [x] Basic tools implemented (get_series, list_series, get_series_info)
- [x] 17 unit tests written (all passing)
- [x] UV package manager integration
- [x] SSE transport + ngrok support (bonus!)
- [x] Claude Desktop integration guide

### Phase 2 - Enhanced Tools (In Progress)
- [x] Simple visualization tool (static plots) - `plot_series` tool
- [ ] Advanced analysis tools
- [ ] Data comparison tools

## Available Tools

### Phase 1 Tools - Data Access

#### `get_series`
Fetch BLS data series by ID with optional date range filtering.

**Parameters:**
- `series_id` (string, required): BLS series ID (e.g., "CUUR0000SA0")
- `start_year` (integer, optional): Start year for data range
- `end_year` (integer, optional): End year for data range

**Example:**
```json
{
  "name": "get_series",
  "arguments": {
    "series_id": "CUUR0000SA0",
    "start_year": 2020,
    "end_year": 2024
  }
}
```

#### `list_series`
List available BLS series with optional filtering.

**Parameters:**
- `category` (string, optional): Filter by category (e.g., "CPI", "Employment")
- `limit` (integer, optional): Maximum number of results (default: 50)

#### `get_series_info`
Get detailed metadata about a specific BLS series.

**Parameters:**
- `series_id` (string, required): BLS series ID

### Phase 2 Tools - Data Formatting for Visualization

#### `plot_series`
Get CPI All Items (CUUR0000SA0) data formatted for client-side plotting.

**Features:**
- Returns structured time series data ready for plotting
- No parameters needed - hardcoded to CPI All Items
- Includes statistics (min, max, average)
- Chronologically sorted data
- Plot instructions for client-side rendering

**Parameters:**
- None required

**Returns:**
- `data`: Array of {date, value, year, month, period} objects
- `statistics`: {count, min, max, average}
- `date_range`: {start, end}
- `plot_instructions`: Suggested chart settings
- `series_title`: Full series name

**Example:**
```json
{
  "name": "plot_series",
  "arguments": {}
}
```

**Example Response:**
```json
{
  "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"
  }
}
```

**Note:** This tool returns data for client-side plotting, not pre-rendered images. The client (ChatGPT, Claude, etc.) can use this data to create charts in their own environment.

## Architecture

### Directory Structure

```
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
```

### Data Flow

1. **Client Request** → MCP protocol (JSON-RPC)
2. **Transport Layer** → stdio or SSE
3. **Server Router** → Route to appropriate tool
4. **Tool Execution** → Fetch data from provider
5. **Data Provider** → Mock or real data source
6. **Response** → JSON formatted response

## Mock Data

The server uses realistic mock BLS data that follows the actual BLS API structure:

- **CPI Series**: Consumer Price Index data for various categories
- **Time Range**: 2020-2024 with monthly data points
- **Coverage**: Multiple categories (All Items, Food, Energy, Housing, etc.)
- **Realistic Values**: Based on actual BLS data patterns

## Development

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=bls_mcp

# Run specific test file
pytest tests/test_tools.py
```

### Code Quality

```bash
# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/
```

### Adding New Tools

1. Create tool file in `src/bls_mcp/tools/`
2. Implement tool class following the base pattern
3. Register tool in `server.py`
4. Add tests in `tests/test_tools.py`
5. Update documentation

## Roadmap

### Phase 1: Foundation ✅ COMPLETE
- [x] Project setup and configuration
- [x] Mock data system
- [x] Core MCP server with stdio transport
- [x] Basic tools (get_series, list_series, get_series_info)
- [x] Unit tests (17 tests, all passing)
- [x] UV package manager integration
- [x] SSE transport implementation (bonus!)
- [x] ngrok integration (bonus!)
- [x] Claude Desktop integration guide

### Phase 2: Enhanced Tools (In Progress)
- [ ] Visualization tools (simple static plots)
- [ ] Data comparison and analysis tools
- [ ] Multi-LLM client testing
- [ ] Enhanced error handling and validation

### Phase 3: Advanced Features
- [ ] MCP resources (catalogs, documentation)
- [ ] Pre-built prompts for analysis
- [ ] Advanced visualization (interactive charts)
- [ ] Migration path to real BLS data

## Configuration

Create a `.env` file (copy from `.env.example`):

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

## Contributing

This is a personal project, but suggestions and feedback are welcome!

## License

MIT License - see LICENSE file for details

## Related Projects

- [bls_data](../bls_data/) - Comprehensive BLS data toolkit (parent project)
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification and documentation

## Support

For issues or questions, please refer to the documentation in the `docs/` directory or check the PLAN.md file for development details.