Standard: capability-surface tools + session/streaming transport contract

[mikemcdougall]

Extends the geospatial-mcp standard with the two surfaces the Honua MCP redesign needs: a client-agnostic capability surface (honua-io/honua-server#1949) and an authoritative session/streaming transport contract (honua-io/honua-server#1954). Part of the v1 epic honua-io/geospatial-mcp#1.

Capability surface + grounding-as-tools (#1949)

New Capability and grounding tool family, with input and output JSON Schemas (draft 2020-12; MCP 2025-06-18 outputSchema), conformance fixtures, and index.json entries:

• resolve_entity — natural-language/text → ranked, evidence-backed canonical entity references (dataset, layer, feature, service, style, theme, template, process), grounded over the CapabilityCatalog and the feature-catalog grounding resource honua://catalog/features; emits a clarification when text is too ambiguous to ground.
• list_capabilities — enumerates the composable tool/resource surface plus the grounding tools and grounding resources a cold client LLM can compose, with per-tool descriptions and safety annotations. Its output is an MCP-owned introspection projection (akin to the conformance manifest).
• Grounding-as-tools is now blessed explicitly in taxonomy.md: the read-only list_capabilities / resolve_entity / ground_candidates / clarify_intent / validate_plan set, with two invariants (evidence-backed grounding over honua://catalog/features; server-owned, not model-owned, correctness).
• Tool safety annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) are codified and recorded machine-readably in index.json for the new tools; surfaced at runtime via list_capabilities.
• Capability matrix, MCP-tools-to-workflow-family mapping, and the canonical concept model updated. Both tools are implementationStatus: known-gap (standard-defined; reference ships them via #1949), so the reference manifest stays FULL.

Sessions & streaming (#1954)

New normative doc spec/transport.md — the authoritative transport contract:

• Supported protocol revision 2025-06-18 (native elicitation, output schemas, annotations), with graceful fallback when an older revision (e.g. 2025-03-26) is negotiated.
• Mcp-Session-Id session model (assignment, echo, 400/404 semantics, DELETE, stateless operation).
• Streamable-HTTP/SSE and stdio transports with transport symmetry (one catalog over every transport).
• notifications/progress for long-running geoprocessing/publish jobs (advisory; does not redefine ExecutionJob/PipelineService ownership; polling remains a fallback), notifications/{tools,resources,prompts}/list_changed (no inert capability flags), and optional resource subscriptions.
• Native-elicitation mapping for the clarification envelope (ties to planning.md §2.6) and capability negotiation. Cross-referenced from taxonomy.md and planning.md.

Validation

All repo checks pass locally:

• conformance/fixtures/validate.py --strict — 27 fixtures, full jsonschema mode, OK
• conformance/check_manifest.py --strict — reference manifest FULL
• tools/check_links.py — 275 internal links/anchors resolve
• markdownlint-cli2 "**/*.md" — 0 errors

Open questions for the standard

• honua://catalog/features is referenced as a grounding resource but not yet given a full per-family inspection contract (consistent with the existing catalog-family deferral). Promoting it to a first-class resource family is a follow-up once upstream #1946 lands its shape.
• outputSchema is published only for the two MCP-owned introspection tools. Whether to backfill output schemas for the rest of the tool surface (vs. the current canonical-object expected-behavior shapes) is a deliberate open decision.
• The reference implementation (working in parallel) may vendor a slightly different shape; this PR defines the canonical standard and notes that divergence is tracked in the referenced tickets.

Related to honua-io/honua-server#1949 and honua-io/honua-server#1954 and #1.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.