clay-server 3.8.1 → 4.0.0-beta.10

package/lib/knowledge-record-store.js

@@ -0,0 +1,188 @@
+// Clay-wide append-only knowledge record backend.
+//
+// One physical store per scope. Every Knowledge surface is a projection over
+// this backend rather than its own store: Project Logs today, Mate Knowledge
+// and Shared Knowledge later. Records are never rewritten in place, so
+// revision chains, tombstones, and author/blame fall out of the storage format
+// instead of being layered on top of it.
+//
+// Storage lives under config.CONFIG_DIR, never inside a user repository:
+//   {CONFIG_DIR}/knowledge/{scope}/{name}/records.jsonl
+//
+// Loading is incremental and torn-write tolerant. Bytes are consumed only up to
+// the last newline, so a partially written trailing line is held back until it
+// completes, and a complete-but-unparseable line is skipped and counted rather
+// than failing the load.
+
+var fs = require("fs");
+var path = require("path");
+var crypto = require("crypto");
+var config = require("./config");
+
+var RECORD_VERSION = 1;
+var MAX_RECORD_BYTES = 64 * 1024;
+var MAX_STORE_BYTES = 64 * 1024 * 1024;
+var SEGMENT_PATTERN = /^[A-Za-z0-9_-]{1,120}$/;
+var NEWLINE = 0x0a;
+
+function knowledgeRoot() {
+  return path.join(config.CONFIG_DIR, "knowledge");
+}
+
+function newRecordId() {
+  return Date.now().toString(36) + "-" + crypto.randomBytes(6).toString("hex");
+}
+
+// A scope id is a slash-separated set of strict segments. Anything else is
+// rejected outright so a caller-supplied value can never escape the root.
+function scopeSegments(scopeId) {
+  if (typeof scopeId !== "string" || !scopeId) throw new Error("A knowledge scope id is required.");
+  var segments = scopeId.split("/");
+  if (segments.length < 2 || segments.length > 4) throw new Error("Invalid knowledge scope id: " + scopeId);
+  for (var i = 0; i < segments.length; i++) {
+    if (!SEGMENT_PATTERN.test(segments[i])) throw new Error("Invalid knowledge scope id: " + scopeId);
+  }
+  return segments;
+}
+
+function createRecordStore(opts) {
+  var options = opts || {};
+  var scopeId = options.scopeId;
+  var segments = scopeSegments(scopeId);
+  var baseDir = options.baseDir || knowledgeRoot();
+  var storeDir = path.join.apply(path, [baseDir].concat(segments));
+  var filePath = path.join(storeDir, "records.jsonl");
+
+  var records = [];
+  var consumed = 0;
+  var partial = Buffer.alloc(0);
+  var skipped = 0;
+  var loaded = false;
+
+  function reset() {
+    records = [];
+    consumed = 0;
+    partial = Buffer.alloc(0);
+    skipped = 0;
+  }
+
+  function readRange(size) {
+    var length = size - consumed;
+    if (length <= 0) return Buffer.alloc(0);
+    var buffer = Buffer.alloc(length);
+    var fd = fs.openSync(filePath, "r");
+    try {
+      var read = fs.readSync(fd, buffer, 0, length, consumed);
+      return read === length ? buffer : buffer.slice(0, read);
+    } finally {
+      fs.closeSync(fd);
+    }
+  }
+
+  function ingest(chunk) {
+    var pending = partial.length > 0 ? Buffer.concat([partial, chunk]) : chunk;
+    var lastNewline = pending.lastIndexOf(NEWLINE);
+    if (lastNewline === -1) {
+      partial = pending;
+      return;
+    }
+    partial = pending.slice(lastNewline + 1);
+    var lines = pending.slice(0, lastNewline).toString("utf8").split("\n");
+    for (var i = 0; i < lines.length; i++) {
+      var line = lines[i].trim();
+      if (!line) continue;
+      var parsed = null;
+      try {
+        parsed = JSON.parse(line);
+      } catch (e) {
+        skipped++;
+        continue;
+      }
+      if (!parsed || typeof parsed !== "object" || parsed.v !== RECORD_VERSION || !parsed.id) {
+        skipped++;
+        continue;
+      }
+      records.push(parsed);
+    }
+  }
+
+  // Pick up appends made by this process and by any other process holding the
+  // same file open. A shrunk file means it was truncated or replaced, so the
+  // projection is rebuilt from the start.
+  function refresh() {
+    var stat = null;
+    try {
+      stat = fs.statSync(filePath);
+    } catch (e) {
+      if (loaded && consumed === 0 && records.length === 0) return;
+      reset();
+      loaded = true;
+      return;
+    }
+    if (stat.size > MAX_STORE_BYTES) throw new Error("Knowledge store is too large to load: " + scopeId);
+    if (stat.size < consumed) reset();
+    if (loaded && stat.size === consumed) return;
+    var chunk = readRange(stat.size);
+    consumed += chunk.length;
+    loaded = true;
+    if (chunk.length > 0) ingest(chunk);
+  }
+
+  // O_APPEND plus a single write syscall keeps a record from interleaving with
+  // a concurrent writer's record. The refresh on either side keeps this
+  // process's projection consistent with what actually landed on disk.
+  function append(record) {
+    if (!record || typeof record !== "object") throw new Error("A knowledge record object is required.");
+    refresh();
+    var stored = Object.assign({}, record, { v: RECORD_VERSION });
+    if (!stored.id) stored.id = newRecordId();
+    var buffer = Buffer.from(JSON.stringify(stored) + "\n", "utf8");
+    if (buffer.indexOf(NEWLINE) !== buffer.length - 1) throw new Error("A knowledge record must serialize to a single line.");
+    if (buffer.length > MAX_RECORD_BYTES) throw new Error("Knowledge record exceeds " + MAX_RECORD_BYTES + " bytes.");
+    fs.mkdirSync(storeDir, { recursive: true });
+    var fd = fs.openSync(filePath, "a");
+    try {
+      fs.writeSync(fd, buffer, 0, buffer.length);
+    } finally {
+      fs.closeSync(fd);
+    }
+    config.chmodSafe(filePath, 0o600);
+    refresh();
+    return stored;
+  }
+
+  // Returned for reading only. Callers project over it and must not mutate it.
+  function all() {
+    refresh();
+    return records;
+  }
+
+  function stats() {
+    refresh();
+    return {
+      scopeId: scopeId,
+      filePath: filePath,
+      records: records.length,
+      skipped: skipped,
+      pendingBytes: partial.length,
+    };
+  }
+
+  return {
+    scopeId: scopeId,
+    filePath: filePath,
+    append: append,
+    all: all,
+    stats: stats,
+    refresh: refresh,
+  };
+}
+
+module.exports = {
+  RECORD_VERSION: RECORD_VERSION,
+  MAX_RECORD_BYTES: MAX_RECORD_BYTES,
+  knowledgeRoot: knowledgeRoot,
+  newRecordId: newRecordId,
+  scopeSegments: scopeSegments,
+  createRecordStore: createRecordStore,
+};

