faostat mcp server changelog

env_vars

FAOSTAT_DOMAINS, FAOSTAT_MIRROR_PATH, FAOSTAT_BULK_BASE_URL, CANVAS_PROVIDER_TYPE, FAOSTAT_DATAFRAME_DROP_ENABLED, MCP_LOG_LEVEL → FAOSTAT_DOMAINS, FAOSTAT_MIRROR_PATH, FAOSTAT_BULK_BASE_URL, CANVAS_PROVIDER_TYPE, FAOSTAT_DATAFRAME_DROP_ENABLED, FAOSTAT_CLAMP_LIMITS, MCP_LOG_LEVEL

version

0.6.0 → 0.7.0

https://raw.githubusercontent.com/cyanheads/faostat-mcp-server/HEAD/AGENTS.md

− **Version:** 0.5.0− - **Aggregate exclusion is the safe default.** `faostat_query_observations` excludes area codes ≥ 5000 (World/continents/groupings) unless `include_aggregates: true`, so a naive `SUM` doesn't double-count. Preserve this.−   description: 'Resolve human terms to the opaque integer codes a query needs …',−       when: 'The dimension tables are not yet populated (mirror cold).', retryable: true,−       recovery: 'Run the mirror init script or wait for the initial sync, then retry.' },− `schema` is required: pass `OBSERVATION_TABLE_SCHEMA` (the ten `streamObservations` columns) or `PROFILE_TABLE_SCHEMA` (those plus `domain`). The staged types are declared, never inferred from the preview rows — inference types `value` from whatever the preview window holds, and a whole-number window truncates every later fractional value.− | `bun run mirror:verify` | Report per-domain sync status, local row counts, and sample reads against the mirror. |− - [ ] `faostat_query_observations` keeps aggregate exclusion as the default (codes ≥ 5000 excluded unless `include_aggregates: true`)+ **Version:** 0.6.0+ - **Area aggregate exclusion is the default.** `faostat_query_observations` excludes area codes ≥ 5000 and curated rollups unless `include_aggregates: true` or explicit `area_codes` are supplied. This prevents area overlap; item groups, units, periods, and source estimates still require separate analytical choices.+   description: 'Resolve human terms to the opaque codes a query needs …',+       when: 'Shared dimensions are empty or the selected item/element domain needs a sync.', retryable: true,+       recovery: 'Run mirror:init or mirror:refresh, or wait for sync, then retry.' },+     if ((input.dimension !== 'area' && !(await mirror.ready(input.domain))) || !(await mirror.dimensions.isPopulated())) {+       throw ctx.fail('index_not_ready', 'The selected vocabulary requires a completed sync.');+     }+ `schema` is required: pass `OBSERVATION_TABLE_SCHEMA` (the `streamObservations` columns, including item text codes, periods, value qualifiers, and sources) or `PROFILE_TABLE_SCHEMA` (those plus `domain`). The staged types are declared, never inferred from the preview rows — inference types `value` from whatever the preview window holds, and a whole-number window truncates every later fractional value.+ | `bun run mirror:verify` | Report per-domain sync status, local row counts, checkpoints, and shared dimension population. |+ - [ ] `faostat_query_observations` keeps area aggregate exclusion as the default (threshold plus curated rollups; explicit area selections bypass it); item-group classification does not change query inclusion

• + faostat-guide

version

0.5.0 → 0.6.0

https://raw.githubusercontent.com/cyanheads/faostat-mcp-server/HEAD/AGENTS.md

