# Israel Statistics MCP Server

A **Model Context Protocol (MCP) server** that provides programmatic access to the Israeli Central Bureau of Statistics (CBS) price indices and economic data. Built with TypeScript, this server offers 8 comprehensive tools for retrieving, analyzing, and calculating Israeli economic statistics.

## 🐳 **Installation & Usage**

### **Docker (Recommended)**

```json
// .mcp.json
{
  "israel-statistics-mcp": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "reuvenaor/israel-statistics-mcp:latest"]
  }
}
```

### **NPX**

```json
// .mcp.json
{
  "israel-statistics-mcp": {
    "command": "npx",
    "args": ["@reuvennaor85/israel-statistics-mcp"]
  }
}
```

### **Claude Desktop Integration**

```bash
# Quick setup
claude mcp add --scope project israel-statistics-mcp npx @reuvennaor85/israel-statistics-mcp
```

## 🚀 **Features**

### **📊 Comprehensive Economic Data Access**

- **Consumer Price Index (CPI)** - General and detailed price indices
- **Housing Market Index** - Real estate prices with bi-monthly updates
- **Producer Price Indices** - Industrial, exports, and services
- **Specialized Indices** - Construction, agriculture, transportation, and more
- **Price Linkage Calculator** - Inflation adjustment calculations

### **🛡️ Enterprise-Grade Architecture**

- **Type-Safe Validation** - Complete Zod schema validation for all inputs/outputs
- **Rate Limiting** - Built-in protection (5 concurrent operations max)
- **Error Handling** - Comprehensive CBS API error handling and retry logic
- **Multi-Format Support** - JSON and XML response parsing
- **Housing Market Warnings** - Automatic notifications for bi-monthly provisional data

### **🔄 Advanced Data Processing**

- **XML/JSON Transformation** - Seamless conversion from CBS API formats
- **Statistical Calculations** - Automatic averages, counts, and summaries
- **Date Range Filtering** - Flexible period selection (monthly/quarterly)
- **Search & Discovery** - Full-text search across indices and topics
- **Pagination Support** - Handle large datasets efficiently (up to 1000 items/page)

## 📋 **Available MCP Tools**

| Tool                   | Description                                      | Key Parameters                             |
| ---------------------- | ------------------------------------------------ | ------------------------------------------ |
| `get_index_topics`     | Browse all available index categories and topics | `period`, `searchText`, `lang`             |
| `get_catalog_chapters` | Get all index chapters (CPI, Housing, etc.)      | `lang`, `pagesize`                         |
| `get_chapter_topics`   | Get topics within a specific chapter             | `chapterId`, `lang`                        |
| `get_subject_codes`    | Get index codes for a specific topic             | `subjectId`, `searchText`                  |
| `get_index_data`       | Retrieve historical price data for an index      | `code`, `startPeriod`, `endPeriod`         |
| `get_index_calculator` | Calculate inflation-adjusted values              | `indexCode`, `value`, `fromDate`, `toDate` |
| `get_main_indices`     | Get current main economic indices                | `oldFormat`, `lang`                        |
| `get_all_indices`      | Get comprehensive index data with filtering      | `chapter`, `oldFormat`                     |

## 🏗️ **Architecture**

```
src/
├── index.ts                    # MCP server entry point with tool registration
├── mcp/
│   ├── handlers/              # 8 MCP tool handlers
│   │   ├── getIndexTopics.ts     # Browse available indices
│   │   ├── getCatalogChapters.ts # Get index chapters
│   │   ├── getChapterTopics.ts   # Topics by chapter
│   │   ├── getSubjectCodes.ts    # Index codes by topic
│   │   ├── getIndexData.ts       # Historical price data
│   │   ├── getIndexCalculator.ts # Inflation calculator
│   │   ├── getMainIndices.ts     # Main indices (current + by period)
│   │   └── getAllIndices.ts      # All indices with filtering
│   └── helpers/
│       ├── fetcher.ts            # Secure CBS API client with XML/JSON parsing
│       └── housingWarnings.ts    # Housing market data warnings
├── schemas/                   # Type-safe Zod validation schemas
│   ├── request.schema.ts         # Input validation schemas
│   ├── response.schema.ts        # Output validation schemas
│   ├── base.schema.ts           # Reusable object schemas
│   └── shared.schema.ts                # Common enums and types
└── utils/
    ├── registry-security.ts      # Security utilities
    └── spinner.ts               # MCP progress notifications
```

### **🔒 Security Features**

- **Rate Limiting**: Maximum 5 concurrent operations
- **Input Validation**: Comprehensive Zod schema validation
- **URL Validation**: Allowlist-based registry URL security
- **Error Sanitization**: Safe error message handling
- **Timeout Protection**: 30-second HTTP request timeouts

### **📝 Schema Architecture**

## 📊 **CBS API Coverage**

The server implements **complete coverage** of the CBS Israel Statistics API:

### **Index Discovery Endpoints**

- `GET /index/catalog/tree` → `get_index_topics`
- `GET /index/catalog/catalog` → `get_catalog_chapters`
- `GET /index/catalog/chapter` → `get_chapter_topics`
- `GET /index/catalog/subject` → `get_subject_codes`

### **Data Retrieval Endpoints**

- `GET /index/data/price` → `get_index_data`
- `GET /index/data/calculator/{id}` → `get_index_calculator`
- `GET /index/data/price_selected` → `get_main_indices`
- `GET /index/data/price_selected_b` → `get_main_indices_by_period`
- `GET /index/data/price_all` → `get_all_indices`

### **Supported Index Categories**

