Skip to content

MCP Lightcast 0.3.0

Version 0.3.0 adds Core LMI, updates the server to current Lightcast and MCP contracts, and requires Python 3.14 or newer. This release includes breaking tool changes: read the migration guide before upgrading an existing integration.

Core LMI

Five new tools expose Lightcast's Core LMI (Agnitio) API:

  • list_core_lmi_datasets: discover datasets available to your account.
  • get_core_lmi_versions: discover releases for a dataset.
  • get_core_lmi_metadata: inspect measures, dimensions, and query capabilities.
  • get_core_lmi_dimension: discover valid dimension codes.
  • query_core_lmi: query employment, earnings, industry trends, education completions, and other licensed datasets.

The Core LMI examples show how to compare software developer employment and wages in California and Washington, combine county restaurant employment, measure industry concentration and shift share, and inspect university computer science completions. Queries preserve null values, column labels, and release provenance, with a separate agnitio OAuth scope and rate limiter.

Live checks on November 12, 2026 found 52 datasets for the tested account. Queries against occupation, industry, and education completions on release 2026.4 passed. Access depends on your Lightcast license. Native API offsets were ignored in live testing, so the client implements bounded local pagination: up to 500 rows per page within the first 5,000 rows, with unknown totals reported as null. Cost-of-living metadata was accessible, but its documented query schema failed upstream validation; working cost-of-living queries are not claimed.

Breaking changes and migration

  • Python >=3.14. Python 3.12 and 3.13 are no longer supported. CI tests 3.14 and 3.15; Docker and release builds use 3.14.
  • Transport defaults to stdio. Set --transport streamable-http explicitly for HTTP. Reverse proxies must configure trusted hosts and origins.
  • Skills contracts are corrected. skill_type accepts IDs such as ST1, ST2, and ST3; unsupported category/subcategory filters are removed. Returned type values retain {id, name}. find_similar_skills returns the API envelope containing data and any warning.
  • Job Postings uses native requests. Replace free-form query, location, occupation_ids, and version arguments with filters, fields, limit, and page. Supply the required filters.when date range.
  • Occupation Benchmark uses native dimensions. Replace the region string and generic version with a region object, LOT dimension, and lot_version; choose actual dataset names in metrics.
  • Version families are independent. Discover releases or use supported latest aliases. Workflows take separate taxonomy, classifier, and LOT version parameters. Read workflow_metadata.status and preserve upstream warnings when a stage returns a partial result.
  • Python imports and configuration change. Import mcp_lightcast, not src.mcp_lightcast. Use LIGHTCAST_REQUESTS_PER_SECOND instead of the unused LIGHTCAST_RATE_LIMIT setting. Settings now ship inside the installed package.
  • Unsupported experimental helpers are removed. Speculative salary, matrix, clustering, arbitrary pathway, and title hierarchy helpers used undocumented endpoints. The experimental unified_skills helper delegates to the supported workflow and retires its old source-selection and hardcoded-mapping arguments.
  • Tool validation is stricter. FastMCP 4 / MCP SDK 2 rejects coerced argument types, such as strings passed for integer limits. Python SDK consumers should use snake_case attributes.

Reliability and documentation

The server exposes 37 tools across eight API families. OAuth tokens and refresh locks are isolated by scope; requests share per-service rate limiting, bounded retries, and token refresh. Corrected API paths and filters preserve real upstream results and warnings instead of fabricating fallback data.

FastMCP 4.1.8 and MCP SDK 2.3.0 support both the 2026-07-28 protocol and legacy 2025-11-25 clients. Tools declare structured output schemas and read-only/idempotent annotations, return actionable errors, and use deterministic discovery. HTTP protects Host and Origin headers and defaults to localhost.

The new documentation site includes generated tool references, recipes, API compatibility notes, search, light/dark themes, and automatic GitHub Pages deployment. Docker and PyPI publishing now run directly from the version tag in one release workflow; the GitHub release is created only after both succeed.

Validation

  • 98 offline tests passed on both Python 3.14 and 3.15, with eight opt-in live tests skipped on each.
  • 32 existing live MCP tool checks and 18 Core LMI live checks passed using real Lightcast credentials during the API review. These establish the tested operations and account access, not every dataset or filter combination.
  • The installed Python 3.14 wheel passed stdio and streamable HTTP checks with both MCP protocol versions and all 37 tools.
  • Lint, formatting, type checks, distribution metadata, strict documentation builds, workflow checks, and production/development Docker builds passed.

Python 3.15 currently emits an upstream beartype / py-key-value-aio protocol-check deprecation warning; tests still pass. The API review records validation scope and known limitations. Automated release tests remain offline and need no Lightcast credentials.

Install

Run the pinned release with Python 3.14:

uvx --python 3.14 mcp-lightcast==0.3.0

Or use the published container with your local credentials file:

docker run --rm -i --env-file .env ghcr.io/lawwu/mcp-lightcast:0.3.0

Docker also publishes the moving 0.3 and latest tags. See configuration for credentials and MCP client setup.