package/lib/knowledge-search.js

@@ -0,0 +1,224 @@
+// Shared BM25 adapter for Clay Knowledge surfaces.
+//
+// There is exactly one ranking implementation in Clay: the generic
+// buildIndex/searchIndex engine in session-search.js, including its tokenizer
+// with CJK/Japanese/Thai bigram segmentation. This module is a thin adapter
+// over it, not a second ranker.
+//
+// Field weighting is expressed by controlled repetition of a field's text
+// before indexing, which is how session-search.js already weights digests.
+// A title repeated three times contributes three times the term frequency of
+// the body, so BM25 saturation and length normalisation still apply normally.
+//
+// Long records are segmented rather than truncated. A record whose body runs to
+// tens of thousands of characters is indexed as several overlapping documents,
+// so a term that appears only near the end is still found. Short fields (title,
+// name, tags) are anchors and are repeated into every segment, so weighting is
+// identical in each one. Segments are collapsed back to one result per original
+// item by taking its best-scoring segment; the caller still applies its own
+// score, recency, and reference tie-breaks on top.
+
+var sessionSearch = require("./session-search");
+
+var MAX_SNIPPET_CHARS = 320;
+var SNIPPET_LEAD_CHARS = 80;
+// A field at or under this length is an anchor, replicated into every segment.
+// Anything longer is windowed.
+var SEGMENT_CHARS = 8000;
+// Overlap so a term straddling a window boundary is still indexed intact.
+var SEGMENT_OVERLAP = 800;
+// Memory bound. A record needing more windows than this is indexed up to the
+// cap; the cap is high enough that no realistic Knowledge record reaches it.
+var MAX_SEGMENTS_PER_ITEM = 64;
+
+function repeat(text, weight) {
+  var out = [];
+  for (var i = 0; i < weight; i++) out.push(text);
+  return out.join(" ");
+}
+
+function normalizeWeight(weight) {
+  return Number.isFinite(weight) ? Math.max(1, Math.floor(weight)) : 1;
+}
+
+function usableFields(fields) {
+  var out = [];
+  for (var i = 0; i < (fields || []).length; i++) {
+    var field = fields[i];
+    if (!field || typeof field.text !== "string" || !field.text) continue;
+    out.push({ text: field.text, weight: normalizeWeight(field.weight) });
+  }
+  return out;
+}
+
+// Kept for callers and tests that want the single-document form. Anchors and
+// short bodies produce exactly this text.
+function weightedText(fields) {
+  var parts = [];
+  var usable = usableFields(fields);
+  for (var i = 0; i < usable.length; i++) parts.push(repeat(usable[i].text, usable[i].weight));
+  return parts.join(" ");
+}
+
+var SEGMENT_STRIDE = SEGMENT_CHARS - SEGMENT_OVERLAP;
+// The maximum searchable characters of one long field that can be indexed
+// before the segment cap stops coverage. Reported to callers so an incomplete
+// index is stated rather than implied.
+var MAX_INDEXED_CHARS = SEGMENT_CHARS + (MAX_SEGMENTS_PER_ITEM - 1) * SEGMENT_STRIDE;
+
+// One shared plan drives both the indexed documents and the coverage report,
+// so what a caller is told was indexed is exactly what was indexed.
+function planSegments(fields) {
+  var usable = usableFields(fields);
+  var anchors = [];
+  var longs = [];
+  for (var i = 0; i < usable.length; i++) {
+    if (usable[i].text.length > SEGMENT_CHARS) longs.push(usable[i]);
+    else anchors.push(usable[i]);
+  }
+
+  var windows = [];
+  var totalChars = 0;
+  var indexedChars = 0;
+  for (var l = 0; l < longs.length; l++) {
+    var text = longs[l].text;
+    totalChars += text.length;
+    var covered = 0;
+    for (var offset = 0; offset < text.length && windows.length < MAX_SEGMENTS_PER_ITEM; offset += SEGMENT_STRIDE) {
+      var end = Math.min(text.length, offset + SEGMENT_CHARS);
+      windows.push({ field: longs[l], start: offset, end: end });
+      covered = end;
+      if (end >= text.length) break;
+    }
+    indexedChars += covered;
+  }
+  for (var a = 0; a < anchors.length; a++) {
+    totalChars += anchors[a].text.length;
+    indexedChars += anchors[a].text.length;
+  }
+
+  return {
+    anchors: anchors,
+    longs: longs,
+    windows: windows,
+    totalChars: totalChars,
+    indexedChars: indexedChars,
+    complete: indexedChars >= totalChars,
+  };
+}
+
+// How much of an item's searchable text this adapter can index. `complete` is
+// false when the segment cap stopped short, which means a term appearing only
+// in the uncovered tail cannot be ranked.
+function coverage(fields) {
+  var plan = planSegments(fields);
+  return { totalChars: plan.totalChars, indexedChars: plan.indexedChars, complete: plan.complete };
+}
+
+// One item becomes one or more BM25 documents. Short fields anchor every
+// segment so title and tag weighting is consistent wherever the body matched.
+function segmentTexts(fields) {
+  var plan = planSegments(fields);
+  var anchorText = weightedText(plan.anchors);
+  if (plan.windows.length === 0) return [anchorText];
+
+  var texts = [];
+  for (var w = 0; w < plan.windows.length; w++) {
+    var window = plan.windows[w];
+    var body = repeat(window.field.text.substring(window.start, window.end), window.field.weight);
+    texts.push(anchorText ? anchorText + " " + body : body);
+  }
+  return texts;
+}
+
+// Build the generic {id, text, meta} documents the shared engine expects.
+// project(item, position) must return { id, fields, meta }. One item may yield
+// several documents; each carries the item's position so results collapse back.
+function buildDocs(items, project) {
+  var docs = [];
+  for (var i = 0; i < (items || []).length; i++) {
+    var projected = project(items[i], i);
+    if (!projected) continue;
+    var texts = segmentTexts(projected.fields);
+    for (var s = 0; s < texts.length; s++) {
+      docs.push({
+        id: projected.id,
+        text: texts[s],
+        meta: { position: i, segment: s, id: projected.id, meta: projected.meta },
+      });
+    }
+  }
+  return docs;
+}
+
+// Rank with the shared engine. Returns [{ id, score, meta }] highest first, one
+// entry per original item. A query that tokenizes to nothing scores nothing,
+// rather than silently falling back to a different matching strategy.
+//
+// Aggregation across an item's segments is the maximum segment score: a record
+// is as relevant as its best-matching part, so a long record is neither
+// penalised for its unmatched bulk nor rewarded for repeating a term across
+// windows that overlap.
+function rank(items, query, project, maxResults) {
+  var docs = buildDocs(items, project);
+  if (docs.length === 0) return [];
+  var index = sessionSearch.buildIndex(docs);
+  var scored = sessionSearch.searchIndex(index, query, docs.length);
+
+  var bestByPosition = new Map();
+  for (var i = 0; i < scored.length; i++) {
+    var envelope = scored[i].meta;
+    if (!envelope) continue;
+    var existing = bestByPosition.get(envelope.position);
+    if (existing && existing.score >= scored[i].score) continue;
+    bestByPosition.set(envelope.position, { id: envelope.id, score: scored[i].score, meta: envelope.meta });
+  }
+
+  var collapsed = [];
+  bestByPosition.forEach(function (entry) { collapsed.push(entry); });
+  // Stable, deterministic ordering before the caller applies its own
+  // recency and reference tie-breaks.
+  collapsed.sort(function (a, b) {
+    return b.score - a.score || String(a.id).localeCompare(String(b.id));
+  });
+  var limit = maxResults || collapsed.length;
+  return collapsed.slice(0, limit);
+}
+
+// A snippet centred on the first query term that appears in the text, so the
+// excerpt shows why the document matched rather than just its opening. Works
+// across the whole record, not only its first segment.
+function snippet(text, query, maxChars) {
+  if (typeof text !== "string" || !text) return "";
+  var limit = maxChars || MAX_SNIPPET_CHARS;
+  var haystack = text.toLowerCase();
+  var tokens = sessionSearch.tokenize(query || "");
+  var best = -1;
+  for (var i = 0; i < tokens.length; i++) {
+    var at = haystack.indexOf(tokens[i]);
+    if (at !== -1 && (best === -1 || at < best)) best = at;
+  }
+  if (best === -1) {
+    var raw = (query || "").trim().toLowerCase();
+    if (raw) best = haystack.indexOf(raw);
+  }
+  var start = best === -1 ? 0 : Math.max(0, best - SNIPPET_LEAD_CHARS);
+  return text.substring(start, start + limit);
+}
+
+module.exports = {
+  MAX_SNIPPET_CHARS: MAX_SNIPPET_CHARS,
+  SEGMENT_CHARS: SEGMENT_CHARS,
+  SEGMENT_OVERLAP: SEGMENT_OVERLAP,
+  SEGMENT_STRIDE: SEGMENT_STRIDE,
+  MAX_SEGMENTS_PER_ITEM: MAX_SEGMENTS_PER_ITEM,
+  MAX_INDEXED_CHARS: MAX_INDEXED_CHARS,
+  tokenize: sessionSearch.tokenize,
+  weightedText: weightedText,
+  planSegments: planSegments,
+  coverage: coverage,
+  segmentTexts: segmentTexts,
+  buildDocs: buildDocs,
+  rank: rank,
+  snippet: snippet,
+};