− **Version:** 0.4.0− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`− **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1 (via the framework)− This server is **tools-only** — seven tools (`faostat_dataframe_drop` opt-in via `FAOSTAT_DATAFRAME_DROP_ENABLED`), no resources, no prompts (the data behind every resource candidate is already reachable through the tools, and the one workflow worth structuring ships as `faostat_commodity_profile`). All definitions live in `src/mcp-server/tools/definitions/`.− `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`FAOSTAT_DOMAINS`) not the path (`domains`). Throws `ConfigurationError`, which the framework prints as a clean startup banner. `CANVAS_PROVIDER_TYPE` is a core var (already in `AppConfig`), not part of this schema; `src/index.ts` defaults it to `duckdb`.− No `resources/` or `prompts/` definitions — this server is tools-only.− Skills are modular instructions in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. The directory is deliberately not `skills/`: Claude Code and Codex auto-load a plugin's root `skills/`, so a server that ships `.claude-plugin/` or `.codex-plugin/` would hand these development skills to every agent that installs it. Keep `skills/` free for skills meant f− | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity and the `server.json` npm entries' shape (run by devcheck). |− `bun run bundle` produces a `.mcpb` extension bundle for one-click install in Claude Desktop. The pack step is followed by `scripts/clean-mcpb.ts`, which prunes dev dependencies (`mcpb clean`) and strips two classes of `node_modules/**` content that root-anchored `.mcpbignore` patterns cannot reach: dependency-shipped agent docs (`framework-skills/`, `skills/`, `.claude/`, `.agents/`, `SKILL.md`) and platform-specific native bindings, which would otherwise lock the bundle to the platform it was + **Version:** 0.5.0+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.18`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.4.0 (via the framework)+ This server exposes seven tools (`faostat_dataframe_drop` opt-in via `FAOSTAT_DATAFRAME_DROP_ENABLED`), one skill resource through the MCP Skills extension, and no prompts. Statistical data is reached through the tools; `skills/faostat-guide/SKILL.md` guides comparisons and staged SQL analysis. All tool definitions live in `src/mcp-server/tools/definitions/`.+ `parseEnvConfig` maps Zod schema paths → env var names so errors name the variable (`FAOSTAT_DOMAINS`) not the path (`domains`). Throws `ConfigurationError`, which the framework prints as a clean startup banner. `CANVAS_PROVIDER_TYPE` is a core var (already in `AppConfig`), not part of this schema; `src/index.ts` uses the framework's `normalizeEnv` to treat blank, whitespace-only, and unsubstituted placeholder values as unset before defaulting to `duckdb`.+ No hand-authored `resources/` or `prompts/` definitions. `createApp({ skills: 'skills' })` serves the root `skills/faostat-guide/SKILL.md` through the MCP Skills extension.+ Development skills live in `framework-skills/` at the project root. Read them directly when a task matches — e.g., `framework-skills/add-tool/SKILL.md` when adding a tool. `bun run list-skills` prints the full registry. Root `skills/` is separate: it holds author-managed skills for agents installing this server, ships in npm, Docker and MCPB, and reaches MCP clients through `createApp({ skills: 'skills' })`. The maintenance sync never authors that tree; use `add-skill` deliberately.+ | `add-skill` | Author a skill the server publishes in root `skills/` for the agents that use it — structure, validation, delivery |+ | `bun run lint:packaging` | Packaging surface checks — registry/bundle env parity, npm launch shape, bundle exclusions, plugin manifests, and published `skills/` (run by devcheck). |+ `bun run bundle` produces a `.mcpb` extension bundle for Claude Desktop. Root development paths need root-anchored `.mcpbignore` lines; root `skills/` ships. The cleaner prunes dev dependencies and strips dependency-root agent docs, platform-specific DuckDB bindings, node-gyp generator/intermediate files, and build-only framework/SQLite package files. Nested SDK runtime `dist/ext/skills/` modules and compiled `*.node` addons stay. `manifest.json` disables canvas in the portable bundle; npm and D+ - [ ] Root `plugin.json` and `mcp.json` follow Agent Plugins 1.0.0; unscoped display name, full npm install name, fixed env matching `.codex-plugin/mcp.json`; keep the Codex overlay's `mcpServers` pointer

version

0.4.1 → 0.5.0

version

0.4.0 → 0.4.1

https://raw.githubusercontent.com/cyanheads/faostat-mcp-server/HEAD/AGENTS.md

− **Version:** 0.3.0− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.11`− **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0 (via the framework)− **Zod:** ^4.6.5− throw new McpError(JsonRpcErrorCode.DatabaseError, 'Connection failed', { pool: 'primary' });− **Every release goes through a release PR, straight-through** — `git-wrapup`'s "Release PR mode", mode `straight-through`. One run: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-and-publish` then fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. A caller's bri+ **Version:** 0.4.0+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.15`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.3.1 (via the framework)+ **Zod:** ^4.6.7+ throw new McpError(JsonRpcErrorCode.InitializationFailed, 'Connection failed', { pool: 'primary' });+ **Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the release digest: theme line, `## Changes`, `## Gates`, changelog link last); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewri

