@adrkit/mcp 0.2.0

package/dist/main-module.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @adrkit/mcp — CLI/startup helpers for the `adrkit-mcp` bin.
+ *
+ * The only place `process.argv`/`process.env` are read, the FR-036 startup check
+ * lives, and the `isMainModule()` guard is defined. A local helper mirroring
+ * `packages/cli/src/main-module.ts` (not imported from it). stdout is reserved for
+ * protocol frames; every diagnostic goes to stderr.
+ */
+export declare function isMainModule(moduleUrl: string, argvPath: string | undefined): boolean;
+export declare function reportUnhandledRejection(reason: unknown, write?: (text: string) => void, fail?: () => void): void;
+export declare function main(argv: string[], env: Record<string, string | undefined>): Promise<0 | 1 | 2>;

package/dist/pagination/cursor.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @adrkit/mcp — opaque, versioned, query-bound pagination cursors and the
+ * query-shape hash (contracts/pagination-and-cursors.md).
+ */
+export type CursorScope = 'search.results' | 'search.findings' | 'get_decision.candidates' | 'get_decision.findings' | 'context.results' | 'context.findings' | 'superseded.results' | 'superseded.findings';
+export interface CursorPayloadV1 {
+    readonly v: 1;
+    readonly scope: CursorScope;
+    readonly fp: string;
+    readonly qh: string;
+    readonly offset: number;
+}
+export type InvalidCursorReason = 'decode-failed' | 'version-unsupported' | 'wrong-channel' | 'corpus-changed' | 'query-mismatch' | 'cursor-not-applicable' | 'offset-out-of-range';
+export interface Page<T> {
+    readonly items: readonly T[];
+    readonly cursor: string | null;
+}
+/** Fixed-field-order base64url(no-pad) UTF-8 JSON — byte-identical for identical payloads. */
+export declare function encodeCursor(payload: CursorPayloadV1): string;
+/** SHA-256 hex over a fixed-order canonical JSON array of the hashed parameters. */
+export declare function queryShapeHash(parts: readonly unknown[]): string;
+export interface VerifyCursorOptions {
+    readonly cursor: string;
+    readonly expectedScope: CursorScope;
+    readonly fp: string;
+    readonly qh: string;
+}
+export type VerifyCursorResult = {
+    readonly ok: true;
+    readonly offset: number;
+} | {
+    readonly ok: false;
+    readonly reason: InvalidCursorReason;
+};
+/** Decode/verify steps 1-6 (pagination §2). */
+export declare function verifyCursor(options: VerifyCursorOptions): VerifyCursorResult;
+export interface PaginateOptions<T> {
+    readonly items: readonly T[];
+    readonly cursor: string | undefined;
+    readonly limit: number;
+    readonly scope: CursorScope;
+    readonly fp: string;
+    readonly qh: string;
+}
+export type PaginateResult<T> = {
+    readonly ok: true;
+    readonly page: Page<T>;
+} | {
+    readonly ok: false;
+    readonly reason: InvalidCursorReason;
+};
+/** Full applicable-channel pagination: verify (1-6), range-check (8), slice (9), mint. */
+export declare function paginate<T>(options: PaginateOptions<T>): PaginateResult<T>;
+export interface InapplicablePrimaryOptions {
+    readonly cursor: string | undefined;
+    readonly scope: CursorScope;
+    readonly fp: string;
+    readonly qh: string;
+}
+export type InapplicablePrimaryResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: InvalidCursorReason;
+};
+/** A primary cursor supplied against an outcome with no primary channel (step 7). */
+export declare function checkInapplicablePrimaryCursor(options: InapplicablePrimaryOptions): InapplicablePrimaryResult;

package/dist/search/normalize.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @adrkit/mcp — deterministic search normalization (research §R5).
+ *
+ * `normalize(s) = s.trim().normalize('NFKC').toLowerCase()` — engine-builtin,
+ * non-ICU, locale-independent. No stemming, fuzzy, weighting, or ranking.
+ */
+export declare function normalize(value: string): string;

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @adrkit/mcp — internal server assembly (package-internal, never publicly exported).
+ *
+ * Owns the concrete `McpServer`, its registration APIs, and the in-memory builder
+ * used only by in-process conformance tests. The public factory (`./index.ts`)
+ * exposes only the sealed lifecycle handle. This module is absent from
+ * `package.json#exports` and every public subpath.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolConfig } from './tools/shared.js';
+export declare const SERVER_INFO: {
+    readonly name: "@adrkit/mcp";
+    readonly version: "0.1.0";
+};
+/** Package-internal: build the concrete server with exactly the four ratified tools. */
+export declare function buildRegisteredServer(config: ToolConfig): McpServer;

