@descryy/mcp 0.1.0

package/dist/tools/verification-status.js

@@ -0,0 +1,179 @@
+/**
+ * `verification_status` — §4 technique 6: *"Coverage is a separate axis and
+ * a separate call. Appending it everywhere pays on every call; a tool pays
+ * once, when the client is actually reporting."*
+ *
+ * Wraps `packages/core/src/query/verification-status.ts`'s
+ * `computeVerificationStatus` — the module's own header calls itself "the
+ * static half only" and says building the `ScopeItem[]` from a caller's refs
+ * is "the caller's job, done above this boundary." This tool is that caller.
+ *
+ * ## Real capability lookup, without ever naming a language up here
+ *
+ * `computeVerificationStatus`'s `ScopeItem.capabilities`, when supplied,
+ * lets a `notExercised` reason describe a real declared gap rather than a
+ * generic absence. The first design attempted here guessed a language from
+ * a ref's file extension and matched it against a `language` tag on a
+ * configured source — and `npm run lint` caught it immediately:
+ * `descry-boundary/no-language-vocabulary` and `no-language-branch` both
+ * fired, because `packages/*\/src/**` (this file included, not just
+ * `packages/core`) is bound by architecture principle 7 — nothing above the
+ * Canonical IR may name or dispatch on a language, full stop. A hardcoded
+ * extension table and a `.get(guessedLanguage)` lookup are exactly the
+ * "lookup dispatch" shape that rule exists to catch, not a false positive.
+ *
+ * The fix moves the decision below the boundary, where it belongs:
+ * `LanguageAdapter` (`@descryy/ir`) gained an optional
+ * `ownsPath(path): boolean` — the adapter decides, using whatever
+ * language-specific logic it wants, entirely inside `descry-adapters`,
+ * which is not bound by this repo's lint. This tool never sees or compares
+ * a language string; it just asks every loaded, configured adapter "do you
+ * own this path," and attaches whichever one says yes. An unresolved ref's
+ * `language` therefore stays `null` here always — this tool does not
+ * determine one, and does not need to: `computeVerificationStatus`'s reason
+ * text already reads correctly either way (see its own module header),
+ * naming an adapter as registered without ever naming which language it is
+ * for.
+ *
+ * A configured source that fails to import cannot be asked at all — this
+ * tool's own `notes` disclose that plainly, the same register `analyze.ts`
+ * already uses for a source that will not import.
+ *
+ * ## Resolving a ref: node id first, then file
+ *
+ * A ref that is a real node id resolves directly (`getNode`). Otherwise it
+ * is tried as a file path (`findNodes({ file: ref })`, the same reader
+ * `lookup.ts`'s `resolveOneNode` already uses for symbol/file matching): the
+ * file's own `FILE`-typed node stands in when one exists, else the node
+ * with the *weakest* resolution in that file — the same "report the
+ * weakest link" convention `resolutionFloor` uses elsewhere in this
+ * package, since a file is only as verified as its least-resolved member.
+ * A ref that resolves neither way is `notExercised`.
+ */
+import { getNode, findNodes, computeVerificationStatus, resolutionOfExercised } from "@descryy/core";
+import { answer, optionalStringArray, ToolInputError, } from "./kit.js";
+import { loadSources } from "../registry.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        refs: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            description: "Node ids and/or repository-relative file paths to check coverage for — typically ids " +
+                "already returned by an earlier call (impact, scope, contracts) that you now want to know " +
+                "whether the graph actually reached.",
+        },
+    },
+    required: ["refs"],
+    additionalProperties: false,
+};
+/** The file's own `FILE` node when present, else the node with the weakest resolution — never picked at random. */
+function representativeForFile(nodes) {
+    const fileNode = nodes.find((n) => n.type === "FILE");
+    if (fileNode !== undefined)
+        return fileNode;
+    return nodes.reduce((weakest, n) => (n.resolution < weakest.resolution ? n : weakest));
+}
+function resolveRef(driver, ref) {
+    const byId = getNode(driver, ref);
+    if (byId !== undefined)
+        return { ref, language: byId.language, node: byId };
+    const inFile = findNodes(driver, { file: ref });
+    if (inFile.length > 0) {
+        const node = representativeForFile(inFile);
+        return { ref, language: node.language, node };
+    }
+    return { ref, language: null, node: null };
+}
+/**
+ * Real capabilities for whichever configured, loaded adapter owns each
+ * unresolved ref — decided entirely by the adapter's own `ownsPath`, never
+ * by a language name compared up here. See the module header.
+ */
+async function capabilitiesForUnresolvedRefs(sources, unresolvedRefs) {
+    const capabilitiesByRef = new Map();
+    const failedNotes = [];
+    if (unresolvedRefs.length === 0 || sources.length === 0)
+        return { capabilitiesByRef, failedNotes };
+    const { loaded, failed } = await loadSources(sources);
+    try {
+        for (const ref of unresolvedRefs) {
+            const owner = loaded.find((entry) => entry.adapter?.ownsPath?.(ref) === true);
+            if (owner?.adapter !== undefined && owner?.adapter !== null) {
+                capabilitiesByRef.set(ref, owner.adapter.capabilities());
+            }
+        }
+    }
+    finally {
+        await Promise.all(loaded.map((entry) => entry.adapter?.dispose()));
+    }
+    for (const failure of failed) {
+        failedNotes.push(`A configured source (${failure.spec.module}) did not import (${failure.reason}), so it could ` +
+            "not be asked whether it owns any of this call's unresolved refs.");
+    }
+    return { capabilitiesByRef, failedNotes };
+}
+async function run(args, ctx) {
+    const refs = optionalStringArray(args, "refs") ?? [];
+    if (refs.length === 0) {
+        throw new ToolInputError('"refs" must name at least one node id or file path — with none, there is nothing to report ' +
+            "coverage for, and an empty answer would look like a check that ran");
+    }
+    const driver = ctx.session.store().driver;
+    const base = ctx.session.provider().baseStamp();
+    ctx.progress(`Checking coverage for ${refs.length} ref(s)`);
+    const resolved = refs.map((ref) => resolveRef(driver, ref));
+    const unresolvedRefs = resolved.filter((r) => r.node === null).map((r) => r.ref);
+    const { capabilitiesByRef, failedNotes } = await capabilitiesForUnresolvedRefs(ctx.session.config.sources, unresolvedRefs);
+    const scope = resolved.map((r) => ({
+        ref: r.ref,
+        language: r.language,
+        node: r.node,
+        capabilities: r.node === null ? capabilitiesByRef.get(r.ref) : undefined,
+    }));
+    const status = computeVerificationStatus(scope);
+    const exercised = status.exercised.map((entry) => resolutionOfExercised(entry));
+    return answer({
+        headline: exercised.length === refs.length
+            ? `All ${refs.length} ref(s) were reached by the graph.`
+            : `${exercised.length} of ${refs.length} ref(s) were reached by the graph; ` +
+                `${status.notExercised.length} were not — see notExercised for why.`,
+        data: { checked: refs, exercised, notExercised: status.notExercised },
+        resolutionFloor: exercised.length === 0 ? 0 : Math.min(...exercised.map((e) => e.resolution)),
+        commitSha: base.commitSha,
+        graphBuiltAt: base.graphBuiltAt,
+        irSchemaVersion: base.irSchemaVersion,
+        // A presence/coverage claim ("was this ref reached, and at what resolution")
+        // is about identity, not shape — the same class impact/history/similar_incidents
+        // already use.
+        nameLevel: true,
+        notes: [
+            ...(status.notExercised.length === 0
+                ? []
+                : [
+                    "This tool never names a language for an absent ref — it only asks each configured, " +
+                        "loaded adapter whether it owns that path. See each notExercised reason for exactly " +
+                        "what was determined.",
+                ]),
+            ...failedNotes,
+        ],
+    });
+}
+export const verificationStatusTool = {
+    name: "verification_status",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Was this actually checked, and at what resolution?",
+    description: "Given a list of node ids and/or file paths, report which were actually reached by the graph " +
+        "and at what resolution, and which were not — with why, where determinable. Coverage is a " +
+        "separate axis from any finding's confidence (§19/§20): use this after another call to learn " +
+        "what that call's answer does and does not actually cover, rather than trusting silence as " +
+        "coverage. When a session's configured adapters can say whether they own an unreached file, " +
+        "real declared capabilities are attached to explain the gap more precisely — see the tool's own " +
+        "notes when some refs are not exercised.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=verification-status.js.map

package/dist/tools/verification-status.js.map

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

package/dist/transport.d.ts

@@ -0,0 +1,58 @@
+/**
+ * stdio transport: newline-delimited JSON over stdin/stdout.
+ *
+ * ## The one rule that breaks everything when broken
+ *
+ * **stdout is the protocol channel and nothing else may write to it.** A single
+ * `console.log` anywhere in the process — in the engine, in a loaded adapter, in
+ * a dependency — emits a line the client tries to parse as a frame, and the
+ * session dies with an error that names the parser rather than the culprit.
+ *
+ * This is not a comment asking people to be careful. `guardStdout()` replaces
+ * `console.log` and friends with writers onto **stderr**, which the MCP host
+ * shows as server logs, so a stray print stays visible and stops being fatal.
+ * The transport keeps the one real handle to stdout for itself.
+ *
+ * ## Framing
+ *
+ * MCP's stdio transport is one JSON object per line, UTF-8, with no embedded
+ * newlines. `JSON.stringify` never emits a raw newline, so writing is a
+ * stringify plus `"\n"`. Reading needs a buffer because a chunk boundary can
+ * land anywhere, including mid-multibyte-character — hence `StringDecoder`
+ * rather than `chunk.toString()`, which would corrupt any non-ASCII payload
+ * split across two chunks.
+ */
+import type { Readable, Writable } from "node:stream";
+export interface Transport {
+    /** Write one frame. Must never be called with anything but a JSON-RPC message. */
+    send(frame: unknown): void;
+}
+/**
+ * Redirect every console channel to stderr and return the real stdout writer.
+ *
+ * Called once, by the stdio runner, before any handler can run. The returned
+ * function is the only sanctioned path to stdout in the process.
+ */
+export declare function guardStdout(stdout: Writable, stderr: Writable): (line: string) => void;
+/**
+ * Split a byte stream into lines, decoding correctly across chunk boundaries.
+ *
+ * Returned as a function rather than a class because the buffer is the entire
+ * state and there is nothing else to hang on an object.
+ */
+export declare function createLineReader(onLine: (line: string) => void): (chunk: Buffer) => void;
+export interface StdioOptions {
+    readonly stdin: Readable;
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+}
+/**
+ * Run a dispatcher over stdio until stdin closes.
+ *
+ * Resolves on end-of-input, which is how an MCP host asks a stdio server to shut
+ * down — it closes the pipe. Anything the server holds open (a database handle,
+ * a worker pool) is disposed by the caller after this resolves, not here: this
+ * function knows about bytes and nothing else.
+ */
+export declare function serveStdio(options: StdioOptions, dispatch: (line: string, transport: Transport) => Promise<void>): Promise<void>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,QAAQ,EAChB,MAAM,EAAE,QAAQ,GACf,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAiBxB;AAWD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAcxF;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,YAAY,EACrB,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAC9D,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/dist/transport.js

@@ -0,0 +1,115 @@
+/**
+ * stdio transport: newline-delimited JSON over stdin/stdout.
+ *
+ * ## The one rule that breaks everything when broken
+ *
+ * **stdout is the protocol channel and nothing else may write to it.** A single
+ * `console.log` anywhere in the process — in the engine, in a loaded adapter, in
+ * a dependency — emits a line the client tries to parse as a frame, and the
+ * session dies with an error that names the parser rather than the culprit.
+ *
+ * This is not a comment asking people to be careful. `guardStdout()` replaces
+ * `console.log` and friends with writers onto **stderr**, which the MCP host
+ * shows as server logs, so a stray print stays visible and stops being fatal.
+ * The transport keeps the one real handle to stdout for itself.
+ *
+ * ## Framing
+ *
+ * MCP's stdio transport is one JSON object per line, UTF-8, with no embedded
+ * newlines. `JSON.stringify` never emits a raw newline, so writing is a
+ * stringify plus `"\n"`. Reading needs a buffer because a chunk boundary can
+ * land anywhere, including mid-multibyte-character — hence `StringDecoder`
+ * rather than `chunk.toString()`, which would corrupt any non-ASCII payload
+ * split across two chunks.
+ */
+import { StringDecoder } from "node:string_decoder";
+/**
+ * Redirect every console channel to stderr and return the real stdout writer.
+ *
+ * Called once, by the stdio runner, before any handler can run. The returned
+ * function is the only sanctioned path to stdout in the process.
+ */
+export function guardStdout(stdout, stderr) {
+    const toStderr = (...args) => {
+        stderr.write(`${args
+            .map((a) => (typeof a === "string" ? a : inspectish(a)))
+            .join(" ")}\n`);
+    };
+    console.log = toStderr;
+    console.info = toStderr;
+    console.warn = toStderr;
+    console.debug = toStderr;
+    console.error = toStderr;
+    return (line) => {
+        stdout.write(line);
+    };
+}
+function inspectish(value) {
+    if (value instanceof Error)
+        return `${value.name}: ${value.message}`;
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Split a byte stream into lines, decoding correctly across chunk boundaries.
+ *
+ * Returned as a function rather than a class because the buffer is the entire
+ * state and there is nothing else to hang on an object.
+ */
+export function createLineReader(onLine) {
+    const decoder = new StringDecoder("utf8");
+    let buffer = "";
+    return (chunk) => {
+        buffer += decoder.write(chunk);
+        let index = buffer.indexOf("\n");
+        while (index !== -1) {
+            const line = buffer.slice(0, index).replace(/\r$/, "");
+            buffer = buffer.slice(index + 1);
+            if (line.trim() !== "")
+                onLine(line);
+            index = buffer.indexOf("\n");
+        }
+    };
+}
+/**
+ * Run a dispatcher over stdio until stdin closes.
+ *
+ * Resolves on end-of-input, which is how an MCP host asks a stdio server to shut
+ * down — it closes the pipe. Anything the server holds open (a database handle,
+ * a worker pool) is disposed by the caller after this resolves, not here: this
+ * function knows about bytes and nothing else.
+ */
+export function serveStdio(options, dispatch) {
+    const write = guardStdout(options.stdout, options.stderr);
+    const transport = {
+        send: (frame) => {
+            write(`${JSON.stringify(frame)}\n`);
+        },
+    };
+    // Frames are handled strictly in arrival order. Concurrency here would let a
+    // fast `tools/list` overtake a slow `analyze`, and while JSON-RPC permits
+    // out-of-order responses, an `analyze` that has not finished writing the graph
+    // must not be overtaken by a `scope` that would then read a half-built one.
+    let chain = Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const feed = createLineReader((line) => {
+            chain = chain.then(() => dispatch(line, transport)).catch((error) => {
+                // A dispatcher that throws is a bug in this package: `dispatch` is
+                // supposed to turn every failure into an error frame. Report it on
+                // stderr and keep the session alive rather than killing a developer's
+                // editor integration over one bad request.
+                options.stderr.write(`descry-mcp: dispatch failed: ${inspectish(error)}\n`);
+            });
+        });
+        options.stdin.on("data", feed);
+        options.stdin.on("error", reject);
+        options.stdin.on("end", () => {
+            chain.then(resolve, resolve);
+        });
+    });
+}
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

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

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@descryy/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Descry's MCP server: the agent-facing front door over the query layer. Zero runtime dependencies — the stdio transport is JSON-RPC 2.0 by hand rather than seventeen packages of HTTP and OAuth.",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "descry-mcp": "dist/bin/descry-mcp.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@descryy/core": "0.1.0",
+    "@descryy/ir": "0.1.0"
+  }
+}