reviewzy 0.1.0

package/src/mcp/file-entries.ts

@@ -0,0 +1,219 @@
+import { createHash } from "node:crypto";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { fileEntries, type NewEntry } from "../db/queries.ts";
+import type { Store } from "../db/store.ts";
+import type { Notifier } from "../notify.ts";
+
+/**
+ * A project slug is 1-63 chars of lowercase letters, digits, and inner hyphens. Lowercase-only is
+ * the load-bearing half: slugs name resource URIs (`reviewzy://projects/{slug}/style-guide`) and
+ * dashboard paths, and a case pair would fold into one path on a case-insensitive mount while
+ * sqlite holds two projects.
+ */
+const SLUG = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+
+/** sha256 as 64 lowercase hex chars: the shape of `anchor_hash` and of a caller-supplied `file_hash`. */
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/** `context` is free-form notes for the human; the only shape it must have is "a json object". */
+const ContextJson = z.record(z.string(), z.json());
+
+/**
+ * The contract's constraint fields, strict so a misspelling (`maxLen`) is refused by name instead
+ * of silently dropping the constraint it was meant to carry.
+ */
+const ConstraintsJson = z.strictObject({
+  max_len: z.number().int().positive().optional(),
+  placeholders: z
+    .array(z.string().min(1))
+    .refine((items) => new Set(items).size === items.length, "placeholder names must be unique")
+    .optional(),
+  tone: z.string().optional(),
+  notes: z.string().optional(),
+});
+
+/**
+ * Held loose on purpose. The SDK's own schema check would refuse a malformed constraints with an
+ * isError tool result naming the tool and the field path ("entries.0.constraints"). The handler's
+ * refusal adds what that cannot: the entry (file and anchor) and the fix. So `context` and
+ * `constraints` stay untyped here and are validated below.
+ */
+const FileEntryArgs = z.object({
+  repo: z.string().min(1),
+  file: z.string().min(1),
+  anchor_text: z.string().min(1),
+  anchor_before: z.string().optional(),
+  anchor_after: z.string().optional(),
+  agent_draft: z.string().optional(),
+  file_content: z.string().optional(),
+  file_hash: z.string().optional(),
+  context: z.unknown().optional(),
+  constraints: z.unknown().optional(),
+});
+
+const FiledOutput = z.object({
+  batch_id: z.string(),
+  results: z.array(
+    z.object({
+      id: z.string(),
+      status: z.enum(["draft", "approved", "applied", "rejected"]),
+      deduped: z.boolean(),
+      updated: z.boolean(),
+    }),
+  ),
+  dashboard_url: z.string(),
+});
+
+const sha256 = (text: string) => createHash("sha256").update(text).digest("hex");
+
+/** The `where` of a refusal: the entry's place in the call plus enough of it to spot it in a repo. */
+function entryName(index: number, file: string, anchorText: string): string {
+  return `entries[${index}] (${file}, anchor "${anchorText.slice(0, 40)}")`;
+}
+
+/** A refusal is an ordinary thrown Error: the SDK answers it as a tool result with `isError: true`, never as a json-rpc protocol error. */
+function refuse(where: string, problem: string, fix: string): never {
+  throw new Error(`file_entries refused: ${where}: ${problem}. fix: ${fix}`);
+}
+
+const CONSTRAINT_FIX: Record<string, string> = {
+  max_len: "send constraints.max_len as an integer greater than 0",
+  placeholders: "send constraints.placeholders as an array of unique non-empty strings",
+  tone: "send constraints.tone as a string",
+  notes: "send constraints.notes as a string",
+};
+
+/** Turns zod's issues into the named-field refusal the contract's error row promises. */
+function refuseConstraints(index: number, file: string, anchorText: string, issues: readonly z.ZodIssue[]): never {
+  const where = entryName(index, file, anchorText);
+  const problem = issues
+    .map((issue) => `constraints.${issue.path.join(".") || "(root)"}: ${issue.message}`)
+    .join("; ");
+  const firstField = String(issues[0]?.path[0] ?? "");
+  const unrecognized = issues.some((issue) => issue.code === "unrecognized_keys");
+  const fix = unrecognized
+    ? "constraints takes only max_len, placeholders, tone, and notes; drop the extra key or spell it snake_case"
+    : (CONSTRAINT_FIX[firstField] ?? "send constraints as an object of max_len, placeholders, tone, and notes");
+  return refuse(where, problem, fix);
+}
+
+/**
+ * One entry from wire shape to store shape: json validated at this boundary, `anchor_hash` always
+ * computed here, and file provenance taken from exactly one of `file_content` (the server hashes
+ * it) or `file_hash` (the caller already did). The server never reads a repo, so it can never
+ * invent this value: an entry carrying neither is refused rather than filed with a fake hash.
+ */
+function validateEntry(index: number, raw: z.output<typeof FileEntryArgs>): NewEntry {
+  const where = entryName(index, raw.file, raw.anchor_text);
+
+  const context = ContextJson.safeParse(raw.context ?? {});
+  if (!context.success) {
+    refuse(
+      where,
+      `context must be a json object of free-form notes for the human (where the string renders, surrounding code), got ${JSON.stringify(
+        raw.context,
+      )?.slice(0, 60)}`,
+      'send an object such as {"where": "hero button"}, or omit context entirely',
+    );
+  }
+
+  const constraints = ConstraintsJson.safeParse(raw.constraints ?? {});
+  if (!constraints.success) {
+    refuseConstraints(index, raw.file, raw.anchor_text, constraints.error.issues);
+  }
+
+  let fileHash: string;
+  if (raw.file_content !== undefined && raw.file_hash !== undefined) {
+    refuse(
+      where,
+      "file_content and file_hash both sent, so the server cannot tell which is authoritative",
+      "send file_content alone (preferred: the server hashes it) and drop file_hash",
+    );
+  } else if (raw.file_content !== undefined) {
+    fileHash = sha256(raw.file_content);
+  } else if (raw.file_hash !== undefined) {
+    if (!SHA256_HEX.test(raw.file_hash)) {
+      refuse(
+        where,
+        `file_hash must be sha256 as 64 lowercase hex characters, got "${raw.file_hash.slice(0, 20)}"`,
+        "send the sha256 hex of the whole file, or send file_content and let the server hash it",
+      );
+    }
+    fileHash = raw.file_hash;
+  } else {
+    refuse(
+      where,
+      "no file provenance: the server never reads repos, so it cannot know what the file looked like",
+      "send file_content (the whole file at filing time) or file_hash (its sha256), exactly one",
+    );
+  }
+
+  return {
+    repo: raw.repo,
+    file: raw.file,
+    anchorText: raw.anchor_text,
+    anchorBefore: raw.anchor_before ?? "",
+    anchorAfter: raw.anchor_after ?? "",
+    anchorHash: sha256(raw.anchor_text),
+    fileHash,
+    agentDraft: raw.agent_draft ?? null,
+    // null (absent or explicit null) means "the newer call does not carry this field": a draft
+    // re-file then keeps the stored value, per the COALESCE in src/db/queries.ts.
+    contextJson: raw.context == null ? null : JSON.stringify(context.data),
+    constraintsJson: raw.constraints == null ? null : JSON.stringify(constraints.data),
+  };
+}
+
+/**
+ * Registers the contract's one writing tool. Every entry in one call shares the minted batch id,
+ * and each resolves against the identity key per the frozen re-file table: a known `draft` is
+ * overwritten in place, anything past `draft` comes back untouched — which is what silences a
+ * re-file against a rejected anchor.
+ */
+export function registerFileEntriesTool(server: McpServer, baseUrl: string, store: Store, notifier: Notifier): void {
+  server.registerTool(
+    "file_entries",
+    {
+      title: "File entries for review",
+      description:
+        "File draft entries for a human to author or approve. Each entry names one exact string to replace: repo (git remote url preferred), file path, anchor_text, and anchor_before/anchor_after context lines. Identity is (project, repo, file, sha256(anchor_text)): re-filing a known draft overwrites the agent draft, context, and constraints in place; an entry already approved, applied, or rejected is returned untouched with its own status, and a rejected anchor stays rejected — stop proposing a turned-down line. file provenance: send exactly one of file_content (the whole file at filing time; the server hashes it) or file_hash (its sha256 hex). constraints: {max_len?, placeholders?: string[], tone?, notes?} — a save breaking max_len or dropping a placeholder is refused later, so declare what the copy must keep. Keys the schema does not list are ignored.",
+      inputSchema: z.object({
+        project: z.string().min(1),
+        entries: z.array(FileEntryArgs).min(1),
+        filed_by: z.string().min(1).optional(),
+      }),
+      outputSchema: FiledOutput,
+    },
+    async (args) => {
+      if (!SLUG.test(args.project)) {
+        refuse(
+          `project "${args.project}"`,
+          "a project slug is 1-63 chars of lowercase letters, digits, and inner hyphens",
+          'lower-case the name and separate words with hyphens, e.g. "my-app"',
+        );
+      }
+
+      const entries = args.entries.map((raw, index) => validateEntry(index, raw));
+      const batch = fileEntries(store, args.project, args.filed_by ?? null, entries);
+
+      // The ping announces work for the human, so only a batch that changed the store fires: an
+      // all-dedupe no-op re-file (the agent loop re-proposing known lines) stays silent, and a
+      // refused call throws before reaching this line.
+      const changed = batch.results.filter((r) => !r.deduped || r.updated).length;
+      if (changed > 0) notifier.notifyBatch(args.project, batch.batchId, changed);
+
+      const output = {
+        batch_id: batch.batchId,
+        results: batch.results,
+        // The project-filtered list view: `/projects/{slug}` never existed as a route, so the old
+        // link 404ed (flagged by the task-13 browser pass).
+        dashboard_url: `${baseUrl}/?project=${encodeURIComponent(args.project)}`,
+      };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  );
+}

package/src/mcp/list-entries.ts

@@ -0,0 +1,107 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { listEntries, projectIdBySlug } from "../db/queries.ts";
+import type { Store } from "../db/store.ts";
+
+/**
+ * Every filter optional, `limit` bounded at the boundary rather than clamped: a caller asking for
+ * 201 rows gets a refusal naming the field, never a silently smaller page. The `ids` and `q`
+ * minimums refuse the degenerate inputs (an empty list, an empty search) instead of guessing what
+ * they meant.
+ */
+const ListEntriesArgs = z.object({
+  project: z.string().min(1).optional(),
+  status: z.enum(["draft", "approved", "applied", "rejected"]).optional(),
+  ids: z.array(z.string().min(1)).min(1).optional(),
+  q: z.string().min(1).optional(),
+  limit: z.number().int().min(1).max(200).default(50),
+  cursor: z.string().min(1).optional(),
+});
+
+/** The wire row is the stored row, `context` and `constraints` kept as their stored JSON strings — no re-parse on the way out. */
+const Entry = z.object({
+  id: z.string(),
+  project_id: z.string(),
+  batch_id: z.string(),
+  repo: z.string(),
+  file: z.string(),
+  anchor_text: z.string(),
+  anchor_before: z.string(),
+  anchor_after: z.string(),
+  anchor_hash: z.string(),
+  file_hash: z.string(),
+  agent_draft: z.string().nullable(),
+  human_text: z.string().nullable(),
+  status: z.enum(["draft", "approved", "applied", "rejected"]),
+  context: z.string(),
+  constraints: z.string(),
+  filed_by: z.string().nullable(),
+  stale_note: z.string().nullable(),
+  applied_hash: z.string().nullable(),
+  created_at: z.number(),
+  updated_at: z.number(),
+  applied_at: z.number().nullable(),
+  archived_at: z.number().nullable(),
+});
+
+const ListEntriesOutput = z.object({
+  entries: z.array(Entry),
+  next_cursor: z.string().optional(),
+});
+
+/** A refusal is an ordinary thrown Error: the SDK answers it as a tool result with `isError: true`, never as a json-rpc protocol error. */
+function refuse(where: string, problem: string, fix: string): never {
+  throw new Error(`list_entries refused: ${where}: ${problem}. fix: ${fix}`);
+}
+
+/**
+ * Registers the contract's read tool. The project lookup and the refusal sit here, not in the
+ * query: reads never auto-create a project, so an unknown slug must surface as a business refusal
+ * naming the slug and the fix before any query runs.
+ */
+export function registerListEntriesTool(server: McpServer, store: Store): void {
+  server.registerTool(
+    "list_entries",
+    {
+      title: "List entries for review",
+      description:
+        "List entries in the review queue, ordered by ascending entry id (ulid, i.e. filing order) — the same order a cursor walk covers. Every filter is optional and they combine with AND: project (a slug with no project is refused: read tools never create one), status (draft, approved, applied, rejected), ids (exact entry ids), q (case-insensitive substring, ASCII-only case fold: a row matches when any of file, anchor_text, agent_draft, human_text contains it), limit (default 50, max 200 — a higher value is refused), cursor (keyset pagination: pass the previous page's next_cursor to continue from after the last entry returned). next_cursor is present only when the page returned exactly limit rows, meaning more may exist; absent means the walk is exhausted — stop paging then, never craft a cursor of your own. Each entry carries its stored fields as stored: id, project_id, batch_id, repo, file, anchor_text, anchor_before, anchor_after, anchor_hash, file_hash, agent_draft, human_text, status, context, constraints, filed_by, stale_note, applied_hash, created_at, updated_at, applied_at, archived_at — with context and constraints as their stored JSON strings, not parsed objects.",
+      inputSchema: ListEntriesArgs,
+      outputSchema: ListEntriesOutput,
+    },
+    async (args) => {
+      let projectId: string | undefined;
+      if (args.project !== undefined) {
+        const id = projectIdBySlug(store, args.project);
+        if (id === null) {
+          refuse(
+            `project "${args.project}"`,
+            "no such project, and a read tool never creates one",
+            "file an entry into it with file_entries first, then list again",
+          );
+        }
+        projectId = id;
+      }
+
+      const { rows, nextCursor } = listEntries(store, {
+        projectId,
+        status: args.status,
+        ids: args.ids,
+        q: args.q,
+        limit: args.limit,
+        cursor: args.cursor,
+      });
+
+      // An exhausted walk carries no `next_cursor` key at all: absent is the signal to stop, so an
+      // empty page must never smuggle one in.
+      const output = {
+        entries: rows,
+        ...(nextCursor === null ? {} : { next_cursor: nextCursor }),
+      };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  );
+}

package/src/mcp/mark-applied.ts

@@ -0,0 +1,103 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import { markApplied, type EntryStatus } from "../db/queries.ts";
+import type { Store } from "../db/store.ts";
+
+/** sha256 as 64 lowercase hex chars: the same shape file_entries checks on a caller-supplied `file_hash`. */
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+
+/**
+ * The contract's four params. `applied_hash` and `found_text` are optional, and each is refused at
+ * this boundary when malformed: the hash must be the sha256 hex shape, and an empty `found_text`
+ * says nothing about what the anchor matched instead.
+ */
+const MarkAppliedArgs = z.object({
+  id: z.string().min(1),
+  result: z.enum(["applied", "anchor_stale"]),
+  applied_hash: z.string().regex(SHA256_HEX).optional(),
+  found_text: z.string().min(1).optional(),
+});
+
+/** The loop-close answer: the id and the resulting status, nothing more. */
+const MarkAppliedOutput = z.object({
+  id: z.string(),
+  status: z.enum(["applied", "approved"]),
+});
+
+/** A refusal is an ordinary thrown Error: the SDK answers it as a tool result with `isError: true`, never as a json-rpc protocol error. */
+function refuse(where: string, problem: string, fix: string): never {
+  throw new Error(`mark_applied refused: ${where}: ${problem}. fix: ${fix}`);
+}
+
+/**
+ * Registers the contract's loop-close tool: the agent reports that it applied the approved text,
+ * or that the anchor no longer matches. Wire shapes are validated here, the status machine lives
+ * in `markApplied` (src/db/queries.ts), and this layer only formats the refusals the store returns
+ * — naming the entry, its status, and the fix. The one rule that needs no store read, `applied_hash`
+ * only ever being set by result "applied", is refused here naming the field.
+ */
+export function registerMarkAppliedTool(server: McpServer, store: Store): void {
+  server.registerTool(
+    "mark_applied",
+    {
+      title: "Report an applied entry or a stale anchor",
+      description:
+        "Report the outcome of applying one entry's approved text, closing the loop: result \"applied\" moves an approved entry to applied and stamps applied_at; result \"anchor_stale\" returns the entry to approved and records found_text (optional — what the anchor matched instead; an empty string is refused, so send the matched text or omit the field) in stale_note for re-anchoring on the dashboard. applied_hash (optional) stores the sha256 hex of the text you applied — 64 lowercase hex characters, refused at the boundary when malformed — and is only ever accepted with result \"applied\". Returns {id, status} with the resulting status. Refused, naming the entry, its status, and the fix: an unknown id; an entry in draft (inert until a human approves or rejects it — an agent can never move a draft); an entry in rejected (terminal); an applied entry reported applied again; applied_hash sent with anchor_stale. approved + anchor_stale stays approved; applied + anchor_stale returns to approved; those and approved + applied are the whole agent-side surface.",
+      inputSchema: MarkAppliedArgs,
+      outputSchema: MarkAppliedOutput,
+    },
+    async (args) => {
+      if (args.result === "anchor_stale" && args.applied_hash !== undefined) {
+        refuse(
+          `entry "${args.id}"`,
+          'applied_hash is only ever set by result "applied", got result "anchor_stale"',
+          'drop applied_hash, or report result "applied"',
+        );
+      }
+
+      const outcome = markApplied(store, {
+        id: args.id,
+        result: args.result,
+        appliedHash: args.applied_hash ?? null,
+        foundText: args.found_text ?? null,
+      });
+      if (!outcome.ok) {
+        if (outcome.refusal.kind === "unknown") {
+          refuse(
+            `entry "${args.id}"`,
+            "no such entry",
+            "file it with file_entries first, or list entries to see the ids that exist",
+          );
+        }
+        const status: EntryStatus = outcome.refusal.status;
+        if (status === "draft") {
+          refuse(
+            `entry "${args.id}"`,
+            "status draft: a draft is inert until a human approves or rejects it, and an agent can never move it",
+            "approve or reject it on the dashboard first, then report again",
+          );
+        }
+        if (status === "rejected") {
+          refuse(
+            `entry "${args.id}"`,
+            "status rejected: rejected is terminal and silences the agent",
+            "file a new entry with a new anchor if the line still needs changing",
+          );
+        }
+        // The only pair left is an applied entry reported applied again: anchor_stale on an
+        // applied entry is the third legal transition, so it never reaches this branch.
+        refuse(
+          `entry "${args.id}"`,
+          "status applied: the entry is already applied",
+          "nothing to do — re-file the entry only if the text changed and needs a fresh review",
+        );
+      }
+
+      const output = { id: args.id, status: outcome.status };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(output) }],
+        structuredContent: output,
+      };
+    },
+  );
+}

