@honua/mcp-server 0.1.2-beta.0 → 0.1.8-beta.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Honua
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -9,6 +9,11 @@ bound to their own platform; this one is bound to none.
 **Release status: beta.** Tool contracts are certified against live and fixture
 targets on every release; remaining pre-1.0 work is hardening, not surface change.
 
+**Scores are published, not claimed.** How well different client models actually
+drive this surface — and where they fail — is in the
+[cross-model MCP eval scorecard](../docs/generated/mcp-eval-scorecard.md),
+generated from the dated run artifacts committed under [`evals/`](evals/README.md).
+
 Two modes:
 
 - **Standalone (platform-free) — the front door.** The `honua-mcp` bin runs the
@@ -21,9 +26,48 @@ Two modes:
 
 ## Requirements
 
-- Node.js `>=20`
+- Node.js `>=20.19`
 - Any reachable FeatureServer/OGC endpoint (public or Honua)
 
+## Install
+
+The server is published as
+[`@honua/mcp-server`](https://www.npmjs.com/package/@honua/mcp-server) with two
+bins: `honua-mcp` (the platform-free stdio server) and `honua-mcp-proxy` (the
+bridge to a Honua deployment's hosted `/mcp` catalog). No checkout, no build:
+
+```bash
+# one-off
+npx -y -p @honua/mcp-server honua-mcp   # reads HONUA_BASE_URL from the environment
+
+# or keep it installed
+npm install -g @honua/mcp-server
+```
+
+Claude Desktop, Claude Code, Cursor, and other MCP clients launch it as a stdio
+server. Copy-paste client config (`.mcp.json` / `mcp.json` / Claude Desktop's
+`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "honua": {
+      "command": "npx",
+      "args": ["-y", "-p", "@honua/mcp-server", "honua-mcp"],
+      "env": {
+        "HONUA_BASE_URL": "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis",
+        "HONUA_TRANSPORT": "rest"
+      }
+    }
+  }
+}
+```
+
+That example points at a public ArcGIS endpoint — swap `HONUA_BASE_URL` for
+your own FeatureServer folder, OGC API root, or Honua deployment. Contributors
+running from a checkout: `npm install && npm run build`, then
+`node dist/src/index.js` with the same environment.
+
 ## Platform-free mode (any ArcGIS / OGC endpoint)
 
 Point `HONUA_BASE_URL` at any origin/folder that serves the standard GeoServices
@@ -31,12 +75,16 @@ REST paths (`/rest/services`, `/FeatureServer/{id}/query`). Example — the publ
 US Census 2020 apportionment FeatureServer on `services.arcgis.com`:
 
 ```bash
-npm install
-npm run build
 HONUA_BASE_URL="https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis" \
-  HONUA_TRANSPORT="rest" node dist/src/index.js
+  HONUA_TRANSPORT="rest" npx -y -p @honua/mcp-server honua-mcp
 ```
 
+The same applies to a bare **OGC API** service root: point `HONUA_BASE_URL` at
+the root, address sources with the neutral `<protocol>:<address>` form
+(`ogc-features:<collectionId>`), and pass `layout: "ogc-api"` on calls against
+a third-party root (see the addressing table below). STAC works the same way
+with `layout: "stac-api"` or `"stac-static"`.
+
 Tools that require a Honua-only surface (server-side styling via OGC API – Styles,
 a `/rest/services` catalog) **degrade gracefully** on a plain endpoint: they
 return a structured result
@@ -48,11 +96,27 @@ return a structured result
 instead of crashing, hanging, or returning misleading empty data. This is the
 same skip-with-reason honesty the certification suite uses.
 
+### Bootstrap-only local installation
+
+Local installation is deliberately absent from the ordinary `honua-mcp`
+catalog. During an explicitly approved laptop bootstrap, start a separate,
+single-purpose process that exposes only `honua_admin_install_local`:
+
+```bash
+HONUA_MCP_BOOTSTRAP=1 npx -y -p @honua/mcp-server honua-mcp
+```
+
+The tool requires `confirm: true`. Stop and remove this bootstrap server from
+the MCP client configuration after installation; the normal platform-free
+server remains read-only and cannot invoke the installer.
+
 ## Environment Variables
 
-- `HONUA_BASE_URL` (required): absolute base URL — a public ArcGIS folder
+- `HONUA_BASE_URL` (required in normal mode): absolute base URL — a public ArcGIS folder
   (`https://services.arcgis.com/<org>/arcgis`) or a Honua deployment
   (`https://honua.example.com`).
+- `HONUA_MCP_BOOTSTRAP` (bootstrap only): set to `1` or `true` to start the
+  isolated local-install catalog instead of the ordinary read-only server.
 - `HONUA_TRANSPORT` (optional): `grpc-web` (default, Honua deployments) or `rest`.
   Use `rest` for plain public ArcGIS/OGC endpoints.
 - `HONUA_API_KEY` (optional): API key when your deployment requires it. Public
@@ -66,14 +130,110 @@ When `HONUA_API_KEY` is configured, use `https://` for non-localhost servers.
 
 All read-only:
 
-- `honua_list_services` — discover services (degrades if the target has no catalog)
-- `honua_describe_layer`
+- `honua_list_sources` — **protocol-neutral discovery.** Returns `<protocol>:<address>` source references plus each source's real capabilities. Every protocol family degrades independently with a reason.
+- `honua_list_services` — GeoServices-specific service catalog (prefer `honua_list_sources`)
+- `honua_describe_layer` — source schema, protocol, and advertised capabilities
 - `honua_query_features`
 - `honua_count_features`
 - `honua_get_extent`
 - `honua_statistics`
 - `honua_explain_capability_gap`
 - `honua_get_style`, `honua_apply_style_preset` — structured-unavailable on a plain FeatureServer
+- `honua_docs_search` — answer a Honua documentation question from the local versioned docs corpus (`llms-full.txt`), with a source-file and release-version citation per hit. Each citation is pinned to the exact commit the corpus bytes come from, so it keeps naming the text that was searched after `trunk` moves; when that commit cannot be established (an installed package with no checkout, or a locally regenerated corpus) the citation reports `sourceRevision: null` and links to `trunk` rather than claiming a pin it cannot back. Offline: reads committed files, never the network, and reports structured-unavailable when the corpus is not present in the installation. Point `HONUA_DOCS_CORPUS_PATH` at a corpus file (any name) or at a directory holding `llms-full.txt` to supply the corpus explicitly; `HONUA_SOURCE_REVISION` declares the commit when git is unavailable.
+
+### Protocol-neutral tool contract
+
+The tool vocabulary is the SDK's `Dataset` → `Source` → `Query` → `Result` contract,
+not GeoServices with extra fields. **No tool schema requires an Esri-only field.**
+
+**Addressing.** A source is one string, `<protocol>:<address>`, exactly as
+`honua_list_sources` emits it:
+
+| protocol | address | example |
+| --- | --- | --- |
+| `geoservices-feature-service` (alias `geoservices`) | `<serviceId>/<layerId>` | `geoservices-feature-service:Parks/0` |
+| `geoservices-map-service` | `<serviceId>/<layerId>` | `geoservices-map-service:Basemap/2` |
+| `ogc-features` (alias `ogc`) | `<collectionId>` | `ogc-features:hotels` |
+| `ogc-records` | `<collectionId>` | `ogc-records:catalog` |
+| `stac` | `<collectionId>` | `stac:sentinel-2-l2a` |
+| `wfs` | `<typeName>` | `wfs:topp:states` |
+| `odata` | `<entitySet>` | `odata:People` |
+
+An unrecognized protocol token is **refused with the accepted forms** rather than
+guessed at. Pass `layout` (`ogc-api` / `auto` / `stac-api` / `stac-static`) when the
+OGC/STAC source lives at a third-party service root rather than the Honua facade.
+
+**Filtering.** `filter` is the SDK's typed semantic filter, which compiles to
+GeoServices SQL-92, CQL2, FES 2.0, or OData `$filter` depending on the backend —
+one filter, same meaning everywhere:
+
+```jsonc
+{
+  "source": "ogc-features:obs",
+  "filter": {
+    "op": "and",
+    "args": [
+      { "op": "eq", "field": "stn_id", "value": 2147 },
+      { "op": "gt", "field": "value", "value": 95 }
+    ]
+  },
+  "orderBy": [{ "field": "value", "direction": "desc" }],
+  "limit": 10
+}
+```
+
+Nodes: `eq`/`ne`/`lt`/`lte`/`gt`/`gte` (`field`, `value`), `in` (`values`),
+`between` (`lower`, `upper`), `is-null`/`is-not-null`, `like` (`pattern`,
+`caseSensitive`), `and`/`or` (`args`), `not` (`arg`), the spatial predicates
+`intersects`/`contains`/`within`/`crosses`/`touches`/`overlaps`/`bbox-intersects`
+(`geometry` or `bbox`), and the temporal predicates
+`before`/`after`/`during`/`time-intersects` (`field`, `value`).
+
+**Geometry** is GeoJSON (RFC 7946), or a `bbox` as `[minX, minY, maxX, maxY]`.
+An envelope tested with `intersects` travels as the portable spatial constraint
+(the OGC `bbox` parameter / a GeoServices geometry parameter); a richer geometry
+or predicate becomes a typed spatial filter, which compiles where supported and
+fails closed where it is not. **Time** is `temporal` — `{ "instant": … }` or
+`{ "start": …, "end": … }`, with an optional `field`; without a field it targets
+the source's own time dimension (`time=` / `datetime=`).
+
+**Results** carry the neutral source identity, GeoJSON geometry, and — when the
+protocol served the request a weaker way — an explicit `degraded` array (e.g. OGC
+API Features has no server-side aggregation, so `honua_statistics` says it
+aggregated client-side rather than presenting the number as authoritative).
+
+**Capability honesty.** A request the backing protocol cannot express returns an
+`isError` result with a structured envelope, never a silently empty feature list:
+
+```json
+{
+  "code": "capability_not_supported",
+  "error": {
+    "kind": "ExecutionFailed",
+    "message": "Capability \"queryAggregate\" is not supported by protocol \"wmts\"",
+    "capability": "queryAggregate",
+    "protocol": "wmts",
+    "guidance": "…what to do instead…"
+  }
+}
+```
+
+### Deprecated inputs (still accepted)
+
+Nothing was removed. The following remain as **optional** compatibility inputs so
+existing MCP clients keep working, and are marked `[DEPRECATED]` in their schema
+descriptions:
+
+- `serviceId` + `layerId` — the GeoServices pair. Equivalent to
+  `source: "geoservices-feature-service:<serviceId>/<layerId>"`. Passing
+  `serviceId` without `layerId` is refused rather than defaulted to layer 0.
+- `where` — source-native filter text, whose language depends on the backend. Use
+  `filter` for a protocol-neutral one.
+- `geometry` as Esri-JSON, with `geometryType` — converted on the way in.
+
+One behavioural note: a source addressed the **deprecated** way keeps the legacy
+Esri-JSON geometry output; a source addressed with `source` gets GeoJSON. Set
+`geometryFormat` explicitly to override either default.
 
 Hosts that use signed safe-agent plans can import
 `@honua/mcp-server/agent-execution`. Its `createReadOnlyMcpAgentExecutor` binds
@@ -184,10 +344,37 @@ The fixture is recorded by `scripts/record-census-fixtures.mjs` into
 `src/certification/census-data.ts`; the evaluator that replays it is verified for
 parity against the live recordings in `test/certification/census-fixture-client.test.ts`.
 
+### Non-GeoServices certification lane
+
+A `standalone`-shaped lane can prove the surface works against Esri and still say
+nothing about vendor neutrality. So a second target — **`standalone-ogc`**
+(`HONUA_MCP_CERT_TARGET=standalone-ogc`, or `--target standalone-ogc`) — runs the
+**same tool catalog** against an in-process fixture of a plain **OGC API Features**
+endpoint, replaying collections recorded from the public
+[pygeoapi demo](https://demo.pygeoapi.io/master) (the pinned `ogc-features` target
+in `config/live-conformance-endpoints.v1.json`). Nothing Esri exists there: the
+GeoServices entry points all reject, so a tool that still secretly required
+`serviceId`/`layerId` fails loudly instead of passing by accident.
+
+```bash
+npm run certify:standalone-ogc            # non-GeoServices cert (OGC API Features fixture)
+npm run test:certification:standalone-ogc # CI gate variant
+```
+
+The fixture serves the OGC API Features Part 1 parameters (`limit`, `offset`,
+`bbox`, `datetime`, `properties`, `sortby`) plus the Part 3 `filter` +
+`filter-lang=cql2-text` the neutral contract compiles to — including a CQL2
+evaluator that **refuses** a construct it cannot evaluate exactly (`S_*` spatial
+predicates) rather than matching every row. Re-record with
+`node scripts/record-ogc-fixtures.mjs`.
+
 Artifacts are written to the package root as
 `mcp-certification-results.json` and `mcp-certification-results.md` (gitignored;
 uploaded by CI). To certify against a **live** honua-server, set `HONUA_BASE_URL`
-(and `HONUA_TRANSPORT`, `HONUA_MCP_SERVICE_ID`, `HONUA_MCP_LAYER_ID`); the
+(and `HONUA_TRANSPORT`, `HONUA_MCP_SERVICE_ID`, `HONUA_MCP_LAYER_ID`; optionally
+`HONUA_MCP_SOURCE` for a neutral `<protocol>:<address>` source ref,
+`HONUA_MCP_ADDRESS` for the geocoding scenario, `HONUA_MCP_STYLE_ID`, and
+`HONUA_MCP_STATISTIC_FIELD`); the
 harness then drives a real `HonuaClient` instead of the fixture.
 
 The standard schemas are vendored under
@@ -217,7 +404,15 @@ Environment variables:
 - `HONUA_MCP_REMOTE_URL` (required; alias `HONUA_MCP_URL`): the remote honua
   `/mcp` endpoint to proxy.
 - `HONUA_MCP_AUTH_TOKEN` (optional): sent as `Authorization: Bearer <token>`.
-- `HONUA_API_KEY` (optional): sent as `x-api-key`.
+- `HONUA_ADMIN_KEY` or `HONUA_API_KEY` (optional): sent as `x-api-key`.
+
+Configure at most one authentication scheme and one API-key source. The proxy
+rejects bearer plus API-key authentication and rejects simultaneous
+`HONUA_ADMIN_KEY` / `HONUA_API_KEY` values instead of choosing by precedence.
+Credentialed endpoints require HTTPS except for exact `localhost`, `127.0.0.1`,
+or `[::1]` HTTP development endpoints. Userinfo, query parameters, fragments,
+non-HTTP(S) URLs are rejected before connect, and redirect targets are never
+followed or sent credentials.
 
 A parity test (`test/proxy.test.ts`) asserts the tool/resource/template catalog
 the downstream client sees is byte-identical to the upstream surface, that
@@ -226,6 +421,13 @@ notifications are forwarded.
 
 ## Cross-model workflow eval (provability)
 
+**Published results:
+[Cross-model MCP eval scorecard](../docs/generated/mcp-eval-scorecard.md)** —
+generated from the committed run artifacts in [`evals/runs/`](evals/runs), with
+the deterministic control row, every non-passing run, and the protocol
+certification failures. It ships on the docs site; its freshness is a CI gate
+(`npm run docs:mcp-scorecard:check` from the repo root).
+
 The package ships a **cross-model workflow eval** that proves the "any client →
 any workflow" claim: a held-out corpus of GIS workflows (`src/eval/corpus.ts`)
 is driven through the MCP surface by different client LLMs and graded for
@@ -273,6 +475,24 @@ hallucinated place name fails. The grading taxonomy is documented in
 npm run eval:standalone       # deterministic control over the census fixture (offline)
 ```
 
+### Non-GeoServices semantic corpus (`src/eval/ogc-corpus.ts`)
+
+The **ogc** corpus runs the identical catalog against the plain OGC API Features
+fixture, addressing every source as `ogc-features:<collectionId>` — no `serviceId`,
+no `layerId`, anywhere in the corpus (a test asserts that). Its assertions are
+anchored to the recorded pygeoapi data (5 observations, 31 Utah cities:
+`avg(value)=96.14`, `sum(POP_2000)=354212`, `stn_id=2147 ⇒ 2 rows`, the
+2001–2004 interval ⇒ 3 rows), and it exercises the typed filter, a GeoJSON/bbox
+spatial constraint, and canonical temporal predicates. Three scenarios grade
+*honesty* rather than data: client-side aggregation must be reported as degraded,
+an extent that came from the declared collection extent must say so, and a CQL2
+spatial predicate the endpoint does not publish must come back as a structured
+capability refusal — never as an empty result set.
+
+```bash
+npm run eval:ogc              # deterministic control over the OGC API Features fixture (offline)
+```
+
 ### Live lane (paid, manual only)
 
 The **operator corpus** (`src/eval/operator-corpus.ts`, 8 harder scenarios) is
@@ -301,6 +521,9 @@ Shared env for every live run:
 - `HONUA_API_KEY`: sent as `x-api-key` (⇒ auth mode `api-key`) when the deployment uses key auth instead.
 - `HONUA_EVAL_REQUIRE_AUTH=1` (recommended): fail fast if neither credential is present.
 
+Set exactly one of `HONUA_MCP_AUTH_TOKEN` or `HONUA_API_KEY` for authenticated
+live runs; ambiguous authentication fails closed.
+
 ```bash
 # Anthropic Claude (default claude-opus-4-8; override with HONUA_EVAL_ANTHROPIC_MODEL):
 HONUA_MCP_REMOTE_URL="https://demo.honua.io/mcp" \

package/dist/src/certification/admin-parity.d.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export interface AdminParityReceipt {
+    readonly schemaVersion: "honua.admin-mcp-parity.v1";
+    readonly family: "honua_admin_*";
+    readonly expectedTools: number;
+    readonly expectedStaticTools: number;
+    readonly expectedTotalTools: number;
+    readonly directTools: number;
+    readonly proxiedTools: number;
+    readonly directStaticTools: number;
+    readonly proxiedStaticTools: number;
+    readonly directTotalTools: number;
+    readonly proxiedTotalTools: number;
+    readonly coverageSha256: string;
+    readonly exclusionRosterSha256: string;
+    readonly contractServerSha: string | null;
+    readonly pass: boolean;
+    readonly differences: readonly string[];
+}
+export interface AdminParityExpectation {
+    readonly publishedToolNames: readonly string[];
+    readonly excludedToolNames: readonly string[];
+    readonly expectedStaticTools: number;
+    readonly expectedTotalTools: number;
+}
+export declare function certifyAdminCatalogParity(directCatalog: readonly Tool[], proxiedCatalog: readonly Tool[], expectation?: AdminParityExpectation): AdminParityReceipt;
+export declare function normalizeAdminTools(tools: readonly Tool[]): {
+    name: string;
+    title: string | undefined;
+    description: string | undefined;
+    inputSchema: {
+        [x: string]: unknown;
+        type: "object";
+        properties?: {
+            [x: string]: object;
+        } | undefined;
+        required?: string[] | undefined;
+    };
+    outputSchema: {
+        [x: string]: unknown;
+        type: "object";
+        properties?: {
+            [x: string]: object;
+        } | undefined;
+        required?: string[] | undefined;
+    } | undefined;
+    annotations: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    } | undefined;
+}[];
+/**
+ * Hostile-server safety ceiling on the number of `tools/list` pages a single
+ * catalog read may consume.
+ *
+ * This is deliberately NOT the expected roster size. A roster assertion says
+ * "this catalog is wrong"; this ceiling says "this server never stopped
+ * paging". Conflating the two produced a single unactionable diagnostic and,
+ * worse, made an opt-in profile catalog (base + analysis + Esri GP) impossible
+ * to read at all because the *transport* refused any catalog larger than the
+ * default roster.
+ */
+export declare const MCP_TOOLS_LIST_MAX_PAGES = 1024;
+/**
+ * Hostile-server safety ceiling on the number of tools a single catalog read
+ * may accumulate. Independent of {@link MCP_DEFAULT_TOTAL_TOOL_COUNT} so that
+ * enabling additive server profiles is a roster question, not a transport
+ * failure.
+ */
+export declare const MCP_TOOLS_LIST_MAX_TOOLS = 8192;
+/** Maximum accepted `tools/list` continuation cursor length, in characters. */
+export declare const MCP_TOOLS_LIST_MAX_CURSOR_LENGTH = 1024;
+/**
+ * Read the complete MCP tool catalog. The server deliberately pages large
+ * catalogs, so a single tools/list response is not certification evidence for
+ * the 432-tool default roster (47 static plus 385 Admin MCP tools).
+ *
+ * Roster size is *not* enforced here. This function is responsible only for
+ * retrieving a complete, non-hostile catalog; deciding whether that catalog is
+ * the 432-tool default roster or a profile-enabled superset belongs to the
+ * certification and preflight callers.
+ */
+export declare function listAllTools(client: {
+    listTools(request?: {
+        cursor?: string;
+    }): Promise<{
+        tools: Tool[];
+        nextCursor?: string;
+    }>;
+}): Promise<Tool[]>;
+export declare function runAdminParityCertification(env?: NodeJS.ProcessEnv, outputPath?: string): Promise<AdminParityReceipt>;
+//# sourceMappingURL=admin-parity.d.ts.map

package/dist/src/certification/admin-parity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-parity.d.ts","sourceRoot":"","sources":["../../../src/certification/admin-parity.ts"],"names":[],"mappings":";AAgBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAG/D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,aAAa,EAAE,2BAA2B,CAAC;IACpD,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/C,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AASD,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,SAAS,IAAI,EAAE,EAC9B,cAAc,EAAE,SAAS,IAAI,EAAE,EAC/B,WAAW,GAAE,sBAA4C,GACxD,kBAAkB,CAqFpB;AAgCD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;IAYzD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,+EAA+E;AAC/E,eAAO,MAAM,gCAAgC,OAAQ,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE;IACzC,SAAS,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3F,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAgClB;AAED,wBAAsB,2BAA2B,CAC/C,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,UAAU,SAA0B,GACnC,OAAO,CAAC,kBAAkB,CAAC,CAwB7B"}