@kryptosai/mcp-observatory 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KryptosAI
+
+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,228 @@
+# MCP Observatory
+
+[![CI](https://github.com/KryptosAI/mcp-observatory/actions/workflows/ci.yml/badge.svg)](https://github.com/KryptosAI/mcp-observatory/actions/workflows/ci.yml)
+[![Real Server Matrix](https://github.com/KryptosAI/mcp-observatory/actions/workflows/real-server-matrix.yml/badge.svg)](https://github.com/KryptosAI/mcp-observatory/actions/workflows/real-server-matrix.yml)
+[![Latest Release](https://img.shields.io/github/v/release/KryptosAI/mcp-observatory?display_name=tag)](https://github.com/KryptosAI/mcp-observatory/releases)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+[![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-339933)](./package.json)
+
+Regression evidence for Node/local-process stdio MCP targets.
+
+Current status: GitHub-release-installable, tested against 7 real servers, and still at zero external adoption proof until that changes. The public package identity is `@kryptosai/mcp-observatory`; npm publishing is wired into the release flow but needs credentials before it becomes a live install path.
+
+> Maintainer note, March 19, 2026: this repo exists because real MCP servers drift in ways conformance does not explain. Some servers pass cleanly with very different capability shapes. Others time out or close early when treated as plain stdio targets. Both outcomes are useful evidence.
+
+## Install
+
+```bash
+# npm (when published)
+npx @kryptosai/mcp-observatory
+
+# or from GitHub release tarball
+npx --yes https://github.com/KryptosAI/mcp-observatory/releases/download/v0.3.0/kryptosai-mcp-observatory-0.3.0.tgz
+```
+
+Running with no arguments auto-discovers your MCP servers and checks them all.
+
+Create one tiny target config in any directory:
+
+```json
+{
+  "targetId": "filesystem-cli-proof",
+  "adapter": "local-process",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+  "timeoutMs": 15000,
+  "metadata": {
+    "package": "@modelcontextprotocol/server-filesystem",
+    "purpose": "standalone-cli-proof"
+  }
+}
+```
+
+Run it:
+
+```bash
+npx --yes https://github.com/KryptosAI/mcp-observatory/releases/download/v0.2.0/kryptosai-mcp-observatory-0.2.0.tgz run --target ./filesystem-target.json
+```
+
+## Known-Good Matrix
+
+Passing matrix refreshed on 2026-03-19:
+
+| Target | Package | Tools | Prompts | Resources | Why it matters |
+| --- | --- | --- | --- | --- | --- |
+| [filesystem-server.json](./examples/targets/filesystem-server.json) | `@modelcontextprotocol/server-filesystem` | pass | unsupported | unsupported | baseline proof that unsupported is not failure |
+| [everything-server.json](./examples/targets/everything-server.json) | `@modelcontextprotocol/server-everything` | pass | pass | pass | broad official reference target |
+| [ref-tools-server.json](./examples/targets/ref-tools-server.json) | `ref-tools-mcp` | pass | pass | unsupported | third-party prompts-capable proof |
+| [context7-server.json](./examples/targets/context7-server.json) | `@upstash/context7-mcp` | pass | unsupported | unsupported | zero-config third-party tools proof |
+| [puppeteer-server.json](./examples/targets/puppeteer-server.json) | `puppeteer-mcp-server` | pass | unsupported | pass | browser-oriented resources case with an optional-endpoint caveat |
+| [promptopia-server.json](./examples/targets/promptopia-server.json) | `promptopia-mcp` | pass | pass | unsupported | second third-party prompts-capable server |
+| [opentofu-server.json](./examples/targets/opentofu-server.json) | `@opentofu/opentofu-mcp-server` | pass | unsupported | pass | second third-party resources-capable server |
+
+To refresh the matrix locally:
+
+```bash
+npm run integration:real
+```
+
+## Working Surface
+
+- `run`: execute checks against one target and persist a run artifact
+- `diff`: compare two runs and classify regressions, recoveries, and schema drift
+- `report`: turn a saved run artifact into readable terminal, JSON, or Markdown output
+- `scan`: auto-discover MCP servers from local config files and check them all (default command)
+- `check`: run a single capability check (tools, prompts, resources, or tools-invoke)
+
+## Scan
+
+Auto-discover MCP server configs from Claude Code, Claude Desktop, and project-level config files, then run checks against every discovered server. This is the default command — running `mcp-observatory` with no arguments runs scan:
+
+```bash
+mcp-observatory
+mcp-observatory scan
+mcp-observatory scan --config ~/.claude.json
+mcp-observatory scan --invoke-tools
+```
+
+Scanned locations (in order):
+- `~/.claude.json` (Claude Code)
+- `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude Desktop, macOS)
+- `%APPDATA%/Claude/claude_desktop_config.json` (Claude Desktop, Windows)
+- `.claude.json` (current directory)
+- `.mcp.json` (current directory)
+
+## Check
+
+Run a single capability check for faster iteration:
+
+```bash
+mcp-observatory check tools --target ./my-server.json
+mcp-observatory check prompts --target ./my-server.json
+mcp-observatory check resources --target ./my-server.json
+mcp-observatory check tools-invoke --target ./my-server.json
+```
+
+## Tool Invocation
+
+Go beyond listing — actually call tools and verify they execute. Only safe tools are invoked: those with no required parameters or with `readOnlyHint` annotation. Arguments are auto-generated from the tool's JSON Schema.
+
+```bash
+mcp-observatory scan --invoke-tools
+mcp-observatory run --target ./my-server.json --invoke-tools
+mcp-observatory check tools-invoke --target ./my-server.json
+```
+
+## Schema Drift
+
+When diffing two runs, schema changes are detected automatically. Added/removed required fields, property changes, and type changes are surfaced alongside status regressions:
+
+```bash
+mcp-observatory diff --base run-a.json --head run-b.json
+```
+
+Example output:
+```
+Schema Drift:
+- search (tools): added required field 'limit', changed 'query' type from 'number' to 'string'
+- old-tool (tools): removed
+```
+
+## Watch
+
+Re-run checks on an interval and output only when something changes:
+
+```bash
+mcp-observatory run --target ./my-server.json --watch
+mcp-observatory run --target ./my-server.json --watch --interval 60
+```
+
+Press Ctrl+C to stop.
+
+## HTTP / SSE Targets
+
+In addition to local-process stdio, you can check remote MCP servers over HTTP (Streamable HTTP and SSE):
+
+```json
+{
+  "targetId": "my-remote-server",
+  "adapter": "http",
+  "url": "http://localhost:3000/mcp",
+  "authToken": "optional-bearer-token",
+  "timeoutMs": 15000
+}
+```
+
+```bash
+mcp-observatory run --target ./remote-target.json
+mcp-observatory run --target ./remote-target.json --invoke-tools
+```
+
+## HTML Reports
+
+Generate a self-contained HTML report from any run or diff artifact:
+
+```bash
+mcp-observatory report --run ./run-artifact.json --format html --output report.html
+mcp-observatory diff --base run-a.json --head run-b.json --format html --output diff.html
+```
+
+Open the file in any browser — no server required, shareable via Slack/email/GitHub comments.
+
+## Do Not Use This If...
+
+- you need deep semantic correctness validation
+- you need every MCP package on npm to work out of the box
+
+If those are the requirements, this repo is the wrong tool.
+
+## Repo-Local Validation
+
+If you do want the repo-local path, use the fixture flow:
+
+```bash
+npm install
+npm run cli -- run --target tests/fixtures/sample-target-config.json
+npm run cli -- diff --base tests/fixtures/sample-run-a.json --head tests/fixtures/sample-run-b.json
+npm run cli -- report --run tests/fixtures/sample-run-b.json --format markdown --output examples/results/sample-report.md
+```
+
+This path exists to validate the repo itself. It is not the only way to use the tool.
+
+## Artifact Contract
+
+Every artifact is versioned and intentionally boring:
+
+- `artifactType`: `run` or `diff`
+- `schemaVersion`: currently `1.0.0`
+- `gate`: `pass` or `fail`
+
+Compatibility rules:
+
+- additive changes stay within `1.x`
+- breaking artifact changes require a major schema bump
+
+Published schemas:
+
+- [schemas/run-artifact.schema.json](./schemas/run-artifact.schema.json)
+- [schemas/diff-artifact.schema.json](./schemas/diff-artifact.schema.json)
+
+Validate checked-in artifacts locally:
+
+```bash
+npm run validate:artifacts
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the contribution bar and the kinds of work likely to be declined.
+
+The fastest way to contribute something credible is to add evidence:
+
+- a real passing target with a distinct capability shape
+- a clearer report surface
+- a cleaner startup diagnosis
+
+## Known Issues
+
+See [docs/known-issues.md](./docs/known-issues.md) for the difference between `unsupported` and `failed`, plus the current list of packages that do not behave like drop-in stdio targets under the local-process harness.

package/dist/src/adapters/http.d.ts

@@ -0,0 +1,5 @@
+import type { HttpTargetConfig } from "../types.js";
+import type { AdapterSession } from "./local-process.js";
+export declare class HttpAdapter {
+    connect(target: HttpTargetConfig): Promise<AdapterSession>;
+}

package/dist/src/adapters/http.js

@@ -0,0 +1,54 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { formatConnectionFailureDiagnosis } from "../utils/failure-diagnosis.js";
+import { TOOL_VERSION } from "../version.js";
+export class HttpAdapter {
+    async connect(target) {
+        const headers = { ...(target.headers ?? {}) };
+        if (target.authToken) {
+            headers["Authorization"] = `Bearer ${target.authToken}`;
+        }
+        const client = new Client({ name: "mcp-observatory", version: TOOL_VERSION }, { capabilities: {} });
+        const stderrLines = [];
+        const url = new URL(target.url);
+        const timeoutMs = target.timeoutMs ?? 15_000;
+        // Try streamable-http first, fall back to SSE
+        let connected = false;
+        try {
+            const transport = new StreamableHTTPClientTransport(url, { requestInit: { headers } });
+            await client.connect(transport, { timeout: timeoutMs });
+            connected = true;
+        }
+        catch {
+            stderrLines.push("Streamable HTTP failed, falling back to SSE.");
+        }
+        if (!connected) {
+            try {
+                const transport = new SSEClientTransport(url, { requestInit: { headers } });
+                await client.connect(transport, { timeout: timeoutMs });
+                connected = true;
+            }
+            catch (error) {
+                const rawMessage = error instanceof Error ? error.message : String(error);
+                await client.close().catch(() => undefined);
+                const msg = formatConnectionFailureDiagnosis(target, rawMessage, stderrLines);
+                const err = new Error(msg);
+                err.name = "AdapterConnectError";
+                throw err;
+            }
+        }
+        const serverVersion = client.getServerVersion();
+        return {
+            client,
+            serverCapabilities: client.getServerCapabilities(),
+            serverName: serverVersion?.name,
+            serverVersion: serverVersion?.version,
+            stderrLines,
+            close: async () => {
+                await client.close();
+            },
+        };
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/src/adapters/http.js.map

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

package/dist/src/adapters/local-process.d.ts

@@ -0,0 +1,19 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { ServerCapabilities } from "@modelcontextprotocol/sdk/types.js";
+import type { LocalProcessTargetConfig, TargetConfig } from "../types.js";
+export interface AdapterSession {
+    client: Client;
+    serverCapabilities?: ServerCapabilities;
+    serverName?: string;
+    serverVersion?: string;
+    stderrLines: string[];
+    close(): Promise<void>;
+}
+export declare class AdapterConnectError extends Error {
+    readonly rawMessage: string;
+    readonly stderrLines: string[];
+    constructor(target: TargetConfig, rawMessage: string, stderrLines: string[]);
+}
+export declare class LocalProcessAdapter {
+    connect(target: LocalProcessTargetConfig): Promise<AdapterSession>;
+}

package/dist/src/adapters/local-process.js

@@ -0,0 +1,63 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { formatConnectionFailureDiagnosis } from "../utils/failure-diagnosis.js";
+import { TOOL_VERSION } from "../version.js";
+export class AdapterConnectError extends Error {
+    rawMessage;
+    stderrLines;
+    constructor(target, rawMessage, stderrLines) {
+        super(formatConnectionFailureDiagnosis(target, rawMessage, stderrLines));
+        this.name = "AdapterConnectError";
+        this.rawMessage = rawMessage;
+        this.stderrLines = stderrLines;
+    }
+}
+export class LocalProcessAdapter {
+    async connect(target) {
+        const transport = new StdioClientTransport({
+            command: target.command,
+            args: target.args,
+            cwd: target.cwd,
+            env: target.env,
+            stderr: "pipe"
+        });
+        const stderrLines = [];
+        transport.stderr?.on("data", (chunk) => {
+            const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            for (const line of text.split(/\r?\n/)) {
+                const trimmed = line.trim();
+                if (trimmed.length > 0) {
+                    stderrLines.push(trimmed);
+                }
+            }
+        });
+        const client = new Client({
+            name: "mcp-observatory",
+            version: TOOL_VERSION
+        }, {
+            capabilities: {}
+        });
+        try {
+            await client.connect(transport, {
+                timeout: target.timeoutMs ?? 10_000
+            });
+        }
+        catch (error) {
+            const rawMessage = error instanceof Error ? error.message : String(error);
+            await client.close().catch(() => undefined);
+            throw new AdapterConnectError(target, rawMessage, stderrLines);
+        }
+        const serverVersion = client.getServerVersion();
+        return {
+            client,
+            serverCapabilities: client.getServerCapabilities(),
+            serverName: serverVersion?.name,
+            serverVersion: serverVersion?.version,
+            stderrLines,
+            close: async () => {
+                await client.close();
+            }
+        };
+    }
+}
+//# sourceMappingURL=local-process.js.map

package/dist/src/adapters/local-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-process.js","sourceRoot":"","sources":["../../../src/adapters/local-process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAIjF,OAAO,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAW7C,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,UAAU,CAAS;IACnB,WAAW,CAAW;IAE/B,YAAY,MAAoB,EAAE,UAAkB,EAAE,WAAqB;QACzE,KAAK,CAAC,gCAAgC,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAED,MAAM,OAAO,mBAAmB;IAC9B,KAAK,CAAC,OAAO,CAAC,MAAgC;QAC5C,MAAM,SAAS,GAAG,IAAI,oBAAoB,CAAC;YACzC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,GAAG,EAAE,MAAM,CAAC,GAAG;YACf,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;QAEH,MAAM,WAAW,GAAa,EAAE,CAAC;QACjC,SAAS,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE;YACtD,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACxE,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;gBACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACvB,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC5B,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB;YACE,IAAI,EAAE,iBAAiB;YACvB,OAAO,EAAE,YAAY;SACtB,EACD;YACE,YAAY,EAAE,EAAE;SACjB,CACF,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE;gBAC9B,OAAO,EAAE,MAAM,CAAC,SAAS,IAAI,MAAM;aACpC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,UAAU,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC1E,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC5C,MAAM,IAAI,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,CAAC;QACjE,CAAC;QAED,MAAM,aAAa,GAAG,MAAM,CAAC,gBAAgB,EAAE,CAAC;QAEhD,OAAO;YACL,MAAM;YACN,kBAAkB,EAAE,MAAM,CAAC,qBAAqB,EAAE;YAClD,UAAU,EAAE,aAAa,EAAE,IAAI;YAC/B,aAAa,EAAE,aAAa,EAAE,OAAO;YACrC,WAAW;YACX,KAAK,EAAE,KAAK,IAAI,EAAE;gBAChB,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACvB,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/src/checks/base.d.ts

@@ -0,0 +1,28 @@
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { ServerCapabilities } from "@modelcontextprotocol/sdk/types.js";
+import type { CheckId, CheckResult, CheckStatus, EvidenceSummary, TargetConfig } from "../types.js";
+export interface CheckContext {
+    client: Client;
+    serverCapabilities?: ServerCapabilities;
+    target: TargetConfig;
+    timeoutMs: number;
+    stderrLines: string[];
+}
+export interface CapabilityObservation {
+    capability: "tools" | "prompts" | "resources";
+    advertised: boolean;
+    responded: boolean;
+    minimalShapePresent: boolean;
+    endpoint: string;
+    itemCount?: number;
+    identifiers?: string[];
+    diagnostics: string[];
+}
+export interface ObservedCheck {
+    result: CheckResult;
+    observation?: CapabilityObservation;
+}
+export declare function makeCheckResult(id: CheckId, status: CheckStatus, durationMs: number, message: string, evidence: EvidenceSummary[]): CheckResult;
+export declare function baseEvidence(observation: CapabilityObservation, stderrLines: string[]): EvidenceSummary;
+export declare function isCapabilityAdvertised(capabilities: ServerCapabilities | undefined, capability: keyof Pick<ServerCapabilities, "tools" | "prompts" | "resources">): boolean;
+export declare function summarizeObservation(observation: CapabilityObservation): string;

package/dist/src/checks/base.js

@@ -0,0 +1,42 @@
+export function makeCheckResult(id, status, durationMs, message, evidence) {
+    return {
+        id,
+        capability: id,
+        status,
+        durationMs,
+        message,
+        evidence
+    };
+}
+export function baseEvidence(observation, stderrLines) {
+    return {
+        endpoint: observation.endpoint,
+        advertised: observation.advertised,
+        responded: observation.responded,
+        minimalShapePresent: observation.minimalShapePresent,
+        itemCount: observation.itemCount,
+        identifiers: observation.identifiers,
+        diagnostics: stderrLines.length > 0
+            ? [...observation.diagnostics, ...stderrLines.slice(-5)]
+            : observation.diagnostics
+    };
+}
+export function isCapabilityAdvertised(capabilities, capability) {
+    return capabilities?.[capability] !== undefined;
+}
+export function summarizeObservation(observation) {
+    if (!observation.advertised) {
+        return "Capability is not advertised by the target.";
+    }
+    if (!observation.responded) {
+        return "Advertised capability did not respond successfully.";
+    }
+    if (!observation.minimalShapePresent) {
+        return "Endpoint responded, but the minimal expected shape was incomplete.";
+    }
+    const countSuffix = observation.itemCount !== undefined
+        ? ` (${observation.itemCount} item${observation.itemCount === 1 ? "" : "s"})`
+        : "";
+    return `Advertised capability responded with the minimal expected shape${countSuffix}.`;
+}
+//# sourceMappingURL=base.js.map

package/dist/src/checks/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/checks/base.ts"],"names":[],"mappings":"AA6BA,MAAM,UAAU,eAAe,CAC7B,EAAW,EACX,MAAmB,EACnB,UAAkB,EAClB,OAAe,EACf,QAA2B;IAE3B,OAAO;QACL,EAAE;QACF,UAAU,EAAE,EAAE;QACd,MAAM;QACN,UAAU;QACV,OAAO;QACP,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,WAAkC,EAClC,WAAqB;IAErB,OAAO;QACL,QAAQ,EAAE,WAAW,CAAC,QAAQ;QAC9B,UAAU,EAAE,WAAW,CAAC,UAAU;QAClC,SAAS,EAAE,WAAW,CAAC,SAAS;QAChC,mBAAmB,EAAE,WAAW,CAAC,mBAAmB;QACpD,SAAS,EAAE,WAAW,CAAC,SAAS;QAChC,WAAW,EAAE,WAAW,CAAC,WAAW;QACpC,WAAW,EACT,WAAW,CAAC,MAAM,GAAG,CAAC;YACpB,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,WAAW,EAAE,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACxD,CAAC,CAAC,WAAW,CAAC,WAAW;KAC9B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,YAA4C,EAC5C,UAA6E;IAE7E,OAAO,YAAY,EAAE,CAAC,UAAU,CAAC,KAAK,SAAS,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,WAAkC;IACrE,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;QAC5B,OAAO,6CAA6C,CAAC;IACvD,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QAC3B,OAAO,qDAAqD,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,CAAC;QACrC,OAAO,oEAAoE,CAAC;IAC9E,CAAC;IACD,MAAM,WAAW,GACf,WAAW,CAAC,SAAS,KAAK,SAAS;QACjC,CAAC,CAAC,KAAK,WAAW,CAAC,SAAS,QAAQ,WAAW,CAAC,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG;QAC7E,CAAC,CAAC,EAAE,CAAC;IACT,OAAO,kEAAkE,WAAW,GAAG,CAAC;AAC1F,CAAC"}

package/dist/src/checks/list-check.d.ts

@@ -0,0 +1,16 @@
+import { type CheckContext, type ObservedCheck } from "./base.js";
+export interface ListCheckConfig<TItem> {
+    /** Capability name: "tools" or "prompts" */
+    capability: "tools" | "prompts";
+    /** The endpoint name used in evidence, e.g. "tools/list" */
+    endpoint: string;
+    /** Calls the appropriate list method on the MCP client */
+    listItems: (context: CheckContext) => Promise<TItem[]>;
+    /** Validates that a single item has the minimal expected shape */
+    hasMinimalShape: (item: TItem) => boolean;
+    /** Extracts the display name/identifier from an item */
+    getItemName: (item: TItem) => string;
+    /** Optionally extracts the schema/definition object for drift detection */
+    getItemSchema?: (item: TItem) => object | undefined;
+}
+export declare function runListCheck<TItem>(config: ListCheckConfig<TItem>, context: CheckContext): Promise<ObservedCheck>;

package/dist/src/checks/list-check.js

@@ -0,0 +1,78 @@
+import { performance } from "node:perf_hooks";
+import { baseEvidence, isCapabilityAdvertised, makeCheckResult, summarizeObservation } from "./base.js";
+export async function runListCheck(config, context) {
+    const startedAt = performance.now();
+    const advertised = isCapabilityAdvertised(context.serverCapabilities, config.capability);
+    if (!advertised) {
+        return {
+            observation: {
+                capability: config.capability,
+                advertised: false,
+                responded: false,
+                minimalShapePresent: false,
+                endpoint: config.endpoint,
+                diagnostics: []
+            },
+            result: makeCheckResult(config.capability, "unsupported", performance.now() - startedAt, `${capitalize(config.capability)} are not advertised by the target.`, [
+                {
+                    endpoint: config.endpoint,
+                    advertised: false,
+                    responded: false,
+                    minimalShapePresent: false,
+                    diagnostics: []
+                }
+            ])
+        };
+    }
+    try {
+        const items = await config.listItems(context);
+        const identifiers = items.map(config.getItemName);
+        const minimalShapePresent = items.every(config.hasMinimalShape);
+        const observation = {
+            capability: config.capability,
+            advertised: true,
+            responded: true,
+            minimalShapePresent,
+            endpoint: config.endpoint,
+            itemCount: items.length,
+            identifiers,
+            diagnostics: []
+        };
+        const evidence = baseEvidence(observation, context.stderrLines);
+        if (config.getItemSchema) {
+            const schemas = {};
+            for (const item of items) {
+                const schema = config.getItemSchema(item);
+                if (schema !== undefined) {
+                    schemas[config.getItemName(item)] = schema;
+                }
+            }
+            if (Object.keys(schemas).length > 0) {
+                evidence.schemas = schemas;
+            }
+        }
+        return {
+            observation,
+            result: makeCheckResult(config.capability, minimalShapePresent ? "pass" : "partial", performance.now() - startedAt, summarizeObservation(observation), [evidence])
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const observation = {
+            capability: config.capability,
+            advertised: true,
+            responded: false,
+            minimalShapePresent: false,
+            endpoint: config.endpoint,
+            diagnostics: [message]
+        };
+        return {
+            observation,
+            result: makeCheckResult(config.capability, "fail", performance.now() - startedAt, `Advertised capability failed during ${config.endpoint}: ${message}`, [baseEvidence(observation, context.stderrLines)])
+        };
+    }
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+//# sourceMappingURL=list-check.js.map

package/dist/src/checks/list-check.js.map

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

package/dist/src/checks/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { CheckContext, ObservedCheck } from "./base.js";
+export declare function runPromptsCheck(context: CheckContext): Promise<ObservedCheck>;

package/dist/src/checks/prompts.js

@@ -0,0 +1,11 @@
+import { runListCheck } from "./list-check.js";
+export async function runPromptsCheck(context) {
+    return runListCheck({
+        capability: "prompts",
+        endpoint: "prompts/list",
+        listItems: async (ctx) => (await ctx.client.listPrompts(undefined, { timeout: ctx.timeoutMs })).prompts,
+        hasMinimalShape: (prompt) => typeof prompt.name === "string" && prompt.name.trim().length > 0,
+        getItemName: (prompt) => prompt.name,
+    }, context);
+}
+//# sourceMappingURL=prompts.js.map

package/dist/src/checks/prompts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompts.js","sourceRoot":"","sources":["../../../src/checks/prompts.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,OAAqB;IACzD,OAAO,YAAY,CAAS;QAC1B,UAAU,EAAE,SAAS;QACrB,QAAQ,EAAE,cAAc;QACxB,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC,SAAS,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,OAAO;QACvG,eAAe,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QAC7F,WAAW,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI;KACrC,EAAE,OAAO,CAAC,CAAC;AACd,CAAC"}

package/dist/src/checks/resources.d.ts

@@ -0,0 +1,2 @@
+import { type CheckContext, type ObservedCheck } from "./base.js";
+export declare function runResourcesCheck(context: CheckContext): Promise<ObservedCheck>;