| Chapter | Description                       | Examples                        |
| ------- | --------------------------------- | ------------------------------- |
| `a`     | Consumer Price Index              | Food, clothing, housing costs   |
| `aa`    | Housing Market Index              | Real estate prices (bi-monthly) |
| `b`     | Producer Price Index - Industrial | Manufacturing output prices     |
| `ba`    | Producer Price Index - Exports    | Export prices for industry      |
| `bb`    | Producer Price Index - Services   | Service industry prices         |
| `c`     | Residential Building Input        | Construction material costs     |
| `ca`    | Commercial Building Input         | Office building costs           |
| `d`     | Road Construction Input           | Infrastructure costs            |
| `e`     | Agriculture Input                 | Agricultural input costs        |
| `f`     | Bus Input                         | Public transportation costs     |
| `fa`    | Public Minibus Input              | Public transport vehicle costs  |

## ⚠️ **Housing Price Index Special Considerations**

The server automatically detects and warns about Housing Price Index data:

- **Bi-monthly Publication**: Updates every 2 months vs. monthly for other indices
- **Temporal Lag**: Data reflects transactions from 2-3 months ago vs. 3-4 months ago
- **Provisional Data**: Last 3 indices may be updated when additional reports arrive
- **Linkage Warnings**: Automatic recommendations against using provisional periods

## 🧪 **Testing & Quality Assurance**

### **Comprehensive Test Suite**

- **Unit Tests**: Complete handler coverage with Vitest
- **Integration Tests**: Real CBS API integration tests
- **Mock Testing**: Isolated handler testing with mocked dependencies
- **Error Handling**: Network error and API error simulation
- **Schema Validation**: Input/output validation testing

### **Code Quality Tools**

- **TypeScript**: Strict type checking with no `any` types
- **ESLint**: Modern flat config with TypeScript rules
- **Prettier**: Consistent code formatting
- **Zod**: Runtime type validation and inference

### **Development Commands**

```bash
# Development
pnpm dev              # Watch mode development
pnpm build           # Production build
pnpm typecheck       # TypeScript validation

# Testing
pnpm test            # Run all tests
pnpm test:dev        # Development mode testing

# Quality
pnpm lint            # Lint code
pnpm lint:fix        # Fix linting issues
pnpm format:check    # Check formatting
pnpm format:write    # Apply formatting

# Docker
docker build -t reuvenaor/israel-statistics-mcp:latest -f Dockerfile .
```

## 🔧 **Development**

### **Project Structure**

- **TypeScript ESM**: Modern ES modules with TypeScript
- **pnpm**: Fast, efficient package management
- **tsup**: Fast TypeScript bundler with ESM output
- **Docker**: Multi-stage builds for optimized containers
- **Vitest**: Fast unit testing framework

### **Key Dependencies**

- `@modelcontextprotocol/sdk`: MCP server implementation
- `zod`: Type-safe validation and schema inference
- `node-fetch`: HTTP client for CBS API calls
- `xml2js`: XML response parsing
- `typescript`: Type system and compilation

### **Configuration Files**

- `tsconfig.json`: TypeScript configuration with strict settings
- `eslint.config.js`: Modern ESLint flat configuration
- `prettier.config.cjs`: Code formatting rules
- `vitest.config.ts`: Test framework configuration
- `tsup.config.ts`: Build tool configuration
- `Dockerfile`: Multi-stage container build

## 📈 **Performance & Scalability**

- **Rate Limiting**: 5 concurrent operations maximum
- **Efficient Parsing**: Optimized XML/JSON transformation
- **Memory Management**: Streaming for large datasets
- **Caching**: Schema validation caching
- **Error Recovery**: Graceful degradation and retry logic

## 📝 **API Response Examples**

### **Index Topics Discovery**

```typescript
// Input
{ lang: "en", searchText: "housing", period: "M" }

// Output
{
  topics: [
    {
      chapterId: "aa",
      chapterName: "Housing Market Index",
      subject: [
        {
          subjectId: 123,
          subjectName: "Apartment Prices",
          code: [
            {
              codeId: 180010,
              codeName: "Housing Price Index - General"
            }
          ]
        }
      ]
    }
  ],
  summary: "Found 15 index codes. ⚠️ Housing Price Index: This is a bi-monthly index..."
}
```

### **Price Linkage Calculation**

```typescript
// Input
{
  indexCode: 120010,
  value: 1000,
  fromDate: "01-01-2020",
  toDate: "01-01-2024"
}

// Output
{
  request: { code: 120010, sum: 1000, from_date: "2020-01-01", to_date: "2024-01-01" },
  answer: {
    from_value: 1000,
    to_value: 1155.2,
    change_percent: 15.52,
    base_year: "2022"
  },
  summary: "Linked 1000 from 2020-01-01 to 2024-01-01: 1155.2 (15.52% change)"
}
```

## 📄 **License**

MIT License - see [LICENSE](LICENSE) file for details.

## 🔗 **Links**

- **Repository**: [https://github.com/reuvenaor/israel-statistics-mcp](https://github.com/reuvenaor/israel-statistics-mcp)
- **Docker Hub**: [reuvenaor/israel-statistics-mcp](https://hub.docker.com/r/reuvenaor/israel-statistics-mcp)
- **NPM Package**: [@reuvennaor85/israel-statistics-mcp](https://www.npmjs.com/package/@reuvennaor85/israel-statistics-mcp)
- **CBS API Documentation**: [Israel Central Bureau of Statistics](https://api.cbs.gov.il/)
- **MCP Protocol**: [Model Context Protocol Specification](https://modelcontextprotocol.io/)

---

**Built with ❤️ for the Israeli tech community and economic research**