package/dist/tools/get-decision-context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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 { type ToolConfig } from './shared.js';
+export declare function registerGetDecisionContext(server: McpServer, config: ToolConfig): void;

package/dist/tools/get-decision.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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 { type ToolConfig } from './shared.js';
+export declare function registerGetDecision(server: McpServer, config: ToolConfig): void;

package/dist/tools/list-superseded.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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 { type ToolConfig } from './shared.js';
+export declare function registerListSuperseded(server: McpServer, config: ToolConfig): void;

package/dist/tools/search-decisions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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 ToolConfig } from './shared.js';
+export declare function registerSearchDecisions(server: McpServer, config: ToolConfig): void;

package/dist/tools/shared.d.ts

@@ -0,0 +1,252 @@
+/**
+ * @adrkit/mcp — the shared tool contract: strict Zod input/output schemas, the
+ * fixed annotations, the deterministic text renderer (contracts/tools.md §2.1),
+ * and the wire shapes every tool returns. This is the ONE place limits, the text
+ * templates, and the envelope live.
+ */
+import { z } from 'zod';
+import { AdrFrontmatter, Status, Scope, type Finding, type FiredMatcher } from '@adrkit/core';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { type CorpusHealth, type CorpusProjection, type CorpusUnavailableReason } from '../corpus/projection.js';
+import type { InvalidCursorReason, Page } from '../pagination/cursor.js';
+export type { Finding, FiredMatcher } from '@adrkit/core';
+export type { CorpusHealth } from '../corpus/projection.js';
+export declare const LIMITS: {
+    readonly query: {
+        readonly min: 1;
+        readonly max: 256;
+    };
+    readonly ref: {
+        readonly min: 1;
+        readonly max: 128;
+    };
+    readonly status: {
+        readonly min: 1;
+        readonly max: 6;
+    };
+    readonly scope: {
+        readonly min: 1;
+        readonly max: 3;
+    };
+    readonly tags: {
+        readonly min: 1;
+        readonly max: 32;
+    };
+    readonly tag: {
+        readonly min: 1;
+        readonly max: 64;
+    };
+    readonly fileLength: {
+        readonly min: 1;
+        readonly max: 1024;
+    };
+    readonly files: {
+        readonly min: 1;
+        readonly max: 256;
+    };
+    readonly page: {
+        readonly min: 1;
+        readonly max: 100;
+        readonly default: 20;
+    };
+    readonly cursorBytes: number;
+    readonly textCap: 512;
+};
+export declare const ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+};
+export declare const INVALID_CURSOR_MESSAGES: Record<InvalidCursorReason, string>;
+export declare const CORPUS_UNAVAILABLE_MESSAGES: Record<CorpusUnavailableReason, string>;
+/** `n === 1 ? one : many`. */
+export declare function plural(n: number, one: string, many: string): string;
+/** Immutable per-server config every tool handler reads to load its projection. */
+export interface ToolConfig {
+    readonly configuredCwd: string;
+    readonly configuredDir: string;
+    readonly expectedCanonicalCwd: string;
+    readonly maxSourceBytes: number;
+}
+export type StatusValue = z.infer<typeof Status>;
+export type ScopeValue = z.infer<typeof Scope>;
+export interface DecisionSummary {
+    readonly id: string;
+    readonly title: string;
+    readonly status: StatusValue;
+    readonly sourcePath: string;
+}
+export interface RelationRefs {
+    readonly supersedes: readonly string[];
+    readonly supersededBy: string | null;
+    readonly relatesTo: readonly string[];
+    readonly conflictsWith: readonly string[];
+}
+export interface FullDecision {
+    readonly requestedRef: string;
+    readonly id: string;
+    readonly title: string;
+    readonly status: StatusValue;
+    readonly sourcePath: string;
+    readonly frontmatter: z.infer<typeof AdrFrontmatter>;
+    readonly body: string;
+}
+export interface SearchMatch extends DecisionSummary {
+    readonly matchedFields: readonly ('id' | 'title' | 'tag' | 'body')[];
+}
+export interface ContextEntry extends DecisionSummary {
+    readonly firedMatchers: readonly FiredMatcher[];
+    readonly relations: RelationRefs;
+}
+export type SupersededByState = {
+    readonly resolved: true;
+    readonly target: DecisionSummary;
+} | {
+    readonly resolved: false;
+    readonly targetRef: string;
+    readonly reason: 'dangling';
+} | {
+    readonly resolved: false;
+    readonly targetRef: string;
+    readonly reason: 'ambiguous';
+    readonly candidateCount: number;
+} | {
+    readonly resolved: false;
+    readonly targetRef: string;
+    readonly reason: 'federated-unavailable';
+    readonly log: string;
+    readonly id: string;
+};
+export interface SupersededEntry extends DecisionSummary {
+    readonly supersededBy: SupersededByState;
+}
+export type FindingsPage = Page<Finding>;
+export interface InvalidCursorOutcome {
+    readonly outcome: 'invalid-cursor';
+    readonly reason: InvalidCursorReason;
+    readonly message: string;
+}
+export interface CorpusUnavailableOutcome {
+    readonly outcome: 'corpus-unavailable';
+    readonly reason: CorpusUnavailableReason;
+    readonly message: string;
+}
+export type SearchDecisionsResult = {
+    outcome: 'results';
+    items: readonly SearchMatch[];
+    cursor: string | null;
+    findings: FindingsPage;
+} | InvalidCursorOutcome | CorpusUnavailableOutcome;
+export type GetDecisionResult = {
+    outcome: 'found';
+    decision: FullDecision;
+    findings: FindingsPage;
+} | {
+    outcome: 'not-found';
+    requestedRef: string;
+    findings: FindingsPage;
+} | {
+    outcome: 'ambiguous-local-id';
+    requestedRef: string;
+    candidates: readonly DecisionSummary[];
+    cursor: string | null;
+    findings: FindingsPage;
+} | {
+    outcome: 'federated-log-unavailable';
+    requestedRef: string;
+    log: string;
+    id: string;
+    findings: FindingsPage;
+} | InvalidCursorOutcome | CorpusUnavailableOutcome;
+export type GetDecisionContextResult = {
+    outcome: 'matches';
+    governing: readonly ContextEntry[];
+    activeProposals: readonly ContextEntry[];
+    history: readonly ContextEntry[];
+    cursor: string | null;
+    findings: FindingsPage;
+} | InvalidCursorOutcome | CorpusUnavailableOutcome;
+export type ListSupersededResult = {
+    outcome: 'entries';
+    items: readonly SupersededEntry[];
+    cursor: string | null;
+    findings: FindingsPage;
+} | InvalidCursorOutcome | CorpusUnavailableOutcome;
+export type TextSpec = {
+    kind: 'results';
+    itemsLength: number;
+    findings: number;
+} | {
+    kind: 'found';
+    id: string;
+    findings: number;
+} | {
+    kind: 'not-found';
+    requestedRef: string;
+    findings: number;
+} | {
+    kind: 'ambiguous-local-id';
+    candidatesLength: number;
+    requestedRef: string;
+    findings: number;
+} | {
+    kind: 'federated-log-unavailable';
+    requestedRef: string;
+    findings: number;
+} | {
+    kind: 'matches';
+    governing: number;
+    activeProposals: number;
+    history: number;
+    findings: number;
+} | {
+    kind: 'entries';
+    itemsLength: number;
+    findings: number;
+} | {
+    kind: 'invalid-cursor';
+    reason: InvalidCursorReason;
+} | {
+    kind: 'corpus-unavailable';
+    reason: CorpusUnavailableReason;
+};
+/** Cap a rendered string at 512 UTF-16 code units. */
+export declare function cap512(value: string): string;
+export declare function renderResponseText(spec: TextSpec): string;
+export type ToolInputSchema = z.ZodType;
+export type ToolOutputSchema = z.ZodRawShape;
+export declare function searchDecisionsInputSchema(): ToolInputSchema;
+export declare function getDecisionInputSchema(): ToolInputSchema;
+export declare function getDecisionContextInputSchema(): ToolInputSchema;
+export declare function listSupersededInputSchema(): ToolInputSchema;
+export declare function findingSchema(): z.ZodType;
+export declare function corpusHealthSchema(): z.ZodType;
+export declare function searchDecisionsOutputSchema(): ToolOutputSchema;
+export declare function getDecisionOutputSchema(): ToolOutputSchema;
+export declare function getDecisionContextOutputSchema(): ToolOutputSchema;
+export declare function listSupersededOutputSchema(): ToolOutputSchema;
+export type StructuredResult = CallToolResult;
+export declare function structuredResult(result: unknown, text: string, corpusHealth: CorpusHealth | undefined): CallToolResult;
+export declare function corpusHealthOf(projection: CorpusProjection): CorpusHealth;
+export declare function invalidCursor(reason: InvalidCursorReason): InvalidCursorOutcome;
+export declare function corpusUnavailable(reason: CorpusUnavailableReason): CorpusUnavailableOutcome;
+export type LoadResult = {
+    readonly ok: true;
+    readonly projection: CorpusProjection;
+} | {
+    readonly ok: false;
+    readonly outcome: CorpusUnavailableOutcome;
+};
+/** Load the fresh projection, mapping a typed `CorpusUnavailableError` to its outcome. */
+export declare function loadProjection(config: ToolConfig): Promise<LoadResult>;
+/** Every tool derives its DecisionSummary from an Adr record the same way. */
+export declare function toSummary(record: {
+    frontmatter: {
+        id: string;
+        title: string;
+        status: StatusValue;
+    };
+    path: string;
+}): DecisionSummary;
+export declare function toRelationRefs(frontmatter: z.infer<typeof AdrFrontmatter>): RelationRefs;

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@adrkit/mcp",
+  "version": "0.2.0",
+  "description": "Local, read-only Model Context Protocol server exposing adrkit decision retrieval over stdio.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://adrkit.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mbeacom/adrkit.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/mbeacom/adrkit/issues"
+  },
+  "keywords": [
+    "adr",
+    "architecture-decision-records",
+    "mcp",
+    "model-context-protocol",
+    "governance"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "adrkit-mcp": "./dist/bin.js"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts ./src/bin.ts --target=node --outdir=dist --packages=external && tsc --project tsconfig.build.json && bun ../../scripts/normalize-dts-imports.ts dist && cp ../../LICENSE ../../NOTICE dist/ && chmod +x dist/bin.js",
+    "lint": "bun run typecheck",
+    "prepack": "bun run build",
+    "typecheck": "tsc --noEmit --customConditions bun --project ../../tsconfig.json"
+  },
+  "dependencies": {
+    "@adrkit/core": "0.2.0",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "src"
+  ]
+}

