specguard-mcp 0.1.1 → 0.1.3

package/README.md

@@ -11,9 +11,9 @@ its prompt.
 SpecGuard is built [primarily for AI coding agents](https://github.com/yatfa-ai/specguard); this
 bridge is how an agent reaches it without scraping a web UI.
 
-> **Status: bootstrap.** Two tools ship today, each wrapping a capability that already exists. The
-> toolset **grows gradually** — see [Adding a tool](#adding-a-tool). It is not published to npm yet;
-> install from a checkout.
+> **Status: bootstrap.** A small set of tools ships today, each wrapping a capability that already
+> exists — see [The tools](#the-tools) for what is in it. The toolset **grows gradually** — see
+> [Adding a tool](#adding-a-tool). It is not published to npm yet; install from a checkout.
 
 ## Install
 
@@ -32,14 +32,17 @@ refuses to boot and takes the tools that needed no configuration down with it.
 
 | Variable | Needed by | Default | What it is |
 | --- | --- | --- | --- |
-| `SPECGUARD_ENDPOINT` | `get_repository_overview` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
+| `SPECGUARD_ENDPOINT` | `get_repository_overview`, `list_repositories` | — | your SpecGuard instance's root URL, **including the scheme** — e.g. `https://specguard.example.com`, or `http://localhost:3000`. A value with no scheme is refused by name (`SPECGUARD_ENDPOINT is not a usable URL: "sg.example.com"`) rather than surfacing later as an opaque failure. `SPECGUARD_URL` is accepted as an alias, and is the name every message uses when it is the one you set. A blank value counts as unset, so leaving `SPECGUARD_ENDPOINT` empty in a templated config falls through to `SPECGUARD_URL` instead of suppressing it |
 | `SPECGUARD_API_KEY` | `get_repository_overview` | — | an agent/CI API key (`sgk_…`) issued by that deployment |
+| `SPECGUARD_USER_API_KEY` | `list_repositories` | — | a **user** API key (`sgu_…`), minted from that deployment's account page. A different credential from the one above, not a second place to put the same value: SpecGuard decides which of them a request may use from the token's prefix, before it reads anything, and answers `401` for the other one. Set whichever your tools need — both, if you use both |
 | `SPECGUARD_LINT_COMMAND` | `lint_intent_annotations` | `specguard-lint` | the command that runs the linter. Most Ruby projects need `bundle exec specguard-lint` |
 | `SPECGUARD_TIMEOUT_MS` | HTTP tools | `30000` | how long a call to SpecGuard may take |
 
 `SPECGUARD_ENDPOINT` and `SPECGUARD_API_KEY` are the same variables
 [`specguard-rspec`](https://github.com/yatfa-ai/specguard-rspec) uses to ship a run, so a repository
-that already posts telemetry to SpecGuard already has them.
+that already posts telemetry to SpecGuard already has them. `SPECGUARD_USER_API_KEY` is **not** one
+of them — the gem has no notion of a user key — so that one is minted and set here for the first
+time.
 
 Register it with your MCP client — for Claude Code:
 
@@ -52,6 +55,7 @@ Register it with your MCP client — for Claude Code:
       "env": {
         "SPECGUARD_ENDPOINT": "https://specguard.example.com",
         "SPECGUARD_API_KEY": "sgk_…",
+        "SPECGUARD_USER_API_KEY": "sgu_…",
         "SPECGUARD_LINT_COMMAND": "bundle exec specguard-lint"
       }
     }
@@ -105,7 +109,7 @@ branch window rather than between the last two runs.
 | `repeated_description` | open ONE repeated description and list the examples that all share it |
 | `unstable_test` | open ONE flaky test and list its outcome run by run across the window, newest run first (needs `branch`) |
 | `commit_sha` | anchor the answer on ONE named run instead of the repository's newest one — every run-grain block moves with it, `history` does not |
-| `unannotated_examples` | `true` to list the individual tests SpecGuard cannot see — the examples behind the annotated ratio — and, in the same answer, which areas carry the most of them |
+| `unannotated_examples` | `true` to list the individual tests carrying no `@intent` — the examples behind the annotated ratio, each labelled with what SpecGuard reads of it — and, in the same answer, which areas carry the most of them |
 
 `branch` narrows `history` only — `latest_run` always names the repository's newest run, which on a
 busy repo may be on another branch. That is a property of the endpoint, not of this bridge — and
@@ -206,9 +210,23 @@ description carried by two examples in one run contributes two, so `rows` is not
 and its length is not the window's `run_count`.
 
 `annotated_ratio` is the product's adoption metric and it was the one population on this endpoint
-you could not walk down: the dashboard prints *"SpecGuard cannot see the other N tests"* and could
+you could not walk down: the dashboard printed *"SpecGuard cannot see the other N tests"* and could
 not name one of them either, so an agent told to raise annotation coverage learned how far it had to
-go and not a single test to annotate. `unannotated_examples` is that rung. It is the one argument
+go and not a single test to annotate. `unannotated_examples` is that rung.
+
+**Unannotated is not the same as unreadable, and the difference is on every response.** A test
+called `Invoice#total sums the line items` has an entity, an action and a behavior in its own
+description, so SpecGuard reads it whether or not anybody annotated it.
+`latest_run.intent_readings` splits the run's examples into `authored` (an `@intent` a human wrote),
+`derived` (read from the description) and `unreadable` (neither), with the `recorded` population
+they were counted from — no flag to pass. **`unreadable` is the only figure on this endpoint that
+means tests SpecGuard can say nothing about.** `total_specs - annotated_specs` is annotation debt,
+which on a suite that has never been annotated is the whole suite and almost all of it readable;
+never render that subtraction as blindness. A derived reading is genuinely weaker than an authored
+one — no preconditions, a behavior written for a test runner's output rather than declared, and a
+layer inferred from the directory — so report it as inferred and never as equivalent. And
+`authored` never replaces `annotated_ratio`: "how much of this suite has a human-written intent" is
+still that figure, off the run's own counters. It is the one argument
 here that is a **flag rather than a name** — pass `true`, not a value — because it opens a
 *population* rather than a pick: `total_specs` minus `annotated_specs` is a subtraction, and a
 subtraction has no line to name. Which population is still yours to choose: sent alone the flag
@@ -216,8 +234,10 @@ opens the whole run, and sent **together with** `spec_file` or `spec_directory`
 file, that area, or the AND of the two — those two keep opening their own blocks as well, so
 narrowing this one is additional rather than instead. `latest_run.unannotated_examples` opens with
 up to 100 of the unannotated examples **of whatever you asked for** (`name`, `file_path`,
-`line_number`, `spec_file_path` each — four fields, not the per-example drill-ins' six), plus that
-same population's own `recorded_count`, the `limit` the row list was cut at, and
+`line_number`, `spec_file_path`, `reading` and `derived_intent` each — six fields, and not the
+per-example drill-ins' six: no `duration_seconds` and no `outcome`), plus that
+same population's own `recorded_count`, `derived_count` and `unreadable_count`, the `limit` the row
+list was cut at, and
 `spec_file`/`spec_directory` **echoed back** as the server read them — `null` for each one you did
 not send. Read the echo before the count: the **worklist's** `recorded_count` — and only that one,
 because the map below deliberately does not narrow — is the figure you would reconcile against
@@ -231,13 +251,20 @@ That one ask opens **two** blocks, each in its own grain: `latest_run.unannotate
 *which tests* to go and annotate, and `latest_run.unannotated_directories` for *where the debt is* —
 the run's annotation debt rolled up by code area, which is what you pick the next `spec_directory`
 narrowing **from**. Both come from the one flag; there is no second argument to send and no new
-value. The map's rows carry `path`, `unannotated_count` and the `recorded_count` that area was
-counted against (the operands, never a fraction), plus `directory_count` — **every** area the run
+value. Each worklist row carries `reading` — `"derived"` or `"unreadable"` — and `derived_intent`,
+the `entity`/`action`/`behavior` SpecGuard got from the description or `null`; the **unreadable rows
+come first**, so the 100-row cap cannot hide them. The map's rows carry `path`,
+`unannotated_count`, the `recorded_count` that area was counted against, and the same three-way
+split — `authored_count`, `derived_count` and `unreadable_count`, which sum to `recorded_count`
+while the last two sum to `unannotated_count` (the operands, never a fraction), plus
+`directory_count` — **every** area the run
 touched, not every area with debt, and not `rows.size` — and its **own** `limit`, which is **10 and
 not the worklist's 100**. Two caps under one ask, and the difference is the kind of list: 100 caps a
 *worklist* to work through, 10 caps a *ranking* to pick from. The orders differ for the same reason —
-the worklist is file-navigable, the map is ranked `unannotated_count` descending with `path` as a
-tiebreak only. A fully-annotated area is a real **row** with `unannotated_count: 0`, never an
+the worklist is file-navigable within each reading, the map is ranked `unreadable_count` descending,
+then `unannotated_count` descending, with `path` as a tiebreak only — the areas SpecGuard cannot
+read lead, because a ten-row ranking led by debt on an unannotated suite is a ranking by area size
+and the dark corners never surface. A fully-annotated area is a real **row** with `unannotated_count: 0`, never an
 omission; those rows sort last *collectively*, so on a run with more areas than the cap they are cut
 and never seen, but on a run inside the cap they *are* listed and listed is correct. So `rows.size` is
 not a count of areas *with* debt — read each row's `unannotated_count`. Both blocks are at run grain,
@@ -297,6 +324,80 @@ a finding and not a disclosure someone forgot.
 Figures are `null` where CI did not report them. A `null` means *not measured*; it is never a zero,
 because a zero would read as a measurement that was taken.
 
+### `list_repositories`
+
+Lists the SpecGuard repositories the person behind `SPECGUARD_USER_API_KEY` may open — *what can I
+ask about*, which is the one question no other tool here can answer. `get_repository_overview` takes
+no repository because its `sgk_…` key **is** the repository, so without this an agent can only report
+on a repository somebody already named for it.
+
+**This tool takes no arguments** — and not as an omission. The credential is the whole of the scope:
+the endpoint takes no parameters, and which repositories are in the answer is decided by SpecGuard
+from the person the key speaks for (owned, plus shared with them through a membership). A repository
+they neither own nor were given access to never enters the response, so it cannot be filtered *in*
+from this side either.
+
+The body comes back as SpecGuard serves it — `{"repositories": […]}`, each entry carrying `id`,
+`full_name`, `name`, `registered_at` and `role`, ordered by `full_name` ascending. The first four are
+deliberately the same four fields, under the same names, that `get_repository_overview` serves in its
+own `repository` block, so a client that reads one reads the other. `role` is `owner` or `member`:
+the list mixes repositories this person owns with repositories somebody shared with them, and nothing
+else tells them apart — read it before assuming a repository is one you may administer. An empty list
+means no access, not an error.
+
+**It reads a different key from `get_repository_overview`.** `SPECGUARD_USER_API_KEY` (`sgu_…`), not
+`SPECGUARD_API_KEY` (`sgk_…`). SpecGuard refuses each credential in the other's place — the prefix
+decides which table is consulted before any of them is read — so the two are not interchangeable and
+setting one does not stand in for the other. Every message this tool produces names the variable
+*it* reads, so a `401` here never sends you to check the key `get_repository_overview` uses.
+
+Registering a repository is now `add_repository`, below — it reads the same `sgu_…` key and takes the
+`full_name` this tool reports. Revoking keys and the rest of the user-scoped surface are still absent,
+because their endpoints have not shipped: a tool here is a promise the agent will act on, so it waits
+for the capability rather than the other way round.
+
+### `add_repository`
+
+Registers a GitHub repository with SpecGuard for the person behind `SPECGUARD_USER_API_KEY`, and
+returns the repository together with its **first CI API key** — the `sgk_…` key that repository's CI
+will use to ingest runs, minted in the same call so a fresh registration is usable without a second
+trip through the browser.
+
+| argument | |
+| --- | --- |
+| `full_name` | the repository to register, as `org/repo` (for example `acme/billing`) — the same handle `list_repositories` reports. Not a URL, not a bare repository name |
+
+The body comes back as SpecGuard serves it: a `repository` block (`id`, `full_name`, `name`,
+`registered_at` — deliberately the same four fields `get_repository_overview` serves in its own
+`repository` block) and an `api_key` block (`name`, `token`, `hint`, `created_at`).
+
+> ⚠️ **`api_key.token` is shown once and never again.** Nothing stores it and no endpoint can
+> re-serve it. Capture it from this response — an agent should hand it straight to the person it is
+> working for. A key that is lost is replaced from SpecGuard's API-keys page in a browser, not from
+> here.
+
+> ⚠️ **This tool is not idempotent, and it writes.** If the call exceeds `SPECGUARD_TIMEOUT_MS` the
+> bridge gives up, but the registration may still have succeeded on the server — taking its one-time
+> token into a response nobody received. The retry is then refused with `has already been taken`,
+> which is the honest answer rather than a bug. Do not retry a timeout blindly; check
+> `list_repositories`, and recover the key in the browser.
+
+**It needs a current record of your GitHub permissions, and only a browser creates one.** SpecGuard
+decides whether you may register a repository from a stored grant, and fails closed when that grant
+is missing or stale — which is every person who has not signed in and connected GitHub recently. That
+refusal arrives as SpecGuard's own sentence, verbatim, naming the fix: *sign in to SpecGuard in a
+browser and reconnect GitHub, then try again*. No argument to this tool substitutes for it. The same
+path carries the other refusals — a repository the SpecGuard GitHub App is not installed on, one you
+do not administer, one already registered.
+
+**The `org/repo` format is not re-checked here.** This bridge verifies only that you passed a
+non-blank string; SpecGuard validates the name and refuses an unusable one in its own words. A second
+format rule on this side would be free to drift from the one that actually decides, and would surface
+as this bridge rejecting a name the platform would have accepted.
+
+It reads `SPECGUARD_USER_API_KEY` (`sgu_…`), the same credential as `list_repositories` and a
+different one from the `sgk_…` key `get_repository_overview` uses.
+
 ## How it works
 
 ```
@@ -306,11 +407,15 @@ agent  ⇄  specguard-mcp  ⇄  SpecGuard         (HTTP, the same API the dashbo
 
 The bridge is a **thin client**: it shells out and it calls the API, and it re-implements neither.
 It carries no knowledge of the OpenTestIntent schema, holds no copy of the linter's rules, and
-reshapes no response — both tools return the shape of the capability they wrap, so a field added
+reshapes no response — every tool returns the shape of the capability it wraps, so a field added
 upstream reaches the agent without a release here.
 
-Authorization and project scoping are enforced by SpecGuard, never by this bridge, using the same
-`sgk_…` keys CI uses to ingest runs. The bridge adds no credentials of its own and stores nothing.
+Authorization and project scoping are enforced by SpecGuard, never by this bridge, using keys you
+issue there — the same `sgk_…` keys CI uses to ingest runs, and, for the tools that answer to a
+person rather than to a repository, an `sgu_…` user key. Which of the two a request may carry is
+SpecGuard's decision and it is taken from the token's prefix, before any credential is looked up, so
+the bridge cannot widen either one's reach: it forwards the key the tool's own variable holds and
+reports what came back. It adds no credentials of its own and stores nothing.
 
 No argument ever reaches a shell: subprocesses are spawned with an argument list, so a path from a
 model is a path that does not exist rather than a command.
@@ -322,11 +427,13 @@ The toolset fills in as more of SpecGuard lands. Adding one is two mechanical ed
 1. a new file under `src/tools/` that default-exports a `ToolDefinition`;
 2. one entry appended to the array in `src/tools/index.ts`.
 
-There is no third — no third *wiring* edit, at least: every tool also earns a `### ` section with an
-argument table above, and every argument earns a row in that table, since this README ships as the
-package's published documentation, and `test/readme.test.ts` derives that obligation from the
-registry so a missing section or an undocumented parameter fails the suite. `src/server.ts` iterates
-that array and contains no per-tool code — no `switch`, no hard-coded name — and everything a tool
+There is no third — no third *wiring* edit, at least: every tool also earns a `### ` section above,
+and every argument earns a row in that section's table, since this README ships as the package's
+published documentation, and `test/readme.test.ts` derives that obligation from the registry so a
+missing section or an undocumented parameter fails the suite. A tool that genuinely takes no
+arguments (`list_repositories` is the first) still earns the section, and is named in that file's
+`ARGUMENT_LESS_TOOLS` — a deliberate line to add, rather than a floor relaxed for everyone.
+`src/server.ts` iterates that array and contains no per-tool code — no `switch`, no hard-coded name — and everything a tool
 touches the world with (config, subprocesses, `fetch`) is injected, so a new tool is testable
 without a live deployment for free. The property tests in `test/tools/registry.test.ts` run over
 whatever the registry holds, so a tool added later is checked by tests written today.

package/dist/bin/specguard-mcp.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createServer } from "../src/server.js";
+import { installTeardown } from "../src/support/teardown.js";
 /**
  * The stdio entrypoint — the only place a transport is named.
  *
@@ -21,6 +22,10 @@ import { createServer } from "../src/server.js";
  * it.
  */
 async function main() {
+    // Installed BEFORE the transport is connected, so there is no window in which
+    // the server is accepting tool calls — and therefore spawning runs — with no
+    // handler to clean them up.
+    installTeardown();
     const server = createServer();
     await server.connect(new StdioServerTransport());
     process.stderr.write("specguard-mcp: ready on stdio\n");

package/dist/bin/specguard-mcp.js.map

@@ -1 +1 @@
-{"version":3,"file":"specguard-mcp.js","sourceRoot":"","sources":["../../bin/specguard-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD;;;;;;;;;;;;;;;;;;GAkBG;AACH,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AAC1D,CAAC;AAED,4EAA4E;AAC5E,gFAAgF;AAChF,0EAA0E;AAC1E,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CACnG,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"specguard-mcp.js","sourceRoot":"","sources":["../../bin/specguard-mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,KAAK,UAAU,IAAI;IACjB,8EAA8E;IAC9E,6EAA6E;IAC7E,4BAA4B;IAC5B,eAAe,EAAE,CAAC;IAElB,MAAM,MAAM,GAAG,YAAY,EAAE,CAAC;IAC9B,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AAC1D,CAAC;AAED,4EAA4E;AAC5E,gFAAgF;AAChF,0EAA0E;AAC1E,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yBAAyB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CACnG,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/src/config.d.ts

@@ -26,6 +26,28 @@
  * too rather than left as a silent no-op for anyone who follows the ticket.
  * `SPECGUARD_ENDPOINT` wins when both are set and disagree, because it is the
  * one the rest of the toolchain is already reading.
+ *
+ * == TWO KEY VARIABLES, because SpecGuard has two credentials that refuse each
+ * == other
+ *
+ * `Api::BaseController` discriminates on the token's PREFIX *before any table is
+ * read*, and answers 401 on a mismatch without a lookup: `sgk_` names ONE
+ * repository (`GET /api/v1/repository`, `POST /api/v1/ingest`), `sgu_` names a
+ * PERSON (`GET /api/v1/repositories`). `UserApiKey::TOKEN_PREFIX` says the two
+ * prefixes are deliberately the same length so neither can be a prefix of the
+ * other — the mutual refusal is designed, not incidental.
+ *
+ * One variable therefore cannot serve both: whichever kind it holds, the tools
+ * needing the other kind 401. So there are two, read independently, and neither
+ * is required — an operator who only ever calls the repository tool sets only
+ * `SPECGUARD_API_KEY`, exactly as before this existed. Prefix-dispatching over a
+ * single variable was the alternative and it cannot work: an operator wanting
+ * both kinds of tool needs both keys present at once.
+ *
+ * Which variable a tool reads is then carried onto `ApiConfig` alongside the
+ * value — see `Credential` — for the same reason `endpointVariable` is: a
+ * diagnostic that names the wrong variable sends an operator to fix something
+ * they never set.
  */
 export interface Config {
     /** SpecGuard deployment root, trailing slash stripped. `undefined` when unset. */
@@ -40,8 +62,18 @@ export interface Config {
      * speak the one that was used.
      */
     readonly endpointVariable: EndpointVariable | undefined;
-    /** An `sgk_…` API key. `undefined` when unset. */
+    /** An `sgk_…` repository API key, from `SPECGUARD_API_KEY`. `undefined` when unset. */
     readonly apiKey: string | undefined;
+    /**
+     * An `sgu_…` user API key, from `SPECGUARD_USER_API_KEY`. `undefined` when unset.
+     *
+     * A SECOND slot rather than a second meaning for the first one — see the note
+     * at the top of this file. It is minted from the account page
+     * (`/account`) and speaks for a person; the repository key is minted per
+     * repository and speaks for one repository. Neither deployment endpoint will
+     * accept the other's token, so the two values live in two places here too.
+     */
+    readonly userApiKey: string | undefined;
     /**
      * The command that runs the `@intent` linter, already tokenised.
      *
@@ -76,27 +108,85 @@ export interface ApiConfig {
      */
     readonly endpointVariable: EndpointVariable;
     readonly apiKey: string;
+    /**
+     * WHICH credential `apiKey` is — the variable it was read from, the prefix
+     * that variable is expected to hold, and how to say both in a sentence.
+     *
+     * Exactly the treatment `endpointVariable` above gets, applied to the other
+     * half, and for the same reason. `describeFailure` in
+     * `support/specguard-api.ts` used to hardcode "SPECGUARD_API_KEY must be an
+     * sgk_… key … keys are per-repository" into every 401, so the first
+     * user-scoped tool routed through `getJson` would have inherited three
+     * sentences that are all false of it — naming a variable its operator may
+     * never have set. Carrying the answer rather than re-deriving it per tool is
+     * what makes the next credential-scoped tool inherit correct naming the same
+     * way it inherits the URL check.
+     */
+    readonly credential: Credential;
     readonly requestTimeoutMs: number;
 }
 export type EndpointVariable = "SPECGUARD_ENDPOINT" | "SPECGUARD_URL";
+export type ApiKeyVariable = "SPECGUARD_API_KEY" | "SPECGUARD_USER_API_KEY";
+/**
+ * One of SpecGuard's two credential kinds, described well enough that a message
+ * about it can be written without knowing which one it is.
+ *
+ * The two prose fields are sentence FRAGMENTS rather than whole messages on
+ * purpose: the surrounding wording — "is not set in the MCP server's
+ * environment", "SpecGuard rejected the API key (401)" — is the same for both
+ * kinds and is written once, at the site that knows the situation. Only the
+ * parts that genuinely differ between an `sgk_` key and an `sgu_` key live
+ * here.
+ */
+export interface Credential {
+    /** The environment variable this kind of key is read from. */
+    readonly variable: ApiKeyVariable;
+    /** The prefix SpecGuard requires of it, checked before any table is read. */
+    readonly prefix: "sgk_" | "sgu_";
+    /** Completes "… issued from ___" in a message about the variable being unset. */
+    readonly issuedFrom: string;
+    /** Completes "… issued by <deployment> ___" in a message about a 401. */
+    readonly rejection: string;
+}
 /**
- * Both halves or a legible failure — never one half and a surprise later.
+ * The `sgk_` key: one repository, and the same variable CI already sets.
  *
- * Reported together rather than one at a time: an operator who set neither
- * should learn that in one round trip instead of fixing a variable, re-calling,
- * and being told about the next one.
+ * The 401 wording is unchanged from when this was the only credential — it is
+ * accurate about this kind, and the reason a second kind exists is precisely
+ * that it was never accurate about the other.
+ */
+export declare const REPOSITORY_CREDENTIAL: Credential;
+/**
+ * The `sgu_` key: a person, and a variable nothing else in the toolchain reads.
  *
- * The endpoint is also PARSED here, not merely counted as present. It is spent
- * later inside `new URL(...)` in the HTTP client, where a malformed value throws
- * a bare `TypeError` — which is not a `SpecGuardMcpError`, so the server's error
- * boundary reads it as a defect and tells the agent "this is a bug in the
- * bridge, not in your project or configuration". For the commonest config typo
- * there is (omitting `https://`) that sentence is the exact opposite of the
- * truth, and it sends an agent looking in the one place the problem is not.
- * Validating here rather than at the call site is deliberate: every HTTP-backed
- * tool added later comes through this function and inherits the check.
+ * `specguard-rspec` ships runs with an `sgk_` key and has no notion of this one,
+ * so an operator who already has CI reporting to SpecGuard does NOT already
+ * have this variable — which is why the message says where to mint one rather
+ * than assuming it is lying around.
+ */
+export declare const USER_CREDENTIAL: Credential;
+/**
+ * What a tool needing the `sgk_` REPOSITORY key requires — the endpoint and
+ * `SPECGUARD_API_KEY`.
+ *
+ * Unchanged in name and in behaviour: every tool that reached the deployment
+ * before this file grew a second credential calls exactly this, and gets exactly
+ * what it got.
  */
 export declare function requireApiConfig(config: Config): ApiConfig;
+/**
+ * What a tool needing the `sgu_` USER key requires — the endpoint and
+ * `SPECGUARD_USER_API_KEY`.
+ *
+ * A sibling rather than a flag on `requireApiConfig`, which is the shape
+ * `loadConfig`'s note at the top of this file already sanctioned: a tool asks
+ * for what IT needs, so a tool needing neither key is unaffected and startup
+ * still validates nothing. The two differ only in which value and which
+ * `Credential` they pass to the one implementation below, so a fix to the
+ * diagnostics reaches both and they cannot drift into describing the same
+ * situation differently.
+ */
+export declare function requireUserApiConfig(config: Config): ApiConfig;
 /**
  * Splits a configured command into argv WITHOUT a shell, honouring single and
  * double quotes so a path with a space survives.

package/dist/src/config.js

@@ -24,21 +24,81 @@ export function loadConfig(env = process.env) {
         endpoint: endpointVariable === undefined ? undefined : normaliseEndpoint(env[endpointVariable]),
         endpointVariable,
         apiKey: presence(env["SPECGUARD_API_KEY"]),
+        userApiKey: presence(env["SPECGUARD_USER_API_KEY"]),
         lintCommand: lintCommand.length > 0 ? lintCommand : DEFAULT_LINT_COMMAND,
         requestTimeoutMs: positiveInteger(env["SPECGUARD_TIMEOUT_MS"]) ?? DEFAULT_REQUEST_TIMEOUT_MS,
     };
 }
+/**
+ * The `sgk_` key: one repository, and the same variable CI already sets.
+ *
+ * The 401 wording is unchanged from when this was the only credential — it is
+ * accurate about this kind, and the reason a second kind exists is precisely
+ * that it was never accurate about the other.
+ */
+export const REPOSITORY_CREDENTIAL = {
+    variable: "SPECGUARD_API_KEY",
+    prefix: "sgk_",
+    issuedFrom: "issued from its API keys page",
+    rejection: "for the repository you are asking about — keys are per-repository, and a " +
+        "revoked key reads the same as a wrong one",
+};
+/**
+ * The `sgu_` key: a person, and a variable nothing else in the toolchain reads.
+ *
+ * `specguard-rspec` ships runs with an `sgk_` key and has no notion of this one,
+ * so an operator who already has CI reporting to SpecGuard does NOT already
+ * have this variable — which is why the message says where to mint one rather
+ * than assuming it is lying around.
+ */
+export const USER_CREDENTIAL = {
+    variable: "SPECGUARD_USER_API_KEY",
+    prefix: "sgu_",
+    issuedFrom: "issued from your account page",
+    rejection: "for your own SpecGuard account — a user key speaks for a person and lists what " +
+        "that person may open, an sgk_… repository key is refused here without a lookup, " +
+        "and a revoked key reads the same as a wrong one",
+};
 /**
  * The name to speak when no variable was set at all — the message is telling
  * someone to set one, and this is the spelling the rest of the toolchain reads.
  */
 const DEFAULT_ENDPOINT_VARIABLE = "SPECGUARD_ENDPOINT";
+/**
+ * What a tool needing the `sgk_` REPOSITORY key requires — the endpoint and
+ * `SPECGUARD_API_KEY`.
+ *
+ * Unchanged in name and in behaviour: every tool that reached the deployment
+ * before this file grew a second credential calls exactly this, and gets exactly
+ * what it got.
+ */
+export function requireApiConfig(config) {
+    return requireCredentialledApiConfig(config, config.apiKey, REPOSITORY_CREDENTIAL);
+}
+/**
+ * What a tool needing the `sgu_` USER key requires — the endpoint and
+ * `SPECGUARD_USER_API_KEY`.
+ *
+ * A sibling rather than a flag on `requireApiConfig`, which is the shape
+ * `loadConfig`'s note at the top of this file already sanctioned: a tool asks
+ * for what IT needs, so a tool needing neither key is unaffected and startup
+ * still validates nothing. The two differ only in which value and which
+ * `Credential` they pass to the one implementation below, so a fix to the
+ * diagnostics reaches both and they cannot drift into describing the same
+ * situation differently.
+ */
+export function requireUserApiConfig(config) {
+    return requireCredentialledApiConfig(config, config.userApiKey, USER_CREDENTIAL);
+}
 /**
  * Both halves or a legible failure — never one half and a surprise later.
  *
  * Reported together rather than one at a time: an operator who set neither
  * should learn that in one round trip instead of fixing a variable, re-calling,
- * and being told about the next one.
+ * and being told about the next one. That property is why the two `require*`
+ * entry points share this body rather than each doing their own presence check:
+ * "together" has to mean the endpoint AND whichever key the calling tool needs,
+ * and a per-tool check would report them one at a time again.
  *
  * The endpoint is also PARSED here, not merely counted as present. It is spent
  * later inside `new URL(...)` in the HTTP client, where a malformed value throws
@@ -49,25 +109,36 @@ const DEFAULT_ENDPOINT_VARIABLE = "SPECGUARD_ENDPOINT";
  * truth, and it sends an agent looking in the one place the problem is not.
  * Validating here rather than at the call site is deliberate: every HTTP-backed
  * tool added later comes through this function and inherits the check.
+ *
+ * The KEY is deliberately NOT validated against `credential.prefix` here. The
+ * deployment is the authority on whether a token is acceptable — it checks the
+ * prefix, then the digest, then whether the key is revoked — and a second,
+ * weaker copy of the first third of that rule on this side would refuse a token
+ * SpecGuard would have accepted the moment the platform mints a third prefix.
+ * The prefix is carried so a MESSAGE can name it, not so this file can enforce
+ * it; the 401 branch of `describeFailure` is where a wrong-kind key is
+ * diagnosed, with the deployment's own verdict in hand.
  */
-export function requireApiConfig(config) {
+function requireCredentialledApiConfig(config, apiKey, credential) {
     const endpointVariable = config.endpointVariable ?? DEFAULT_ENDPOINT_VARIABLE;
     const missing = [];
     if (config.endpoint === undefined)
         missing.push(endpointVariable);
-    if (config.apiKey === undefined)
-        missing.push("SPECGUARD_API_KEY");
+    if (apiKey === undefined)
+        missing.push(credential.variable);
     if (missing.length > 0) {
         throw new ConfigError(`This tool talks to a SpecGuard deployment, and ${missing.join(" and ")} ` +
             `${missing.length === 1 ? "is" : "are"} not set in the MCP server's environment. ` +
             "Set them in your MCP client's server config " +
-            `(${endpointVariable} is your deployment's root URL, SPECGUARD_API_KEY an sgk_… key ` +
-            "issued from its API keys page). Tools that do not reach the deployment are unaffected.");
+            `(${endpointVariable} is your deployment's root URL, ${credential.variable} ` +
+            `an ${credential.prefix}… key ${credential.issuedFrom}). ` +
+            "Tools that do not reach the deployment are unaffected.");
     }
     return {
         endpoint: requireHttpUrl(config.endpoint, endpointVariable),
         endpointVariable,
-        apiKey: config.apiKey,
+        apiKey: apiKey,
+        credential,
         requestTimeoutMs: config.requestTimeoutMs,
     };
 }

package/dist/src/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -1,5 +1,5 @@
 export { createServer, SERVER_NAME, SERVER_VERSION, type CreateServerOptions } from "./server.js";
-export { loadConfig, requireApiConfig, tokenise, type ApiConfig, type Config } from "./config.js";
+export { loadConfig, requireApiConfig, requireUserApiConfig, tokenise, type ApiConfig, type ApiKeyVariable, type Config, type Credential, } from "./config.js";
 export { ApiError, ArgumentError, CommandError, ConfigError, SpecGuardMcpError } from "./errors.js";
 export { TOOLS } from "./tools/index.js";
 export type { ToolContext, ToolDefinition, ToolResult } from "./tools/types.js";

package/dist/src/index.js

@@ -1,5 +1,10 @@
 export { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
-export { loadConfig, requireApiConfig, tokenise } from "./config.js";
+// `requireUserApiConfig` is re-exported beside `requireApiConfig` rather than
+// left behind it: the two are one seam with two credentials, and a consumer that
+// can name only half of it would have to deep-import past this entrypoint to
+// reach the other — the same unnameable-but-typed state `test/index.test.ts`
+// exists to keep out of the error taxonomy.
+export { loadConfig, requireApiConfig, requireUserApiConfig, tokenise, } from "./config.js";
 export { ApiError, ArgumentError, CommandError, ConfigError, SpecGuardMcpError } from "./errors.js";
 export { TOOLS } from "./tools/index.js";
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAA4B,MAAM,aAAa,CAAC;AAClG,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,QAAQ,EAA+B,MAAM,aAAa,CAAC;AAClG,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAA4B,MAAM,aAAa,CAAC;AAClG,8EAA8E;AAC9E,iFAAiF;AACjF,6EAA6E;AAC7E,6EAA6E;AAC7E,4CAA4C;AAC5C,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,QAAQ,GAKT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC"}