@adrkit/mcp 0.2.0

package/dist/index.js

@@ -0,0 +1,1093 @@
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolve as resolve2 } from "node:path";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/corpus/ordering.ts
+function compareCodeUnits(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function compareFindings(a, b) {
+  return compareCodeUnits(a.rule, b.rule) || compareCodeUnits(a.id ?? "", b.id ?? "") || compareCodeUnits(a.pattern ?? "", b.pattern ?? "") || compareCodeUnits(a.path ?? "", b.path ?? "") || compareCodeUnits(a.field ?? "", b.field ?? "") || compareCodeUnits(a.message, b.message);
+}
+function sortFindingsCanonical(findings) {
+  return [...findings].sort(compareFindings);
+}
+
+// src/search/normalize.ts
+function normalize(value) {
+  return value.trim().normalize("NFKC").toLowerCase();
+}
+
+// src/pagination/cursor.ts
+import { createHash } from "node:crypto";
+var CURSOR_KEYS = ["v", "scope", "fp", "qh", "offset"];
+function encodeCursor(payload) {
+  const json = `{"v":1,"scope":${JSON.stringify(payload.scope)},` + `"fp":${JSON.stringify(payload.fp)},"qh":${JSON.stringify(payload.qh)},` + `"offset":${payload.offset}}`;
+  return Buffer.from(json, "utf8").toString("base64url");
+}
+function queryShapeHash(parts) {
+  return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+function decodeStrict(cursor) {
+  let text;
+  try {
+    text = Buffer.from(cursor, "base64url").toString("utf8");
+  } catch {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+    return;
+  const keys = Object.keys(parsed);
+  if (keys.length !== CURSOR_KEYS.length || !CURSOR_KEYS.every((k) => keys.includes(k)))
+    return;
+  const obj = parsed;
+  if (typeof obj.v !== "number" || typeof obj.scope !== "string" || typeof obj.fp !== "string" || typeof obj.qh !== "string" || typeof obj.offset !== "number" || !Number.isSafeInteger(obj.offset) || obj.offset < 1) {
+    return;
+  }
+  return { v: obj.v, scope: obj.scope, fp: obj.fp, qh: obj.qh, offset: obj.offset };
+}
+function verifyCursor(options) {
+  const decoded = decodeStrict(options.cursor);
+  if (!decoded)
+    return { ok: false, reason: "decode-failed" };
+  if (decoded.v !== 1)
+    return { ok: false, reason: "version-unsupported" };
+  if (decoded.scope !== options.expectedScope)
+    return { ok: false, reason: "wrong-channel" };
+  if (decoded.fp !== options.fp)
+    return { ok: false, reason: "corpus-changed" };
+  if (decoded.qh !== options.qh)
+    return { ok: false, reason: "query-mismatch" };
+  return { ok: true, offset: decoded.offset };
+}
+function paginate(options) {
+  const { items, cursor, limit, scope, fp, qh } = options;
+  let offset = 0;
+  if (cursor !== undefined) {
+    const verified = verifyCursor({ cursor, expectedScope: scope, fp, qh });
+    if (!verified.ok)
+      return { ok: false, reason: verified.reason };
+    offset = verified.offset;
+    if (offset >= items.length)
+      return { ok: false, reason: "offset-out-of-range" };
+  }
+  const slice = items.slice(offset, offset + limit);
+  const nextOffset = offset + slice.length;
+  const nextCursor = nextOffset < items.length ? encodeCursor({ v: 1, scope, fp, qh, offset: nextOffset }) : null;
+  return { ok: true, page: { items: slice, cursor: nextCursor } };
+}
+function checkInapplicablePrimaryCursor(options) {
+  if (options.cursor === undefined)
+    return { ok: true };
+  const verified = verifyCursor({
+    cursor: options.cursor,
+    expectedScope: options.scope,
+    fp: options.fp,
+    qh: options.qh
+  });
+  if (!verified.ok)
+    return { ok: false, reason: verified.reason };
+  return { ok: false, reason: "cursor-not-applicable" };
+}
+
+// src/tools/shared.ts
+import { z } from "zod";
+import { AdrFrontmatter, AdrRef, Status, Scope } from "@adrkit/core";
+
+// src/corpus/projection.ts
+import { access, constants as FS, lstat, realpath, stat } from "node:fs/promises";
+import { createHash as createHash2 } from "node:crypto";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { discoverAdrFiles, lintCorpus, normalizeDisplayPath } from "@adrkit/core";
+var MAX_SOURCE_BYTES = 64 * 1024;
+
+class CorpusUnavailableError extends Error {
+  reason;
+  constructor(reason) {
+    super(reason);
+    this.name = "CorpusUnavailableError";
+    this.reason = reason;
+  }
+}
+function fail(reason) {
+  throw new CorpusUnavailableError(reason);
+}
+function errorCode(error) {
+  return error && typeof error === "object" && "code" in error ? String(error.code) : undefined;
+}
+function isContained(parent, child) {
+  if (parent === child)
+    return true;
+  const rel = relative(parent, child);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+async function resolveCanonicalRoots(options) {
+  let canonicalCwd;
+  try {
+    canonicalCwd = await realpath(options.cwd);
+  } catch (error) {
+    fail(errorCode(error) === "ENOENT" ? "root-not-found" : "root-not-readable");
+  }
+  try {
+    const info = await stat(canonicalCwd);
+    if (!info.isDirectory())
+      fail("root-not-directory");
+  } catch (error) {
+    if (error instanceof CorpusUnavailableError)
+      throw error;
+    fail(errorCode(error) === "ENOENT" ? "root-not-found" : "root-not-readable");
+  }
+  try {
+    await access(canonicalCwd, FS.R_OK | FS.X_OK);
+  } catch {
+    fail("root-not-readable");
+  }
+  const gitEntry = resolve(canonicalCwd, ".git");
+  try {
+    await stat(gitEntry);
+    await access(gitEntry, FS.R_OK);
+  } catch {
+    fail("root-not-git");
+  }
+  const dirInput = isAbsolute(options.dir) ? options.dir : resolve(canonicalCwd, options.dir);
+  let canonicalDir;
+  try {
+    canonicalDir = await realpath(dirInput);
+  } catch (error) {
+    fail(errorCode(error) === "ENOENT" ? "dir-not-found" : "dir-not-readable");
+  }
+  try {
+    const info = await stat(canonicalDir);
+    if (!info.isDirectory())
+      fail("dir-not-directory");
+  } catch (error) {
+    if (error instanceof CorpusUnavailableError)
+      throw error;
+    fail(errorCode(error) === "ENOENT" ? "dir-not-found" : "dir-not-readable");
+  }
+  try {
+    await access(canonicalDir, FS.R_OK | FS.X_OK);
+  } catch {
+    fail("dir-not-readable");
+  }
+  if (!isContained(canonicalCwd, canonicalDir))
+    fail("dir-outside-root");
+  return { canonicalCwd, canonicalDir };
+}
+function statError(displayPath) {
+  return {
+    rule: "record-stat-error",
+    severity: "error",
+    path: displayPath,
+    message: "ADR candidate could not be read to validate its size and was excluded from this response"
+  };
+}
+function tooLarge(displayPath) {
+  return {
+    rule: "record-too-large",
+    severity: "error",
+    path: displayPath,
+    message: "ADR source exceeds the 64 KiB maximum and was excluded from this response"
+  };
+}
+async function verifyRoots(options) {
+  const roots = await resolveCanonicalRoots({ cwd: options.configuredCwd, dir: options.configuredDir });
+  if (roots.canonicalCwd !== options.expectedCanonicalCwd)
+    fail("root-not-found");
+  return roots;
+}
+function canonicalStringify(value) {
+  if (value === null || value === undefined)
+    return "null";
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "string") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value))
+    return `[${value.map(canonicalStringify).join(",")}]`;
+  if (typeof value === "object") {
+    const record = value;
+    const keys = Object.keys(record).filter((key) => record[key] !== undefined).sort(compareCodeUnits);
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalStringify(record[key])}`).join(",")}}`;
+  }
+  return "null";
+}
+function fingerprintOf(records, corpusFindings, recordCount, excludedCount) {
+  const projection = {
+    records: records.map((record) => ({ sourcePath: record.path, frontmatter: record.frontmatter, body: record.body })),
+    corpusFindings,
+    corpusHealth: { recordCount, excludedCount }
+  };
+  return createHash2("sha256").update(canonicalStringify(projection), "utf8").digest("hex");
+}
+async function loadCorpusProjection(options) {
+  const roots = await verifyRoots(options);
+  let candidates;
+  try {
+    candidates = await discoverAdrFiles(roots.canonicalDir, roots.canonicalCwd);
+  } catch (error) {
+    fail(errorCode(error) === "ENOENT" ? "dir-not-found" : "dir-not-readable");
+  }
+  const preReadFindings = [];
+  const kept = [];
+  for (const candidate of candidates) {
+    const displayPath = normalizeDisplayPath(candidate, roots.canonicalCwd);
+    try {
+      const link = await lstat(candidate);
+      if (link.isSymbolicLink() || !link.isFile()) {
+        preReadFindings.push(statError(displayPath));
+        continue;
+      }
+      const real = await realpath(candidate);
+      if (!isContained(roots.canonicalDir, real)) {
+        preReadFindings.push(statError(displayPath));
+        continue;
+      }
+      const info = await stat(candidate, { bigint: true });
+      if (Number(info.size) > options.maxSourceBytes) {
+        preReadFindings.push(tooLarge(displayPath));
+        continue;
+      }
+      kept.push({
+        absolutePath: candidate,
+        displayPath,
+        identity: { dev: info.dev, ino: info.ino, size: info.size, mtimeNs: info.mtimeNs }
+      });
+    } catch {
+      preReadFindings.push(statError(displayPath));
+    }
+  }
+  let records = [];
+  let lintFindings = [];
+  if (kept.length > 0) {
+    const result = await lintCorpus({ paths: kept.map((k) => k.absolutePath), cwd: roots.canonicalCwd });
+    records = result.records;
+    lintFindings = result.findings;
+  }
+  const postRoots = await verifyRoots(options);
+  if (postRoots.canonicalDir !== roots.canonicalDir)
+    fail("corpus-changed-during-load");
+  for (const candidate of kept) {
+    try {
+      const link = await lstat(candidate.absolutePath);
+      if (link.isSymbolicLink() || !link.isFile())
+        fail("corpus-changed-during-load");
+      const real = await realpath(candidate.absolutePath);
+      if (!isContained(postRoots.canonicalDir, real))
+        fail("corpus-changed-during-load");
+      const info = await stat(candidate.absolutePath, { bigint: true });
+      if (Number(info.size) > options.maxSourceBytes)
+        fail("corpus-changed-during-load");
+      if (info.dev !== candidate.identity.dev || info.ino !== candidate.identity.ino || info.size !== candidate.identity.size || info.mtimeNs !== candidate.identity.mtimeNs) {
+        fail("corpus-changed-during-load");
+      }
+    } catch (error) {
+      if (error instanceof CorpusUnavailableError)
+        throw error;
+      fail("corpus-changed-during-load");
+    }
+  }
+  const orderedRecords = [...records].sort((a, b) => compareCodeUnits(a.frontmatter.id, b.frontmatter.id) || compareCodeUnits(a.path, b.path));
+  const byId = new Map;
+  for (const record of orderedRecords) {
+    const bucket = byId.get(record.frontmatter.id) ?? [];
+    bucket.push(record);
+    byId.set(record.frontmatter.id, bucket);
+  }
+  const corpusFindings = sortFindingsCanonical([...lintFindings, ...preReadFindings]);
+  const recordCount = orderedRecords.length;
+  const excludedCount = candidates.length - recordCount;
+  const fingerprint = fingerprintOf(orderedRecords, corpusFindings, recordCount, excludedCount);
+  return {
+    records: orderedRecords,
+    byId,
+    corpusFindings,
+    fingerprint,
+    recordCount,
+    excludedCount
+  };
+}
+
+// src/tools/shared.ts
+var LIMITS = {
+  query: { min: 1, max: 256 },
+  ref: { min: 1, max: 128 },
+  status: { min: 1, max: 6 },
+  scope: { min: 1, max: 3 },
+  tags: { min: 1, max: 32 },
+  tag: { min: 1, max: 64 },
+  fileLength: { min: 1, max: 1024 },
+  files: { min: 1, max: 256 },
+  page: { min: 1, max: 100, default: 20 },
+  cursorBytes: 4 * 1024,
+  textCap: 512
+};
+var ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var INVALID_CURSOR_MESSAGES = {
+  "decode-failed": "Cursor could not be decoded.",
+  "version-unsupported": "Cursor version is not supported.",
+  "wrong-channel": "Cursor does not belong to this tool channel.",
+  "corpus-changed": "Corpus changed after this cursor was issued.",
+  "query-mismatch": "Cursor was issued for different request parameters.",
+  "cursor-not-applicable": "Cursor does not apply to this outcome.",
+  "offset-out-of-range": "Cursor offset is outside the current result set."
+};
+var CORPUS_UNAVAILABLE_MESSAGES = {
+  "root-not-found": "Configured repository root was not found.",
+  "root-not-directory": "Configured repository root is not a directory.",
+  "root-not-readable": "Configured repository root is not readable.",
+  "root-not-git": "Configured repository root is not a Git worktree.",
+  "dir-not-found": "Configured ADR directory was not found.",
+  "dir-not-directory": "Configured ADR directory is not a directory.",
+  "dir-not-readable": "Configured ADR directory is not readable.",
+  "dir-outside-root": "Configured ADR directory resolves outside the repository root.",
+  "corpus-changed-during-load": "Corpus changed while it was being loaded; retry the call."
+};
+var INVALID_CURSOR_REASONS = Object.keys(INVALID_CURSOR_MESSAGES);
+var CORPUS_UNAVAILABLE_REASONS = Object.keys(CORPUS_UNAVAILABLE_MESSAGES);
+function plural(n, one, many) {
+  return n === 1 ? one : many;
+}
+function cap512(value) {
+  return value.length > LIMITS.textCap ? value.slice(0, LIMITS.textCap) : value;
+}
+function findingsPhrase(findings) {
+  return `${findings} ${plural(findings, "finding", "findings")} on this page.`;
+}
+function renderResponseText(spec) {
+  let text;
+  switch (spec.kind) {
+    case "results":
+      text = `Returned ${spec.itemsLength} decision ${plural(spec.itemsLength, "result", "results")}; ${findingsPhrase(spec.findings)}`;
+      break;
+    case "found":
+      text = `Found decision "${spec.id}"; ${findingsPhrase(spec.findings)}`;
+      break;
+    case "not-found":
+      text = `No local decision matches "${spec.requestedRef}"; ${findingsPhrase(spec.findings)}`;
+      break;
+    case "ambiguous-local-id":
+      text = `Returned ${spec.candidatesLength} ${plural(spec.candidatesLength, "candidate", "candidates")} for ambiguous local ref "${spec.requestedRef}"; ${findingsPhrase(spec.findings)}`;
+      break;
+    case "federated-log-unavailable":
+      text = `Named-log federation is unavailable for "${spec.requestedRef}"; ${findingsPhrase(spec.findings)}`;
+      break;
+    case "matches": {
+      const pageMatchCount = spec.governing + spec.activeProposals + spec.history;
+      text = `Returned ${pageMatchCount} context ${plural(pageMatchCount, "match", "matches")}: ${spec.governing} governing, ${spec.activeProposals} active ${plural(spec.activeProposals, "proposal", "proposals")}, ${spec.history} historical; ${findingsPhrase(spec.findings)}`;
+      break;
+    }
+    case "entries":
+      text = `Returned ${spec.itemsLength} superseded decision ${plural(spec.itemsLength, "entry", "entries")}; ${findingsPhrase(spec.findings)}`;
+      break;
+    case "invalid-cursor":
+      text = INVALID_CURSOR_MESSAGES[spec.reason];
+      break;
+    case "corpus-unavailable":
+      text = CORPUS_UNAVAILABLE_MESSAGES[spec.reason];
+      break;
+  }
+  return cap512(text);
+}
+var uniqueArray = (schema, min, max) => z.array(schema).min(min).max(max).refine((values) => new Set(values.map((v) => JSON.stringify(v))).size === values.length, {
+  message: "Items must be unique"
+});
+function paginationShape() {
+  const cursor = z.string().max(LIMITS.cursorBytes).optional();
+  const limit = z.number().int().min(LIMITS.page.min).max(LIMITS.page.max).default(LIMITS.page.default);
+  return { cursor, limit, findingsCursor: cursor, findingsLimit: limit };
+}
+function isSafePosixPath(path) {
+  if (path.includes("\\"))
+    return false;
+  if (path.startsWith("/"))
+    return false;
+  if (/^[a-zA-Z]:/.test(path))
+    return false;
+  if (path.split("/").includes(".."))
+    return false;
+  return path.length > 0;
+}
+function searchDecisionsInputSchema() {
+  return z.strictObject({
+    query: z.string().min(LIMITS.query.min).max(LIMITS.query.max).refine((q) => q.trim().length >= 1, { message: "query must be non-empty after trimming" }),
+    status: uniqueArray(Status, LIMITS.status.min, LIMITS.status.max).optional(),
+    tags: uniqueArray(z.string().min(LIMITS.tag.min).max(LIMITS.tag.max), LIMITS.tags.min, LIMITS.tags.max).optional(),
+    scope: uniqueArray(Scope, LIMITS.scope.min, LIMITS.scope.max).optional(),
+    ...paginationShape()
+  });
+}
+function getDecisionInputSchema() {
+  return z.strictObject({
+    ref: AdrRef.max(LIMITS.ref.max),
+    ...paginationShape()
+  });
+}
+function getDecisionContextInputSchema() {
+  return z.strictObject({
+    files: z.array(z.string().min(LIMITS.fileLength.min).max(LIMITS.fileLength.max).refine(isSafePosixPath, { message: "files must be repo-relative POSIX paths" })).min(LIMITS.files.min).max(LIMITS.files.max),
+    ...paginationShape()
+  });
+}
+function listSupersededInputSchema() {
+  return z.strictObject({ ...paginationShape() });
+}
+function findingSchema() {
+  return z.object({
+    rule: z.string(),
+    severity: z.enum(["error", "warn", "info"]),
+    message: z.string(),
+    path: z.string().optional(),
+    id: z.string().optional(),
+    field: z.string().optional(),
+    pattern: z.string().optional()
+  });
+}
+function corpusHealthSchema() {
+  return z.object({
+    fingerprint: z.string(),
+    recordCount: z.number().int(),
+    excludedCount: z.number().int()
+  });
+}
+function findingsPageSchema() {
+  return z.object({ items: z.array(findingSchema()), cursor: z.string().nullable() });
+}
+function decisionSummarySchema() {
+  return z.object({ id: z.string(), title: z.string(), status: Status, sourcePath: z.string() });
+}
+function relationRefsSchema() {
+  return z.object({
+    supersedes: z.array(z.string()),
+    supersededBy: z.string().nullable(),
+    relatesTo: z.array(z.string()),
+    conflictsWith: z.array(z.string())
+  });
+}
+function invalidCursorSchema() {
+  return z.object({
+    outcome: z.literal("invalid-cursor"),
+    reason: z.enum(INVALID_CURSOR_REASONS),
+    message: z.string()
+  });
+}
+function corpusUnavailableSchema() {
+  return z.object({
+    outcome: z.literal("corpus-unavailable"),
+    reason: z.enum(CORPUS_UNAVAILABLE_REASONS),
+    message: z.string()
+  });
+}
+function searchDecisionsOutputSchema() {
+  const searchMatch = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: Status,
+    sourcePath: z.string(),
+    matchedFields: z.array(z.enum(["id", "title", "tag", "body"]))
+  });
+  return {
+    corpusHealth: corpusHealthSchema().optional(),
+    result: z.discriminatedUnion("outcome", [
+      z.object({
+        outcome: z.literal("results"),
+        items: z.array(searchMatch),
+        cursor: z.string().nullable(),
+        findings: findingsPageSchema()
+      }),
+      invalidCursorSchema(),
+      corpusUnavailableSchema()
+    ])
+  };
+}
+function getDecisionOutputSchema() {
+  const fullDecision = z.object({
+    requestedRef: z.string(),
+    id: z.string(),
+    title: z.string(),
+    status: Status,
+    sourcePath: z.string(),
+    frontmatter: AdrFrontmatter,
+    body: z.string()
+  });
+  return {
+    corpusHealth: corpusHealthSchema().optional(),
+    result: z.discriminatedUnion("outcome", [
+      z.object({ outcome: z.literal("found"), decision: fullDecision, findings: findingsPageSchema() }),
+      z.object({ outcome: z.literal("not-found"), requestedRef: z.string(), findings: findingsPageSchema() }),
+      z.object({
+        outcome: z.literal("ambiguous-local-id"),
+        requestedRef: z.string(),
+        candidates: z.array(decisionSummarySchema()),
+        cursor: z.string().nullable(),
+        findings: findingsPageSchema()
+      }),
+      z.object({
+        outcome: z.literal("federated-log-unavailable"),
+        requestedRef: z.string(),
+        log: z.string(),
+        id: z.string(),
+        findings: findingsPageSchema()
+      }),
+      invalidCursorSchema(),
+      corpusUnavailableSchema()
+    ])
+  };
+}
+function getDecisionContextOutputSchema() {
+  const contextEntry = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: Status,
+    sourcePath: z.string(),
+    firedMatchers: z.array(z.object({ type: z.string(), pattern: z.string() })),
+    relations: relationRefsSchema()
+  });
+  return {
+    corpusHealth: corpusHealthSchema().optional(),
+    result: z.discriminatedUnion("outcome", [
+      z.object({
+        outcome: z.literal("matches"),
+        governing: z.array(contextEntry),
+        activeProposals: z.array(contextEntry),
+        history: z.array(contextEntry),
+        cursor: z.string().nullable(),
+        findings: findingsPageSchema()
+      }),
+      invalidCursorSchema(),
+      corpusUnavailableSchema()
+    ])
+  };
+}
+function listSupersededOutputSchema() {
+  const supersededBy = z.union([
+    z.object({ resolved: z.literal(true), target: decisionSummarySchema() }),
+    z.object({ resolved: z.literal(false), targetRef: z.string(), reason: z.literal("dangling") }),
+    z.object({
+      resolved: z.literal(false),
+      targetRef: z.string(),
+      reason: z.literal("ambiguous"),
+      candidateCount: z.number().int()
+    }),
+    z.object({
+      resolved: z.literal(false),
+      targetRef: z.string(),
+      reason: z.literal("federated-unavailable"),
+      log: z.string(),
+      id: z.string()
+    })
+  ]);
+  const supersededEntry = z.object({
+    id: z.string(),
+    title: z.string(),
+    status: Status,
+    sourcePath: z.string(),
+    supersededBy
+  });
+  return {
+    corpusHealth: corpusHealthSchema().optional(),
+    result: z.discriminatedUnion("outcome", [
+      z.object({
+        outcome: z.literal("entries"),
+        items: z.array(supersededEntry),
+        cursor: z.string().nullable(),
+        findings: findingsPageSchema()
+      }),
+      invalidCursorSchema(),
+      corpusUnavailableSchema()
+    ])
+  };
+}
+function structuredResult(result, text, corpusHealth) {
+  const structuredContent = corpusHealth === undefined ? { result } : { corpusHealth, result };
+  return { structuredContent, content: [{ type: "text", text }] };
+}
+function corpusHealthOf(projection) {
+  return {
+    fingerprint: projection.fingerprint,
+    recordCount: projection.recordCount,
+    excludedCount: projection.excludedCount
+  };
+}
+function invalidCursor(reason) {
+  return { outcome: "invalid-cursor", reason, message: INVALID_CURSOR_MESSAGES[reason] };
+}
+function corpusUnavailable(reason) {
+  return { outcome: "corpus-unavailable", reason, message: CORPUS_UNAVAILABLE_MESSAGES[reason] };
+}
+async function loadProjection(config) {
+  try {
+    const projection = await loadCorpusProjection({
+      configuredCwd: config.configuredCwd,
+      configuredDir: config.configuredDir,
+      expectedCanonicalCwd: config.expectedCanonicalCwd,
+      maxSourceBytes: config.maxSourceBytes
+    });
+    return { ok: true, projection };
+  } catch (error) {
+    if (error instanceof CorpusUnavailableError)
+      return { ok: false, outcome: corpusUnavailable(error.reason) };
+    throw error;
+  }
+}
+function toSummary(record) {
+  return {
+    id: record.frontmatter.id,
+    title: record.frontmatter.title,
+    status: record.frontmatter.status,
+    sourcePath: record.path
+  };
+}
+function toRelationRefs(frontmatter) {
+  return {
+    supersedes: frontmatter.supersedes,
+    supersededBy: frontmatter.supersededBy ?? null,
+    relatesTo: frontmatter.relatesTo,
+    conflictsWith: frontmatter.conflictsWith
+  };
+}
+
+// src/tools/search-decisions.ts
+function sortedUnique(values) {
+  return values ? [...new Set(values)].sort(compareCodeUnits) : [];
+}
+function passesFilters(record, status, scope, tags) {
+  if (status && !status.includes(record.frontmatter.status))
+    return false;
+  if (scope && !scope.includes(record.frontmatter.scope))
+    return false;
+  if (tags && !tags.every((tag) => record.frontmatter.tags.includes(tag)))
+    return false;
+  return true;
+}
+function matchedFields(record, needle) {
+  const fields = [];
+  if (normalize(record.body).includes(needle))
+    fields.push("body");
+  if (normalize(record.frontmatter.id).includes(needle))
+    fields.push("id");
+  if (record.frontmatter.tags.some((tag) => normalize(tag).includes(needle)))
+    fields.push("tag");
+  if (normalize(record.frontmatter.title).includes(needle))
+    fields.push("title");
+  return fields;
+}
+function registerSearchDecisions(server, config) {
+  server.registerTool("search_decisions", {
+    title: "Search decisions",
+    description: "Search the decision corpus (including the graveyard by default) by deterministic normalized literal substring over id, title, tags, and Markdown body. Optional status/scope (any-of) and tags (all-of) filters are ANDed. Returns bounded summaries only — no ranking, no model, no body.",
+    inputSchema: searchDecisionsInputSchema(),
+    outputSchema: searchDecisionsOutputSchema(),
+    annotations: ANNOTATIONS
+  }, async (args) => {
+    const { query, status, tags, scope, cursor, limit, findingsCursor, findingsLimit } = args;
+    const loaded = await loadProjection(config);
+    if (!loaded.ok) {
+      return structuredResult(loaded.outcome, renderResponseText({ kind: "corpus-unavailable", reason: loaded.outcome.reason }), undefined);
+    }
+    const projection = loaded.projection;
+    const health = corpusHealthOf(projection);
+    const fp = projection.fingerprint;
+    const needle = normalize(query);
+    const primaryQh = queryShapeHash([needle, sortedUnique(status), sortedUnique(tags), sortedUnique(scope), limit]);
+    const findingsQh = queryShapeHash([findingsLimit]);
+    const matches = [];
+    for (const record of projection.records) {
+      if (!passesFilters(record, status, scope, tags))
+        continue;
+      const fields = matchedFields(record, needle);
+      if (fields.length === 0)
+        continue;
+      matches.push({ ...toSummary(record), matchedFields: fields });
+    }
+    const primary = paginate({ items: matches, cursor, limit, scope: "search.results", fp, qh: primaryQh });
+    if (!primary.ok)
+      return invalid(primary.reason);
+    const findingsPage = paginate({
+      items: projection.corpusFindings,
+      cursor: findingsCursor,
+      limit: findingsLimit,
+      scope: "search.findings",
+      fp,
+      qh: findingsQh
+    });
+    if (!findingsPage.ok)
+      return invalid(findingsPage.reason);
+    const result = {
+      outcome: "results",
+      items: primary.page.items,
+      cursor: primary.page.cursor,
+      findings: findingsPage.page
+    };
+    return structuredResult(result, renderResponseText({ kind: "results", itemsLength: primary.page.items.length, findings: findingsPage.page.items.length }), health);
+    function invalid(reason) {
+      return structuredResult(invalidCursor(reason), renderResponseText({ kind: "invalid-cursor", reason }), health);
+    }
+  });
+}
+
+// src/tools/get-decision.ts
+import { parseAdrRef } from "@adrkit/core";
+function fullDecision(record, ref) {
+  return {
+    requestedRef: ref,
+    id: record.frontmatter.id,
+    title: record.frontmatter.title,
+    status: record.frontmatter.status,
+    sourcePath: record.path,
+    frontmatter: record.frontmatter,
+    body: record.body
+  };
+}
+function registerGetDecision(server, config) {
+  server.registerTool("get_decision", {
+    title: "Get a decision by ref",
+    description: 'Fetch one architecture decision by its bare local id (e.g. "0042"). Returns the complete typed frontmatter and Markdown body, or an explicit not-found / ambiguous-local-id / federated-log-unavailable outcome. Relation refs are surfaced verbatim, never expanded.',
+    inputSchema: getDecisionInputSchema(),
+    outputSchema: getDecisionOutputSchema(),
+    annotations: ANNOTATIONS
+  }, async (args) => {
+    const { ref, cursor, limit, findingsCursor, findingsLimit } = args;
+    const loaded = await loadProjection(config);
+    if (!loaded.ok) {
+      return structuredResult(loaded.outcome, renderResponseText({ kind: "corpus-unavailable", reason: loaded.outcome.reason }), undefined);
+    }
+    const projection = loaded.projection;
+    const health = corpusHealthOf(projection);
+    const fp = projection.fingerprint;
+    const responseFindings = projection.corpusFindings;
+    const findingsPage = paginate({
+      items: responseFindings,
+      cursor: findingsCursor,
+      limit: findingsLimit,
+      scope: "get_decision.findings",
+      fp,
+      qh: queryShapeHash([findingsLimit])
+    });
+    const parsed = parseAdrRef(ref);
+    const candidatesQh = queryShapeHash([ref, limit]);
+    if (parsed.log !== undefined) {
+      const inapplicable2 = checkInapplicablePrimaryCursor({ cursor, scope: "get_decision.candidates", fp, qh: candidatesQh });
+      if (!inapplicable2.ok)
+        return invalidResult(inapplicable2.reason, health);
+      if (!findingsPage.ok)
+        return invalidResult(findingsPage.reason, health);
+      const result2 = {
+        outcome: "federated-log-unavailable",
+        requestedRef: ref,
+        log: parsed.log,
+        id: parsed.id,
+        findings: findingsPage.page
+      };
+      return structuredResult(result2, renderResponseText({ kind: "federated-log-unavailable", requestedRef: ref, findings: findingsPage.page.items.length }), health);
+    }
+    const bucket = projection.byId.get(parsed.id) ?? [];
+    if (bucket.length > 1) {
+      const candidates = bucket.map(toSummary);
+      const primary = paginate({
+        items: candidates,
+        cursor,
+        limit,
+        scope: "get_decision.candidates",
+        fp,
+        qh: candidatesQh
+      });
+      if (!primary.ok)
+        return invalidResult(primary.reason, health);
+      if (!findingsPage.ok)
+        return invalidResult(findingsPage.reason, health);
+      const result2 = {
+        outcome: "ambiguous-local-id",
+        requestedRef: ref,
+        candidates: primary.page.items,
+        cursor: primary.page.cursor,
+        findings: findingsPage.page
+      };
+      return structuredResult(result2, renderResponseText({
+        kind: "ambiguous-local-id",
+        candidatesLength: primary.page.items.length,
+        requestedRef: ref,
+        findings: findingsPage.page.items.length
+      }), health);
+    }
+    const inapplicable = checkInapplicablePrimaryCursor({ cursor, scope: "get_decision.candidates", fp, qh: candidatesQh });
+    if (!inapplicable.ok)
+      return invalidResult(inapplicable.reason, health);
+    if (!findingsPage.ok)
+      return invalidResult(findingsPage.reason, health);
+    if (bucket.length === 1) {
+      const record = bucket[0];
+      const result2 = { outcome: "found", decision: fullDecision(record, ref), findings: findingsPage.page };
+      return structuredResult(result2, renderResponseText({ kind: "found", id: record.frontmatter.id, findings: findingsPage.page.items.length }), health);
+    }
+    const result = { outcome: "not-found", requestedRef: ref, findings: findingsPage.page };
+    return structuredResult(result, renderResponseText({ kind: "not-found", requestedRef: ref, findings: findingsPage.page.items.length }), health);
+    function invalidResult(reason, corpusHealth) {
+      const outcome = invalidCursor(reason);
+      return structuredResult(outcome, renderResponseText({ kind: "invalid-cursor", reason }), corpusHealth);
+    }
+  });
+}
+
+// src/tools/get-decision-context.ts
+import { resolveAffects } from "@adrkit/core";
+function bucketFor(status) {
+  if (status === "accepted")
+    return "governing";
+  if (status === "draft" || status === "proposed")
+    return "activeProposals";
+  return "history";
+}
+function contextEntry(record, firedMatchers) {
+  return { ...toSummary(record), firedMatchers, relations: toRelationRefs(record.frontmatter) };
+}
+function registerGetDecisionContext(server, config) {
+  server.registerTool("get_decision_context", {
+    title: "Get decision context for files",
+    description: "Given repo-relative logical file paths, report which decisions govern them, which active proposals touch them, and which historical records once did — using the corpus’s own affects matchers. The supplied paths are compared against patterns only; they are never opened or read.",
+    inputSchema: getDecisionContextInputSchema(),
+    outputSchema: getDecisionContextOutputSchema(),
+    annotations: ANNOTATIONS
+  }, async (args) => {
+    const { files, cursor, limit, findingsCursor, findingsLimit } = args;
+    const loaded = await loadProjection(config);
+    if (!loaded.ok) {
+      return structuredResult(loaded.outcome, renderResponseText({ kind: "corpus-unavailable", reason: loaded.outcome.reason }), undefined);
+    }
+    const projection = loaded.projection;
+    const health = corpusHealthOf(projection);
+    const fp = projection.fingerprint;
+    const canonicalFiles = [...new Set(files)].sort(compareCodeUnits);
+    const primaryQh = queryShapeHash([canonicalFiles, limit]);
+    const findingsQh = queryShapeHash([canonicalFiles, findingsLimit]);
+    const flat = [];
+    const derivedFindings = [];
+    for (const record of projection.records) {
+      const resolved = resolveAffects({ records: [record], changedFiles: files });
+      derivedFindings.push(...resolved.findings);
+      const match = resolved.matches[0];
+      if (match)
+        flat.push(contextEntry(record, match.firedMatchers));
+    }
+    const responseFindings = sortFindingsCanonical([...projection.corpusFindings, ...derivedFindings]);
+    const primary = paginate({ items: flat, cursor, limit, scope: "context.results", fp, qh: primaryQh });
+    if (!primary.ok)
+      return invalid(primary.reason);
+    const findingsPage = paginate({
+      items: responseFindings,
+      cursor: findingsCursor,
+      limit: findingsLimit,
+      scope: "context.findings",
+      fp,
+      qh: findingsQh
+    });
+    if (!findingsPage.ok)
+      return invalid(findingsPage.reason);
+    const governing = [];
+    const activeProposals = [];
+    const history = [];
+    for (const entry of primary.page.items) {
+      const target = bucketFor(entry.status) === "governing" ? governing : bucketFor(entry.status) === "activeProposals" ? activeProposals : history;
+      target.push(entry);
+    }
+    const result = {
+      outcome: "matches",
+      governing,
+      activeProposals,
+      history,
+      cursor: primary.page.cursor,
+      findings: findingsPage.page
+    };
+    return structuredResult(result, renderResponseText({
+      kind: "matches",
+      governing: governing.length,
+      activeProposals: activeProposals.length,
+      history: history.length,
+      findings: findingsPage.page.items.length
+    }), health);
+    function invalid(reason) {
+      return structuredResult(invalidCursor(reason), renderResponseText({ kind: "invalid-cursor", reason }), health);
+    }
+  });
+}
+
+// src/tools/list-superseded.ts
+import { parseAdrRef as parseAdrRef2 } from "@adrkit/core";
+function resolveEntry(record, byId) {
+  const targetRef = record.frontmatter.supersededBy;
+  const parsed = parseAdrRef2(targetRef);
+  const summary = toSummary(record);
+  if (parsed.log !== undefined) {
+    const supersededBy2 = {
+      resolved: false,
+      targetRef,
+      reason: "federated-unavailable",
+      log: parsed.log,
+      id: parsed.id
+    };
+    const derived2 = {
+      rule: "superseded-target-federated-unavailable",
+      severity: "info",
+      id: record.frontmatter.id,
+      message: `supersededBy target "${targetRef}" is a log-qualified ref; named-log federation is not available in this phase`
+    };
+    return { entry: { ...summary, supersededBy: supersededBy2 }, derived: derived2 };
+  }
+  const bucket = byId.get(parsed.id) ?? [];
+  if (bucket.length === 1) {
+    return { entry: { ...summary, supersededBy: { resolved: true, target: toSummary(bucket[0]) } }, derived: undefined };
+  }
+  if (bucket.length === 0) {
+    return { entry: { ...summary, supersededBy: { resolved: false, targetRef, reason: "dangling" } }, derived: undefined };
+  }
+  const supersededBy = { resolved: false, targetRef, reason: "ambiguous", candidateCount: bucket.length };
+  const derived = {
+    rule: "superseded-target-ambiguous",
+    severity: "warn",
+    id: record.frontmatter.id,
+    message: `supersededBy target "${targetRef}" resolves to ${bucket.length} local records; see get_decision("${targetRef}") for the full candidate list`
+  };
+  return { entry: { ...summary, supersededBy }, derived };
+}
+function registerListSuperseded(server, config) {
+  server.registerTool("list_superseded", {
+    title: "List superseded decisions",
+    description: "List every superseded decision with its direct local replacement state: resolved, dangling, ambiguous (candidateCount only), or federated-unavailable. Direct edges only — no transitive lineage, no embedded candidate arrays.",
+    inputSchema: listSupersededInputSchema(),
+    outputSchema: listSupersededOutputSchema(),
+    annotations: ANNOTATIONS
+  }, async (args) => {
+    const { cursor, limit, findingsCursor, findingsLimit } = args;
+    const loaded = await loadProjection(config);
+    if (!loaded.ok) {
+      return structuredResult(loaded.outcome, renderResponseText({ kind: "corpus-unavailable", reason: loaded.outcome.reason }), undefined);
+    }
+    const projection = loaded.projection;
+    const health = corpusHealthOf(projection);
+    const fp = projection.fingerprint;
+    const entries = [];
+    const derivedFindings = [];
+    for (const record of projection.records) {
+      if (record.frontmatter.status !== "superseded")
+        continue;
+      const resolved = resolveEntry(record, projection.byId);
+      entries.push(resolved.entry);
+      if (resolved.derived)
+        derivedFindings.push(resolved.derived);
+    }
+    const responseFindings = sortFindingsCanonical([...projection.corpusFindings, ...derivedFindings]);
+    const primary = paginate({ items: entries, cursor, limit, scope: "superseded.results", fp, qh: queryShapeHash([limit]) });
+    if (!primary.ok)
+      return invalid(primary.reason);
+    const findingsPage = paginate({
+      items: responseFindings,
+      cursor: findingsCursor,
+      limit: findingsLimit,
+      scope: "superseded.findings",
+      fp,
+      qh: queryShapeHash([findingsLimit])
+    });
+    if (!findingsPage.ok)
+      return invalid(findingsPage.reason);
+    const result = {
+      outcome: "entries",
+      items: primary.page.items,
+      cursor: primary.page.cursor,
+      findings: findingsPage.page
+    };
+    return structuredResult(result, renderResponseText({ kind: "entries", itemsLength: primary.page.items.length, findings: findingsPage.page.items.length }), health);
+    function invalid(reason) {
+      return structuredResult(invalidCursor(reason), renderResponseText({ kind: "invalid-cursor", reason }), health);
+    }
+  });
+}
+
+// src/server.ts
+var SERVER_INFO = { name: "@adrkit/mcp", version: "0.1.0" };
+function buildRegisteredServer(config) {
+  const server = new McpServer(SERVER_INFO);
+  registerSearchDecisions(server, config);
+  registerGetDecision(server, config);
+  registerGetDecisionContext(server, config);
+  registerListSuperseded(server, config);
+  return server;
+}
+
+// src/index.ts
+function createAdrkitMcpServer(options) {
+  const cwd = resolve2(options?.cwd ?? process.cwd());
+  const dir = options?.dir ?? "docs/adr";
+  let server;
+  let startPromise;
+  let closePromise;
+  let closed = false;
+  function start() {
+    if (closed) {
+      return Promise.reject(new Error("adrkit MCP server handle is closed"));
+    }
+    if (startPromise)
+      return startPromise;
+    startPromise = (async () => {
+      let nextServer;
+      try {
+        const roots = await resolveCanonicalRoots({ cwd, dir });
+        const config = {
+          configuredCwd: cwd,
+          configuredDir: dir,
+          expectedCanonicalCwd: roots.canonicalCwd,
+          maxSourceBytes: MAX_SOURCE_BYTES
+        };
+        nextServer = buildRegisteredServer(config);
+        server = nextServer;
+        await nextServer.connect(new StdioServerTransport);
+      } catch (error) {
+        server = undefined;
+        if (nextServer) {
+          try {
+            await nextServer.close();
+          } catch (closeError) {
+            startPromise = undefined;
+            throw new AggregateError([error, closeError], "MCP server startup and cleanup failed");
+          }
+        }
+        startPromise = undefined;
+        throw error;
+      }
+    })();
+    return startPromise;
+  }
+  function close() {
+    if (closePromise)
+      return closePromise;
+    closed = true;
+    closePromise = (async () => {
+      if (startPromise)
+        await startPromise;
+      const current = server;
+      server = undefined;
+      if (current)
+        await current.close();
+    })();
+    return closePromise;
+  }
+  const handle = Object.create(null);
+  handle.start = start;
+  handle.close = close;
+  return Object.freeze(handle);
+}
+export {
+  createAdrkitMcpServer
+};