specshield-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecShield Software Private Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# SpecShield MCP Server
+
+**The API-change deploy gate for AI coding agents.** Ask *"is it safe to ship this
+API change to my consumers?"* right inside Claude, Cursor, and other MCP clients —
+and catch breaking changes before they reach your consumers.
+
+It's a thin adapter over the [SpecShield](https://specshield.io) backend. Every tool
+is **read-only / analyze-only — it never modifies your code.**
+
+> Why not just diff specs? Plenty of tools (including free ones) list breaking
+> changes. SpecShield's job is the *decision*: **can I deploy this?** — the deploy
+> gate is the hero tool here.
+
+> ⚙️ **In CI/CD instead of an agent?** The [`specshield` CLI](https://www.npmjs.com/package/specshield) runs the same breaking-change and `can-i-deploy` checks in your pipeline (GitHub Action, exit codes). Same job, two entry points: this server for AI agents, the CLI for CI/CD.
+
+## Tools
+
+| # | Tool | What it answers |
+|---|------|-----------------|
+| 1 | **`is_change_safe`** ⭐ | Is this change safe to merge/deploy? Will it break consumers? (`safeToMerge` + risk + blocking reasons) |
+| 2 | `explain_breaking_changes` | What breaks, developer & consumer impact, suggested migration |
+| 3 | `generate_migration_guide` | Migration guide (markdown) + safe rollout steps |
+| 4 | `generate_release_notes` | Release notes for developer / customer / internal |
+| 5 | `compare_specs` | The raw diff (breaking / additions / modifications / warnings) + risk score |
+
+Each tool accepts specs inline (`baseSpecContent` / `targetSpecContent`) or by path
+(`baseSpecPath` / `targetSpecPath`).
+
+_`run_governance_review` is planned — it ships once the backend governance endpoint
+lands._
+
+> Full setup, verification & troubleshooting: **[docs/mcp-server-setup.md](docs/mcp-server-setup.md)**.
+
+## Install
+
+Requires **Node.js ≥ 20** and a SpecShield API key (from
+[specshield.io/account](https://specshield.io/account)).
+
+```bash
+npx -y specshield-mcp-server
+```
+
+### Claude Desktop
+`claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "specshield": {
+      "command": "npx",
+      "args": ["-y", "specshield-mcp-server"],
+      "env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }
+    }
+  }
+}
+```
+
+### Claude Code
+```bash
+claude mcp add specshield --env SPECSHIELD_API_KEY=ss_your_key_here -- npx -y specshield-mcp-server
+```
+
+### Cursor
+`~/.cursor/mcp.json` (or the project `.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "specshield": {
+      "command": "npx",
+      "args": ["-y", "specshield-mcp-server"],
+      "env": { "SPECSHIELD_API_KEY": "ss_your_key_here" }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Env var | Required | Default | Purpose |
+|---------|----------|---------|---------|
+| `SPECSHIELD_API_KEY` | **yes** | — | Your SpecShield API key. Store it as a secret; never commit it. |
+| `SPECSHIELD_API_URL` | no | `https://api.specshield.io` | Backend base URL (override for self-hosted/staging). |
+| `SPECSHIELD_TIMEOUT_MS` | no | `30000` | Per-request timeout. |
+| `SPECSHIELD_LOG_LEVEL` | no | `info` | `debug` \| `info` \| `warn` \| `error` (logs go to stderr). |
+
+## Example prompts (lead with the deploy gate)
+
+- *"Here are my old and new `openapi.yaml` — **is it safe to ship this API change to my consumers?**"*
+- *"Compare `v1.yaml` and `v2.yaml` and tell me if I can deploy, and why not."*
+- *"Explain the breaking changes between these two specs and how consumers should migrate."*
+- *"Generate customer-facing release notes for this API change."*
+
+## Security & privacy
+
+- **API key required.** Sent only as the `X-Api-Key` header to your configured backend.
+- **Read-only / analyze-only.** No mutation tools, no shell execution, no arbitrary
+  file access (a spec file is read only when you explicitly pass a path).
+- **No secret or spec logging.** The server never logs spec content, API keys, or
+  request bodies; error messages are redacted and machine-readable.
+- Specs are sent to your configured SpecShield backend for analysis.
+
+## Local development
+
+```bash
+npm install
+npm run build      # tsc → dist/
+npm test           # vitest (no network)
+npm run lint
+npm run smoke      # boots the server against a stubbed backend and lists tools
+npm start          # run the built server over stdio
+```
+
+## License
+
+MIT © SpecShield Software Private Limited

package/dist/backendTypes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Shapes returned by the SpecShield backend /api/intelligence/** endpoints
+ * (Phase 1 facade). Kept in one place so the tools stay thin mappers.
+ */
+export type RiskLevel = "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+export interface ChangeItem {
+    type: string;
+    changeId: string;
+    path: string | null;
+    method: string | null;
+    field: string | null;
+    oldValue: string | null;
+    newValue: string | null;
+    description: string | null;
+    severity: string;
+}
+export interface RiskScore {
+    level: RiskLevel;
+    score: number;
+    breakingCount: number;
+    totalChanges: number;
+    summary: string;
+}
+/** POST /api/intelligence/change-safety */
+export interface ChangeSafetyResponse {
+    safeToMerge: boolean;
+    riskLevel: RiskLevel;
+    blockingReasons: string[];
+    recommendedAction: string;
+    reportUrl?: string;
+    environment?: string;
+}
+/** POST /api/intelligence/compare */
+export interface IntelligenceCompareResponse {
+    breakingChanges: ChangeItem[];
+    additions: ChangeItem[];
+    modifications: ChangeItem[];
+    warnings: ChangeItem[];
+    risk: RiskScore;
+    safeToMerge: boolean;
+    compatibilitySummary: string;
+}
+/** POST /api/intelligence/release-notes-preview */
+export interface ReleaseNotesPreview {
+    audience: string;
+    markdown: string;
+}
+/** POST /api/intelligence/migration-guide-preview */
+export interface MigrationAdvice {
+    summary: string;
+    steps: string[];
+    language: string;
+}

package/dist/backendTypes.js

@@ -0,0 +1,6 @@
+/**
+ * Shapes returned by the SpecShield backend /api/intelligence/** endpoints
+ * (Phase 1 facade). Kept in one place so the tools stay thin mappers.
+ */
+export {};
+//# sourceMappingURL=backendTypes.js.map

package/dist/backendTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backendTypes.js","sourceRoot":"","sources":["../src/backendTypes.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/client.d.ts

@@ -0,0 +1,35 @@
+import type { SpecShieldConfig } from "./config.js";
+import type { Logger } from "./logger.js";
+export interface ApiClientOptions {
+    /** Total attempts including the first (retries = maxAttempts - 1). */
+    maxAttempts?: number;
+    /** Base backoff in ms; delay grows linearly per attempt. 0 disables sleeping (tests). */
+    baseDelayMs?: number;
+    /** Injectable fetch + sleep for tests. */
+    fetchImpl?: typeof fetch;
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/**
+ * Thin HTTP adapter over the SpecShield backend `/api/intelligence/**` endpoints.
+ * It holds NO diff/risk logic — every result comes from the backend.
+ *
+ * Contract:
+ *  - sends `X-Api-Key` on every request;
+ *  - retries only transient 429 / 5xx / network / timeout, up to `maxAttempts`;
+ *  - never retries 4xx validation/auth errors;
+ *  - enforces `SPECSHIELD_TIMEOUT_MS`;
+ *  - throws {@link SpecShieldError} whose message never contains the spec, the
+ *    API key, or the request body.
+ */
+export declare class SpecShieldApiClient {
+    private readonly config;
+    private readonly logger;
+    private readonly maxAttempts;
+    private readonly baseDelayMs;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(config: SpecShieldConfig, logger: Logger, options?: ApiClientOptions);
+    /** POST a JSON body and return the parsed JSON response. */
+    post<T>(path: string, body: unknown): Promise<T>;
+    private backoff;
+}

package/dist/client.js

@@ -0,0 +1,93 @@
+import { SpecShieldError } from "./errors.js";
+/**
+ * Thin HTTP adapter over the SpecShield backend `/api/intelligence/**` endpoints.
+ * It holds NO diff/risk logic — every result comes from the backend.
+ *
+ * Contract:
+ *  - sends `X-Api-Key` on every request;
+ *  - retries only transient 429 / 5xx / network / timeout, up to `maxAttempts`;
+ *  - never retries 4xx validation/auth errors;
+ *  - enforces `SPECSHIELD_TIMEOUT_MS`;
+ *  - throws {@link SpecShieldError} whose message never contains the spec, the
+ *    API key, or the request body.
+ */
+export class SpecShieldApiClient {
+    config;
+    logger;
+    maxAttempts;
+    baseDelayMs;
+    fetchImpl;
+    sleep;
+    constructor(config, logger, options = {}) {
+        this.config = config;
+        this.logger = logger;
+        this.maxAttempts = options.maxAttempts ?? 3;
+        this.baseDelayMs = options.baseDelayMs ?? 300;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.sleep = options.sleepImpl ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    /** POST a JSON body and return the parsed JSON response. */
+    async post(path, body) {
+        const url = `${this.config.apiUrl}${path}`;
+        for (let attempt = 1;; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+            try {
+                const res = await this.fetchImpl(url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        "X-Api-Key": this.config.apiKey,
+                        "X-SpecShield-Client": "mcp",
+                    },
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+                if (res.ok) {
+                    return (await res.json());
+                }
+                const status = res.status;
+                // 4xx auth/validation: never retry.
+                if (status === 401 || status === 403) {
+                    throw new SpecShieldError("auth_error", "SpecShield rejected the API key. Check SPECSHIELD_API_KEY.", status);
+                }
+                if (status >= 400 && status < 500 && status !== 429) {
+                    throw new SpecShieldError("validation_error", `SpecShield rejected the request as invalid (HTTP ${status}). ` +
+                        "Check that both specs are valid OpenAPI.", status);
+                }
+                // 429 / 5xx: retry if attempts remain.
+                if (attempt < this.maxAttempts) {
+                    this.logger.debug("retrying after transient status", { status, attempt });
+                    await this.backoff(attempt);
+                    continue;
+                }
+                throw new SpecShieldError(status === 429 ? "rate_limited" : "backend_error", `SpecShield request failed after ${this.maxAttempts} attempts (HTTP ${status}).`, status);
+            }
+            catch (err) {
+                if (err instanceof SpecShieldError)
+                    throw err;
+                const aborted = err instanceof Error && err.name === "AbortError";
+                if (attempt < this.maxAttempts) {
+                    this.logger.debug("retrying after transient error", {
+                        attempt,
+                        kind: aborted ? "timeout" : "network",
+                    });
+                    await this.backoff(attempt);
+                    continue;
+                }
+                if (aborted) {
+                    throw new SpecShieldError("timeout", `SpecShield request timed out after ${this.config.timeoutMs}ms.`);
+                }
+                throw new SpecShieldError("network_error", "Could not reach SpecShield.");
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+    }
+    async backoff(attempt) {
+        if (this.baseDelayMs > 0)
+            await this.sleep(this.baseDelayMs * attempt);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAY9C;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,mBAAmB;IAOX;IACA;IAPF,WAAW,CAAS;IACpB,WAAW,CAAS;IACpB,SAAS,CAAe;IACxB,KAAK,CAAgC;IAEtD,YACmB,MAAwB,EACxB,MAAc,EAC/B,UAA4B,EAAE;QAFb,WAAM,GAAN,MAAM,CAAkB;QACxB,WAAM,GAAN,MAAM,CAAQ;QAG/B,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,GAAG,CAAC;QAC9C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC;QAC5C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,SAAS,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IACpF,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,IAAI,CAAI,IAAY,EAAE,IAAa;QACvC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;QAE3C,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAClC,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAC1E,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE;oBACpC,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE;wBACP,cAAc,EAAE,kBAAkB;wBAClC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;wBAC/B,qBAAqB,EAAE,KAAK;qBAC7B;oBACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;oBAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;iBAC1B,CAAC,CAAC;gBAEH,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;oBACX,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAM,CAAC;gBACjC,CAAC;gBAED,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;gBAC1B,oCAAoC;gBACpC,IAAI,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;oBACrC,MAAM,IAAI,eAAe,CACvB,YAAY,EACZ,4DAA4D,EAC5D,MAAM,CACP,CAAC;gBACJ,CAAC;gBACD,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,KAAK,GAAG,EAAE,CAAC;oBACpD,MAAM,IAAI,eAAe,CACvB,kBAAkB,EAClB,oDAAoD,MAAM,KAAK;wBAC7D,0CAA0C,EAC5C,MAAM,CACP,CAAC;gBACJ,CAAC;gBACD,uCAAuC;gBACvC,IAAI,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;oBAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;oBAC1E,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;oBAC5B,SAAS;gBACX,CAAC;gBACD,MAAM,IAAI,eAAe,CACvB,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,eAAe,EACjD,mCAAmC,IAAI,CAAC,WAAW,mBAAmB,MAAM,IAAI,EAChF,MAAM,CACP,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,eAAe;oBAAE,MAAM,GAAG,CAAC;gBAE9C,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC;gBAClE,IAAI,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;oBAC/B,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,EAAE;wBAClD,OAAO;wBACP,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;qBACtC,CAAC,CAAC;oBACH,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;oBAC5B,SAAS;gBACX,CAAC;gBACD,IAAI,OAAO,EAAE,CAAC;oBACZ,MAAM,IAAI,eAAe,CACvB,SAAS,EACT,sCAAsC,IAAI,CAAC,MAAM,CAAC,SAAS,KAAK,CACjE,CAAC;gBACJ,CAAC;gBACD,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,6BAA6B,CAAC,CAAC;YAC5E,CAAC;oBAAS,CAAC;gBACT,YAAY,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,OAAe;QACnC,IAAI,IAAI,CAAC,WAAW,GAAG,CAAC;YAAE,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,CAAC;IACzE,CAAC;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface SpecShieldConfig {
+    apiUrl: string;
+    apiKey: string;
+    timeoutMs: number;
+    logLevel: LogLevel;
+}
+/**
+ * Loads configuration from environment variables. SPECSHIELD_API_KEY is required;
+ * everything else has a sensible default. Throws {@link ConfigError} (never
+ * echoing the key) when the key is missing.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): SpecShieldConfig;

package/dist/config.js

@@ -0,0 +1,30 @@
+import { ConfigError } from "./errors.js";
+const DEFAULT_API_URL = "https://api.specshield.io";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const LOG_LEVELS = ["debug", "info", "warn", "error"];
+/**
+ * Loads configuration from environment variables. SPECSHIELD_API_KEY is required;
+ * everything else has a sensible default. Throws {@link ConfigError} (never
+ * echoing the key) when the key is missing.
+ */
+export function loadConfig(env = process.env) {
+    const apiKey = env.SPECSHIELD_API_KEY?.trim();
+    if (!apiKey) {
+        throw new ConfigError("SPECSHIELD_API_KEY is required. Set it to a SpecShield API key from " +
+            "https://specshield.io/account (store it as a secret; never commit it).");
+    }
+    const apiUrl = (env.SPECSHIELD_API_URL?.trim() || DEFAULT_API_URL).replace(/\/+$/, "");
+    const timeoutMs = parsePositiveInt(env.SPECSHIELD_TIMEOUT_MS, DEFAULT_TIMEOUT_MS);
+    const rawLevel = env.SPECSHIELD_LOG_LEVEL?.trim().toLowerCase();
+    const logLevel = LOG_LEVELS.includes(rawLevel ?? "")
+        ? rawLevel
+        : "info";
+    return { apiUrl, apiKey, timeoutMs, logLevel };
+}
+function parsePositiveInt(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW1C,MAAM,eAAe,GAAG,2BAA2B,CAAC;AACpD,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAClC,MAAM,UAAU,GAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,MAAM,GAAG,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC;IAC9C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,WAAW,CACnB,sEAAsE;YACpE,wEAAwE,CAC3E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,IAAI,eAAe,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAEvF,MAAM,SAAS,GAAG,gBAAgB,CAAC,GAAG,CAAC,qBAAqB,EAAE,kBAAkB,CAAC,CAAC;IAElF,MAAM,QAAQ,GAAG,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAChE,MAAM,QAAQ,GAAc,UAAgC,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC;QACnF,CAAC,CAAE,QAAqB;QACxB,CAAC,CAAC,MAAM,CAAC;IAEX,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;AACjD,CAAC;AAED,SAAS,gBAAgB,CAAC,GAAuB,EAAE,QAAgB;IACjE,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpD,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Machine-readable error codes surfaced to the MCP client. Deliberately coarse
+ * and free of any spec content or credentials.
+ */
+export type ErrorCode = "config_error" | "validation_error" | "auth_error" | "rate_limited" | "backend_error" | "timeout" | "network_error" | "not_available";
+/**
+ * The only error type this server throws outward. Its message is safe to show
+ * an end user: it never contains spec content, API keys, JWTs, or request bodies.
+ */
+export declare class SpecShieldError extends Error {
+    readonly code: ErrorCode;
+    readonly status?: number | undefined;
+    constructor(code: ErrorCode, message: string, status?: number | undefined);
+    /** Structured, safe payload for a tool's `isError` result. */
+    toPayload(): {
+        error: {
+            code: ErrorCode;
+            message: string;
+            status?: number;
+        };
+    };
+}
+export declare class ConfigError extends SpecShieldError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,24 @@
+/**
+ * The only error type this server throws outward. Its message is safe to show
+ * an end user: it never contains spec content, API keys, JWTs, or request bodies.
+ */
+export class SpecShieldError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "SpecShieldError";
+    }
+    /** Structured, safe payload for a tool's `isError` result. */
+    toPayload() {
+        return { error: { code: this.code, message: this.message, status: this.status } };
+    }
+}
+export class ConfigError extends SpecShieldError {
+    constructor(message) {
+        super("config_error", message);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAcA;;;GAGG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAEtB;IAEA;IAHlB,YACkB,IAAe,EAC/B,OAAe,EACC,MAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJC,SAAI,GAAJ,IAAI,CAAW;QAEf,WAAM,GAAN,MAAM,CAAS;QAG/B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;IAED,8DAA8D;IAC9D,SAAS;QACP,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC;IACpF,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,eAAe;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createLogger } from "./logger.js";
+import { SpecShieldApiClient } from "./client.js";
+import { createServer } from "./server.js";
+import { SpecShieldError } from "./errors.js";
+async function main() {
+    const config = loadConfig();
+    const logger = createLogger(config.logLevel);
+    const client = new SpecShieldApiClient(config, logger);
+    const server = createServer({ client, logger });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // apiUrl is safe to log; the API key is never logged.
+    logger.info("specshield-mcp-server started (stdio)", { apiUrl: config.apiUrl });
+}
+main().catch((err) => {
+    const message = err instanceof SpecShieldError ? err.message : "Failed to start specshield-mcp-server.";
+    process.stderr.write(`[specshield-mcp] fatal: ${message}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAEhD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,sDAAsD;IACtD,MAAM,CAAC,IAAI,CAAC,uCAAuC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAClF,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,MAAM,OAAO,GACX,GAAG,YAAY,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,wCAAwC,CAAC;IAC1F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,2BAA2B,OAAO,IAAI,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/logger.d.ts

@@ -0,0 +1,14 @@
+import type { LogLevel } from "./config.js";
+export interface Logger {
+    debug(msg: string, meta?: Record<string, unknown>): void;
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+/**
+ * Minimal level-gated logger. Writes to **stderr** only — stdout is reserved for
+ * the MCP JSON-RPC stream. Callers must never pass spec content, API keys, JWTs,
+ * or request bodies as `msg`/`meta`; this logger does not attempt to parse specs
+ * out of arbitrary strings, so the discipline lives at the call sites.
+ */
+export declare function createLogger(level?: LogLevel): Logger;

package/dist/logger.js

@@ -0,0 +1,25 @@
+const RANK = { debug: 10, info: 20, warn: 30, error: 40 };
+/**
+ * Minimal level-gated logger. Writes to **stderr** only — stdout is reserved for
+ * the MCP JSON-RPC stream. Callers must never pass spec content, API keys, JWTs,
+ * or request bodies as `msg`/`meta`; this logger does not attempt to parse specs
+ * out of arbitrary strings, so the discipline lives at the call sites.
+ */
+export function createLogger(level = "info") {
+    const threshold = RANK[level];
+    const emit = (lvl, msg, meta) => {
+        if (RANK[lvl] < threshold)
+            return;
+        const line = meta
+            ? `[specshield-mcp] ${lvl}: ${msg} ${JSON.stringify(meta)}`
+            : `[specshield-mcp] ${lvl}: ${msg}`;
+        process.stderr.write(line + "\n");
+    };
+    return {
+        debug: (m, meta) => emit("debug", m, meta),
+        info: (m, meta) => emit("info", m, meta),
+        warn: (m, meta) => emit("warn", m, meta),
+        error: (m, meta) => emit("error", m, meta),
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAEA,MAAM,IAAI,GAA6B,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;AASpF;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,QAAkB,MAAM;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,CAAC,GAAa,EAAE,GAAW,EAAE,IAA8B,EAAE,EAAE;QAC1E,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,SAAS;YAAE,OAAO;QAClC,MAAM,IAAI,GAAG,IAAI;YACf,CAAC,CAAC,oBAAoB,GAAG,KAAK,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE;YAC3D,CAAC,CAAC,oBAAoB,GAAG,KAAK,GAAG,EAAE,CAAC;QACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACpC,CAAC,CAAC;IACF,OAAO;QACL,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC;QAC1C,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC;QACxC,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC;QACxC,KAAK,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC;KAC3C,CAAC;AACJ,CAAC"}

package/dist/resources/help.d.ts

@@ -0,0 +1 @@
+export declare const HELP_TEXT = "# SpecShield MCP tools\n\nSpecShield answers one question inside your AI coding agent: **\"Is it safe to ship\nthis API change to my consumers?\"** All tools are **read-only** \u2014 they analyze API\ncontract compatibility and never modify your code.\n\n## Tools (in order)\n\n1. **is_change_safe** \u2014 THE DEPLOY GATE. Given a base and target spec, returns\n   `safeToMerge`, a risk level, and the exact blocking reasons. Use this before\n   merging or releasing an API change.\n2. **explain_breaking_changes** \u2014 plain-language explanation of what breaks, the\n   developer/consumer impact, and suggested migration.\n3. **generate_migration_guide** \u2014 a migration guide (markdown) + safe rollout steps.\n4. **generate_release_notes** \u2014 release notes for developer/customer/internal audiences.\n5. **compare_specs** \u2014 the raw diff (breaking / additions / modifications / warnings)\n   with a risk score. Prefer is_change_safe for a go/no-go decision.\n\nEach tool accepts specs as inline content (`baseSpecContent`/`targetSpecContent`)\nor file paths (`baseSpecPath`/`targetSpecPath`).\n\n## Planned\n\n- **run_governance_review** \u2014 deterministic API governance ruleset. Ships once the\n  backend `/api/governance` endpoint lands (a later release).\n\n## Privacy\n\nRequires a SpecShield API key (`SPECSHIELD_API_KEY`). Specs are sent to your\nconfigured SpecShield backend for analysis. This server never logs spec content or\nAPI keys.\n";

package/dist/resources/help.js

@@ -0,0 +1,33 @@
+export const HELP_TEXT = `# SpecShield MCP tools
+
+SpecShield answers one question inside your AI coding agent: **"Is it safe to ship
+this API change to my consumers?"** All tools are **read-only** — they analyze API
+contract compatibility and never modify your code.
+
+## Tools (in order)
+
+1. **is_change_safe** — THE DEPLOY GATE. Given a base and target spec, returns
+   \`safeToMerge\`, a risk level, and the exact blocking reasons. Use this before
+   merging or releasing an API change.
+2. **explain_breaking_changes** — plain-language explanation of what breaks, the
+   developer/consumer impact, and suggested migration.
+3. **generate_migration_guide** — a migration guide (markdown) + safe rollout steps.
+4. **generate_release_notes** — release notes for developer/customer/internal audiences.
+5. **compare_specs** — the raw diff (breaking / additions / modifications / warnings)
+   with a risk score. Prefer is_change_safe for a go/no-go decision.
+
+Each tool accepts specs as inline content (\`baseSpecContent\`/\`targetSpecContent\`)
+or file paths (\`baseSpecPath\`/\`targetSpecPath\`).
+
+## Planned
+
+- **run_governance_review** — deterministic API governance ruleset. Ships once the
+  backend \`/api/governance\` endpoint lands (a later release).
+
+## Privacy
+
+Requires a SpecShield API key (\`SPECSHIELD_API_KEY\`). Specs are sent to your
+configured SpecShield backend for analysis. This server never logs spec content or
+API keys.
+`;
+//# sourceMappingURL=help.js.map

package/dist/resources/help.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.js","sourceRoot":"","sources":["../../src/resources/help.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BxB,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { SpecShieldApiClient } from "./client.js";
+import type { Logger } from "./logger.js";
+export declare const SERVER_NAME = "specshield-mcp-server";
+export declare const SERVER_VERSION = "0.1.0";
+export interface ServerDeps {
+    client: SpecShieldApiClient;
+    logger: Logger;
+}
+/**
+ * Builds the MCP server with all tools registered in pitch order and the single
+ * read-only help resource. `deps.client` is injectable so tests can mock the
+ * backend without any network I/O.
+ */
+export declare function createServer(deps: ServerDeps): McpServer;

package/dist/server.js

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TOOLS } from "./tools/index.js";
+import { HELP_TEXT } from "./resources/help.js";
+export const SERVER_NAME = "specshield-mcp-server";
+export const SERVER_VERSION = "0.1.0";
+/**
+ * Builds the MCP server with all tools registered in pitch order and the single
+ * read-only help resource. `deps.client` is injectable so tests can mock the
+ * backend without any network I/O.
+ */
+export function createServer(deps) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    const ctx = { client: deps.client, logger: deps.logger };
+    for (const tool of TOOLS) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+        }, (args) => tool.handler(args, ctx));
+    }
+    server.registerResource("help", "specshield://help/tools", {
+        title: "SpecShield MCP tools",
+        description: "How to use the SpecShield deploy-gate tools.",
+        mimeType: "text/markdown",
+    }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "text/markdown", text: HELP_TEXT }],
+    }));
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEhD,MAAM,CAAC,MAAM,WAAW,GAAG,uBAAuB,CAAC;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAOtC;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,IAAgB;IAC3C,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAgB,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAEtE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE;SACjF,EACD,CAAC,IAA6B,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAC3D,CAAC;IACJ,CAAC;IAED,MAAM,CAAC,gBAAgB,CACrB,MAAM,EACN,yBAAyB,EACzB;QACE,KAAK,EAAE,sBAAsB;QAC7B,WAAW,EAAE,8CAA8C;QAC3D,QAAQ,EAAE,eAAe;KAC1B,EACD,KAAK,EAAE,GAAQ,EAAE,EAAE,CAAC,CAAC;QACnB,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KAC1E,CAAC,CACH,CAAC;IAEF,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/specResolver.d.ts

@@ -0,0 +1,11 @@
+export interface SpecSource {
+    content?: string;
+    path?: string;
+}
+/**
+ * Resolves a spec to its text content from either inline content or a file path.
+ * A path is only read when the user explicitly passed one through the MCP client.
+ * Error messages never include the spec content (and only a generic note about
+ * the path, not the file body).
+ */
+export declare function resolveSpec(source: SpecSource, label: string): Promise<string>;

package/dist/specResolver.js

@@ -0,0 +1,23 @@
+import { readFile } from "node:fs/promises";
+import { SpecShieldError } from "./errors.js";
+/**
+ * Resolves a spec to its text content from either inline content or a file path.
+ * A path is only read when the user explicitly passed one through the MCP client.
+ * Error messages never include the spec content (and only a generic note about
+ * the path, not the file body).
+ */
+export async function resolveSpec(source, label) {
+    if (source.content && source.content.trim().length > 0) {
+        return source.content;
+    }
+    if (source.path && source.path.trim().length > 0) {
+        try {
+            return await readFile(source.path, "utf8");
+        }
+        catch {
+            throw new SpecShieldError("validation_error", `Could not read the ${label} spec from the provided file path.`);
+        }
+    }
+    throw new SpecShieldError("validation_error", `Provide either ${label}SpecContent or ${label}SpecPath.`);
+}
+//# sourceMappingURL=specResolver.js.map

package/dist/specResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specResolver.js","sourceRoot":"","sources":["../src/specResolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAO9C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAkB,EAAE,KAAa;IACjE,IAAI,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvD,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjD,IAAI,CAAC;YACH,OAAO,MAAM,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,eAAe,CACvB,kBAAkB,EAClB,sBAAsB,KAAK,oCAAoC,CAChE,CAAC;QACJ,CAAC;IACH,CAAC;IACD,MAAM,IAAI,eAAe,CACvB,kBAAkB,EAClB,kBAAkB,KAAK,kBAAkB,KAAK,WAAW,CAC1D,CAAC;AACJ,CAAC"}

package/dist/tools/compareSpecs.d.ts

@@ -0,0 +1,6 @@
+import { type ToolDef } from "./shared.js";
+/**
+ * Table-stakes raw diff — registered LAST. The differentiated value is the
+ * deploy gate (is_change_safe); this is here for completeness.
+ */
+export declare const compareSpecs: ToolDef;

package/dist/tools/compareSpecs.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { guarded, resolveBothSpecs, specSourceShape, textResult } from "./shared.js";
+/**
+ * Table-stakes raw diff — registered LAST. The differentiated value is the
+ * deploy gate (is_change_safe); this is here for completeness.
+ */
+export const compareSpecs = {
+    name: "compare_specs",
+    title: "Compare two API specs",
+    description: "Compares two API specs and lists breaking changes, additions, modifications, and warnings " +
+        "with a risk score and compatibility summary. For a merge/deploy decision prefer " +
+        "is_change_safe. Analyzes API contract compatibility only; it does NOT modify code.",
+    inputSchema: {
+        ...specSourceShape,
+        specFormat: z.enum(["openapi", "pact"]).optional(),
+        failOnBreaking: z
+            .boolean()
+            .optional()
+            .describe("If true, the header flags when any breaking change is present."),
+    },
+    handler: guarded(async (args, ctx) => {
+        const { baseSpec, targetSpec } = await resolveBothSpecs(args);
+        const res = await ctx.client.post("/api/intelligence/compare", { baseSpec, targetSpec, specFormat: args.specFormat });
+        const breakingCount = res.breakingChanges?.length ?? 0;
+        const header = args.failOnBreaking && breakingCount > 0
+            ? `⛔ ${breakingCount} breaking change(s) (failOnBreaking) — risk ${res.risk.level}`
+            : `risk ${res.risk.level} · ${breakingCount} breaking · ${res.additions?.length ?? 0} additions`;
+        return textResult(header, res);
+    }),
+};
+//# sourceMappingURL=compareSpecs.js.map

package/dist/tools/compareSpecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compareSpecs.js","sourceRoot":"","sources":["../../src/tools/compareSpecs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAgB,MAAM,aAAa,CAAC;AAEnG;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAY;IACnC,IAAI,EAAE,eAAe;IACrB,KAAK,EAAE,uBAAuB;IAC9B,WAAW,EACT,4FAA4F;QAC5F,kFAAkF;QAClF,oFAAoF;IACtF,WAAW,EAAE;QACX,GAAG,eAAe;QAClB,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE;QAClD,cAAc,EAAE,CAAC;aACd,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,gEAAgE,CAAC;KAC9E;IACD,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACnC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC9D,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAC/B,2BAA2B,EAC3B,EAAE,QAAQ,EAAE,UAAU,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CACtD,CAAC;QACF,MAAM,aAAa,GAAG,GAAG,CAAC,eAAe,EAAE,MAAM,IAAI,CAAC,CAAC;QACvD,MAAM,MAAM,GACV,IAAI,CAAC,cAAc,IAAI,aAAa,GAAG,CAAC;YACtC,CAAC,CAAC,KAAK,aAAa,+CAA+C,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE;YACnF,CAAC,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,MAAM,aAAa,eAAe,GAAG,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC,YAAY,CAAC;QACrG,OAAO,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC,CAAC;CACH,CAAC"}

package/dist/tools/explainBreakingChanges.d.ts

@@ -0,0 +1,8 @@
+import { type ToolDef } from "./shared.js";
+/**
+ * Explains the breaking changes in plain language. Deterministic in the MVP: it
+ * sources the changes and the migration steps entirely from the backend
+ * (/compare + /migration-guide-preview) and only reshapes them — no diff or risk
+ * logic lives here. AI-enhanced explanations arrive after Phase 4.
+ */
+export declare const explainBreakingChanges: ToolDef;

package/dist/tools/explainBreakingChanges.js

@@ -0,0 +1,37 @@
+import { consumerImpact, guarded, resolveBothSpecs, specSourceShape, textResult, } from "./shared.js";
+/**
+ * Explains the breaking changes in plain language. Deterministic in the MVP: it
+ * sources the changes and the migration steps entirely from the backend
+ * (/compare + /migration-guide-preview) and only reshapes them — no diff or risk
+ * logic lives here. AI-enhanced explanations arrive after Phase 4.
+ */
+export const explainBreakingChanges = {
+    name: "explain_breaking_changes",
+    title: "Explain the breaking changes",
+    description: "Explains what breaks in an API spec change and why, with developer impact, likely consumer " +
+        "impact, and suggested migration steps. Analyzes API contract compatibility only; it does " +
+        "NOT modify code.",
+    inputSchema: { ...specSourceShape },
+    handler: guarded(async (args, ctx) => {
+        const { baseSpec, targetSpec } = await resolveBothSpecs(args);
+        const cmp = await ctx.client.post("/api/intelligence/compare", { baseSpec, targetSpec });
+        const migration = await ctx.client.post("/api/intelligence/migration-guide-preview", { baseSpec, targetSpec, language: "generic" });
+        const breaking = cmp.breakingChanges ?? [];
+        const result = {
+            explanation: breaking.length > 0
+                ? `${breaking.length} breaking change(s) detected between the two specs.`
+                : "No breaking changes detected.",
+            breakingChanges: breaking.map((c) => ({
+                change: c.type,
+                where: `${(c.method ?? "").toUpperCase()} ${c.path ?? ""}`.trim(),
+                detail: c.description,
+            })),
+            developerImpact: cmp.risk.summary,
+            likelyConsumerImpact: consumerImpact(cmp.risk.level),
+            suggestedMigration: migration.steps,
+        };
+        const header = breaking.length > 0 ? `⛔ ${breaking.length} breaking change(s)` : "✅ No breaking changes";
+        return textResult(header, result);
+    }),
+};
+//# sourceMappingURL=explainBreakingChanges.js.map

package/dist/tools/explainBreakingChanges.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"explainBreakingChanges.js","sourceRoot":"","sources":["../../src/tools/explainBreakingChanges.ts"],"names":[],"mappings":"AACA,OAAO,EACL,cAAc,EACd,OAAO,EACP,gBAAgB,EAChB,eAAe,EACf,UAAU,GAEX,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAY;IAC7C,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,8BAA8B;IACrC,WAAW,EACT,6FAA6F;QAC7F,2FAA2F;QAC3F,kBAAkB;IACpB,WAAW,EAAE,EAAE,GAAG,eAAe,EAAE;IACnC,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACnC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC9D,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAC/B,2BAA2B,EAC3B,EAAE,QAAQ,EAAE,UAAU,EAAE,CACzB,CAAC;QACF,MAAM,SAAS,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CACrC,2CAA2C,EAC3C,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,SAAS,EAAE,CAC9C,CAAC;QAEF,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,IAAI,EAAE,CAAC;QAC3C,MAAM,MAAM,GAAG;YACb,WAAW,EACT,QAAQ,CAAC,MAAM,GAAG,CAAC;gBACjB,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,qDAAqD;gBACzE,CAAC,CAAC,+BAA+B;YACrC,eAAe,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACpC,MAAM,EAAE,CAAC,CAAC,IAAI;gBACd,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE;gBACjE,MAAM,EAAE,CAAC,CAAC,WAAW;aACtB,CAAC,CAAC;YACH,eAAe,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO;YACjC,oBAAoB,EAAE,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC;YACpD,kBAAkB,EAAE,SAAS,CAAC,KAAK;SACpC,CAAC;QACF,MAAM,MAAM,GACV,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,MAAM,qBAAqB,CAAC,CAAC,CAAC,uBAAuB,CAAC;QAC5F,OAAO,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC;CACH,CAAC"}

package/dist/tools/generateMigrationGuide.d.ts

@@ -0,0 +1,6 @@
+import { type ToolDef } from "./shared.js";
+/**
+ * Deterministic migration guide, sourced entirely from the backend
+ * (/migration-guide-preview). No migration logic lives here.
+ */
+export declare const generateMigrationGuide: ToolDef;

package/dist/tools/generateMigrationGuide.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { guarded, markdownResult, resolveBothSpecs, specSourceShape } from "./shared.js";
+/**
+ * Deterministic migration guide, sourced entirely from the backend
+ * (/migration-guide-preview). No migration logic lives here.
+ */
+export const generateMigrationGuide = {
+    name: "generate_migration_guide",
+    title: "Generate a migration guide",
+    description: "Generates a migration guide (markdown) and safe rollout steps for the breaking changes in " +
+        "an API spec change. Analyzes API contract compatibility only; it does NOT modify code.",
+    inputSchema: {
+        ...specSourceShape,
+        language: z.enum(["java", "node", "python", "go", "curl", "generic"]).optional(),
+    },
+    handler: guarded(async (args, ctx) => {
+        const { baseSpec, targetSpec } = await resolveBothSpecs(args);
+        const advice = await ctx.client.post("/api/intelligence/migration-guide-preview", { baseSpec, targetSpec, language: args.language ?? "generic" });
+        const lines = [
+            `# Migration guide (${advice.language})`,
+            "",
+            advice.summary,
+            "",
+            ...(advice.steps.length > 0
+                ? ["## Steps", ...advice.steps.map((s, i) => `${i + 1}. ${s}`)]
+                : ["_No breaking changes — no migration required._"]),
+            "",
+            "## Safe rollout",
+            "1. Ship the change behind a new API version where possible.",
+            "2. Announce the change and give consumers a migration window.",
+            "3. Monitor error rates on affected endpoints after release.",
+        ];
+        return markdownResult(lines.join("\n"));
+    }),
+};
+//# sourceMappingURL=generateMigrationGuide.js.map

package/dist/tools/generateMigrationGuide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateMigrationGuide.js","sourceRoot":"","sources":["../../src/tools/generateMigrationGuide.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAgB,MAAM,aAAa,CAAC;AAEvG;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAY;IAC7C,IAAI,EAAE,0BAA0B;IAChC,KAAK,EAAE,4BAA4B;IACnC,WAAW,EACT,4FAA4F;QAC5F,wFAAwF;IAC1F,WAAW,EAAE;QACX,GAAG,eAAe;QAClB,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE;KACjF;IACD,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACnC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAClC,2CAA2C,EAC3C,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,SAAS,EAAE,CAC/D,CAAC;QAEF,MAAM,KAAK,GAAG;YACZ,sBAAsB,MAAM,CAAC,QAAQ,GAAG;YACxC,EAAE;YACF,MAAM,CAAC,OAAO;YACd,EAAE;YACF,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;gBACzB,CAAC,CAAC,CAAC,UAAU,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;gBAC/D,CAAC,CAAC,CAAC,gDAAgD,CAAC,CAAC;YACvD,EAAE;YACF,iBAAiB;YACjB,6DAA6D;YAC7D,+DAA+D;YAC/D,6DAA6D;SAC9D,CAAC;QACF,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1C,CAAC,CAAC;CACH,CAAC"}

package/dist/tools/generateReleaseNotes.d.ts

@@ -0,0 +1,5 @@
+import { type ToolDef } from "./shared.js";
+/**
+ * Deterministic release notes, sourced from the backend (/release-notes-preview).
+ */
+export declare const generateReleaseNotes: ToolDef;

package/dist/tools/generateReleaseNotes.js

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { guarded, markdownResult, resolveBothSpecs, specSourceShape } from "./shared.js";
+/**
+ * Deterministic release notes, sourced from the backend (/release-notes-preview).
+ */
+export const generateReleaseNotes = {
+    name: "generate_release_notes",
+    title: "Generate release notes",
+    description: "Generates release notes (markdown) for an API spec change, grouped into breaking changes, " +
+        "additions, and other changes, tailored to an audience. Analyzes API contract compatibility " +
+        "only; it does NOT modify code.",
+    inputSchema: {
+        ...specSourceShape,
+        audience: z.enum(["developer", "customer", "internal"]).optional(),
+    },
+    handler: guarded(async (args, ctx) => {
+        const { baseSpec, targetSpec } = await resolveBothSpecs(args);
+        const notes = await ctx.client.post("/api/intelligence/release-notes-preview", { baseSpec, targetSpec, audience: args.audience ?? "developer" });
+        return markdownResult(notes.markdown);
+    }),
+};
+//# sourceMappingURL=generateReleaseNotes.js.map

package/dist/tools/generateReleaseNotes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateReleaseNotes.js","sourceRoot":"","sources":["../../src/tools/generateReleaseNotes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,eAAe,EAAgB,MAAM,aAAa,CAAC;AAEvG;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAY;IAC3C,IAAI,EAAE,wBAAwB;IAC9B,KAAK,EAAE,wBAAwB;IAC/B,WAAW,EACT,4FAA4F;QAC5F,6FAA6F;QAC7F,gCAAgC;IAClC,WAAW,EAAE;QACX,GAAG,eAAe;QAClB,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE;KACnE;IACD,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACnC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CACjC,yCAAyC,EACzC,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,WAAW,EAAE,CACjE,CAAC;QACF,OAAO,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC,CAAC;CACH,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,10 @@
+import type { ToolDef } from "./shared.js";
+/**
+ * Registration order IS the pitch: the differentiated deploy gate
+ * (is_change_safe) is first; the table-stakes raw diff (compare_specs) is last.
+ *
+ * `run_governance_review` is intentionally NOT registered in the MVP: there is
+ * no backend governance endpoint yet (it ships with /api/governance in Phase 4),
+ * and every registered tool must call the backend rather than fabricate results.
+ */
+export declare const TOOLS: ToolDef[];

package/dist/tools/index.js

@@ -0,0 +1,21 @@
+import { isChangeSafe } from "./isChangeSafe.js";
+import { explainBreakingChanges } from "./explainBreakingChanges.js";
+import { generateMigrationGuide } from "./generateMigrationGuide.js";
+import { generateReleaseNotes } from "./generateReleaseNotes.js";
+import { compareSpecs } from "./compareSpecs.js";
+/**
+ * Registration order IS the pitch: the differentiated deploy gate
+ * (is_change_safe) is first; the table-stakes raw diff (compare_specs) is last.
+ *
+ * `run_governance_review` is intentionally NOT registered in the MVP: there is
+ * no backend governance endpoint yet (it ships with /api/governance in Phase 4),
+ * and every registered tool must call the backend rather than fabricate results.
+ */
+export const TOOLS = [
+    isChangeSafe,
+    explainBreakingChanges,
+    generateMigrationGuide,
+    generateReleaseNotes,
+    compareSpecs,
+];
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAGjD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAc;IAC9B,YAAY;IACZ,sBAAsB;IACtB,sBAAsB;IACtB,oBAAoB;IACpB,YAAY;CACb,CAAC"}

package/dist/tools/isChangeSafe.d.ts

@@ -0,0 +1,5 @@
+import { type ToolDef } from "./shared.js";
+/**
+ * THE HERO TOOL — the deploy gate. Registered first.
+ */
+export declare const isChangeSafe: ToolDef;

package/dist/tools/isChangeSafe.js

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { guarded, resolveBothSpecs, specSourceShape, textResult } from "./shared.js";
+/**
+ * THE HERO TOOL — the deploy gate. Registered first.
+ */
+export const isChangeSafe = {
+    name: "is_change_safe",
+    title: "Is this API change safe to ship?",
+    description: "THE DEPLOY GATE. Analyzes whether an API spec change is safe to merge/deploy — will it " +
+        "break existing consumers? Returns a safeToMerge verdict, a risk level, the exact blocking " +
+        "reasons, and a recommended action. Use this before merging or releasing an API change to " +
+        "catch breaking changes before they reach your consumers. Analyzes API contract " +
+        "compatibility only; it does NOT modify code.",
+    inputSchema: {
+        ...specSourceShape,
+        specFormat: z.enum(["openapi", "pact"]).optional(),
+        environment: z
+            .string()
+            .optional()
+            .describe("Optional target environment, e.g. staging or production."),
+    },
+    handler: guarded(async (args, ctx) => {
+        const { baseSpec, targetSpec } = await resolveBothSpecs(args);
+        const res = await ctx.client.post("/api/intelligence/change-safety", { baseSpec, targetSpec, environment: args.environment });
+        const header = res.safeToMerge
+            ? "✅ SAFE TO MERGE"
+            : `⛔ NOT SAFE TO MERGE — risk ${res.riskLevel}`;
+        return textResult(header, res);
+    }),
+};
+//# sourceMappingURL=isChangeSafe.js.map

package/dist/tools/isChangeSafe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isChangeSafe.js","sourceRoot":"","sources":["../../src/tools/isChangeSafe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,EAAgB,MAAM,aAAa,CAAC;AAEnG;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAY;IACnC,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,kCAAkC;IACzC,WAAW,EACT,yFAAyF;QACzF,4FAA4F;QAC5F,2FAA2F;QAC3F,iFAAiF;QACjF,8CAA8C;IAChD,WAAW,EAAE;QACX,GAAG,eAAe;QAClB,UAAU,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE;QAClD,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,0DAA0D,CAAC;KACxE;IACD,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACnC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,MAAM,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC9D,MAAM,GAAG,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAC/B,iCAAiC,EACjC,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CACxD,CAAC;QACF,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW;YAC5B,CAAC,CAAC,iBAAiB;YACnB,CAAC,CAAC,8BAA8B,GAAG,CAAC,SAAS,EAAE,CAAC;QAClD,OAAO,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjC,CAAC,CAAC;CACH,CAAC"}

package/dist/tools/shared.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { SpecShieldApiClient } from "../client.js";
+import type { Logger } from "../logger.js";
+import type { RiskLevel } from "../backendTypes.js";
+export interface ToolContext {
+    client: SpecShieldApiClient;
+    logger: Logger;
+}
+export interface ToolDef {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<CallToolResult>;
+}
+/** base/target spec inputs shared by every tool (inline content or a file path). */
+export declare const specSourceShape: {
+    baseSpecContent: z.ZodOptional<z.ZodString>;
+    baseSpecPath: z.ZodOptional<z.ZodString>;
+    targetSpecContent: z.ZodOptional<z.ZodString>;
+    targetSpecPath: z.ZodOptional<z.ZodString>;
+};
+export declare function resolveBothSpecs(args: Record<string, unknown>): Promise<{
+    baseSpec: string;
+    targetSpec: string;
+}>;
+export declare function textResult(header: string, data: unknown): CallToolResult;
+export declare function markdownResult(markdown: string): CallToolResult;
+export declare function errorResult(err: unknown): CallToolResult;
+/** Wrap a handler so any error becomes a safe, machine-readable isError result. */
+export declare function guarded(fn: (args: Record<string, unknown>, ctx: ToolContext) => Promise<CallToolResult>): ToolDef["handler"];
+export declare function consumerImpact(level: RiskLevel): string;

package/dist/tools/shared.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { SpecShieldError } from "../errors.js";
+import { resolveSpec } from "../specResolver.js";
+/** base/target spec inputs shared by every tool (inline content or a file path). */
+export const specSourceShape = {
+    baseSpecContent: z.string().optional().describe("Inline base (old) spec content."),
+    baseSpecPath: z.string().optional().describe("Path to the base (old) spec file."),
+    targetSpecContent: z.string().optional().describe("Inline target (new) spec content."),
+    targetSpecPath: z.string().optional().describe("Path to the target (new) spec file."),
+};
+export async function resolveBothSpecs(args) {
+    const baseSpec = await resolveSpec({ content: args.baseSpecContent, path: args.baseSpecPath }, "base");
+    const targetSpec = await resolveSpec({ content: args.targetSpecContent, path: args.targetSpecPath }, "target");
+    return { baseSpec, targetSpec };
+}
+export function textResult(header, data) {
+    const body = JSON.stringify(data, null, 2);
+    return { content: [{ type: "text", text: header ? `${header}\n\n${body}` : body }] };
+}
+export function markdownResult(markdown) {
+    return { content: [{ type: "text", text: markdown }] };
+}
+export function errorResult(err) {
+    const e = err instanceof SpecShieldError
+        ? err
+        : new SpecShieldError("backend_error", "Unexpected error while contacting SpecShield.");
+    return { isError: true, content: [{ type: "text", text: JSON.stringify(e.toPayload(), null, 2) }] };
+}
+/** Wrap a handler so any error becomes a safe, machine-readable isError result. */
+export function guarded(fn) {
+    return async (args, ctx) => {
+        try {
+            return await fn(args, ctx);
+        }
+        catch (err) {
+            // Log the code only — never the message body, spec, or key.
+            ctx.logger.warn("tool call failed", {
+                code: err instanceof SpecShieldError ? err.code : "unknown",
+            });
+            return errorResult(err);
+        }
+    };
+}
+export function consumerImpact(level) {
+    switch (level) {
+        case "CRITICAL":
+            return "Existing consumers will break until they are updated.";
+        case "HIGH":
+            return "Existing consumers are likely to break; coordinate an upgrade.";
+        case "MEDIUM":
+            return "No breaking changes, but consumers may see behavior differences.";
+        case "LOW":
+        default:
+            return "Additive/non-breaking; existing consumers are unaffected.";
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/tools/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/tools/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAgBjD,oFAAoF;AACpF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;IAClF,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IACjF,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;IACtF,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;CACtF,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAA6B;IAE7B,MAAM,QAAQ,GAAG,MAAM,WAAW,CAChC,EAAE,OAAO,EAAE,IAAI,CAAC,eAAyB,EAAE,IAAI,EAAE,IAAI,CAAC,YAAsB,EAAE,EAC9E,MAAM,CACP,CAAC;IACF,MAAM,UAAU,GAAG,MAAM,WAAW,CAClC,EAAE,OAAO,EAAE,IAAI,CAAC,iBAA2B,EAAE,IAAI,EAAE,IAAI,CAAC,cAAwB,EAAE,EAClF,QAAQ,CACT,CAAC;IACF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,IAAa;IACtD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3C,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgB;IAC7C,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,CAAC,GACL,GAAG,YAAY,eAAe;QAC5B,CAAC,CAAC,GAAG;QACL,CAAC,CAAC,IAAI,eAAe,CAAC,eAAe,EAAE,+CAA+C,CAAC,CAAC;IAC5F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACtG,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,OAAO,CACrB,EAAgF;IAEhF,OAAO,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;QACzB,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,4DAA4D;YAC5D,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE;gBAClC,IAAI,EAAE,GAAG,YAAY,eAAe,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;aAC5D,CAAC,CAAC;YACH,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,UAAU;YACb,OAAO,uDAAuD,CAAC;QACjE,KAAK,MAAM;YACT,OAAO,gEAAgE,CAAC;QAC1E,KAAK,QAAQ;YACX,OAAO,kEAAkE,CAAC;QAC5E,KAAK,KAAK,CAAC;QACX;YACE,OAAO,2DAA2D,CAAC;IACvE,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "specshield-mcp-server",
+  "version": "0.1.0",
+  "description": "SpecShield MCP server — the API-change deploy gate for AI coding agents. Ask 'is it safe to ship this API change to my consumers?' inside Claude, Cursor, and other MCP clients. Analyze-only; it never modifies code.",
+  "license": "MIT",
+  "author": "SpecShield Software Private Limited",
+  "homepage": "https://specshield.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/specshield26/specshield-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/specshield26/specshield-mcp-server/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "specshield-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "smoke": "node scripts/smoke.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "openapi",
+    "api",
+    "breaking-changes",
+    "contract-compatibility-testing",
+    "can-i-deploy",
+    "deploy-gate",
+    "specshield",
+    "claude",
+    "cursor"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.7.0",
+    "@types/node": "^20.14.0",
+    "eslint": "^9.7.0",
+    "prettier": "^3.3.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.0.0"
+  }
+}