package/lib/mate-creation-mcp-server.js

@@ -0,0 +1,55 @@
+// Query-bound proposal tool for Clay-led Mate creation interviews.
+
+var z;
+try { z = require("zod"); } catch (e) { z = null; }
+
+function schema() {
+  if (!z) return {};
+  return {
+    name: z.string().describe("The proposed Mate name"),
+    bio: z.string().describe("A concise public description of how this Mate helps"),
+    relationship: z.string().describe("The working relationship this Mate should have with the user"),
+    activities: z.string().describe("JSON array of the Mate's main activities or contexts"),
+    communicationStyle: z.string().describe("JSON array of communication preferences"),
+    autonomy: z.string().describe("A concise description of autonomy, boundaries, and escalation behavior"),
+    identityMarkdown: z.string().describe("The complete first-person Mate identity in Markdown"),
+  };
+}
+
+function parseArray(value, field) {
+  var parsed;
+  try { parsed = JSON.parse(value || "[]"); } catch (e) { throw new Error(field + " must be a JSON array."); }
+  if (!Array.isArray(parsed)) throw new Error(field + " must be a JSON array.");
+  return parsed;
+}
+
+function getToolDefs(onPropose) {
+  return [{
+    name: "propose_mate",
+    description: "Present the completed Mate identity for explicit user approval. This does not create the Mate until the user approves the inline proposal.",
+    inputSchema: schema(),
+    handler: function (args) {
+      var proposal;
+      try {
+        proposal = {
+          name: args.name,
+          bio: args.bio,
+          relationship: args.relationship,
+          activities: parseArray(args.activities, "activities"),
+          communicationStyle: parseArray(args.communicationStyle, "communicationStyle"),
+          autonomy: args.autonomy,
+          identityMarkdown: args.identityMarkdown,
+        };
+      } catch (error) {
+        return Promise.resolve({ content: [{ type: "text", text: "Error: " + error.message }], isError: true });
+      }
+      return onPropose(proposal).then(function (result) {
+        if (result && result.action === "create") return { content: [{ type: "text", text: "Mate created: " + proposal.name }] };
+        if (result && result.action === "error") return { content: [{ type: "text", text: "Error: " + (result.error || "The Mate could not be created.") }], isError: true };
+        return { content: [{ type: "text", text: "Mate proposal was cancelled by the user." }] };
+      });
+    },
+  }];
+}
+
+module.exports = { getToolDefs: getToolDefs };

