@adrkit/mcp 0.2.0

package/src/corpus/projection.ts

@@ -0,0 +1,299 @@
+/**
+ * @adrkit/mcp — the per-call, in-memory corpus projection (data-model.md §3, §8).
+ *
+ * Rebuilt from scratch on every tool call: fresh canonical-root validation, the
+ * pre-read 64 KiB size guard, `discoverAdrFiles` + `lintCorpus`, a local multi-valued
+ * `byId` index, immutable corpus findings, and a canonical SHA-256 fingerprint.
+ * No cache, index, or database of any kind.
+ */
+
+import { access, constants as FS, lstat, realpath, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { discoverAdrFiles, lintCorpus, normalizeDisplayPath, type Adr, type Finding } from '@adrkit/core';
+import { compareCodeUnits, sortFindingsCanonical } from './ordering.ts';
+
+export const MAX_SOURCE_BYTES = 64 * 1024;
+
+export type CorpusUnavailableReason =
+  | 'root-not-found'
+  | 'root-not-directory'
+  | 'root-not-readable'
+  | 'root-not-git'
+  | 'dir-not-found'
+  | 'dir-not-directory'
+  | 'dir-not-readable'
+  | 'dir-outside-root'
+  | 'corpus-changed-during-load';
+
+/** Typed rejection carrying one of the `CorpusUnavailableOutcome` reasons (data-model.md §5). */
+export class CorpusUnavailableError extends Error {
+  readonly reason: CorpusUnavailableReason;
+  constructor(reason: CorpusUnavailableReason) {
+    super(reason);
+    this.name = 'CorpusUnavailableError';
+    this.reason = reason;
+  }
+}
+
+export interface CorpusHealth {
+  readonly fingerprint: string;
+  readonly recordCount: number;
+  readonly excludedCount: number;
+}
+
+export interface CorpusProjection {
+  readonly records: readonly Adr[];
+  readonly byId: ReadonlyMap<string, readonly Adr[]>;
+  readonly corpusFindings: readonly Finding[];
+  readonly fingerprint: string;
+  readonly recordCount: number;
+  readonly excludedCount: number;
+}
+
+function fail(reason: CorpusUnavailableReason): never {
+  throw new CorpusUnavailableError(reason);
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error && typeof error === 'object' && 'code' in error ? String((error as { code: unknown }).code) : undefined;
+}
+
+/** Path-segment-safe containment on two ALREADY-canonical paths (never a string prefix). */
+function isContained(parent: string, child: string): boolean {
+  if (parent === child) return true;
+  const rel = relative(parent, child);
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+export interface ResolveCanonicalRootsOptions {
+  readonly cwd: string;
+  readonly dir: string;
+}
+
+export interface CanonicalRoots {
+  readonly canonicalCwd: string;
+  readonly canonicalDir: string;
+}
+
+/** The one canonicalization/containment routine both `start()` and every load call use. */
+export async function resolveCanonicalRoots(options: ResolveCanonicalRootsOptions): Promise<CanonicalRoots> {
+  let canonicalCwd: string;
+  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: string;
+  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 };
+}
+
+export interface LoadCorpusProjectionOptions {
+  readonly configuredCwd: string;
+  readonly configuredDir: string;
+  readonly expectedCanonicalCwd: string;
+  readonly maxSourceBytes: number;
+}
+
+interface KeptCandidate {
+  readonly absolutePath: string;
+  readonly displayPath: string;
+  readonly identity: { dev: bigint; ino: bigint; size: bigint; mtimeNs: bigint };
+}
+
+function statError(displayPath: string): Finding {
+  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: string): Finding {
+  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: LoadCorpusProjectionOptions): Promise<CanonicalRoots> {
+  const roots = await resolveCanonicalRoots({ cwd: options.configuredCwd, dir: options.configuredDir });
+  if (roots.canonicalCwd !== options.expectedCanonicalCwd) fail('root-not-found');
+  return roots;
+}
+
+function canonicalStringify(value: unknown): string {
+  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 as Record<string, unknown>;
+    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: readonly Adr[], corpusFindings: readonly Finding[], recordCount: number, excludedCount: number): string {
+  const projection = {
+    records: records.map((record) => ({ sourcePath: record.path, frontmatter: record.frontmatter, body: record.body })),
+    corpusFindings,
+    corpusHealth: { recordCount, excludedCount },
+  };
+  return createHash('sha256').update(canonicalStringify(projection), 'utf8').digest('hex');
+}
+
+/** The one entry point every tool handler calls, fresh, at the start of its execution. */
+export async function loadCorpusProjection(options: LoadCorpusProjectionOptions): Promise<CorpusProjection> {
+  const roots = await verifyRoots(options);
+
+  let candidates: string[];
+  try {
+    candidates = await discoverAdrFiles(roots.canonicalDir, roots.canonicalCwd);
+  } catch (error) {
+    fail(errorCode(error) === 'ENOENT' ? 'dir-not-found' : 'dir-not-readable');
+  }
+
+  const preReadFindings: Finding[] = [];
+  const kept: KeptCandidate[] = [];
+
+  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));
+    }
+  }
+
+  // Never call lintCorpus with an empty paths array: expandRecordInputs would
+  // re-discover the whole directory and reinstate the excluded files (data-model.md §3.3).
+  let records: Adr[] = [];
+  let lintFindings: Finding[] = [];
+  if (kept.length > 0) {
+    const result = await lintCorpus({ paths: kept.map((k) => k.absolutePath), cwd: roots.canonicalCwd });
+    records = result.records;
+    lintFindings = result.findings;
+  }
+
+  // Post-load revalidation: roots plus every kept candidate's type, containment, and identity.
+  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<string, Adr[]>();
+  for (const record of orderedRecords) {
+    const bucket = byId.get(record.frontmatter.id) ?? [];
+    bucket.push(record);
+    byId.set(record.frontmatter.id, bucket);
+  }
+  // Each bucket inherits `orderedRecords`' canonical (id, sourcePath) order already.
+
+  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,
+  };
+}

package/src/index.ts

@@ -0,0 +1,96 @@
+/**
+ * @adrkit/mcp — public entry point.
+ *
+ * Exports ONLY the sealed stdio lifecycle factory and its option/handle types.
+ * No SDK server, registration API, internal builder, transport, or test subpath is
+ * reachable from here. No side effects at import time; no filesystem access at
+ * construction time (data-model.md §8, contracts/tools.md §1).
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { resolve } from 'node:path';
+import { buildRegisteredServer } from './server.ts';
+import { resolveCanonicalRoots, MAX_SOURCE_BYTES } from './corpus/projection.ts';
+import type { ToolConfig } from './tools/shared.ts';
+
+export interface AdrkitMcpServerOptions {
+  readonly cwd: string;
+  readonly dir: string;
+}
+
+export interface AdrkitMcpServerHandle {
+  start(): Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * The public stdio lifecycle factory. Performs NO filesystem access at construction;
+ * `start()` validates the configured root, builds the closure-private server, creates
+ * exactly one `StdioServerTransport`, and connects it. The concrete server, its
+ * registrations, and its transport remain unreachable to the caller.
+ */
+export function createAdrkitMcpServer(
+  options?: Partial<AdrkitMcpServerOptions>,
+): Readonly<AdrkitMcpServerHandle> {
+  const cwd = resolve(options?.cwd ?? process.cwd());
+  const dir = options?.dir ?? 'docs/adr';
+
+  let server: McpServer | undefined;
+  let startPromise: Promise<void> | undefined;
+  let closePromise: Promise<void> | undefined;
+  let closed = false;
+
+  function start(): Promise<void> {
+    if (closed) {
+      return Promise.reject(new Error('adrkit MCP server handle is closed'));
+    }
+    if (startPromise) return startPromise;
+
+    startPromise = (async () => {
+      let nextServer: McpServer | undefined;
+      try {
+        const roots = await resolveCanonicalRoots({ cwd, dir });
+        const config: ToolConfig = {
+          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(): Promise<void> {
+    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) as AdrkitMcpServerHandle;
+  handle.start = start;
+  handle.close = close;
+  return Object.freeze(handle);
+}

package/src/main-module.ts

@@ -0,0 +1,82 @@
+/**
+ * @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.
+ */
+
+import { existsSync, realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { createAdrkitMcpServer } from './index.ts';
+import { resolveCanonicalRoots, CorpusUnavailableError } from './corpus/projection.ts';
+import { CORPUS_UNAVAILABLE_MESSAGES } from './tools/shared.ts';
+
+export function isMainModule(moduleUrl: string, argvPath: string | undefined): boolean {
+  if (!argvPath || !existsSync(argvPath)) return false;
+  return realpathSync(fileURLToPath(moduleUrl)) === realpathSync(argvPath);
+}
+
+const USAGE = 'usage: adrkit-mcp [--cwd <path>] [--dir <path>]\n';
+
+function writeStderr(text: string): void {
+  process.stderr.write(text);
+}
+
+export function reportUnhandledRejection(
+  reason: unknown,
+  write: (text: string) => void = writeStderr,
+  fail: () => void = () => {
+    process.exitCode = 1;
+  },
+): void {
+  const detail = reason instanceof Error ? reason.message : String(reason);
+  write(`adrkit-mcp: unhandled rejection: ${detail}\n`);
+  fail();
+}
+
+export async function main(
+  argv: string[],
+  env: Record<string, string | undefined>,
+): Promise<0 | 1 | 2> {
+  let values: { cwd?: string; dir?: string };
+  try {
+    ({ values } = parseArgs({
+      args: argv,
+      options: { cwd: { type: 'string' }, dir: { type: 'string' } },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (error) {
+    writeStderr(`${error instanceof Error ? error.message : String(error)}\n${USAGE}`);
+    return 2;
+  }
+
+  const cwd = values.cwd ?? env.ADRKIT_MCP_CWD ?? process.cwd();
+  const dir = values.dir ?? env.ADRKIT_MCP_DIR ?? 'docs/adr';
+
+  // Fail-fast startup check (FR-036): validate the configured root before any transport.
+  try {
+    await resolveCanonicalRoots({ cwd, dir });
+  } catch (error) {
+    if (error instanceof CorpusUnavailableError) {
+      writeStderr(`${CORPUS_UNAVAILABLE_MESSAGES[error.reason]}\n`);
+      return 1;
+    }
+    throw error;
+  }
+
+  const handle = createAdrkitMcpServer({ cwd, dir });
+
+  const shutdown = (): void => {
+    void handle.close().finally(() => process.exit(0));
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  process.on('unhandledRejection', (reason) => reportUnhandledRejection(reason));
+
+  await handle.start();
+  return 0;
+}

package/src/pagination/cursor.ts

@@ -0,0 +1,162 @@
+/**
+ * @adrkit/mcp — opaque, versioned, query-bound pagination cursors and the
+ * query-shape hash (contracts/pagination-and-cursors.md).
+ */
+
+import { createHash } from 'node:crypto';
+
+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;
+}
+
+const CURSOR_KEYS = ['v', 'scope', 'fp', 'qh', 'offset'] as const;
+
+/** Fixed-field-order base64url(no-pad) UTF-8 JSON — byte-identical for identical payloads. */
+export function encodeCursor(payload: CursorPayloadV1): string {
+  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');
+}
+
+/** SHA-256 hex over a fixed-order canonical JSON array of the hashed parameters. */
+export function queryShapeHash(parts: readonly unknown[]): string {
+  return createHash('sha256').update(JSON.stringify(parts)).digest('hex');
+}
+
+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 };
+
+function decodeStrict(
+  cursor: string,
+): { v: number; scope: string; fp: string; qh: string; offset: number } | undefined {
+  let text: string;
+  try {
+    text = Buffer.from(cursor, 'base64url').toString('utf8');
+  } catch {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
+  const keys = Object.keys(parsed);
+  if (keys.length !== CURSOR_KEYS.length || !CURSOR_KEYS.every((k) => keys.includes(k))) return undefined;
+  const obj = parsed as Record<string, unknown>;
+  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 undefined;
+  }
+  return { v: obj.v, scope: obj.scope, fp: obj.fp, qh: obj.qh, offset: obj.offset };
+}
+
+/** Decode/verify steps 1-6 (pagination §2). */
+export function verifyCursor(options: VerifyCursorOptions): VerifyCursorResult {
+  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 };
+}
+
+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 function paginate<T>(options: PaginateOptions<T>): PaginateResult<T> {
+  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 } };
+}
+
+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 function checkInapplicablePrimaryCursor(options: InapplicablePrimaryOptions): InapplicablePrimaryResult {
+  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' };
+}

package/src/search/normalize.ts

@@ -0,0 +1,9 @@
+/**
+ * @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 function normalize(value: string): string {
+  return value.trim().normalize('NFKC').toLowerCase();
+}

package/src/server.ts

@@ -0,0 +1,27 @@
+/**
+ * @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 { registerSearchDecisions } from './tools/search-decisions.ts';
+import { registerGetDecision } from './tools/get-decision.ts';
+import { registerGetDecisionContext } from './tools/get-decision-context.ts';
+import { registerListSuperseded } from './tools/list-superseded.ts';
+import type { ToolConfig } from './tools/shared.ts';
+
+export const SERVER_INFO = { name: '@adrkit/mcp', version: '0.1.0' } as const;
+
+/** Package-internal: build the concrete server with exactly the four ratified tools. */
+export function buildRegisteredServer(config: ToolConfig): McpServer {
+  const server = new McpServer(SERVER_INFO);
+  registerSearchDecisions(server, config);
+  registerGetDecision(server, config);
+  registerGetDecisionContext(server, config);
+  registerListSuperseded(server, config);
+  return server;
+}