feat(mcp): stage 3 context and bounded selector candidates

[hmishra2250]

Scope

One ordered Stage-3 candidate train on top of c524c5a:

1. A — context copy (8dd2ec0): audited copy-only reductions from Enhance tool descriptions and validations #330 plus the Stage-1 keyless Search/Scrape/Parse wording correction. No schemas, validation, routing, or tool registration changed. Its initialize text is selector-safe: it never names a tool outside @core-v1.
2. B — Claude context hint (bef51ef): adds the inert-for-other-clients anthropic/alwaysLoad metadata only to Search/Scrape/Parse on the hosted primary full profile. Account, search (including the in-process companion), and stdio profiles remain unchanged; B is independently merge-safe.
3. C — bounded selectors (bc9becf): enables ?tools= only for hosted /v2/mcp; validates single, bounded selectors; supports immutable @core-v1/@full-v1; intersects with actual registrations; prevents keyless escalation; and rejects direct calls to omitted tools.

Selectors are deliberately request-scoped because the current hosted FastMCP transport is stateless. A request without ?tools= is an ordinary default session; clients that select must retain the configured URL on each request.

/v2/mcp-oauth and /v2/mcp-search now reject any selector explicitly with HTTP 400 / TOOL_SELECTOR_UNSUPPORTED; they never silently ignore it. Search remains six-tool frozen without a selector.

Corrections folded before review

• @core-v1 initialize instructions no longer name tools it omits.
• Credential recovery (CREDENTIAL_INVALID) takes precedence over selector rejection.
• Selector telemetry is sanitized and low-cardinality ([MCP_SELECTOR]): outcome, reason, auth mode, selected-tool count, and fixed resource only — never selector text, URLs, credentials, IPs, or identifiers.
• The selector count boundary is tested with 64/65 short @core-v1 values below the independent 1024-byte cap.
• Removed no-op alwaysLoad wrappers from search registration paths.

Contract coverage

• @core-v1 is exactly Search/Scrape/Parse; @full-v1 equals the full default tool definitions.
• Initialize under @core-v1 contains no unavailable feedback/crawl/extract tool names.
• Selector list narrowing and direct-call rejection (TOOL_NOT_SELECTED) cause no backend scrape, upload, or parse call.
• Invalid/revoked credentials receive CREDENTIAL_INVALID even when a selector would omit the requested tool.
• blank, malformed, repeated, unknown, >64-entry, and >1024-UTF-8-byte selectors -> 400.
• keyless @full-v1 escalation -> 403.
• account/search selector usage -> explicit 400 TOOL_SELECTOR_UNSUPPORTED.
• existing keyless identity, Parse ZDR, API-key, OAuth, audience, recovery, search profile, nginx, and package smoke suites remain green.

Validation

• pnpm install --frozen-lockfile
• pnpm lint
• pnpm test — 49/49 passed
• pnpm pack --pack-destination /tmp/mcp337-pack-rebased
• docker build -f Dockerfile.service -t firecrawl-mcp-server:stage3-selector-review-83cd47b .

Package-manager note

Use pnpm for local validation. patches/fastmcp@4.3.2.patch is referenced by pnpm-lock.yaml; an npm install does not apply it and produces false tool-list failures. The production service Dockerfile and the validation above use pnpm.

AX gate — not run

No paid AX traces were run. A durable local A+C candidate exists for the factorial:

• A: 8dd2ec0
• A+B: bef51ef
• A+B+C: bc9becf
• A+C: local branch experiment/stage3-context-selectors-a-c, commit 97dc37f, tag ax-candidate-a-c-20260727, local image firecrawl-mcp-server:ax-a-c-97dc37f (sha256:b10eb456cd34dbe35180909bcca6b04be74d7679916e1a44e707d977f54b760c)

AX remains blocked until those exact immutable candidates are reachable from the approved E2B sandbox. Do not treat production-baseline traces as candidate results. The protocol must use a scorer-emitted metric verified on current AX main, a powered no-drop decision rule, and a positive control before B/C merge eligibility.

Required gates before merge

• A: AX no-drop experiment on the exact A candidate.
• B/C: factorial AX matrix on the exact A, A+B, A+C, and A+B+C candidates, including the selector-aware @core-v1 instructions arm.
• No deployment, merge, production configuration, or production telemetry write is included in this draft.