Tools

Four BLS data tools are always available. Setting CANVAS_PROVIDER_TYPE=duckdb adds two DataCanvas SQL tools; setting BLS_DATAFRAME_DROP_ENABLED=true as well adds the seventh, destructive cleanup tool.

bls_list_surveys

List available BLS survey programs and their metadata.

• Covers all major BLS programs: CPS, CES, CPI, PPI, JOLTS, LAUS, OEWS, ECEC, and others
• Optional category filter (prices, employment, wages, productivity, injuries, time_use)
• Returns survey codes, descriptions, and calculation-support flags (allowsNetChange, allowsPercentChange, hasAnnualAverages)
• Backed by the live BLS surveys API with monthly caching; does not consume daily API quota

bls_search_series

The entry point for most BLS workflows. Resolves human concepts to BLS SeriesIDs.

• BLS identifiers like LNS14000000 and CES0000000001 encode survey + area + item + seasonal flag in opaque positional codes — this tool decodes them
• Free-text and keyword search against the full BLS series catalog
• Filter by survey code, geographic area (state name, MSA, or FIPS), and seasonal adjustment flag
• Returns decoded series components (survey, area, item, seasonal flag) alongside the plain-language name
• Operates entirely offline against LABSTAT flat files bundled at startup — no API quota consumed
• Use before bls_get_series or bls_get_latest when you have a concept but not a SeriesID

bls_get_series

Fetch historical time-series data for one or more BLS series.

• Batch fetch up to 50 series per request (counts as one of the 500 daily API queries)
• Optional start_year / end_year window (BLS caps history at 20 years per request)
• Optional calculations: true for BLS-server-side net change and percent change — a survey returns whichever it supports (CPI/PPI return percent change only); check bls_list_surveys for per-survey support
• Optional annual_average: true adds each year's annual-average row (period M13, Q05 or S03) — the mean of that year's real periods, not an additional one. enrichment.annualAverageRows reports how many were added
• Returns observations with series metadata plus available; BLS's raw - missing-value sentinel is preserved but excluded from availableObservationCount and called out in the notice
• Mixed batches preserve valid series when another SeriesID is invalid or has no data; the unresolved ID remains visible with zero observations and reason-specific guidance
• With CANVAS_PROVIDER_TYPE=duckdb, spills to a DataCanvas dataframe when the observation count exceeds the inline context budget. Rows preserve raw value and add available plus nullable numeric value_numeric for safe SQL arithmetic. Call bls_dataframe_describe with the returned dataset.name to inspect column_schema, then use that table name in bls_dataframe_query SQL. Without DataCanvas, narrow oversized requests with start_year / end_year.

bls_get_latest

Get the current value for one or more BLS series.

• Issues one GET per SeriesID (no batch-latest endpoint exists in BLS v2) — each counts as one of the 500 daily API queries
• Recommended limit: ≤10 series per call; accepts up to 50
• For "current value" across many series, bls_get_series with a narrow year window is more quota-efficient (one API query regardless of series count)
• Partial success reporting — failed series are returned in a separate failed[] array alongside successful results
• Latest observations expose available; a BLS - value renders explicitly as unavailable with its footnote reason

bls_dataframe_describe

Inspect canvas dataframes registered by bls_get_series.

Available only when CANVAS_PROVIDER_TYPE=duckdb.

• Lists all active dataframes for the current tenant: table name, source tool, query params, row count, column schema, TTL
• Optionally describe a single dataframe by name
• Lazy-sweeps expired entries before responding
• Use before writing SQL to confirm column names

bls_dataframe_query

Run SQL against canvas dataframes registered by bls_get_series.

Available only when CANVAS_PROVIDER_TYPE=duckdb.

• Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected
• Supports JOINs, aggregates, window functions, and CTEs
• Optional register_as persists the query result as a new named dataframe with a fresh TTL — useful for chaining analyses without re-consuming BLS API quota
• Inline row cap: 1,000 rows by default (max 10,000); full results live on-canvas when register_as is set
• Zero BLS API quota consumed

bls_dataframe_drop

Drop a canvas dataframe by name. Idempotent — returns dropped: false when nothing matched.

• Use to free canvas resources ahead of the per-table TTL when an analysis is complete
• Requires CANVAS_PROVIDER_TYPE=duckdb and must be explicitly enabled via BLS_DATAFRAME_DROP_ENABLED=true (TTL handles cleanup by default)

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

BLS-specific: