feat(mcp): expose deferred pure-read REST operations as expanded tools

## Summary

The Tier-4 MCP/API parity test is green, but it documents a real product gap: 54 OpenAPI operations are intentionally excluded as `deferred-to-future-tool`, meaning they are pure/read-oriented REST operations with data that is not yet exposed through an MCP tool `_apiPaths` entry.

This issue tracks converting the high-value, safe subset of those deferred operations into MCP-accessible tools, mostly by expanding existing cache tools or adding a small number of domain tools with explicit `_apiPaths`, `_cacheKeys` / `_coverageKeys`, freshness metadata, and tests.

## Current evidence

As of 2026-06-30:

```bash
./node_modules/.bin/tsx --test tests/mcp-api-parity.test.mjs
```

Emits:

```text
[mcp-api-parity] 66 covered / 126 excluded (mutating:14 llm-passthrough:2 fetch-on-miss:29 admin:0 manual-mapping:27 deferred-to-future-tool:54) / 192 total ops
```

Source of truth:

- `tests/mcp-api-parity.test.mjs` — `EXCLUDED_FROM_MCP_PARITY`, especially the `deferred-to-future-tool` bucket.
- `api/mcp/registry/cache-tools.ts` and `api/mcp/registry/rpc-tools.ts` — `_apiPaths`, `_cacheKeys`, `_coverageKeys`, freshness metadata, public schemas.
- `docs/api/*.openapi.json` — public REST operation inventory.

## Deferred operations to expose or explicitly de-scope

### Disabled company-intel placeholders (2)

These should not be exposed until the underlying handlers become real data products:

- `GET /api/intelligence/v1/get-company-enrichment`
- `GET /api/intelligence/v1/list-company-signals`

Both are currently documented in parity as disabled/empty-envelope handlers pending a verified attribution model and source registry.

### Data gaps: good MCP candidates (52)

Aviation:

- `GET /api/aviation/v1/get-airport-ops-summary`

Consumer prices:

- `GET /api/consumer-prices/v1/get-consumer-price-basket-series`

Cyber:

- `GET /api/cyber/v1/list-cyber-threats`

Economic / energy / macro:

- `GET /api/economic/v1/get-bis-credit`
- `GET /api/economic/v1/get-bis-exchange-rates`
- `GET /api/economic/v1/get-bis-policy-rates`
- `GET /api/economic/v1/get-crude-inventories`
- `GET /api/economic/v1/get-economic-stress`
- `GET /api/economic/v1/get-energy-capacity`
- `GET /api/economic/v1/get-energy-prices`
- `GET /api/economic/v1/get-eu-fsi`
- `GET /api/economic/v1/get-eu-gas-storage`
- `GET /api/economic/v1/get-eurostat-country-data`
- `GET /api/economic/v1/get-macro-signals`
- `GET /api/economic/v1/get-nat-gas-storage`
- `GET /api/economic/v1/get-oil-inventories`
- `GET /api/economic/v1/get-oil-stocks-analysis`
- `GET /api/economic/v1/list-grocery-basket-prices`

Forecast:

- `GET /api/forecast/v1/get-simulation-outcome`
- `GET /api/forecast/v1/get-simulation-package`

Infrastructure:

- `GET /api/infrastructure/v1/list-internet-ddos-attacks`
- `GET /api/infrastructure/v1/list-internet-traffic-anomalies`

Intelligence:

- `GET /api/intelligence/v1/get-country-energy-profile`
- `GET /api/intelligence/v1/get-gdelt-topic-timeline`
- `GET /api/intelligence/v1/get-pizzint-status`
- `GET /api/intelligence/v1/list-gps-interference`
- `GET /api/intelligence/v1/list-oref-alerts`
- `GET /api/intelligence/v1/list-satellites`
- `GET /api/intelligence/v1/list-security-advisories`

Market:

- `GET /api/market/v1/get-gold-intelligence`
- `GET /api/market/v1/get-hyperliquid-flow`
- `GET /api/market/v1/get-market-breadth-history`
- `GET /api/market/v1/list-ai-tokens`
- `GET /api/market/v1/list-crypto-sectors`
- `GET /api/market/v1/list-defi-tokens`
- `GET /api/market/v1/list-other-tokens`
- `GET /api/market/v1/list-stablecoin-markets`

Military:

- `GET /api/military/v1/get-usni-fleet-report`
- `GET /api/military/v1/list-defense-patents`

Resilience:

- `GET /api/resilience/v1/get-runtime-manifest`

Scenario:

- `GET /api/scenario/v1/get-scenario-status`

Supply chain / energy infrastructure:

- `GET /api/supply-chain/v1/get-bypass-options`
- `GET /api/supply-chain/v1/get-chokepoint-history`
- `GET /api/supply-chain/v1/get-pipeline-detail`
- `GET /api/supply-chain/v1/get-shipping-rates`
- `GET /api/supply-chain/v1/get-storage-facility-detail`
- `GET /api/supply-chain/v1/list-pipelines`
- `GET /api/supply-chain/v1/list-storage-facilities`

Thermal:

- `GET /api/thermal/v1/list-thermal-escalations`

Trade:

- `GET /api/trade/v1/get-trade-barriers`
- `GET /api/trade/v1/get-trade-restrictions`

Shipping v2:

- `GET /api/v2/shipping/route-intelligence`

## Proposed work breakdown

1. Prioritize low-risk existing-domain expansions first:
- economic/energy macro data into `get_economic_data` or a new `get_energy_economic_data` tool;
- market token/flow data into `get_market_data` or a new expanded market tool;
- supply-chain pipeline/storage/shipping/chokepoint reads into `get_supply_chain_data` or sibling tools;
- intelligence/security feeds into an expanded intelligence tool.
2. For each operation selected for exposure:
- add `_apiPaths` coverage in the owning MCP tool;
- add any required `_cacheKeys` / `_coverageKeys` and freshness metadata;
- expose parameters in the public input schema only when the operation shape is stable and bounded;
- keep `summary` and `jmespath` behavior working for cache tools;
- remove the operation from `EXCLUDED_FROM_MCP_PARITY` once covered.
3. For composite operations like `get-gold-intelligence`, decide whether the existing tool should expand or whether a dedicated tool is cleaner.
4. Leave disabled company-intel handlers excluded until the underlying data model is real.

## Documentation work required

- Update `docs/mcp-tools-reference.mdx` with new tools/parameters and freshness notes.
- Update `docs/mcp-quickstart.mdx` with examples for the highest-value new domains.
- Update `docs/api-platform.mdx` or `docs/adding-endpoints.mdx` with the rule: every new OpenAPI operation must either be covered by `_apiPaths` or categorized in parity with a documented reason.
- If a new domain tool is added, update the MCP server card / registry-facing docs if tool names or descriptions materially change.

## Acceptance criteria

- [ ] A prioritized first batch of deferred operations is exposed through MCP tools with `_apiPaths` entries.
- [ ] Covered operations are removed from `EXCLUDED_FROM_MCP_PARITY`; no double-coverage remains.
- [ ] `./node_modules/.bin/tsx --test tests/mcp-api-parity.test.mjs` stays green.
- [ ] Relevant MCP tool schema/output tests cover the new or expanded tools.
- [ ] Documentation describes the newly exposed domains, parameters, freshness, examples, and known exclusions.
- [ ] Any remaining deferred operations have a concrete follow-up reason: disabled handler, awaiting product decision, or deliberately out of scope.

## Related

- Historical cache-key coverage tracker: #3029
- MCP free-tier/listing work: #4277
- Simulation trigger MCP policy note: #3798

Start with tests/mcp-api-parity.test.mjs, then read api/mcp/registry/cache-tools.ts, api/mcp/registry/rpc-tools.ts, and the relevant docs/api/*.openapi.json entries. Identify a narrowly prioritized operation batch and its owning tools before checking existing schema, cache, freshness, and coverage patterns. Done means the selected operations are covered without double-coverage, parity remains green, relevant tests pass, and the MCP documentation is updated.

Written by the indexing model from the issue text.