chore(mcp): triage manual-mapping and cost-gated REST exclusions

## Summary

The MCP/API parity test intentionally excludes 126 public OpenAPI operations from MCP coverage. Some are straightforward non-goals (`mutating`, `llm-passthrough`), but two buckets need active product/engineering triage:

- `manual-mapping` (27): parameterized cache keys, inline Redis/Convex, or equivalent data available through sibling cache tools.
- `fetch-on-miss` (29): handlers that can trigger paid upstream calls, high-cardinality lookups, or external fetches on cache miss.

This issue tracks turning those buckets from a static exclusion list into explicit policy decisions: expose safely, document as intentionally REST-only, or create bounded MCP wrappers with quotas/tier gates.

## 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` — category definitions and `EXCLUDED_FROM_MCP_PARITY`.
- `api/mcp/registry/cache-tools.ts` and `api/mcp/registry/rpc-tools.ts` — actual MCP surface.
- `server/worldmonitor/**` — handler behavior for inline Redis, Convex, paid upstreams, and high-cardinality inputs.

## Manual-mapping inventory (27)

Inline Redis / Convex / manual triage required:

- `GET /api/aviation/v1/search-flight-prices`
- `GET /api/displacement/v1/get-population-exposure`
- `GET /api/infrastructure/v1/get-ip-geo`
- `GET /api/intelligence/v1/get-regime-history`
- `GET /api/intelligence/v1/list-telegram-feed`
- `GET /api/market/v1/get-stock-analysis-history`
- `GET /api/market/v1/list-stored-stock-backtests`
- `GET /api/military/v1/get-wingbits-status`
- `GET /api/resilience/v1/get-resilience-score`
- `GET /api/scenario/v1/list-scenario-templates`

Parameterized cache keys or prefix-level equivalent data already covered by sibling cache tools:

- `GET /api/economic/v1/get-bls-series`
- `GET /api/economic/v1/get-fred-series`
- `POST /api/economic/v1/get-fred-series-batch`
- `GET /api/infrastructure/v1/get-bootstrap-data`
- `GET /api/infrastructure/v1/get-temporal-baseline`
- `GET /api/intelligence/v1/get-regional-brief`
- `GET /api/intelligence/v1/get-regional-snapshot`
- `GET /api/intelligence/v1/list-market-implications`
- `GET /api/news/v1/summarize-article-cache`
- `GET /api/research/v1/list-arxiv-papers`
- `GET /api/research/v1/list-hackernews-items`
- `GET /api/research/v1/list-trending-repos`
- `GET /api/supply-chain/v1/get-country-products`
- `GET /api/supply-chain/v1/get-multi-sector-cost-shock`
- `GET /api/trade/v1/get-tariff-trends`
- `GET /api/trade/v1/get-trade-flows`
- `GET /api/trade/v1/list-comtrade-flows`

## Fetch-on-miss inventory (29)

Paid upstream / external fetch candidates:

- `GET /api/intelligence/v1/get-risk-scores`
- `GET /api/aviation/v1/get-carrier-ops`
- `GET /api/aviation/v1/get-youtube-live-stream-info`
- `GET /api/aviation/v1/list-airport-flights`
- `GET /api/aviation/v1/list-aviation-news`
- `GET /api/conflict/v1/get-humanitarian-summary`
- `GET /api/conflict/v1/list-acled-events`
- `POST /api/conflict/v1/get-humanitarian-summary-batch`
- `GET /api/economic/v1/list-world-bank-indicators`
- `GET /api/giving/v1/get-giving-summary`
- `GET /api/infrastructure/v1/get-cable-health`
- `GET /api/infrastructure/v1/list-service-statuses`
- `GET /api/intelligence/v1/get-country-facts`
- `GET /api/maritime/v1/list-navigational-warnings`
- `GET /api/market/v1/get-country-stock-index`
- `GET /api/market/v1/get-insider-transactions`
- `GET /api/military/v1/get-wingbits-live-flight`
- `GET /api/military/v1/list-military-bases`
- `GET /api/supply-chain/v1/get-country-cost-shock`
- `GET /api/supply-chain/v1/get-critical-minerals`
- `GET /api/supply-chain/v1/get-route-explorer-lane`
- `GET /api/supply-chain/v1/get-route-impact`
- `GET /api/supply-chain/v1/get-sector-dependency`
- `GET /api/webcam/v1/get-webcam-image`

High-cardinality input candidates:

- `GET /api/aviation/v1/get-flight-status`
- `GET /api/imagery/v1/search-imagery`
- `GET /api/market/v1/backtest-stock`
- `GET /api/military/v1/get-aircraft-details`
- `POST /api/military/v1/get-aircraft-details-batch`

## Non-goals unless a separate threat/cost model is approved

Keep these excluded by default:

- `mutating` operations (14): state writes, queues, lead/contact writes, webhook registration, derived cache writes.
- `llm-passthrough` operations (2): `classify-event`, `analyze-stock`.

If any of those become MCP-accessible, they need a separate issue with auth, quota, abuse, cost, and audit-log requirements.

## Proposed work breakdown

1. For each `manual-mapping` operation, classify it as:
- already covered by an existing cache tool at useful granularity;
- worth adding as a bounded MCP parameter to an existing tool;
- worth a dedicated tool;
- intentionally REST-only.
2. For each `fetch-on-miss` operation, classify it as:
- safe only as cached snapshot data;
- safe as Pro-only on-demand tool with quotas/rate limits;
- too high-cardinality or too expensive for MCP;
- candidate for a new pre-seeded cache key instead of on-demand MCP access.
3. Replace vague parity reasons with stronger product policy where needed.
4. If a handler is exposed, move it from exclusion to `_apiPaths` and add tests.
5. If a handler stays excluded, document the user-facing reason in MCP docs, not only the test file.

## Documentation work required

- Add an MCP coverage/exclusion matrix covering `covered`, `deferred`, `manual-mapping`, `fetch-on-miss`, `mutating`, and `llm-passthrough`.
- Document the policy for paid upstream and high-cardinality tools: when they can be MCP tools, when they must be REST-only, and when they should become seeded cache data first.
- Update `docs/adding-endpoints.mdx` so new REST operations include an MCP exposure decision as part of endpoint review.
- Update `docs/mcp-tools-reference.mdx` with any newly exposed manual/fetch-on-miss wrappers and tier/usage notes.

## Acceptance criteria

- [ ] Every `manual-mapping` entry has a reviewed owner decision and a concrete outcome.
- [ ] Every `fetch-on-miss` entry has a reviewed cost/cardinality/tier decision.
- [ ] Any newly exposed operation is moved to `_apiPaths`, removed from `EXCLUDED_FROM_MCP_PARITY`, and covered by focused tests.
- [ ] Any operation that remains excluded has a docs-visible reason, not only a test comment.
- [ ] `./node_modules/.bin/tsx --test tests/mcp-api-parity.test.mjs` remains green.

## Related

- Pure-read deferred implementation tracker: #4525
- Historical seeded-cache coverage tracker: #3029
- MCP free-tier/listing work: #4277
- Simulation trigger MCP policy note: #3798

Start by running ./node_modules/.bin/tsx --test tests/mcp-api-parity.test.mjs and reading its category definitions and EXCLUDED_FROM_MCP_PARITY. Then inspect api/mcp/registry/cache-tools.ts, api/mcp/registry/rpc-tools.ts, and the relevant server/worldmonitor handlers. Done means every listed operation has a reviewed outcome, exposed operations have focused tests, excluded operations have user-facing documentation, and the parity test remains green.

Written by the indexing model from the issue text.