package/src/mcp/route.ts

@@ -0,0 +1,88 @@
+import {
+  bearerAuthChallengeResponse,
+  createMcpHandler,
+  OAuthError,
+  OAuthErrorCode,
+} from "@modelcontextprotocol/server";
+import type { Hono } from "hono";
+import { timingSafeEqual } from "hono/utils/buffer";
+import type { Config } from "../config.ts";
+import type { Store } from "../db/store.ts";
+import { Notifier } from "../notify.ts";
+import { createMcpServer } from "./server.ts";
+
+/** One endpoint, POST only. `docs/mcp-contract.md` freezes the surface. */
+const MCP_PATH = "/mcp";
+
+/**
+ * A refusal made before the SDK sees the request. `-32000` matches the SDK's own 403 and 405 down
+ * to the message string, which is why those two rungs use it.
+ */
+function refuse(status: 403 | 405, message: string, headers: Record<string, string> = {}) {
+  return new Response(JSON.stringify({ jsonrpc: "2.0", error: { code: -32000, message }, id: null }), {
+    status,
+    headers: { "content-type": "application/json", ...headers },
+  });
+}
+
+/**
+ * `hono/bearer-auth` answers a malformed `Authorization` header with 400, which collides with the
+ * `-32020` header-mismatch rung below this one; every credential failure here is one 401 instead.
+ */
+async function tokenAccepted(header: string | undefined, token: string): Promise<boolean> {
+  // RFC 7235 makes the scheme case-insensitive.
+  const presented = /^bearer +(.+)$/i.exec(header ?? "")?.[1];
+  if (presented === undefined) return false;
+  return timingSafeEqual(token, presented);
+}
+
+/**
+ * The reference implementation's own 401: an OAuth challenge body plus `WWW-Authenticate`, the
+ * shape `bearerAuthChallengeResponse` emits. Built from its own exports so the two cannot drift.
+ */
+function authRequired(description: string): Response {
+  return bearerAuthChallengeResponse(new OAuthError(OAuthErrorCode.InvalidToken, description));
+}
+
+/**
+ * Mounts the stateless MCP endpoint. The checks run in a pinned order, and the order is the
+ * contract: a request refused by a lower rung must never reveal that a higher one would have
+ * passed. Everything past the gate is the SDK's: `_meta` validation, header-versus-body agreement,
+ * revision negotiation, and the method registry.
+ */
+// The default notifier serves direct mounts (tests): built over the same config `createApp` uses,
+// so a mount with no transports armed stays silent exactly like the daemon's.
+export function mountMcp(
+  app: Hono,
+  config: Config,
+  store: Store,
+  notifier: Notifier = new Notifier({ config, baseUrl: config.baseUrl }),
+): void {
+  // `legacy: 'reject'` is the whole of the revision guard, so the endpoint serves only the one
+  // revision `docs/mcp-contract.md` freezes. `supportedProtocolVersions` on the server cannot do
+  // it and is deliberately unset: the SDK's `installDiscoverHandler` unions its served modern
+  // revisions back into that array regardless of what was passed, and on a legacy leg
+  // (`Server._oninitialize`) the list only picks WHICH 2025-era revision to answer with —
+  // `legacyVersions[0] ?? LATEST_PROTOCOL_VERSION`, and `LATEST_PROTOCOL_VERSION` is
+  // `"2025-11-25"`. A modern-only list empties `legacyVersions`, which is exactly what reaches
+  // that hardcoded fallback, so narrowing it is what would serve one.
+  // The store is the daemon's own open handle (`startDaemon` opens it before the port binds), so
+  // every tool call writes through the one connection the daemon will close on shutdown.
+  const handler = createMcpHandler(() => createMcpServer(config, store, notifier), { legacy: "reject" });
+
+  // The `Origin` rung is `originGate`, mounted app-wide in `createApp`; it runs before this
+  // handler, so the pinned order (origin, then method, then credential) holds without a repeat of
+  // the check here.
+  app.all(MCP_PATH, async (c) => {
+    if (c.req.method !== "POST") {
+      return refuse(405, "Method not allowed.", { allow: "POST" });
+    }
+
+    const token = config.REVIEWZY_TOKEN;
+    if (token !== undefined && !(await tokenAccepted(c.req.header("Authorization"), token))) {
+      return authRequired("REVIEWZY_TOKEN is set; a bearer token is required");
+    }
+
+    return handler.fetch(c.req.raw);
+  });
+}