package/lib/mate-knowledge-mcp-server.js

@@ -0,0 +1,151 @@
+// SDK-free `clay-knowledge` MCP tool definitions for Mate Knowledge.
+//
+// Two disjoint tool sets. An ordinary Mate gets tools with no mateId, owner, or
+// scope argument at all, because the binding decides the scope and a tool
+// argument must never be able to widen it or reveal that other Mates exist.
+// Authoritative builtin Clay gets same-user cross-Mate read tools that may name
+// a mateId for list and search, while read resolves an opaque reference inside
+// the authorized user's Mate scopes only.
+
+var buildShape = require("./session-spawn-mcp-server").buildShape;
+var service = require("./mate-knowledge-service");
+
+var MATE_CONTRACT =
+  "Your Knowledge is the durable personal and expertise context you own: what you have learned, the material you keep, and your accumulated observations. " +
+  "It is yours alone. There are no other Knowledge collections available to you here, and project Logs are a separate, unrelated surface. " +
+  "Search it when recalling something specific would genuinely change your answer, and read only the records you actually need. " +
+  "Do not enumerate or restate your Knowledge to the user unasked, and never reproduce whole records as filler.";
+
+var CLAY_CONTRACT =
+  "You may read the Knowledge of Mates belonging to the current user in order to coordinate between them, and only for that user. " +
+  "Use it to find who holds relevant expertise or context, and to answer with that context attributed to the Mate that owns it. " +
+  "Search first, read narrowly, and cite the owning Mate. Never reproduce a Mate's Knowledge wholesale, and never present it as your own.";
+
+var REF_DESCRIPTION = "Opaque knowledge reference returned by a list or search tool.";
+var PAGE_DESCRIPTION = "Page size, from 1 to " + service.MAX_PAGE + ".";
+var CURSOR_DESCRIPTION = "Opaque pagination cursor from a previous response.";
+var OFFSET_DESCRIPTION = "Character offset to start from. Omit for the beginning; pass the previous response's nextOffset to continue.";
+var MAX_CHARS_DESCRIPTION = "Characters to return, from 1 to " + service.MAX_READ_CHARS + ". Defaults to " + service.DEFAULT_READ_CHARS + ".";
+var READ_RESULT = " The whole record is reassembled and verified before any slice is returned. The response carries offset, totalChars, nextOffset, and complete; when nextOffset is not null, call again with it to continue.";
+
+function textResult(value) {
+  return Promise.resolve({ content: [{ type: "text", text: JSON.stringify(value) }] });
+}
+
+function errorResult(error) {
+  return Promise.resolve({
+    content: [{ type: "text", text: "Error: " + (error && error.message ? error.message : String(error)) }],
+    isError: true,
+  });
+}
+
+// An unbound descriptor exists only so a tool list can be advertised before a
+// session is known. Every call against it fails closed.
+function handler(bound, method) {
+  return function (args) {
+    if (!bound || typeof bound[method] !== "function") {
+      return errorResult(new Error("Knowledge tools require an exact session-bound Mate."));
+    }
+    try {
+      return textResult(bound[method](args || {}));
+    } catch (e) {
+      return errorResult(e);
+    }
+  };
+}
+
+function mateTools(bound) {
+  return [
+    {
+      name: "list_knowledge",
+      description: MATE_CONTRACT + " List your own Knowledge records, most recently updated first. Returns summaries with a short preview, not full records.",
+      inputSchema: buildShape({
+        kind: { type: "string", description: "Optional record kind filter, such as knowledge-file, memory-summary, session-digest, or user-observation." },
+        cursor: { type: "string", description: CURSOR_DESCRIPTION },
+        limit: { type: "number", description: PAGE_DESCRIPTION },
+      }),
+      handler: handler(bound, "listKnowledge"),
+    },
+    {
+      name: "search_knowledge",
+      description: MATE_CONTRACT + " Search your own Knowledge by relevance. Returns ranked summaries with a matching snippet.",
+      inputSchema: buildShape({
+        query: { type: "string", description: "Search query." },
+        kind: { type: "string", description: "Optional record kind filter." },
+        cursor: { type: "string", description: CURSOR_DESCRIPTION },
+        limit: { type: "number", description: PAGE_DESCRIPTION },
+      }, ["query"]),
+      handler: handler(bound, "searchKnowledge"),
+    },
+    {
+      name: "read_knowledge",
+      description: MATE_CONTRACT + " Read one of your own Knowledge records. Read only what you need." + READ_RESULT,
+      inputSchema: buildShape({
+        ref: { type: "string", description: REF_DESCRIPTION },
+        offset: { type: "number", description: OFFSET_DESCRIPTION },
+        maxChars: { type: "number", description: MAX_CHARS_DESCRIPTION },
+      }, ["ref"]),
+      handler: handler(bound, "readKnowledge"),
+    },
+  ];
+}
+
+function clayTools(bound) {
+  return [
+    {
+      name: "list_mate_knowledge",
+      description: CLAY_CONTRACT + " List Knowledge records across the current user's Mates, or one named Mate. Available only to authoritative builtin Clay.",
+      inputSchema: buildShape({
+        mateId: { type: "string", description: "Optional exact Mate id belonging to the current user. Omit to span all of them." },
+        kind: { type: "string", description: "Optional record kind filter." },
+        cursor: { type: "string", description: CURSOR_DESCRIPTION },
+        limit: { type: "number", description: PAGE_DESCRIPTION },
+      }),
+      handler: handler(bound, "listMateKnowledge"),
+    },
+    {
+      name: "search_mate_knowledge",
+      description: CLAY_CONTRACT + " Search Knowledge across the current user's Mates, or one named Mate. Results identify the owning Mate. Available only to authoritative builtin Clay.",
+      inputSchema: buildShape({
+        query: { type: "string", description: "Search query." },
+        mateId: { type: "string", description: "Optional exact Mate id belonging to the current user." },
+        kind: { type: "string", description: "Optional record kind filter." },
+        cursor: { type: "string", description: CURSOR_DESCRIPTION },
+        limit: { type: "number", description: PAGE_DESCRIPTION },
+      }, ["query"]),
+      handler: handler(bound, "searchMateKnowledge"),
+    },
+    {
+      name: "read_mate_knowledge",
+      description: CLAY_CONTRACT + " Read one Knowledge record using the opaque reference returned by a list or search tool. The reference resolves only inside the current user's Mate Knowledge. Available only to authoritative builtin Clay." + READ_RESULT,
+      inputSchema: buildShape({
+        ref: { type: "string", description: REF_DESCRIPTION },
+        offset: { type: "number", description: OFFSET_DESCRIPTION },
+        maxChars: { type: "number", description: MAX_CHARS_DESCRIPTION },
+      }, ["ref"]),
+      handler: handler(bound, "readMateKnowledge"),
+    },
+  ];
+}
+
+// A binding is either one Mate's own scope or Clay's cross-Mate read view. The
+// two sets are never advertised together, so no tool name is duplicated.
+function getToolDefs(bound, includeClay) {
+  return includeClay === true ? clayTools(bound) : mateTools(bound);
+}
+
+function createMcpServer(adapter, bound, includeClay) {
+  if (!adapter || typeof adapter.createToolServer !== "function") return null;
+  return adapter.createToolServer({
+    name: "clay-knowledge",
+    version: "1.0.0",
+    tools: getToolDefs(bound, includeClay),
+  });
+}
+
+module.exports = {
+  MATE_CONTRACT: MATE_CONTRACT,
+  CLAY_CONTRACT: CLAY_CONTRACT,
+  getToolDefs: getToolDefs,
+  createMcpServer: createMcpServer,
+};