Skillget

israel-statistics-mcp

skill
SUMMARY

Israel Statistics MCP

README.md

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)

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

NPX

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

Claude Desktop Integration

# 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

# 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

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

// 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 file for details.

🔗 Links

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

Yorumlar (0)

Sonuc bulunamadi