@cerefox/memory 0.7.1 → 0.8.0

package/dist/server-assets/_shared/mcp-tools/audit-log.ts

@@ -0,0 +1,95 @@
+/**
+ * `cerefox_get_audit_log` — retrieve audit log entries with filters
+ * (document, author, operation, time range, limit).
+ */
+
+import type { MCPSupabaseClient } from "./types.ts";
+
+import { logUsage } from "./_utils.ts";
+import type { ToolContext, ToolDefinition } from "./types.ts";
+
+async function handler(
+  supabase: MCPSupabaseClient,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<string> {
+  const params: Record<string, unknown> = {};
+  if (args.document_id) params.p_document_id = args.document_id;
+  if (args.author) params.p_author = args.author;
+  if (args.operation) params.p_operation = args.operation;
+  if (args.since) params.p_since = args.since;
+  if (args.until) params.p_until = args.until;
+  if (args.limit) params.p_limit = Math.min(Number(args.limit) || 50, 200);
+
+  const { data, error } = await supabase.rpc("cerefox_list_audit_entries", params);
+
+  if (error) throw new Error(`RPC error: ${error.message}`);
+
+  const entries = (data ?? []) as Array<{
+    id: string;
+    document_id: string | null;
+    doc_title: string | null;
+    operation: string;
+    author: string;
+    author_type: string;
+    size_before: number | null;
+    size_after: number | null;
+    description: string;
+    created_at: string;
+  }>;
+
+  logUsage(supabase, {
+    operation: "get_audit_log",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor as string | undefined,
+    result_count: entries.length,
+  });
+
+  if (!entries.length) return "No audit log entries found.";
+
+  const lines = entries.map((e) => {
+    const docLabel =
+      e.doc_title ?? (e.document_id ? e.document_id.slice(0, 8) + "..." : "(deleted)");
+    const sizeInfo =
+      e.size_before != null && e.size_after != null
+        ? ` | ${e.size_before} -> ${e.size_after} chars`
+        : e.size_after != null
+          ? ` | ${e.size_after} chars`
+          : "";
+    return `${e.created_at.slice(0, 19)} | ${e.operation} | ${e.author} (${e.author_type}) | ${docLabel}${sizeInfo} | ${e.description}`;
+  });
+  return `Audit log (${entries.length} entries, newest first):\n\n${lines.join("\n")}`;
+}
+
+export const auditLogTool: ToolDefinition = {
+  name: "cerefox_get_audit_log",
+  description:
+    "Retrieve audit log entries showing who changed what and when. Supports filtering by document, author, operation type, and time range. Returns entries with document titles, author attribution, size changes, and descriptions.",
+  inputSchema: {
+    type: "object",
+    required: [],
+    properties: {
+      document_id: { type: "string", description: "Filter by document UUID (optional)" },
+      author: { type: "string", description: "Filter by author name (optional)" },
+      operation: {
+        type: "string",
+        description:
+          "Filter by operation type: create, update-content, update-metadata, delete, status-change, archive, unarchive (optional)",
+      },
+      since: {
+        type: "string",
+        description: "ISO timestamp lower bound for temporal queries (optional)",
+      },
+      limit: {
+        type: "integer",
+        description: "Maximum number of entries to return (default: 50, max: 200)",
+      },
+      requestor: {
+        type: "string",
+        description:
+          'Name of the agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent" if not provided. May be enforced via server config.',
+      },
+    },
+  },
+  handler,
+};

package/dist/server-assets/_shared/mcp-tools/get-document.ts

@@ -0,0 +1,73 @@
+/**
+ * `cerefox_get_document` — retrieve full document content by ID. Pass
+ * `version_id` (from `cerefox_list_versions`) to retrieve an archived
+ * version; omit for the current version.
+ */
+
+import type { MCPSupabaseClient } from "./types.ts";
+
+import { logUsage } from "./_utils.ts";
+import { McpInvalidParams, type ToolContext, type ToolDefinition } from "./types.ts";
+
+async function handler(
+  supabase: MCPSupabaseClient,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<string> {
+  const document_id = args.document_id as string | undefined;
+  const version_id = (args.version_id as string | null | undefined) ?? null;
+
+  if (!document_id) throw new McpInvalidParams("document_id is required");
+
+  const { data, error } = await supabase.rpc("cerefox_get_document", {
+    p_document_id: document_id,
+    p_version_id: version_id,
+  });
+
+  if (error) throw new Error(`RPC error: ${error.message}`);
+
+  const row = data?.[0] as
+    | {
+        doc_title?: string;
+        full_content?: string;
+        chunk_count?: number;
+        total_chars?: number;
+      }
+    | undefined;
+
+  if (!row) return "Document not found.";
+
+  logUsage(supabase, {
+    operation: "get_document",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor as string | undefined,
+    document_id,
+    result_count: 1,
+  });
+
+  const label = version_id !== null ? " (archived version)" : " (current)";
+  return `# ${row.doc_title ?? "Untitled"}${label}\n\n${row.full_content ?? ""}`;
+}
+
+export const getDocumentTool: ToolDefinition = {
+  name: "cerefox_get_document",
+  description:
+    "Retrieve the full reconstructed content of a document. Pass version_id to retrieve an archived version; omit it (or pass null) for the current version. Version UUIDs are returned by cerefox_list_versions.",
+  inputSchema: {
+    type: "object",
+    required: ["document_id"],
+    properties: {
+      document_id: { type: "string", description: "UUID of the document to retrieve" },
+      version_id: {
+        type: "string",
+        description: "UUID of a specific archived version to retrieve (optional)",
+      },
+      requestor: {
+        type: "string",
+        description:
+          'Name of the agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent" if not provided. May be enforced via server config.',
+      },
+    },
+  },
+  handler,
+};

package/dist/server-assets/_shared/mcp-tools/get-help-content.ts

@@ -0,0 +1,26 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Generated by `bun scripts/bundle_help.ts` from AGENT_QUICK_REFERENCE.md.
+ * Re-run after editing the source file. CI's `scripts/check_help_bundle.ts`
+ * fails if this file diverges from the source.
+ *
+ * Bundled into both `@cerefox/memory` and the `cerefox-mcp` Edge Function
+ * so the `cerefox_get_help` MCP tool can return content without filesystem
+ * access. Layer 3 of the MCP discoverability response — see
+ * docs/specs/polish-and-distribution-design.md §10d.
+ */
+
+export const HELP_FULL = "# Cerefox Knowledge Base -- Agent Quick Reference\n\nCerefox is a persistent, shared knowledge base. You have **10 MCP tools** (9 of them have CLI equivalents — `cerefox_get_help` is MCP-only). For the full guide, search Cerefox for \"How AI Agents Use Cerefox\" or call `cerefox_get_help` to retrieve this content over MCP.\n\n## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |\n\n## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.\n\n## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```\n\n## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```\n\n## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```\n\n## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. From v0.5+ the canonical invocation is plain **`cerefox <subcommand>`** (installed via `npm install -g @cerefox/memory`). The legacy `uv run cerefox <subcommand>` (Python CLI in a Cerefox checkout) still works through v0.7 but emits a deprecation banner.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); short forms (`--filter`, `--project`, `--count`, `--update`, `--version`) work as aliases.\n\n| MCP tool | CLI (v0.5+ canonical) |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox ingest --paste --title \"<t>\" --document-id \"<uuid>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox get-doc <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox list-versions <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox list-projects --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox list-metadata-keys` |\n| `cerefox_metadata_search` | `cerefox metadata-search --metadata-filter '<json>' --requestor \"<your-name>\"` |\n| `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |\n| `cerefox_get_audit_log` | `cerefox get-audit-log --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox docs agent-quick-reference --print` (or `cerefox docs --list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`ingest`, `ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.\n";
+
+/** Sections keyed by their H2 heading text (lower-cased for matching). */
+export const HELP_SECTIONS: Record<string, string> = {
+  "Tools": "## Tools\n\n| Tool | Purpose | Key params |\n|------|---------|------------|\n| `cerefox_search` | Find documents (hybrid FTS + semantic) | `query` (required), `project_name`, `metadata_filter`, `requestor` |\n| `cerefox_ingest` | Save or update a document | `title`, `content` (required), `document_id` (update by ID), `update_if_exists`, `project_name` (single, non-destructive add on update), `project_names` (list, destructive replace on update), `metadata`, `author` |\n| `cerefox_get_document` | Get full document by ID | `document_id` (required) |\n| `cerefox_list_versions` | Version history of a document | `document_id` (required) |\n| `cerefox_metadata_search` | Find docs by metadata (no text query) | `metadata_filter` (required), `include_content`, `updated_since` |\n| `cerefox_list_metadata_keys` | Discover available metadata keys | (none required) |\n| `cerefox_list_projects` | List all projects | (none required) |\n| `cerefox_set_document_projects` | Set doc's project memberships to exactly the given list (destructive replace; metadata-only, no content change) | `document_id`, `project_names` (required) |\n| `cerefox_get_audit_log` | Query write operation history | `document_id`, `author`, `operation`, `since` |\n| `cerefox_get_help` | Retrieve Cerefox conventions (this reference) over MCP. **Call this whenever uncertain.** | `topic` (optional, case-insensitive H2 substring match) |",
+  "Essential Rules": "## Essential Rules\n\n1. **Search before ingesting** -- check if the document exists first.\n2. **Prefer ID-based updates** -- pass `document_id` from search results for deterministic updates. Falls back to title-matching with `update_if_exists: true`.\n3. **Set `author`/`requestor`** to your name on every call (e.g., \"Claude Code\", \"archiver\"). On MCP, pass as parameters. On CLI, pass `--author`/`--author-type`/`--requestor` flags, or rely on `CEREFOX_AUTHOR_NAME`/`CEREFOX_AUTHOR_TYPE`/`CEREFOX_REQUESTOR_NAME` env vars set in the user's `.env`.\n4. **Use `document_id` from search results** `[id: uuid]` for get_document and list_versions.\n5. **Add metadata** -- at minimum `type` (\"decision-log\", \"research\", \"design-doc\") and `status` (\"active\", \"draft\").\n6. **Write structured Markdown** with H1/H2/H3 headings for good chunking and search.\n7. **Deletes are soft (recoverable); purge is web-UI-only.** If you decide to delete, surface it to the user (`I soft-deleted X — recoverable from the Cerefox web UI trash`). You cannot un-do your own delete from agent code by design.\n8. **Cross-doc links inside content**: **always use `[Text](document-uuid)`.** UUIDs are the only fully reliable link form — stable across title changes, never ambiguous, no encoding gotchas. Every `cerefox_search` result shows `[id: <uuid>]` after the title; grab it and use it. Title-based linking (`[Text](<Title With Spaces>)`) is fragile (breaks on colons, parens, ampersands, brackets — silently navigates to wrong page) — **don't write title-based links**; do an extra search to get the UUID instead. Repo-path forms (`[Text](docs/path.md)`) exist for repo-ingested files; don't construct manually. See `AGENT_GUIDE.md → Writing linkable content` for the full rule.\n9. **Project memberships — non-destructive by default**: on `cerefox_ingest` updates, **`project_name` (singular) is a non-destructive add** (ensures membership, preserves others). Use **`project_names` (list)** when you want to set the doc's full project set in one call (destructive replace). For metadata-only project changes without writing content, use **`cerefox_set_document_projects(document_id, project_names)`** — that tool is the destructive-replace contract made explicit. Never call `cerefox_set_document_projects` with a single name when you mean \"add\" — that would REMOVE the doc from all other projects. When in doubt, use `cerefox_ingest` with singular `project_name`.",
+  "Update Workflow (ID-based -- preferred)": "## Update Workflow (ID-based -- preferred)\n\n```\nsearch(\"topic\") -> find doc [id: abc123] -> get_document(abc123) -> modify ->\ningest(title=\"Same Title\", content=\"...\", document_id=\"abc123\", author=\"my-agent\")\n```",
+  "Update Workflow (title-based -- fallback)": "## Update Workflow (title-based -- fallback)\n\n```\nsearch(\"topic\") -> find doc -> modify ->\ningest(title=\"Same Title\", content=\"...\", update_if_exists=true, author=\"my-agent\")\n```",
+  "Catch-Up Workflow": "## Catch-Up Workflow\n\n```\nmetadata_search(metadata_filter={\"type\": \"decision-log\"}, updated_since=\"2026-03-28T00:00:00Z\")\n```",
+  "CLI fallback (when MCP is unavailable)": "## CLI fallback (when MCP is unavailable)\n\nIf `cerefox_search` is not in your tool list, your user has likely installed the Cerefox CLI. From v0.5+ the canonical invocation is plain **`cerefox <subcommand>`** (installed via `npm install -g @cerefox/memory`). The legacy `uv run cerefox <subcommand>` (Python CLI in a Cerefox checkout) still works through v0.7 but emits a deprecation banner.\n\nSame operations, same conventions. Full reference: [`docs/guides/cli.md`](docs/guides/cli.md). CLI flag names match MCP parameter names exactly (e.g. `metadata_filter` ↔ `--metadata-filter`); short forms (`--filter`, `--project`, `--count`, `--update`, `--version`) work as aliases.\n\n| MCP tool | CLI (v0.5+ canonical) |\n|---|---|\n| `cerefox_search` | `cerefox search \"<q>\" --requestor \"<your-name>\"` |\n| `cerefox_ingest` (paste) | `printf '...' \\| cerefox ingest --paste --title \"<t>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_ingest` (update by ID) | `printf '...' \\| cerefox ingest --paste --title \"<t>\" --document-id \"<uuid>\" --author \"<your-name>\" --author-type agent` |\n| `cerefox_get_document` | `cerefox get-doc <id> --version-id <vid> --requestor \"<your-name>\"` |\n| `cerefox_list_versions` | `cerefox list-versions <id> --requestor \"<your-name>\"` |\n| `cerefox_list_projects` | `cerefox list-projects --requestor \"<your-name>\"` |\n| `cerefox_list_metadata_keys` | `cerefox list-metadata-keys` |\n| `cerefox_metadata_search` | `cerefox metadata-search --metadata-filter '<json>' --requestor \"<your-name>\"` |\n| `cerefox_set_document_projects` | _MCP-only; a CLI command will be added in a future release. Until then, run via MCP if available._ |\n| `cerefox_get_audit_log` | `cerefox get-audit-log --requestor \"<your-name>\"` (add `--json` for scripted access) |\n| `cerefox_get_help` | `cerefox docs agent-quick-reference --print` (or `cerefox docs --list` for the full bundled-docs index) |\n\n**Set identity on every call**, exactly as you would on MCP:\n- Writes (`ingest`, `ingest-dir`): `--author \"<your-name>\" --author-type agent`\n- Reads: `--requestor \"<your-name>\"`\n\nOr have your user set `CEREFOX_AUTHOR_NAME` / `CEREFOX_AUTHOR_TYPE` / `CEREFOX_REQUESTOR_NAME` in their `.env` to apply defaults once.",
+};
+
+export const HELP_SECTION_HEADINGS: string[] = ["Tools", "Essential Rules", "Update Workflow (ID-based -- preferred)", "Update Workflow (title-based -- fallback)", "Catch-Up Workflow", "CLI fallback (when MCP is unavailable)"];

package/dist/server-assets/_shared/mcp-tools/get-help.ts

@@ -0,0 +1,90 @@
+/**
+ * `cerefox_get_help` — return curated agent guidance.
+ *
+ * Layer 3 of the MCP discoverability response (design doc §10d). Bundles
+ * `AGENT_QUICK_REFERENCE.md` whole so remote / hosted-MCP / Edge-Function-only
+ * agents — who can't read the repo filesystem — have an in-protocol way to
+ * discover Cerefox conventions.
+ *
+ * The bundle is generated by `scripts/bundle_help.ts` from
+ * `AGENT_QUICK_REFERENCE.md` and CI-checked by `scripts/check_help_bundle.ts`.
+ *
+ * Topic filter: case-insensitive substring match against H2 headings (e.g.
+ * `topic="links"` matches the section whose heading contains "links",
+ * `topic="update"` matches both "Update Workflow" sections). No topic →
+ * the full file plus an index of section headings.
+ */
+
+import type { MCPSupabaseClient } from "./types.ts";
+
+import { logUsage } from "./_utils.ts";
+import {
+  HELP_FULL,
+  HELP_SECTION_HEADINGS,
+  HELP_SECTIONS,
+} from "./get-help-content.ts";
+import type { ToolContext, ToolDefinition } from "./types.ts";
+
+async function handler(
+  supabase: MCPSupabaseClient,
+  args: Record<string, unknown>,
+  ctx: ToolContext,
+): Promise<string> {
+  const topic = (args.topic as string | undefined)?.trim();
+
+  logUsage(supabase, {
+    operation: "get_help",
+    accessPath: ctx.accessPath,
+    requestor: args.requestor as string | undefined,
+    query_text: topic ?? null,
+    result_count: 1,
+  });
+
+  if (!topic) {
+    const idx = HELP_SECTION_HEADINGS.map((h) => `  - ${h}`).join("\n");
+    return (
+      HELP_FULL +
+      "\n\n---\n\n" +
+      "## Available topics\n\n" +
+      "Call `cerefox_get_help(topic: \"<heading>\")` to retrieve a single section.\n\n" +
+      idx +
+      "\n\n(Topic match is case-insensitive substring on the headings above.)"
+    );
+  }
+
+  const t = topic.toLowerCase();
+  const matched = HELP_SECTION_HEADINGS.filter((h) => h.toLowerCase().includes(t));
+
+  if (matched.length === 0) {
+    return (
+      `No help topic matched "${topic}".\n\n` +
+      `Available topics:\n` +
+      HELP_SECTION_HEADINGS.map((h) => `  - ${h}`).join("\n") +
+      "\n\nCall `cerefox_get_help()` with no topic for the full document."
+    );
+  }
+
+  return matched.map((h) => HELP_SECTIONS[h]).join("\n\n---\n\n");
+}
+
+export const getHelpTool: ToolDefinition = {
+  name: "cerefox_get_help",
+  description:
+    "Retrieve Cerefox's own agent-usage guidance (the AGENT_QUICK_REFERENCE.md content). Call with no arguments to get the full reference + a section index. Call with `topic` to get a single section (case-insensitive substring match against H2 headings). Use this whenever you're uncertain about Cerefox conventions — link forms, project-membership semantics, update workflows, etc.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      topic: {
+        type: "string",
+        description:
+          'Optional. Case-insensitive substring against H2 headings (e.g. "links", "update", "metadata"). Omit for the full reference.',
+      },
+      requestor: {
+        type: "string",
+        description:
+          'Name of the agent or user making this request. Recorded in the usage log. Defaults to "mcp-agent".',
+      },
+    },
+  },
+  handler,
+};

