@adrkit/mcp 0.2.0

package/src/tools/get-decision-context.ts

@@ -0,0 +1,137 @@
+/**
+ * @adrkit/mcp — the `get_decision_context` tool (US2, contracts/tools.md §6).
+ *
+ * Reports governing, active-proposal, and historical records for logical file
+ * paths using the existing `resolveAffects` resolver, once per record, without ever
+ * reading a caller-supplied path. One canonical flat walk is paginated, then the
+ * page is partitioned by status.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { resolveAffects, type Adr, type Finding, type FiredMatcher } from '@adrkit/core';
+import { compareCodeUnits, sortFindingsCanonical } from '../corpus/ordering.ts';
+import { paginate, queryShapeHash } from '../pagination/cursor.ts';
+import {
+  ANNOTATIONS,
+  corpusHealthOf,
+  getDecisionContextInputSchema,
+  getDecisionContextOutputSchema,
+  invalidCursor,
+  loadProjection,
+  renderResponseText,
+  structuredResult,
+  toRelationRefs,
+  toSummary,
+  type ContextEntry,
+  type GetDecisionContextResult,
+  type ToolConfig,
+} from './shared.ts';
+
+interface GetDecisionContextArgs {
+  readonly files: string[];
+  readonly cursor?: string;
+  readonly limit: number;
+  readonly findingsCursor?: string;
+  readonly findingsLimit: number;
+}
+
+type Bucket = 'governing' | 'activeProposals' | 'history';
+
+function bucketFor(status: string): Bucket {
+  if (status === 'accepted') return 'governing';
+  if (status === 'draft' || status === 'proposed') return 'activeProposals';
+  return 'history';
+}
+
+function contextEntry(record: Adr, firedMatchers: readonly FiredMatcher[]): ContextEntry {
+  return { ...toSummary(record), firedMatchers, relations: toRelationRefs(record.frontmatter) };
+}
+
+export function registerGetDecisionContext(server: McpServer, config: ToolConfig): void {
+  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\u2019s 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 as GetDecisionContextArgs;
+
+      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]);
+
+      // Once per record, in canonical order. Derived findings are concatenated.
+      const flat: ContextEntry[] = [];
+      const derivedFindings: Finding[] = [];
+      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: ContextEntry[] = [];
+      const activeProposals: ContextEntry[] = [];
+      const history: ContextEntry[] = [];
+      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: GetDecisionContextResult = {
+        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: Parameters<typeof invalidCursor>[0]) {
+        return structuredResult(invalidCursor(reason), renderResponseText({ kind: 'invalid-cursor', reason }), health);
+      }
+    },
+  );
+}

package/src/tools/get-decision.ts

@@ -0,0 +1,169 @@
+/**
+ * @adrkit/mcp — the `get_decision` tool (US1, contracts/tools.md §4).
+ *
+ * Fetches one within-limit decision by ref. `parseAdrRef` detects a log-qualified
+ * ref first (→ federated-log-unavailable, never a local substitute); a bare id is
+ * resolved through the fresh local `byId` bucket into found / not-found /
+ * ambiguous-local-id. Relation refs are surfaced verbatim, never expanded.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { parseAdrRef, type Adr } from '@adrkit/core';
+import { paginate, queryShapeHash, checkInapplicablePrimaryCursor } from '../pagination/cursor.ts';
+import {
+  ANNOTATIONS,
+  corpusHealthOf,
+  getDecisionInputSchema,
+  getDecisionOutputSchema,
+  invalidCursor,
+  loadProjection,
+  renderResponseText,
+  structuredResult,
+  toSummary,
+  type DecisionSummary,
+  type FullDecision,
+  type GetDecisionResult,
+  type ToolConfig,
+} from './shared.ts';
+
+interface GetDecisionArgs {
+  readonly ref: string;
+  readonly cursor?: string;
+  readonly limit: number;
+  readonly findingsCursor?: string;
+  readonly findingsLimit: number;
+}
+
+function fullDecision(record: Adr, ref: string): FullDecision {
+  return {
+    requestedRef: ref,
+    id: record.frontmatter.id,
+    title: record.frontmatter.title,
+    status: record.frontmatter.status,
+    sourcePath: record.path,
+    frontmatter: record.frontmatter,
+    body: record.body,
+  };
+}
+
+export function registerGetDecision(server: McpServer, config: ToolConfig): void {
+  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 as GetDecisionArgs;
+
+      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; // get_decision derives none.
+
+      // Findings channel (always applicable).
+      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]);
+
+      // Log-qualified refs are federated-log-unavailable; byId is never consulted.
+      if (parsed.log !== undefined) {
+        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);
+        const result: GetDecisionResult = {
+          outcome: 'federated-log-unavailable',
+          requestedRef: ref,
+          log: parsed.log,
+          id: parsed.id,
+          findings: findingsPage.page,
+        };
+        return structuredResult(
+          result,
+          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: DecisionSummary[] = 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 result: GetDecisionResult = {
+          outcome: 'ambiguous-local-id',
+          requestedRef: ref,
+          candidates: primary.page.items,
+          cursor: primary.page.cursor,
+          findings: findingsPage.page,
+        };
+        return structuredResult(
+          result,
+          renderResponseText({
+            kind: 'ambiguous-local-id',
+            candidatesLength: primary.page.items.length,
+            requestedRef: ref,
+            findings: findingsPage.page.items.length,
+          }),
+          health,
+        );
+      }
+
+      // found / not-found: the primary channel does not exist.
+      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] as Adr;
+        const result: GetDecisionResult = { outcome: 'found', decision: fullDecision(record, ref), findings: findingsPage.page };
+        return structuredResult(
+          result,
+          renderResponseText({ kind: 'found', id: record.frontmatter.id, findings: findingsPage.page.items.length }),
+          health,
+        );
+      }
+
+      const result: GetDecisionResult = { 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: Parameters<typeof invalidCursor>[0], corpusHealth: ReturnType<typeof corpusHealthOf>) {
+        const outcome = invalidCursor(reason);
+        return structuredResult(outcome, renderResponseText({ kind: 'invalid-cursor', reason }), corpusHealth);
+      }
+    },
+  );
+}

package/src/tools/list-superseded.ts

@@ -0,0 +1,148 @@
+/**
+ * @adrkit/mcp — the `list_superseded` tool (US4, contracts/tools.md §7).
+ *
+ * Lists every superseded record with its DIRECT local replacement state, resolving
+ * only unqualified local targets through the fresh `byId` bucket. Never walks
+ * lineage, never embeds candidate arrays, and mints only the two specified derived
+ * finding templates.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { parseAdrRef, type Adr, type Finding } from '@adrkit/core';
+import { sortFindingsCanonical } from '../corpus/ordering.ts';
+import { paginate, queryShapeHash } from '../pagination/cursor.ts';
+import {
+  ANNOTATIONS,
+  corpusHealthOf,
+  invalidCursor,
+  loadProjection,
+  renderResponseText,
+  listSupersededInputSchema,
+  listSupersededOutputSchema,
+  structuredResult,
+  toSummary,
+  type ListSupersededResult,
+  type SupersededByState,
+  type SupersededEntry,
+  type ToolConfig,
+} from './shared.ts';
+
+interface ListSupersededArgs {
+  readonly cursor?: string;
+  readonly limit: number;
+  readonly findingsCursor?: string;
+  readonly findingsLimit: number;
+}
+
+interface ResolvedEntry {
+  readonly entry: SupersededEntry;
+  readonly derived: Finding | undefined;
+}
+
+function resolveEntry(record: Adr, byId: ReadonlyMap<string, readonly Adr[]>): ResolvedEntry {
+  // The schema invariant guarantees a superseded record has supersededBy.
+  const targetRef = record.frontmatter.supersededBy as string;
+  const parsed = parseAdrRef(targetRef);
+  const summary = toSummary(record);
+
+  if (parsed.log !== undefined) {
+    const supersededBy: SupersededByState = {
+      resolved: false,
+      targetRef,
+      reason: 'federated-unavailable',
+      log: parsed.log,
+      id: parsed.id,
+    };
+    const derived: Finding = {
+      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 }, derived };
+  }
+
+  const bucket = byId.get(parsed.id) ?? [];
+  if (bucket.length === 1) {
+    return { entry: { ...summary, supersededBy: { resolved: true, target: toSummary(bucket[0] as Adr) } }, derived: undefined };
+  }
+  if (bucket.length === 0) {
+    return { entry: { ...summary, supersededBy: { resolved: false, targetRef, reason: 'dangling' } }, derived: undefined };
+  }
+  const supersededBy: SupersededByState = { resolved: false, targetRef, reason: 'ambiguous', candidateCount: bucket.length };
+  const derived: Finding = {
+    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 };
+}
+
+export function registerListSuperseded(server: McpServer, config: ToolConfig): void {
+  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 \u2014 no transitive lineage, no embedded candidate arrays.',
+      inputSchema: listSupersededInputSchema(),
+      outputSchema: listSupersededOutputSchema(),
+      annotations: ANNOTATIONS,
+    },
+    async (args) => {
+      const { cursor, limit, findingsCursor, findingsLimit } = args as ListSupersededArgs;
+
+      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: SupersededEntry[] = [];
+      const derivedFindings: Finding[] = [];
+      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: ListSupersededResult = {
+        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: Parameters<typeof invalidCursor>[0]) {
+        return structuredResult(invalidCursor(reason), renderResponseText({ kind: 'invalid-cursor', reason }), health);
+      }
+    },
+  );
+}

package/src/tools/search-decisions.ts

@@ -0,0 +1,131 @@
+/**
+ * @adrkit/mcp — the `search_decisions` tool (US3, contracts/tools.md §5).
+ *
+ * Deterministic normalized literal substring search over id, title, tags, and
+ * body. Filters (status any-of, scope any-of, tags all-of, ANDed) apply before the
+ * normalizer. Graveyard records are included by default. Returns bounded summaries
+ * only — never a body, ranking score, or hidden index.
+ */
+
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { Adr } from '@adrkit/core';
+import { compareCodeUnits } from '../corpus/ordering.ts';
+import { normalize } from '../search/normalize.ts';
+import { paginate, queryShapeHash } from '../pagination/cursor.ts';
+import {
+  ANNOTATIONS,
+  corpusHealthOf,
+  invalidCursor,
+  loadProjection,
+  renderResponseText,
+  searchDecisionsInputSchema,
+  searchDecisionsOutputSchema,
+  structuredResult,
+  toSummary,
+  type SearchDecisionsResult,
+  type SearchMatch,
+  type ToolConfig,
+} from './shared.ts';
+
+interface SearchDecisionsArgs {
+  readonly query: string;
+  readonly status?: string[];
+  readonly tags?: string[];
+  readonly scope?: string[];
+  readonly cursor?: string;
+  readonly limit: number;
+  readonly findingsCursor?: string;
+  readonly findingsLimit: number;
+}
+
+const MATCHED_FIELD_ORDER = ['body', 'id', 'tag', 'title'] as const;
+type MatchedField = (typeof MATCHED_FIELD_ORDER)[number];
+
+function sortedUnique(values: readonly string[] | undefined): string[] {
+  return values ? [...new Set(values)].sort(compareCodeUnits) : [];
+}
+
+function passesFilters(record: Adr, status: string[] | undefined, scope: string[] | undefined, tags: string[] | undefined): boolean {
+  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: Adr, needle: string): MatchedField[] {
+  const fields: MatchedField[] = [];
+  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; // already in the fixed ['body','id','tag','title'] order
+}
+
+export function registerSearchDecisions(server: McpServer, config: ToolConfig): void {
+  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 \u2014 no ranking, no model, no body.',
+      inputSchema: searchDecisionsInputSchema(),
+      outputSchema: searchDecisionsOutputSchema(),
+      annotations: ANNOTATIONS,
+    },
+    async (args) => {
+      const { query, status, tags, scope, cursor, limit, findingsCursor, findingsLimit } = args as SearchDecisionsArgs;
+
+      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: SearchMatch[] = [];
+      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: SearchDecisionsResult = {
+        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: Parameters<typeof invalidCursor>[0]) {
+        return structuredResult(invalidCursor(reason), renderResponseText({ kind: 'invalid-cursor', reason }), health);
+      }
+    },
+  );
+}