package/src/mcp/server.ts

@@ -0,0 +1,59 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import type { Config } from "../config.ts";
+import type { Store } from "../db/store.ts";
+import { registerAwaitApprovedTool } from "./await-approved.ts";
+import { registerFetchApprovedTool } from "./fetch-approved.ts";
+import { registerFileEntriesTool } from "./file-entries.ts";
+import { registerListEntriesTool } from "./list-entries.ts";
+import { registerMarkAppliedTool } from "./mark-applied.ts";
+import { registerStyleGuideResource } from "./style-guide-resource.ts";
+import type { Notifier } from "../notify.ts";
+import { NAME, VERSION } from "../version.ts";
+
+/**
+ * Read by a client before it calls anything, so it states the rule an agent cannot discover from a
+ * tool signature: prose belongs to the human, and filing a draft is not shipping it.
+ */
+const INSTRUCTIONS = `reviewzy is a review queue for user-facing text. Agents draft, a human signs off.
+
+File the strings you want to change as draft entries against a project. A human authors or approves the wording on the dashboard, then you fetch those words back and apply them in place. You can create a draft, move an approved entry to applied, and report an anchor that no longer matches. You can never approve or reject an entry, and a rejected anchor stays rejected: re-filing it returns the existing entry instead of proposing the line again.`;
+
+/**
+ * A fresh server per request, since the 2026-07-28 revision is stateless and `createMcpHandler`
+ * builds one instance per HTTP request. Every instance registers the tools over the same store the
+ * daemon opened at boot, so the write path never opens a connection of its own; later queue tasks
+ * register theirs the same way.
+ */
+export function createMcpServer(config: Config, store: Store, notifier: Notifier): McpServer {
+  const server: McpServer = new McpServer(
+    { name: NAME, version: VERSION },
+    {
+      // The keys do not gate handler registration: `registerTool` and `registerResource` install
+      // the `tools/*` and `resources/*` handlers regardless, and merge a dropped key back in with
+      // `listChanged` defaulted to `true` (measured on this SDK). The keys' real job is pinning
+      // that `listChanged` to `false`: v1 has no notification stream to carry the change
+      // notification, and an advertised `true` is what makes the SDK honor a client's
+      // `toolsListChanged`/`resourcesListChanged` subscription request.
+      capabilities: { tools: { listChanged: false }, resources: { listChanged: false } },
+      instructions: INSTRUCTIONS,
+      // The SDK's own default is `ttlMs: 0`, which tells a client the answer is already stale. Both
+      // of these are fixed for a running daemon, so they are good for as long as the process lives.
+      // `private` because the endpoint can be bearer-guarded, and a `public` result may be served to
+      // any caller by a shared cache. `resources/templates/list` is pinned to 60s by the contract,
+      // and `resources/read` carries the same values from the resource's own cacheHint.
+      cacheHints: {
+        "server/discover": { ttlMs: 3_600_000, cacheScope: "private" },
+        "tools/list": { ttlMs: 3_600_000, cacheScope: "private" },
+        "resources/templates/list": { ttlMs: 60_000, cacheScope: "private" },
+      },
+    },
+  );
+
+  registerFileEntriesTool(server, config.baseUrl, store, notifier);
+  registerListEntriesTool(server, store);
+  registerFetchApprovedTool(server, store);
+  registerMarkAppliedTool(server, store);
+  registerAwaitApprovedTool(server, store);
+  registerStyleGuideResource(server, store);
+  return server;
+}