package/dist/server-assets/_shared/mcp-tools/index.ts

@@ -0,0 +1,67 @@
+/**
+ * `_shared/mcp-tools/` — runtime-neutral MCP tool handlers.
+ *
+ * Single source of truth for the Cerefox MCP tool surface. Imported by:
+ * - `supabase/functions/cerefox-mcp/index.ts` (Deno; HTTP transport).
+ * - `packages/memory/src/server.ts` (Bun/Node; stdio transport).
+ *
+ * Adding a new tool: write `<name>.ts` exporting a `ToolDefinition`, then
+ * add it to `ALL_TOOLS` below. Both consumers pick it up automatically.
+ *
+ * Tool surface (v0.4.0): 10 tools.
+ */
+
+import { auditLogTool } from "./audit-log.ts";
+import { getDocumentTool } from "./get-document.ts";
+import { getHelpTool } from "./get-help.ts";
+import { ingestTool } from "./ingest.ts";
+import { listMetadataKeysTool } from "./list-metadata-keys.ts";
+import { listProjectsTool } from "./list-projects.ts";
+import { listVersionsTool } from "./list-versions.ts";
+import { metadataSearchTool } from "./metadata-search.ts";
+import { searchTool } from "./search.ts";
+import { setDocumentProjectsTool } from "./set-document-projects.ts";
+import type { ToolDefinition } from "./types.ts";
+
+/** All Cerefox MCP tools, in canonical order (matches AGENT_QUICK_REFERENCE.md). */
+export const ALL_TOOLS: ToolDefinition[] = [
+  searchTool,
+  ingestTool,
+  getDocumentTool,
+  listVersionsTool,
+  metadataSearchTool,
+  listMetadataKeysTool,
+  listProjectsTool,
+  setDocumentProjectsTool,
+  auditLogTool,
+  getHelpTool,
+];
+
+/** Build a name → definition map for fast dispatch. */
+export const TOOLS_BY_NAME: Record<string, ToolDefinition> = Object.fromEntries(
+  ALL_TOOLS.map((t) => [t.name, t]),
+);
+
+export { McpInvalidParams } from "./types.ts";
+export type {
+  AccessPath,
+  JsonSchema,
+  ToolContext,
+  ToolDefinition,
+} from "./types.ts";
+
+// Re-export individual tools so non-MCP consumers (e.g. the v0.5 CLI's
+// `ingest` / `delete-doc` commands) can call a specific handler directly
+// without going through ALL_TOOLS dispatch.
+export {
+  auditLogTool,
+  getDocumentTool,
+  getHelpTool,
+  ingestTool,
+  listMetadataKeysTool,
+  listProjectsTool,
+  listVersionsTool,
+  metadataSearchTool,
+  searchTool,
+  setDocumentProjectsTool,
+};