package/src/bin.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * @adrkit/mcp — the `adrkit-mcp` stdio entrypoint.
+ *
+ * Never imported by anything except the compiled `bin` entry itself. Reserves
+ * stdout for protocol frames; all diagnostics go to stderr.
+ */
+
+import { isMainModule, main } from './main-module.ts';
+
+if (isMainModule(import.meta.url, process.argv[1])) {
+  process.exitCode = await main(process.argv.slice(2), process.env);
+}

package/src/corpus/ordering.ts

@@ -0,0 +1,41 @@
+/**
+ * @adrkit/mcp — the one locale-independent comparator and the canonical orderings
+ * every channel uses. Never `String.prototype.localeCompare` (research §R6).
+ */
+
+import type { Finding } from '@adrkit/core';
+
+/** The sole code-unit comparator: `a < b ? -1 : a > b ? 1 : 0` over UTF-16 units. */
+export function compareCodeUnits(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+export interface OrderedSummary {
+  readonly id: string;
+  readonly sourcePath: string;
+}
+
+/** Canonical `(id, sourcePath)` ascending order; sourcePath is the unique tiebreak. */
+export function compareByIdThenPath(a: OrderedSummary, b: OrderedSummary): number {
+  return compareCodeUnits(a.id, b.id) || compareCodeUnits(a.sourcePath, b.sourcePath);
+}
+
+/** Canonical finding order using `sortFindings`' field tuple with the code-unit comparator. */
+export function compareFindings(a: Finding, b: Finding): number {
+  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)
+  );
+}
+
+export function sortFindingsCanonical(findings: readonly Finding[]): Finding[] {
+  return [...findings].sort(compareFindings);
+}
+
+export function sortByIdThenPath<T extends OrderedSummary>(items: readonly T[]): T[] {
+  return [...items].sort(compareByIdThenPath);
+}