package/src/mcp/style-guide-resource.ts

@@ -0,0 +1,40 @@
+import { ResourceNotFoundError, ResourceTemplate } from "@modelcontextprotocol/server";
+import type { McpServer } from "@modelcontextprotocol/server";
+import { projectIdBySlug } from "../db/queries.ts";
+import { mergedStyleGuide } from "../db/style-guide.ts";
+import type { Store } from "../db/store.ts";
+
+/** The pinned resource of `docs/mcp-contract.md`'s resource section; `{slug}` is the only variable. */
+const STYLE_GUIDE_TEMPLATE = "reviewzy://projects/{slug}/style-guide";
+
+/**
+ * Registers the contract's one resource: the merged style guide, served to a drafting agent before
+ * it writes a word. `list` stays undefined so the template is advertised through
+ * `resources/templates/list` only — v1 has no notification stream, and a client enumerating
+ * concrete `resources/list` entries would be fed a list it cannot subscribe to.
+ */
+export function registerStyleGuideResource(server: McpServer, store: Store): void {
+  server.registerResource(
+    "style-guide",
+    new ResourceTemplate(STYLE_GUIDE_TEMPLATE, { list: undefined }),
+    {
+      title: "Style guide",
+      description:
+        "The merged style guide for a project: the global guide, then the project's own rules below it, then the union of banned words and the glossary (a term defined in both resolves to the project). Read this before drafting any entry.",
+      mimeType: "text/markdown",
+      // The read is a pure function of the store, so a 60s TTL is safe; `private` because the
+      // endpoint can be bearer-guarded and a shared cache may not serve one tenant's copy to
+      // another. The same values must appear on `resources/templates/list` via the server-level
+      // cacheHints entry in src/mcp/server.ts.
+      cacheHint: { ttlMs: 60_000, cacheScope: "private" },
+    },
+    (uri, variables) => {
+      const slug = String(variables.slug);
+      if (projectIdBySlug(store, slug) === null) {
+        // The SDK's own miss shape: `-32602` with `data.uri`, never a business tool result.
+        throw new ResourceNotFoundError(uri.href);
+      }
+      return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: mergedStyleGuide(store, slug) }] };
+    },
+  );
+}