version

0.3.0 → 0.4.0

https://raw.githubusercontent.com/cyanheads/faostat-mcp-server/HEAD/AGENTS.md

− **Version:** 0.2.5− **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.10`− **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0 (via the framework)− This server is **tools-only** — six tools, no resources, no prompts (the data behind every resource candidate is already reachable through the tools, and the one workflow worth structuring ships as `faostat_commodity_profile`). All definitions live in `src/mcp-server/tools/definitions/`.− Real definitions: `list-domains`, `resolve-codes`, `query-observations`, `commodity-profile`, `dataframe-query`, `dataframe-describe`. The shape below — typed `errors[]` contract, `ctx.fail()`, `ctx.enrich`, and a `format()` that renders every field — is shared across them.− `faostat_query_observations` and `faostat_commodity_profile` inline a small preview and **spill** large result sets to a DuckDB-backed canvas table via the staging helpers in `src/services/canvas-staging.ts`. The returned `canvas_id` + `table_name` are then read through the mandatory `faostat_dataframe_describe` / `faostat_dataframe_query` pair — without that pair the spilled token is dead output. Guard with `canvasEnabled()` and surface `canvas_disabled` when staging is off.−           commodityProfileTool, dataframeQueryTool, dataframeDescribeTool],−     canvas-staging.ts                   # spill / query / describe staging over the DataCanvas− | `bun run lint:packaging` | Validate `manifest.json` ↔ `server.json` env-var consistency (run by devcheck). |+ **Version:** 0.3.0+ **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.11`+ **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0 (via the framework)+ This server is **tools-only** — seven tools (`faostat_dataframe_drop` opt-in via `FAOSTAT_DATAFRAME_DROP_ENABLED`), no resources, no prompts (the data behind every resource candidate is already reachable through the tools, and the one workflow worth structuring ships as `faostat_commodity_profile`). All definitions live in `src/mcp-server/tools/definitions/`.+ Real definitions: `list-domains`, `resolve-codes`, `query-observations`, `commodity-profile`, `dataframe-query`, `dataframe-describe`, `dataframe-drop`. The shape below — typed `errors[]` contract, `ctx.fail()`, `ctx.enrich`, and a `format()` that renders every field — is shared across them.+ `faostat_query_observations` and `faostat_commodity_profile` inline a small preview and **spill** large result sets to a DuckDB-backed canvas table via the staging helpers in `src/services/canvas-staging.ts`. The returned `canvas_id` + `table_name` are then read through the mandatory `faostat_dataframe_describe` / `faostat_dataframe_query` pair — without that pair the spilled token is dead output. `faostat_dataframe_drop` removes one staged table ahead of its TTL; it is opt-in, so `src/index.ts`+   dataframeDropEnabled: z.stringbool().default(false)+     .describe('Register faostat_dataframe_drop live; otherwise it is registered disabled.'),+     dataframeDropEnabled: 'FAOSTAT_DATAFRAME_DROP_ENABLED',+ `src/index.ts` loads `./.env` and reads the drop flag with `dataframeDropRequested()` before `createApp()`, since the flag decides how a tool registers. That read never throws; the full config is validated by `getServerConfig()` in `setup()`, so a bad value fails behind the framework's startup banner.+           commodityProfileTool, dataframeQueryTool, dataframeDescribeTool,+           dataframeDropRegistration(dataframeDropEnabled)],+     canvas-staging.ts                   # spill / query / describe / drop staging over the DataCanvas+         dataframe-drop.tool.ts+ | `bun run lint:packaging` | Packaging surface checks — `server.json`/`manifest.json` env-var parity and the `server.json` npm entries' shape (run by devcheck). |

env_vars

FAOSTAT_DOMAINS, FAOSTAT_MIRROR_PATH, FAOSTAT_BULK_BASE_URL, CANVAS_PROVIDER_TYPE, MCP_LOG_LEVEL → FAOSTAT_DOMAINS, FAOSTAT_MIRROR_PATH, FAOSTAT_BULK_BASE_URL, CANVAS_PROVIDER_TYPE, FAOSTAT_DATAFRAME_DROP_ENABLED, MCP_LOG_LEVEL

version

0.2.5 → 0.3.0