ultra11y 2.22.0

package/src/mcp/resources.ts

@@ -0,0 +1,136 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// The skill's own documentation, served over MCP.
+//
+// A tool list hands a client the ENGINE. It does not hand it the method: the
+// rule that you answer only from retrieved evidence, the citation format, the
+// rubric a good answer is held to. Inside Claude Code that method arrives as
+// SKILL.md. Everywhere else — Cursor, Zed, Claude Desktop — nothing carries it,
+// and a model driving these tools from cold reinvents a worse protocol.
+//
+// So SKILL.md and references/*.md are exposed as resources. Nothing here is
+// generated: they are the same files the skill ships, read off disk at request
+// time, which is why a documentation fix never needs a rebuild to reach a
+// client.
+
+export const SKILL_NAME = "ultra11y";
+
+const URI_SCHEME = "skill://";
+
+export interface ResourceDecl {
+  uri: string;
+  name: string;
+  title?: string;
+  description?: string;
+  mimeType: string;
+}
+
+export interface ResourceContents {
+  uri: string;
+  mimeType: string;
+  text: string;
+}
+
+// Where SKILL.md lives, relative to whatever directory this module was loaded
+// from. Three layouts, tried in order, because the same code runs from all of
+// them:
+//
+//   <payload>/scripts/ultra11y.mjs  → <payload>/SKILL.md              (installed skill)
+//   <repo>/scripts/ultra11y.mjs     → <repo>/skills/ultra11y/SKILL.md (repo-root bundle)
+//   <repo>/src/mcp/resources.ts     → <repo>/skills/ultra11y/SKILL.md (source tree, tests)
+//
+// `moduleDir` is injectable for the same reason the vendored engine makes it
+// injectable (codeindex-engine.mjs:5560): a test must be able to point this at
+// a fixture without staging a fake bundle on disk.
+export function resolveSkillRoot(moduleDir?: string): string | undefined {
+  const here = moduleDir ?? dirname(fileURLToPath(import.meta.url));
+  const candidates = [resolve(here, ".."), resolve(here, "..", "skills", SKILL_NAME), resolve(here, "..", "..", "skills", SKILL_NAME)];
+  return candidates.find((dir) => existsSync(join(dir, "SKILL.md")));
+}
+
+// The catalogue. An unresolvable root is not an error: a skill installed
+// without its payload should still serve every tool it has, with an empty
+// resource list, rather than refuse to start over missing documentation.
+export function listResources(moduleDir?: string): ResourceDecl[] {
+  const root = resolveSkillRoot(moduleDir);
+  if (!root) return [];
+
+  const out: ResourceDecl[] = [describe(root, "SKILL.md", `${SKILL_NAME}: the skill`)];
+
+  const refDir = join(root, "references");
+  if (!existsSync(refDir)) return out;
+  for (const file of readdirSync(refDir).sort()) {
+    if (!file.endsWith(".md")) continue;
+    out.push(describe(root, join("references", file), `${SKILL_NAME} reference: ${basename(file, ".md")}`));
+  }
+  return out;
+}
+
+export function readResource(uri: string, moduleDir?: string): ResourceContents {
+  if (!uri.startsWith(URI_SCHEME)) {
+    throw new ResourceError(`unknown resource scheme in "${uri}" (expected ${URI_SCHEME}…)`);
+  }
+  const root = resolveSkillRoot(moduleDir);
+  if (!root) throw new ResourceError("no skill payload found next to this build — nothing to read");
+
+  const rel = uri.slice(URI_SCHEME.length);
+  if (!rel) throw new ResourceError("empty resource path");
+
+  // Containment is checked on the REALPATH, not on the joined string. A
+  // `skill://../../.ssh/id_rsa` normalises away, but a symlink inside
+  // references/ pointing out of the tree does not — and this server may be
+  // reachable over HTTP.
+  const target = resolve(root, rel);
+  const rootReal = realpathSync(root);
+  let targetReal: string;
+  try {
+    targetReal = realpathSync(target);
+  } catch {
+    throw new ResourceError(`no such resource: ${uri}`);
+  }
+  if (targetReal !== rootReal && !targetReal.startsWith(rootReal + sep)) {
+    throw new ResourceError(`resource path escapes the skill root: ${uri}`);
+  }
+  if (!statSync(targetReal).isFile()) throw new ResourceError(`not a file: ${uri}`);
+
+  return { uri, mimeType: "text/markdown", text: readFileSync(targetReal, "utf8") };
+}
+
+// Thrown for a resource the caller asked for wrongly. The server turns it into
+// a JSON-RPC error, the way an unknown tool is one: the client named something
+// that does not exist, which is a client bug, not a failed read.
+export class ResourceError extends Error {}
+
+function describe(root: string, rel: string, fallbackTitle: string): ResourceDecl {
+  const decl: ResourceDecl = {
+    uri: `${URI_SCHEME}${rel.split(sep).join("/")}`,
+    name: rel.split(sep).join("/"),
+    title: fallbackTitle,
+    mimeType: "text/markdown",
+  };
+  const summary = firstProse(join(root, rel));
+  if (summary) decl.description = summary;
+  return decl;
+}
+
+// The first real sentence of a markdown file, for the resource description.
+// Skips YAML frontmatter, headings and blockquote callouts, so what a client
+// shows is the document's claim rather than its title repeated.
+function firstProse(file: string): string | undefined {
+  let text: string;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  const body = text.startsWith("---\n") ? text.slice(text.indexOf("\n---", 3) + 4) : text;
+  for (const block of body.split(/\n\s*\n/)) {
+    const line = block.trim();
+    if (!line || line.startsWith("#") || line.startsWith(">") || line.startsWith("|") || line.startsWith("```")) continue;
+    const flat = line.replace(/\s+/g, " ").replace(/[*`]/g, "");
+    return flat.length > 300 ? `${flat.slice(0, 297)}…` : flat;
+  }
+  return undefined;
+}

package/src/mcp/server.ts

@@ -0,0 +1,228 @@
+import { VERSION } from "../types.js";
+import { callTool, ToolError, type HandlerDefaults } from "./handlers.js";
+import { getPrompt, PROMPTS, PromptError } from "./prompts.js";
+import { listResources, readResource, ResourceError } from "./resources.js";
+import { toolsFor, type ToolDecl } from "./tools.js";
+import {
+  DEFAULT_MAX_RESPONSE_BYTES,
+  LATEST_PROTOCOL,
+  RICH_TOOLS_SINCE,
+  capResponse,
+  negotiateProtocol,
+  structuredContentFor,
+  validateArgs,
+  type ProtocolVersion,
+} from "./protocol.js";
+
+// The JSON-RPC layer, with no idea how the bytes arrive. stdio.ts frames it in
+// newline-delimited JSON, http.ts in request bodies; both call `handle`.
+//
+// Responses go out through a `send` callback rather than a return value. That
+// is not decoration: it is what lets a later revision stream progress
+// notifications over SSE without touching this file.
+
+export interface JsonRpcMessage {
+  jsonrpc?: string;
+  id?: string | number | null;
+  method?: string;
+  params?: Record<string, unknown>;
+  [k: string]: unknown;
+}
+
+export interface ServerOptions extends HandlerDefaults {
+  maxResponseBytes?: number;
+  serverName?: string;
+  // Where to look for the skill payload (SKILL.md + references/). Injectable
+  // for tests; in production resources.ts finds it from its own module path.
+  skillDir?: string;
+}
+
+export const ERR_INVALID_REQUEST = -32600;
+export const ERR_METHOD_NOT_FOUND = -32601;
+export const ERR_INVALID_PARAMS = -32602;
+export const ERR_INTERNAL = -32603;
+
+export interface McpServer {
+  // Handle one message. `send` is called zero times for a notification, once
+  // for a request. Never throws.
+  handle(msg: JsonRpcMessage, send: (out: JsonRpcMessage) => void): Promise<void>;
+  // The version agreed during `initialize`. The HTTP transport overrides it per
+  // request from the MCP-Protocol-Version header, since it has no session.
+  protocolVersion(): ProtocolVersion;
+  setProtocolVersion(v: ProtocolVersion): void;
+  tools(): ToolDecl[];
+}
+
+export function createServer(opts: ServerOptions = {}): McpServer {
+  const serverInfo = { name: opts.serverName ?? "ultra11y", version: VERSION };
+  const maxBytes = opts.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+  // Until a client says otherwise, assume the newest. `initialize` replaces it.
+  let protocol: ProtocolVersion = LATEST_PROTOCOL;
+  // Requests the client withdrew. Per spec a cancelled request gets NO response
+  // at all, so the id has to survive until the in-flight work finishes. An id
+  // that never had a request in flight is never claimed, so the set is bounded:
+  // a client that cancels ids it never sent cannot grow it without limit in a
+  // process that may run for days.
+  const cancelled = new Set<string>();
+  const CANCELLED_MAX = 1024;
+
+  const listTools = () => toolsFor(protocol, { defaultCwd: opts.defaultCwd, allowWrite: opts.allowWrite });
+
+  async function handle(msg: JsonRpcMessage, send: (out: JsonRpcMessage) => void): Promise<void> {
+    if (msg === null || typeof msg !== "object" || Array.isArray(msg)) {
+      send({ jsonrpc: "2.0", id: null, error: { code: ERR_INVALID_REQUEST, message: "invalid request: expected a JSON-RPC object" } });
+      return;
+    }
+
+    // A message with no id is a notification: act on it, answer nothing.
+    if (msg.id === undefined || msg.id === null) {
+      if (msg.method === "notifications/cancelled") {
+        const target = msg.params?.requestId;
+        if (typeof target === "string" || typeof target === "number") {
+          if (cancelled.size >= CANCELLED_MAX) cancelled.delete(cancelled.values().next().value!);
+          cancelled.add(String(target));
+        }
+      }
+      return;
+    }
+    const id = msg.id;
+
+    const reply = (out: Omit<JsonRpcMessage, "jsonrpc" | "id">) => {
+      // A cancelled request is dropped on the floor — answering it after the
+      // client moved on is exactly what the notification asks us not to do.
+      if (cancelled.delete(String(id))) return;
+      send({ jsonrpc: "2.0", id, ...out });
+    };
+
+    try {
+      switch (msg.method) {
+        case "initialize": {
+          protocol = negotiateProtocol(msg.params?.protocolVersion);
+          reply({
+            result: {
+              protocolVersion: protocol,
+              // Three primitives, because a skill is three things: the engine
+              // (tools), the method (prompts) and the documentation the method
+              // refers to (resources). A client given only the first has to
+              // invent the other two.
+              capabilities: {
+                tools: { listChanged: false },
+                resources: { subscribe: false, listChanged: false },
+                prompts: { listChanged: false },
+              },
+              serverInfo,
+            },
+          });
+          return;
+        }
+        case "ping":
+          reply({ result: {} });
+          return;
+        case "tools/list":
+          reply({ result: { tools: listTools() } });
+          return;
+        case "tools/call":
+          await handleToolCall(msg, reply);
+          return;
+        case "resources/list":
+          reply({ result: { resources: listResources(opts.skillDir) } });
+          return;
+        case "resources/read": {
+          const uri = typeof msg.params?.uri === "string" ? msg.params.uri : "";
+          if (!uri) {
+            reply({ error: { code: ERR_INVALID_PARAMS, message: "`uri` is required" } });
+            return;
+          }
+          try {
+            reply({ result: { contents: [readResource(uri, opts.skillDir)] } });
+          } catch (e) {
+            // A resource the client named wrongly is a client bug, the same as
+            // an unknown tool — not a read that failed on its own terms.
+            if (e instanceof ResourceError) reply({ error: { code: ERR_INVALID_PARAMS, message: e.message } });
+            else reply({ error: { code: ERR_INTERNAL, message: errMessage(e) } });
+          }
+          return;
+        }
+        case "prompts/list":
+          reply({ result: { prompts: PROMPTS } });
+          return;
+        case "prompts/get": {
+          const name = typeof msg.params?.name === "string" ? msg.params.name : "";
+          const args = (msg.params?.arguments ?? {}) as Record<string, unknown>;
+          try {
+            reply({ result: getPrompt(name, args) });
+          } catch (e) {
+            if (e instanceof PromptError) reply({ error: { code: ERR_INVALID_PARAMS, message: e.message } });
+            else reply({ error: { code: ERR_INTERNAL, message: errMessage(e) } });
+          }
+          return;
+        }
+        default:
+          reply({ error: { code: ERR_METHOD_NOT_FOUND, message: `method not found: ${String(msg.method)}` } });
+          return;
+      }
+    } catch (e) {
+      // Nothing above is supposed to throw. Reaching here is a bug in the
+      // server, not a bad request — report it as such rather than as a tool
+      // failure the model might try to work around.
+      reply({ error: { code: ERR_INTERNAL, message: errMessage(e) } });
+    }
+  }
+
+  async function handleToolCall(msg: JsonRpcMessage, reply: (out: Omit<JsonRpcMessage, "jsonrpc" | "id">) => void): Promise<void> {
+    const params = msg.params ?? {};
+    const name = typeof params.name === "string" ? params.name : "";
+    const args = (params.arguments ?? {}) as Record<string, unknown>;
+
+    // An unknown tool and malformed arguments are PROTOCOL errors: the client
+    // asked for something that doesn't exist or sent something the declared
+    // schema forbids. They are not tool failures, and conflating the two (as
+    // the vendored blueprint does) hides a client bug inside a model-readable
+    // result the model then tries to reason around.
+    const decl = listTools().find((t) => t.name === name);
+    if (!decl) {
+      reply({ error: { code: ERR_INVALID_PARAMS, message: `unknown tool: ${name || "(none given)"}` } });
+      return;
+    }
+    const invalid = validateArgs(decl.inputSchema, args);
+    if (invalid) {
+      reply({ error: { code: ERR_INVALID_PARAMS, message: invalid } });
+      return;
+    }
+
+    try {
+      const { text: raw, artifact } = await callTool(name, args, { defaultCwd: opts.defaultCwd, allowWrite: opts.allowWrite });
+      const text = capResponse(raw, name, maxBytes, artifact);
+      const capped = text !== raw;
+      const structured = protocol >= RICH_TOOLS_SINCE ? structuredContentFor(text, capped, decl.outputSchema !== undefined) : undefined;
+      reply({ result: { content: [{ type: "text", text }], ...(structured ? { structuredContent: structured } : {}) } });
+    } catch (e) {
+      // The tool ran and could not finish: a repo that won't clone, a path
+      // outside the tree, a dossier that isn't there. The caller can act on all
+      // of these, so they come back as a readable result, not a protocol error.
+      //
+      // What never lands here: a source that degraded. Those are `notes` inside
+      // a successful result — an unreachable issues API is information, not a
+      // failure, and reporting it as one would make the model retry work that
+      // already told it everything it is going to.
+      if (e instanceof ToolError) {
+        reply({ result: { content: [{ type: "text", text: e.message }], isError: true } });
+        return;
+      }
+      reply({ error: { code: ERR_INTERNAL, message: errMessage(e) } });
+    }
+  }
+
+  return {
+    handle,
+    protocolVersion: () => protocol,
+    setProtocolVersion: (v: ProtocolVersion) => {
+      protocol = v;
+    },
+    tools: listTools,
+  };
+}
+
+function errMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

package/src/mcp/stdio.ts

@@ -0,0 +1,119 @@
+import { createInterface } from "node:readline";
+import type { Readable, Writable } from "node:stream";
+import { createServer, ERR_INVALID_REQUEST, type JsonRpcMessage, type ServerOptions } from "./server.js";
+
+// The stdio transport: one JSON-RPC message per line, in on stdin, out on
+// stdout. This is what `claude mcp add --transport stdio` and Claude Desktop
+// speak, and it is the default.
+//
+// Two properties this file exists to guarantee:
+//
+// 1. stdout carries frames and nothing else. Today no module outside cli.ts
+//    writes to stdout, but "nobody does it yet" is an invariant maintained by
+//    discipline. Reassigning process.stdout.write makes it one maintained by
+//    construction: a console.log added to a source module in a year lands on
+//    stderr instead of corrupting the stream mid-session.
+//
+// 2. A slow tool never blocks a fast one. `ultra11y_ask` on a cold repo takes
+//    tens of seconds; serializing the read loop behind it would make `ping` and
+//    `tools/list` time out. JSON-RPC explicitly permits out-of-order responses.
+
+// How many tool calls may be in flight at once. Above this, ultra11y's own
+// per-source concurrency and the git subprocesses stop paying for themselves.
+const MAX_IN_FLIGHT = 4;
+
+export interface StdioOptions extends ServerOptions {
+  input?: Readable;
+  output?: Writable;
+  // Skip the stdout guard. Only for tests, which need to read what the server
+  // wrote through a stream they control.
+  captureStdout?: boolean;
+}
+
+export async function runStdioServer(opts: StdioOptions = {}): Promise<void> {
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+
+  // Capture the real writer BEFORE the guard goes up, so frames still reach the
+  // client afterwards.
+  const emit = output.write.bind(output);
+  let restore: (() => void) | undefined;
+  if (!opts.captureStdout && output === process.stdout) {
+    const original = process.stdout.write;
+    process.stdout.write = ((chunk: unknown, ...rest: unknown[]) =>
+      (process.stderr.write as (...a: unknown[]) => boolean)(chunk, ...rest)) as typeof process.stdout.write;
+    restore = () => {
+      process.stdout.write = original;
+    };
+  }
+
+  const server = createServer(opts);
+  const send = (msg: JsonRpcMessage) => {
+    emit(JSON.stringify(msg) + "\n");
+  };
+
+  const inFlight = new Set<Promise<void>>();
+  const track = (p: Promise<void>) => {
+    inFlight.add(p);
+    void p.finally(() => inFlight.delete(p));
+    return p;
+  };
+  const drainToLimit = async () => {
+    while (inFlight.size >= MAX_IN_FLIGHT) await Promise.race(inFlight);
+  };
+
+  const rl = createInterface({ input, terminal: false });
+  try {
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+        continue;
+      }
+
+      await drainToLimit();
+
+      if (Array.isArray(parsed)) {
+        // A batch answers as one array, so the client can match it to what it
+        // sent. Notifications inside it contribute nothing, and a batch of only
+        // notifications produces no frame at all.
+        track(
+          (async () => {
+            const out: JsonRpcMessage[] = [];
+            await Promise.all(parsed.map((m) => server.handle(m as JsonRpcMessage, (r) => void out.push(r))));
+            if (out.length) emit(JSON.stringify(out) + "\n");
+          })().catch(reportInternal(send)),
+        );
+        continue;
+      }
+
+      if (parsed === null || typeof parsed !== "object") {
+        send({ jsonrpc: "2.0", id: null, error: { code: ERR_INVALID_REQUEST, message: "invalid request: expected a JSON-RPC object" } });
+        continue;
+      }
+
+      // Deliberately not awaited: the loop goes back for the next frame while
+      // this one works.
+      track(server.handle(parsed as JsonRpcMessage, send).catch(reportInternal(send)));
+    }
+
+    // stdin closed. Let whatever is still running finish and answer — calling
+    // process.exit() here would drop these frames, because stdout on a pipe is
+    // asynchronous and exit() does not flush it.
+    await Promise.all(inFlight);
+  } finally {
+    rl.close();
+    restore?.();
+  }
+}
+
+function reportInternal(send: (msg: JsonRpcMessage) => void) {
+  return (e: unknown) => {
+    send({ jsonrpc: "2.0", id: null, error: { code: -32603, message: e instanceof Error ? e.message : String(e) } });
+  };
+}