@dudamel/mcp-context 0.1.0 → 2026.918.1

package/dist/index.js

@@ -1,3 +1,1645 @@
-export { createContextServer } from './server.js';
-export { ContextServerClient, ContextServerError } from './context-client.js';
-//# sourceMappingURL=index.js.map
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/context-client.ts
+import yaml from "js-yaml";
+var ContextServerError = class extends Error {
+  constructor(message, status, url) {
+    super(message);
+    this.status = status;
+    this.url = url;
+    this.name = "ContextServerError";
+  }
+};
+var ContextServerClient = class {
+  baseUrl;
+  apiKey;
+  pathPrefix;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.pathPrefix = this.apiKey ? "/api/context" : "";
+  }
+  url(path) {
+    if (!path.startsWith("/"))
+      throw new Error(`ContextServerClient path must start with "/", got "${path}"`);
+    return `${this.baseUrl}${this.pathPrefix}${path}`;
+  }
+  headers(extra) {
+    const out = { ...extra ?? {} };
+    if (this.apiKey) out["Authorization"] = `ApiKey ${this.apiKey}`;
+    return out;
+  }
+  async get(path) {
+    const target = this.url(path);
+    const res = await fetch(target, { method: "GET", headers: this.headers() });
+    if (!res.ok) {
+      const body = await res.text().catch(() => "");
+      throw new ContextServerError(
+        `GET ${path} -> ${res.status}${body ? `: ${body}` : ""}`,
+        res.status,
+        target
+      );
+    }
+    return await res.json();
+  }
+  async post(path, body) {
+    const target = this.url(path);
+    const res = await fetch(target, {
+      method: "POST",
+      headers: this.headers({ "Content-Type": "application/json" }),
+      body: JSON.stringify(body ?? {})
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new ContextServerError(
+        `POST ${path} -> ${res.status}${text ? `: ${text}` : ""}`,
+        res.status,
+        target
+      );
+    }
+    return await res.json();
+  }
+  /** Cheap change-detection digest of the whole VFS (used by the local mirror). */
+  getManifest() {
+    return this.get("/manifest");
+  }
+  grep(req) {
+    return this.post("/search/grep", req);
+  }
+  find(req) {
+    return this.post("/search/find", req);
+  }
+  stat(path) {
+    return this.post("/search/stat", { path });
+  }
+  tree(path, maxDepth) {
+    return this.post("/search/tree", { path, maxDepth });
+  }
+  tail(path, lines) {
+    return this.post("/search/tail", { path, lines });
+  }
+  readSection(path, heading) {
+    return this.post("/search/section", { path, heading });
+  }
+  readYaml(path, keyPath) {
+    return this.post("/search/yaml", { path, keyPath });
+  }
+  readCsv(path, opts) {
+    return this.post("/search/csv", { path, ...opts });
+  }
+  /**
+   * Fetch a file's raw text from the VFS. Path is VFS-relative:
+   *   "AGENTS.md"  -> /data/context/AGENTS.md
+   *   "src/foo"    -> /data/context/src/foo
+   */
+  async readFile(vfsPath) {
+    const segments = vfsPath.split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) throw new Error("Path cannot be empty");
+    const [sourceName, ...rest] = segments;
+    const encoded = encodeURIComponent(sourceName);
+    const url = rest.length === 0 ? `/read/${encoded}` : `/read/${encoded}/${rest.map(encodeURIComponent).join("/")}`;
+    return this.get(url);
+  }
+  /**
+   * Parsed .index.yaml for a directory.
+   * `dirPath` is VFS-relative: "source" or "source/sub/dir".
+   */
+  async readDirectoryCatalog(dirPath) {
+    const trimmed = dirPath.replace(/\/$/, "");
+    const catalogPath = trimmed.length === 0 ? ".index.yaml" : `${trimmed}/.index.yaml`;
+    const raw = await this.readFile(catalogPath);
+    return parseCatalog(raw.content);
+  }
+};
+function parseCatalog(text) {
+  const parsed = yaml.load(text);
+  if (parsed == null || typeof parsed !== "object") {
+    throw new Error(`Catalog YAML did not parse into an object: ${typeof parsed}`);
+  }
+  return parsed;
+}
+
+// src/mirror-backend.ts
+import {
+  existsSync as existsSync2,
+  mkdirSync,
+  readFileSync as readFileSync3,
+  readdirSync as readdirSync3,
+  renameSync,
+  rmSync,
+  statSync as statSync3,
+  writeFileSync
+} from "node:fs";
+import { dirname, join as join3 } from "node:path";
+
+// ../../vfs-search/dist/search.js
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import yaml2 from "js-yaml";
+
+// ../../vfs-search/dist/logger.js
+var noopLogger = {
+  debug() {
+  },
+  warn() {
+  }
+};
+var current = noopLogger;
+function vfsLogger() {
+  return current;
+}
+
+// ../../vfs-search/dist/search.js
+var execFileAsync = promisify(execFile);
+var GREP_TIMEOUT_MS = 15e3;
+var FIND_TIMEOUT_MS = 5e3;
+var TAIL_TIMEOUT_MS = 5e3;
+var DEFAULT_MAX_RESULTS = 50;
+var HARD_MAX_RESULTS = 500;
+var HARD_MAX_OUTPUT_BYTES = 1 * 1024 * 1024;
+var DEFAULT_TREE_DEPTH = 3;
+var HARD_MAX_TREE_ENTRIES = 2e3;
+var DEFAULT_TAIL_LINES = 20;
+var HARD_MAX_TAIL_LINES = 1e3;
+function resolveScope(contextDir, userPath) {
+  const trimmed = (userPath ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+  const absolute = resolve(contextDir, trimmed);
+  const relativeBack = relative(contextDir, absolute);
+  if (relativeBack.startsWith("..") || resolve(relativeBack) === resolve(".."))
+    return null;
+  if (!existsSync(absolute))
+    return null;
+  return absolute;
+}
+function toVfsPath(contextDir, absolutePath) {
+  return relative(contextDir, absolutePath);
+}
+async function grepVfs(contextDir, opts) {
+  const scopes = [];
+  if (opts.paths && opts.paths.length > 0) {
+    for (const p of opts.paths) {
+      const s = resolveScope(contextDir, p);
+      if (s)
+        scopes.push(s);
+    }
+  } else {
+    const s = resolveScope(contextDir, opts.path);
+    if (s)
+      scopes.push(s);
+  }
+  if (scopes.length === 0)
+    return { results: [], truncated: false };
+  const maxResults = Math.min(opts.maxResults ?? DEFAULT_MAX_RESULTS, HARD_MAX_RESULTS);
+  const args = ["-r", "-n", "-H", "-I"];
+  if (opts.fixedString)
+    args.push("-F");
+  else
+    args.push("-E");
+  if (opts.ignoreCase)
+    args.push("-i");
+  args.push("--color=never");
+  args.push("--exclude=.index.yaml");
+  args.push("--exclude-dir=.git");
+  args.push("-m", String(maxResults));
+  args.push("--");
+  args.push(opts.pattern);
+  args.push(...scopes);
+  vfsLogger().debug({ scopes, pattern: opts.pattern, maxResults }, "grep running");
+  let stdout;
+  try {
+    const res = await execFileAsync("grep", args, {
+      timeout: GREP_TIMEOUT_MS,
+      maxBuffer: HARD_MAX_OUTPUT_BYTES,
+      env: { ...process.env, LC_ALL: "C" }
+    });
+    stdout = res.stdout;
+  } catch (error) {
+    const err = error;
+    if (err.code === 1)
+      return { results: [], truncated: false };
+    if (err.code === 2) {
+      vfsLogger().warn({ pattern: opts.pattern, stderr: error.stderr }, "grep rejected pattern");
+      return { results: [], truncated: false };
+    }
+    stdout = err.stdout ?? "";
+  }
+  const hits = [];
+  for (const rawLine of stdout.split("\n")) {
+    if (rawLine.length === 0)
+      continue;
+    const first = rawLine.indexOf(":");
+    if (first < 0)
+      continue;
+    const second = rawLine.indexOf(":", first + 1);
+    if (second < 0)
+      continue;
+    const absolute = rawLine.slice(0, first);
+    const lineStr = rawLine.slice(first + 1, second);
+    const text = rawLine.slice(second + 1);
+    const lineNo = parseInt(lineStr, 10);
+    if (Number.isNaN(lineNo))
+      continue;
+    const vfsPath = toVfsPath(contextDir, absolute);
+    if (vfsPath.split("/").some((seg) => seg.startsWith(".")))
+      continue;
+    hits.push({ path: vfsPath, line: lineNo, text });
+    if (hits.length >= maxResults)
+      break;
+  }
+  const truncated = hits.length >= maxResults;
+  return { results: hits, truncated };
+}
+async function findVfs(contextDir, opts) {
+  const scopes = [];
+  if (opts.paths && opts.paths.length > 0) {
+    for (const p of opts.paths) {
+      const s = resolveScope(contextDir, p);
+      if (s)
+        scopes.push(s);
+    }
+  } else {
+    const s = resolveScope(contextDir, opts.path);
+    if (s)
+      scopes.push(s);
+  }
+  if (scopes.length === 0)
+    return { results: [], truncated: false };
+  const maxResults = Math.min(opts.maxResults ?? DEFAULT_MAX_RESULTS, HARD_MAX_RESULTS);
+  const args = [...scopes];
+  if (opts.type === "f")
+    args.push("-type", "f");
+  else if (opts.type === "d")
+    args.push("-type", "d");
+  args.push("-not", "-path", "*/.*");
+  args.push("-not", "-name", ".*");
+  args.push("-name", opts.name);
+  vfsLogger().debug({ scopes, name: opts.name, type: opts.type }, "find running");
+  let stdout;
+  try {
+    const res = await execFileAsync("find", args, {
+      timeout: FIND_TIMEOUT_MS,
+      maxBuffer: HARD_MAX_OUTPUT_BYTES
+    });
+    stdout = res.stdout;
+  } catch (error) {
+    const err = error;
+    vfsLogger().warn({ name: opts.name, code: err.code, stderr: err.stderr }, "find failed");
+    stdout = err.stdout ?? "";
+  }
+  const rawPaths = stdout.split("\n").filter((line) => line.length > 0);
+  const results = [];
+  for (const absolute of rawPaths) {
+    const vfsPath = toVfsPath(contextDir, absolute);
+    if (!vfsPath || vfsPath === "." || vfsPath === "..")
+      continue;
+    results.push(vfsPath);
+    if (results.length >= maxResults)
+      break;
+  }
+  const truncated = results.length >= maxResults && rawPaths.length > maxResults;
+  return { results, truncated };
+}
+var STAT_LINE_COUNT_MAX_BYTES = 2 * 1024 * 1024;
+function statVfs(contextDir, vfsPath) {
+  const absolute = resolveScope(contextDir, vfsPath);
+  if (!absolute)
+    return { exists: false };
+  try {
+    const st = statSync(absolute);
+    if (st.isDirectory()) {
+      const children = readdirSync(absolute).filter((name) => !name.startsWith("."));
+      return {
+        exists: true,
+        type: "directory",
+        entries: children.length,
+        modified: st.mtime.toISOString()
+      };
+    }
+    if (st.isFile()) {
+      const result = {
+        exists: true,
+        type: "file",
+        size: st.size,
+        modified: st.mtime.toISOString()
+      };
+      if (st.size <= STAT_LINE_COUNT_MAX_BYTES) {
+        try {
+          const buf = readFileSync(absolute);
+          let lines = 0;
+          for (let i = 0; i < buf.length; i++)
+            if (buf[i] === 10)
+              lines++;
+          if (buf.length > 0 && buf[buf.length - 1] !== 10)
+            lines++;
+          result.lines = lines;
+        } catch {
+        }
+      }
+      return result;
+    }
+    return { exists: true, type: "other", modified: st.mtime.toISOString() };
+  } catch {
+    return { exists: false };
+  }
+}
+function treeVfs(contextDir, opts) {
+  const scope = resolveScope(contextDir, opts.path);
+  const rootLabel = (opts.path ?? "").replace(/\/$/, "");
+  if (!scope)
+    return { root: rootLabel, entries: [], truncated: false };
+  const maxDepth = Math.max(1, Math.min(opts.maxDepth ?? DEFAULT_TREE_DEPTH, 10));
+  const entries = [];
+  let truncated = false;
+  function walk(absolute, depth) {
+    if (truncated)
+      return;
+    if (depth > maxDepth)
+      return;
+    let children;
+    try {
+      children = readdirSync(absolute, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    children.sort((a, b) => {
+      if (a.isDirectory() && !b.isDirectory())
+        return -1;
+      if (!a.isDirectory() && b.isDirectory())
+        return 1;
+      return a.name.localeCompare(b.name);
+    });
+    for (const entry of children) {
+      if (entry.name.startsWith("."))
+        continue;
+      if (entries.length >= HARD_MAX_TREE_ENTRIES) {
+        truncated = true;
+        return;
+      }
+      const childAbs = join(absolute, entry.name);
+      const vfsPath = toVfsPath(contextDir, childAbs);
+      if (entry.isDirectory()) {
+        entries.push({ path: vfsPath, type: "directory", depth });
+        walk(childAbs, depth + 1);
+      } else if (entry.isFile()) {
+        entries.push({ path: vfsPath, type: "file", depth });
+      }
+    }
+  }
+  walk(scope, 1);
+  return { root: rootLabel, entries, truncated };
+}
+function parseMarkdownHeadings(content) {
+  const lines = content.split("\n");
+  const headings = [];
+  let fence = null;
+  for (let i = 0; i < lines.length; i++) {
+    const rawLine = lines[i];
+    if (rawLine === void 0)
+      continue;
+    const trimmed = rawLine.trim();
+    if (!fence && (trimmed.startsWith("```") || trimmed.startsWith("~~~"))) {
+      fence = trimmed.slice(0, 3);
+      continue;
+    }
+    if (fence && trimmed.startsWith(fence)) {
+      fence = null;
+      continue;
+    }
+    if (fence)
+      continue;
+    const match = /^(#{1,6})\s+(.+?)\s*#*\s*$/.exec(rawLine);
+    if (match) {
+      headings.push({ line: i + 1, level: match[1].length, text: match[2] });
+    }
+  }
+  return headings;
+}
+function readMarkdownSection(contextDir, opts) {
+  const absolute = resolveScope(contextDir, opts.path);
+  if (!absolute)
+    return { exists: false, headings: [] };
+  let content;
+  try {
+    const st = statSync(absolute);
+    if (!st.isFile())
+      return { exists: false, headings: [] };
+    content = readFileSync(absolute, "utf-8");
+  } catch {
+    return { exists: false, headings: [] };
+  }
+  const headings = parseMarkdownHeadings(content);
+  const result = { exists: true, headings };
+  if (!opts.heading)
+    return result;
+  const needle = opts.heading.toLowerCase();
+  const matches = headings.filter((h) => h.text.toLowerCase().includes(needle));
+  if (matches.length === 0)
+    return result;
+  const selected = matches[0];
+  if (!selected)
+    return result;
+  const selectedIdx = headings.indexOf(selected);
+  const lines = content.split("\n");
+  let endLine = lines.length;
+  for (let i = selectedIdx + 1; i < headings.length; i++) {
+    const heading = headings[i];
+    if (heading && heading.level <= selected.level) {
+      endLine = heading.line - 1;
+      break;
+    }
+  }
+  const sectionLines = lines.slice(selected.line - 1, endLine);
+  result.match = {
+    heading: selected,
+    startLine: selected.line,
+    endLine,
+    content: sectionLines.join("\n"),
+    ambiguousMatches: matches.length > 1 ? matches.length : void 0
+  };
+  return result;
+}
+async function tailVfs(contextDir, opts) {
+  const absolute = resolveScope(contextDir, opts.path);
+  if (!absolute)
+    return { content: "", returnedLines: 0, size: 0, exists: false };
+  let size;
+  try {
+    const st = statSync(absolute);
+    if (!st.isFile())
+      return { content: "", returnedLines: 0, size: 0, exists: false };
+    size = st.size;
+  } catch {
+    return { content: "", returnedLines: 0, size: 0, exists: false };
+  }
+  const n = Math.max(1, Math.min(opts.lines ?? DEFAULT_TAIL_LINES, HARD_MAX_TAIL_LINES));
+  let stdout;
+  try {
+    const res = await execFileAsync("tail", ["-n", String(n), "--", absolute], {
+      timeout: TAIL_TIMEOUT_MS,
+      maxBuffer: HARD_MAX_OUTPUT_BYTES
+    });
+    stdout = res.stdout;
+  } catch (error) {
+    const err = error;
+    vfsLogger().warn({ path: opts.path, stderr: err.stderr }, "tail failed");
+    stdout = err.stdout ?? "";
+  }
+  const trimmed = stdout.endsWith("\n") ? stdout.slice(0, -1) : stdout;
+  const returnedLines = trimmed.length === 0 ? 0 : trimmed.split("\n").length;
+  return { content: stdout, returnedLines, size, exists: true };
+}
+function yamlTypeOf(value) {
+  if (value === null || value === void 0)
+    return "null";
+  if (Array.isArray(value))
+    return "array";
+  if (typeof value === "object")
+    return "object";
+  if (typeof value === "number")
+    return "number";
+  if (typeof value === "boolean")
+    return "boolean";
+  return "string";
+}
+function yamlPreview(value) {
+  const t = yamlTypeOf(value);
+  if (t === "null")
+    return "null";
+  if (t === "string") {
+    const s = String(value);
+    return s.length > 80 ? `"${s.slice(0, 77)}..."` : `"${s}"`;
+  }
+  if (t === "number" || t === "boolean")
+    return String(value);
+  if (t === "array")
+    return `[${value.length} items]`;
+  const keys = Object.keys(value);
+  return `{${keys.length} keys: ${keys.slice(0, 5).join(", ")}${keys.length > 5 ? ", ..." : ""}}`;
+}
+function resolveYamlKeyPath(root, keyPath) {
+  const segments = keyPath.split(".");
+  let current2 = root;
+  for (const seg of segments) {
+    if (current2 === null || current2 === void 0)
+      return void 0;
+    if (Array.isArray(current2)) {
+      const idx = parseInt(seg, 10);
+      if (Number.isNaN(idx) || idx < 0 || idx >= current2.length)
+        return void 0;
+      current2 = current2[idx];
+    } else if (typeof current2 === "object") {
+      const obj = current2;
+      if (!(seg in obj))
+        return void 0;
+      current2 = obj[seg];
+    } else {
+      return void 0;
+    }
+  }
+  return current2;
+}
+function listYamlKeys(value) {
+  if (value === null || value === void 0)
+    return [];
+  if (Array.isArray(value)) {
+    return value.map((item, i) => ({
+      key: String(i),
+      type: yamlTypeOf(item),
+      preview: yamlPreview(item)
+    }));
+  }
+  if (typeof value === "object") {
+    return Object.entries(value).map(([k, v]) => ({
+      key: k,
+      type: yamlTypeOf(v),
+      preview: yamlPreview(v)
+    }));
+  }
+  return [];
+}
+function readYamlPath(contextDir, opts) {
+  const absolute = resolveScope(contextDir, opts.path);
+  if (!absolute)
+    return { exists: false, keys: [] };
+  let content;
+  try {
+    const st = statSync(absolute);
+    if (!st.isFile())
+      return { exists: false, keys: [] };
+    content = readFileSync(absolute, "utf-8");
+  } catch {
+    return { exists: false, keys: [] };
+  }
+  let parsed;
+  try {
+    parsed = yaml2.load(content);
+  } catch (e) {
+    vfsLogger().warn({ path: opts.path, error: e instanceof Error ? e.message : String(e) }, "YAML parse failed");
+    return { exists: true, keys: [] };
+  }
+  if (!opts.keyPath) {
+    return { exists: true, keys: listYamlKeys(parsed) };
+  }
+  const value = resolveYamlKeyPath(parsed, opts.keyPath);
+  if (value === void 0) {
+    return { exists: true, keys: listYamlKeys(parsed) };
+  }
+  const t = yamlTypeOf(value);
+  const serialized = t === "string" || t === "number" || t === "boolean" || t === "null" ? String(value) : yaml2.dump(value, { lineWidth: 120, noRefs: true }).trimEnd();
+  const result = {
+    exists: true,
+    keys: listYamlKeys(value),
+    match: {
+      keyPath: opts.keyPath,
+      type: t,
+      content: serialized
+    }
+  };
+  return result;
+}
+var DEFAULT_CSV_PREVIEW_ROWS = 10;
+var HARD_MAX_CSV_ROWS = 200;
+function parseCsvLine(line) {
+  const fields = [];
+  let current2 = "";
+  let inQuotes = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"') {
+        if (i + 1 < line.length && line[i + 1] === '"') {
+          current2 += '"';
+          i++;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        current2 += ch;
+      }
+    } else {
+      if (ch === '"') {
+        inQuotes = true;
+      } else if (ch === ",") {
+        fields.push(current2.trim());
+        current2 = "";
+      } else {
+        current2 += ch;
+      }
+    }
+  }
+  fields.push(current2.trim());
+  return fields;
+}
+function readCsvRows(contextDir, opts) {
+  const absolute = resolveScope(contextDir, opts.path);
+  if (!absolute)
+    return { exists: false, headers: [], totalRows: 0, rows: [], truncated: false };
+  let content;
+  try {
+    const st = statSync(absolute);
+    if (!st.isFile())
+      return { exists: false, headers: [], totalRows: 0, rows: [], truncated: false };
+    content = readFileSync(absolute, "utf-8");
+  } catch {
+    return { exists: false, headers: [], totalRows: 0, rows: [], truncated: false };
+  }
+  const rawLines = content.split("\n").filter((l) => l.trim().length > 0);
+  if (rawLines.length === 0) {
+    return { exists: true, headers: [], totalRows: 0, rows: [], truncated: false };
+  }
+  const headerFields = parseCsvLine(rawLines[0]);
+  const headers = headerFields.map((name, index) => ({ name, index }));
+  const headerNames = new Set(headerFields.map((h) => h.toLowerCase()));
+  const maxRows = Math.min(opts.maxRows ?? DEFAULT_CSV_PREVIEW_ROWS, HARD_MAX_CSV_ROWS);
+  const selectedCols = opts.columns ? opts.columns.filter((c) => headerNames.has(c.toLowerCase())) : void 0;
+  const filterCol = opts.filterColumn?.toLowerCase();
+  const filterVal = opts.filterValue?.toLowerCase();
+  const filterIdx = filterCol ? headerFields.findIndex((h) => h.toLowerCase() === filterCol) : -1;
+  const rows = [];
+  let matchedTotal = 0;
+  const totalRows = rawLines.length - 1;
+  for (let i = 1; i < rawLines.length; i++) {
+    const fields = parseCsvLine(rawLines[i]);
+    if (filterIdx >= 0 && filterVal) {
+      const cellValue = (fields[filterIdx] ?? "").toLowerCase();
+      if (!cellValue.includes(filterVal))
+        continue;
+    }
+    matchedTotal++;
+    if (rows.length >= maxRows)
+      continue;
+    const row = {};
+    if (selectedCols) {
+      for (const col of selectedCols) {
+        const idx = headerFields.findIndex((h) => h.toLowerCase() === col.toLowerCase());
+        if (idx >= 0)
+          row[headerFields[idx]] = fields[idx] ?? "";
+      }
+    } else {
+      for (let j = 0; j < headerFields.length; j++) {
+        row[headerFields[j]] = fields[j] ?? "";
+      }
+    }
+    rows.push(row);
+  }
+  const result = {
+    exists: true,
+    headers,
+    totalRows,
+    rows,
+    truncated: rows.length < matchedTotal
+  };
+  if (filterIdx >= 0 && filterVal) {
+    result.filterApplied = {
+      column: opts.filterColumn,
+      value: opts.filterValue,
+      matchedRows: matchedTotal
+    };
+  }
+  return result;
+}
+
+// ../../vfs-search/dist/manifest.js
+import { createHash } from "node:crypto";
+import { readdirSync as readdirSync2, readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
+import { join as join2, relative as relative2 } from "node:path";
+var HASH_HEX = 32;
+var defaultFileHasher = (_meta, absPath) => createHash("sha256").update(readFileSync2(absPath)).digest("hex");
+function walkFiles(root) {
+  const out = [];
+  function walk(dir) {
+    let entries;
+    try {
+      entries = readdirSync2(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === ".git")
+        continue;
+      const abs = join2(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(abs);
+      } else if (entry.isFile()) {
+        let st;
+        try {
+          st = statSync2(abs);
+        } catch {
+          continue;
+        }
+        out.push({
+          path: relative2(root, abs).split("\\").join("/"),
+          mtimeMs: st.mtimeMs,
+          size: st.size
+        });
+      }
+    }
+  }
+  walk(root);
+  out.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return out;
+}
+function hashLocalFile(absPath, hasher = defaultFileHasher) {
+  let st;
+  try {
+    st = statSync2(absPath);
+  } catch {
+    return "";
+  }
+  return hasher({ path: absPath, mtimeMs: st.mtimeMs, size: st.size }, absPath).slice(0, HASH_HEX);
+}
+
+// src/mirror-backend.ts
+import yaml3 from "js-yaml";
+var READ_MAX_BYTES = 1048576;
+function log(msg) {
+  process.stderr.write(`[dudamel-mcp-context] ${msg}
+`);
+}
+var MirrorContextBackend = class {
+  http;
+  mirrorDir;
+  statePath;
+  ttlMs;
+  maxBytes;
+  /** entry path -> applied digest (files materialized on disk). */
+  applied = /* @__PURE__ */ new Map();
+  /** entries that contain an un-mirrorable file (>1 MiB) — always served via HTTP for parity. */
+  proxyOnly = /* @__PURE__ */ new Set();
+  lastManifest = null;
+  lastManifestAt = 0;
+  refreshing = null;
+  disabled = false;
+  constructor(http, cache) {
+    this.http = http;
+    this.mirrorDir = join3(cache.dir, "mirror");
+    this.statePath = join3(cache.dir, "state.json");
+    this.ttlMs = cache.ttlMs;
+    this.maxBytes = cache.maxBytes;
+    this.loadState();
+  }
+  // ── State persistence (warm start across sessions) ─────────────────────────
+  loadState() {
+    try {
+      const raw = JSON.parse(readFileSync3(this.statePath, "utf-8"));
+      for (const [k, v] of Object.entries(raw.appliedDigests ?? {})) this.applied.set(k, v);
+      this.lastManifestAt = typeof raw.lastManifestAt === "number" ? raw.lastManifestAt : 0;
+    } catch {
+    }
+  }
+  saveState() {
+    const state = {
+      appliedDigests: Object.fromEntries(this.applied),
+      lastManifestAt: this.lastManifestAt
+    };
+    try {
+      mkdirSync(dirname(this.statePath), { recursive: true });
+      writeFileSync(this.statePath, JSON.stringify(state), "utf-8");
+    } catch (error) {
+      log(
+        `failed to persist cache state: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  // ── Freshness / refresh ────────────────────────────────────────────────────
+  /** Synchronously bring the mirror up to date (pre-warm; also used by tests). */
+  async warm() {
+    if (this.disabled) return;
+    await this.refresh();
+  }
+  /** Kick off a background refresh if the manifest is stale. Never blocks. */
+  ensureFresh() {
+    if (this.disabled || this.refreshing) return;
+    const now = Date.now();
+    if (this.lastManifestAt !== 0 && now - this.lastManifestAt < this.ttlMs) return;
+    this.refreshing = this.refresh().catch((error) => {
+      log(`refresh failed: ${error instanceof Error ? error.message : String(error)}`);
+    }).finally(() => {
+      this.refreshing = null;
+    });
+  }
+  async refresh() {
+    const manifest = await this.http.getManifest();
+    const total = manifest.entries.reduce((sum, e) => sum + entrySize(e), 0);
+    if (total > this.maxBytes) {
+      this.disabled = true;
+      log(
+        `VFS (${Math.round(total / 1024)} KiB) exceeds cache cap (${Math.round(
+          this.maxBytes / 1024
+        )} KiB) \u2014 local cache disabled, serving via HTTP.`
+      );
+      return;
+    }
+    const manifestPaths = new Set(manifest.entries.map((e) => e.path));
+    for (const entry of manifest.entries) {
+      if (this.applied.get(entry.path) === entry.digest && !this.proxyOnly.has(entry.path)) {
+        continue;
+      }
+      try {
+        await this.refreshEntry(entry);
+      } catch (error) {
+        log(
+          `failed to mirror "${entry.path}": ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    for (const applied of [...this.applied.keys()]) {
+      if (!manifestPaths.has(applied)) {
+        rmSync(join3(this.mirrorDir, applied), { recursive: true, force: true });
+        this.applied.delete(applied);
+        this.proxyOnly.delete(applied);
+      }
+    }
+    this.lastManifest = manifest;
+    this.lastManifestAt = Date.now();
+    this.saveState();
+  }
+  async refreshEntry(entry) {
+    if (entry.type === "file") {
+      if (entry.size > READ_MAX_BYTES) {
+        this.markProxyOnly(entry.path);
+        return;
+      }
+      const abs = join3(this.mirrorDir, entry.path);
+      if (hashLocalFile(abs) !== entry.digest) await this.downloadFile(entry.path);
+      this.applied.set(entry.path, entry.digest);
+      this.proxyOnly.delete(entry.path);
+      return;
+    }
+    if (entry.files.some((f) => f.size > READ_MAX_BYTES)) {
+      this.markProxyOnly(entry.path);
+      return;
+    }
+    const entryDir = join3(this.mirrorDir, entry.path);
+    const target = new Set(entry.files.map((f) => f.path));
+    for (const f of entry.files) {
+      const abs = join3(entryDir, f.path);
+      if (hashLocalFile(abs) !== f.hash) {
+        await this.downloadFile(`${entry.path}/${f.path}`);
+      }
+    }
+    if (existsSync2(entryDir)) {
+      for (const local of walkFiles(entryDir)) {
+        if (!target.has(local.path)) rmSync(join3(entryDir, local.path), { force: true });
+      }
+      pruneEmptyDirs(entryDir);
+    }
+    this.applied.set(entry.path, entry.digest);
+    this.proxyOnly.delete(entry.path);
+  }
+  markProxyOnly(entryPath) {
+    this.proxyOnly.add(entryPath);
+    this.applied.delete(entryPath);
+    rmSync(join3(this.mirrorDir, entryPath), { recursive: true, force: true });
+  }
+  /** Fetch one file over HTTP and write it into the mirror atomically. */
+  async downloadFile(vfsPath) {
+    const res = await this.http.readFile(vfsPath);
+    const abs = join3(this.mirrorDir, vfsPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    const tmp = `${abs}.tmp-${process.pid}-${writeCounter++}`;
+    writeFileSync(tmp, res.content, "utf-8");
+    renameSync(tmp, abs);
+  }
+  // ── Serving decisions ──────────────────────────────────────────────────────
+  /** Top-level entry name for a VFS path ("src/foo/bar.md" -> "src"). */
+  entryOf(vfsPath) {
+    return vfsPath.split("/").filter((s) => s.length > 0)[0];
+  }
+  /** Can this path be answered from the mirror? (undefined = whole-VFS op). */
+  canServe(vfsPath) {
+    if (this.disabled) return false;
+    if (vfsPath === void 0 || vfsPath === "") return this.fullyWarm();
+    const top = this.entryOf(vfsPath);
+    return top !== void 0 && this.applied.has(top) && !this.proxyOnly.has(top);
+  }
+  /** Whole-VFS reads (unscoped grep/find) need every current entry mirrored. */
+  fullyWarm() {
+    if (this.disabled || !this.lastManifest) return false;
+    return this.lastManifest.entries.every(
+      (e) => this.applied.get(e.path) === e.digest && !this.proxyOnly.has(e.path)
+    );
+  }
+  // ── ContextBackend surface ─────────────────────────────────────────────────
+  async grep(req) {
+    this.ensureFresh();
+    if (!this.canServe(req.path)) return this.http.grep(req);
+    return grepVfs(this.mirrorDir, {
+      pattern: req.pattern,
+      path: req.path,
+      maxResults: req.maxResults,
+      fixedString: req.fixedString,
+      ignoreCase: req.ignoreCase
+    });
+  }
+  async find(req) {
+    this.ensureFresh();
+    if (!this.canServe(req.path)) return this.http.find(req);
+    return findVfs(this.mirrorDir, {
+      name: req.name,
+      path: req.path,
+      maxResults: req.maxResults,
+      type: req.type
+    });
+  }
+  async stat(path) {
+    this.ensureFresh();
+    if (!this.canServe(path)) return this.http.stat(path);
+    return statVfs(this.mirrorDir, path);
+  }
+  async tree(path, maxDepth) {
+    this.ensureFresh();
+    if (!this.canServe(path)) return this.http.tree(path, maxDepth);
+    return treeVfs(this.mirrorDir, { path, maxDepth });
+  }
+  async tail(path, lines) {
+    this.ensureFresh();
+    if (!this.canServe(path)) return this.http.tail(path, lines);
+    return tailVfs(this.mirrorDir, { path, lines });
+  }
+  async readSection(path, heading) {
+    this.ensureFresh();
+    if (!this.canServe(path)) return this.http.readSection(path, heading);
+    return readMarkdownSection(this.mirrorDir, { path, heading });
+  }
+  async readYaml(path, keyPath) {
+    this.ensureFresh();
+    if (!this.canServe(path)) return this.http.readYaml(path, keyPath);
+    return readYamlPath(this.mirrorDir, { path, keyPath });
+  }
+  async readCsv(path, opts) {
+    this.ensureFresh();
+    if (!this.canServe(path)) return this.http.readCsv(path, opts);
+    return readCsvRows(this.mirrorDir, { path, ...opts });
+  }
+  async readFile(vfsPath) {
+    this.ensureFresh();
+    if (!this.canServe(vfsPath)) return this.http.readFile(vfsPath);
+    const abs = join3(this.mirrorDir, vfsPath);
+    try {
+      const st = statSync3(abs);
+      if (!st.isFile() || st.size > READ_MAX_BYTES) return this.http.readFile(vfsPath);
+      const content = readFileSync3(abs, "utf-8");
+      const segments = vfsPath.split("/").filter((s) => s.length > 0);
+      const displayPath = segments.length <= 1 ? vfsPath : segments.slice(1).join("/");
+      return { content, size: st.size, path: displayPath };
+    } catch {
+      return this.http.readFile(vfsPath);
+    }
+  }
+  async readDirectoryCatalog(dirPath) {
+    const trimmed = dirPath.replace(/\/$/, "");
+    const catalogPath = trimmed.length === 0 ? ".index.yaml" : `${trimmed}/.index.yaml`;
+    const raw = await this.readFile(catalogPath);
+    const parsed = yaml3.load(raw.content);
+    if (parsed == null || typeof parsed !== "object") {
+      throw new Error(`Catalog YAML did not parse into an object: ${typeof parsed}`);
+    }
+    return parsed;
+  }
+};
+var writeCounter = 0;
+function entrySize(entry) {
+  return entry.type === "file" ? entry.size : entry.files.reduce((s, f) => s + f.size, 0);
+}
+function pruneEmptyDirs(root) {
+  function walk(dir) {
+    let entries;
+    try {
+      entries = readdirSync3(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        const child = join3(dir, e.name);
+        walk(child);
+        try {
+          if (readdirSync3(child).length === 0) rmSync(child, { recursive: true, force: true });
+        } catch {
+        }
+      }
+    }
+  }
+  walk(root);
+}
+
+// src/tools/instructions.ts
+function registerInstructionsTool(server, client) {
+  server.tool(
+    "get_instructions",
+    "Read the usage guide for this knowledge base (AGENTS.md). Recommended on your first interaction \u2014 it explains the .index.yaml catalog structure and navigation conventions. Not required: `list_sources` and `browse` work without it.",
+    {},
+    { readOnlyHint: true },
+    async () => {
+      try {
+        const result = await client.readFile("AGENTS.md");
+        return {
+          content: [{ type: "text", text: result.content }]
+        };
+      } catch (error) {
+        if (error instanceof ContextServerError && error.status === 404) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: 'No AGENTS.md was found at the VFS root. The admin may not have seeded one yet. For reference, each directory should contain a .index.yaml like:\n\n```yaml\ndescription: "Summary of this directory"\nentries:\n  - path: file.md\n    type: file\n    description: "Summary of this file"\n```\n\nStart by calling `list_sources`, then `browse` to drill down, and `read_file` for actual content.'
+              }
+            ]
+          };
+        }
+        throw error;
+      }
+    }
+  );
+}
+
+// src/tools/navigate.ts
+import { z } from "zod";
+function registerListSourcesTool(server, client) {
+  server.tool(
+    "list_sources",
+    "List the top-level knowledge sources in this VFS. Each source is a directory at the VFS root with its own documentation tree. Use this to discover what is available, then call `browse` on a source to explore it. If you have not read the usage guide yet, call `get_instructions` first.",
+    {},
+    { readOnlyHint: true },
+    async () => {
+      const catalog = await client.readDirectoryCatalog("");
+      const entries = catalog.entries ?? [];
+      if (entries.length === 0) {
+        return {
+          content: [{ type: "text", text: "No sources are configured in the VFS yet." }]
+        };
+      }
+      const text = entries.map((e) => `- **${e.path}** \u2014 ${e.description || "(no description)"}`).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+function registerBrowseTool(server, client) {
+  server.tool(
+    "browse",
+    'List the contents of a directory in the VFS with a description for each entry. Path is VFS-relative, e.g. "my-source" or "my-source/subdir". Omit `path` to browse the root. Prefer this over `read_file` for navigation \u2014 reading catalog descriptions is much cheaper than reading every file.',
+    {
+      path: z.string().optional().describe(
+        'VFS path to the directory. Examples: "my-source", "my-source/tech", "". Leave empty for the root.'
+      )
+    },
+    { readOnlyHint: true },
+    async ({ path }) => {
+      const normalised = (path ?? "").replace(/\/$/, "");
+      try {
+        const catalog = await client.readDirectoryCatalog(normalised);
+        const lines = [
+          normalised === "" ? "# / (root)" : `# /${normalised}`,
+          "",
+          catalog.description ? catalog.description : "(no directory description)",
+          "",
+          "## Entries"
+        ];
+        if (!catalog.entries || catalog.entries.length === 0) {
+          lines.push("_(empty)_");
+        } else {
+          for (const entry of catalog.entries) {
+            lines.push(
+              `- **${entry.path}** (${entry.type}) \u2014 ${entry.description || "(no description)"}`
+            );
+          }
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
+      } catch (error) {
+        if (error instanceof ContextServerError && error.status === 404) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No directory catalog found at "${normalised}". The path may not exist or may not have been indexed yet. Try \`list_sources\` to see what's available.`
+              }
+            ],
+            isError: true
+          };
+        }
+        throw error;
+      }
+    }
+  );
+}
+function registerTreeTool(server, client) {
+  server.tool(
+    "tree",
+    "Recursively list directories + files under a VFS path, with depth information. Returns a compact outline \u2014 much cheaper than chained `browse` calls when you want a broad map. Defaults to depth 3; max 10.",
+    {
+      path: z.string().optional().describe(
+        'VFS path to the subtree root. Examples: "my-source", "my-source/tech". Omit for the whole VFS.'
+      ),
+      maxDepth: z.number().int().min(1).max(10).optional().describe("How many levels deep to descend (default 3, hard cap 10).")
+    },
+    { readOnlyHint: true },
+    async ({ path, maxDepth }) => {
+      const result = await client.tree(path, maxDepth);
+      if (result.entries.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No entries under ${result.root ? `"${result.root}"` : "the VFS root"} (or it doesn't exist).`
+            }
+          ]
+        };
+      }
+      const lines = formatTree(result.entries);
+      const footer = result.truncated ? "\n\n(truncated \u2014 pass a more specific `path` or a smaller `maxDepth`)" : "";
+      const header = result.root ? `# /${result.root}
+` : "# / (root)\n";
+      return { content: [{ type: "text", text: header + lines + footer }] };
+    }
+  );
+}
+function formatTree(entries) {
+  return entries.map((e) => {
+    const indent = "  ".repeat(Math.max(0, e.depth - 1));
+    const suffix = e.type === "directory" ? "/" : "";
+    return `${indent}- ${e.path}${suffix}`;
+  }).join("\n");
+}
+
+// src/tools/read.ts
+import { z as z2 } from "zod";
+var MAX_SLICE_BYTES = 256 * 1024;
+var MAX_TAIL_LINES = 1e3;
+function registerReadFileTool(server, client) {
+  server.tool(
+    "read_file",
+    `Read the full text of a file in the VFS. Path is VFS-relative, e.g. "AGENTS.md" or "my-source/tech/spec.md". Supports optional byte offset + length slicing for big files (max ${MAX_SLICE_BYTES} bytes per call). Prefer \`browse\` first to see descriptions before reading.`,
+    {
+      path: z2.string().min(1).describe('VFS path to the file. Examples: "AGENTS.md", "my-source/tech/spec.md".'),
+      offset: z2.number().int().nonnegative().optional().describe("Optional byte offset to start reading from. Defaults to 0."),
+      length: z2.number().int().positive().optional().describe(`Optional max bytes to return. Capped at ${MAX_SLICE_BYTES}.`)
+    },
+    { readOnlyHint: true },
+    async ({ path, offset, length }) => {
+      try {
+        const file = await client.readFile(path);
+        const start = offset ?? 0;
+        const requested = Math.min(length ?? MAX_SLICE_BYTES, MAX_SLICE_BYTES);
+        const totalChars = file.content.length;
+        const totalBytes = file.size;
+        if (start >= totalChars) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `File "${path}" is ${totalBytes} bytes. Offset ${start} is past the end.`
+              }
+            ]
+          };
+        }
+        const slice = file.content.slice(start, start + requested);
+        const end = start + slice.length;
+        const truncated = end < totalChars;
+        const header = start === 0 && !truncated ? `# ${path} (${totalBytes} bytes)` : `# ${path} \u2014 chars ${start}..${end} of ${totalChars} (${totalBytes} bytes)${truncated ? ` (truncated, call again with offset=${end} for more)` : ""}`;
+        return {
+          content: [{ type: "text", text: `${header}
+
+${slice}` }]
+        };
+      } catch (error) {
+        if (error instanceof ContextServerError) {
+          if (error.status === 404) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `File "${path}" not found. Use \`browse\` to see what exists at that path.`
+                }
+              ],
+              isError: true
+            };
+          }
+          if (error.status === 413) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: `File "${path}" is too large to fetch in one call. Use the \`offset\` + \`length\` arguments to read it in chunks.`
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+        throw error;
+      }
+    }
+  );
+}
+function registerStatTool(server, client) {
+  server.tool(
+    "stat",
+    "Return metadata for a VFS path (exists, type, size, lines, entries, modified). Use this to size a file before reading or to confirm a path before acting on it.",
+    {
+      path: z2.string().min(1).describe('VFS path. Examples: "AGENTS.md", "my-source/tech", "my-source/CLAUDE.md".')
+    },
+    { readOnlyHint: true },
+    async ({ path }) => {
+      const info = await client.stat(path);
+      if (!info.exists) {
+        return {
+          content: [{ type: "text", text: `"${path}" does not exist in the VFS.` }]
+        };
+      }
+      const bits = [`# ${path}`, `type: ${info.type ?? "unknown"}`];
+      if (info.size !== void 0) bits.push(`size: ${info.size} bytes`);
+      if (info.lines !== void 0) bits.push(`lines: ${info.lines}`);
+      if (info.entries !== void 0) bits.push(`entries: ${info.entries}`);
+      if (info.modified) bits.push(`modified: ${info.modified}`);
+      return { content: [{ type: "text", text: bits.join("\n") }] };
+    }
+  );
+}
+function registerTailTool(server, client) {
+  server.tool(
+    "tail",
+    `Return the last N lines of a VFS file (default 20, max ${MAX_TAIL_LINES}). Use this for logs or when you only need the tail of a large file \u2014 for arbitrary byte slices, use \`read_file\` with offset/length.`,
+    {
+      path: z2.string().min(1).describe("VFS path to the file."),
+      lines: z2.number().int().positive().max(MAX_TAIL_LINES).optional().describe(`Number of trailing lines to return (default 20, max ${MAX_TAIL_LINES}).`)
+    },
+    { readOnlyHint: true },
+    async ({ path, lines }) => {
+      try {
+        const result = await client.tail(path, lines);
+        if (!result.exists) {
+          return {
+            content: [{ type: "text", text: `File "${path}" does not exist in the VFS.` }],
+            isError: true
+          };
+        }
+        const header = `# ${path} \u2014 last ${result.returnedLines} line${result.returnedLines === 1 ? "" : "s"} of ${result.size} bytes`;
+        return { content: [{ type: "text", text: `${header}
+
+${result.content}` }] };
+      } catch (error) {
+        if (error instanceof ContextServerError && error.status === 404) {
+          return {
+            content: [{ type: "text", text: `File "${path}" not found.` }],
+            isError: true
+          };
+        }
+        throw error;
+      }
+    }
+  );
+}
+function registerReadSectionTool(server, client) {
+  server.tool(
+    "read_section",
+    "Read a single section of a markdown file by heading (case-insensitive substring match). The section spans from the matched heading down to the next heading at the same or higher level. Omit `heading` to just list the file's available headings. Ideal to pull one part of a large doc without reading it all.",
+    {
+      path: z2.string().min(1).describe("VFS path to the markdown file."),
+      heading: z2.string().optional().describe(
+        'Heading text or case-insensitive substring (e.g. "Screens", "state management"). Omit to list headings.'
+      )
+    },
+    { readOnlyHint: true },
+    async ({ path, heading }) => {
+      try {
+        const result = await client.readSection(path, heading);
+        if (!result.exists) {
+          return {
+            content: [{ type: "text", text: `File "${path}" does not exist in the VFS.` }],
+            isError: true
+          };
+        }
+        if (!heading) {
+          if (result.headings.length === 0) {
+            return {
+              content: [{ type: "text", text: `File "${path}" has no markdown headings.` }]
+            };
+          }
+          const lines = result.headings.map(
+            (h) => `${"  ".repeat(Math.max(0, h.level - 1))}- L${h.line} (h${h.level}): ${h.text}`
+          );
+          return {
+            content: [{ type: "text", text: `# Headings in ${path}
+
+${lines.join("\n")}` }]
+          };
+        }
+        if (!result.match) {
+          const suggestions = result.headings.length === 0 ? " No headings in this file." : ` Available headings: ${result.headings.map((h) => `"${h.text}"`).join(", ")}.`;
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No heading in "${path}" matched "${heading}".${suggestions}`
+              }
+            ],
+            isError: true
+          };
+        }
+        const { match } = result;
+        const ambig = match.ambiguousMatches ? ` (${match.ambiguousMatches} headings matched; returning the first)` : "";
+        const header = `# ${path} \u2014 section "${match.heading.text}" (L${match.startLine}..${match.endLine})${ambig}`;
+        return {
+          content: [{ type: "text", text: `${header}
+
+${match.content}` }]
+        };
+      } catch (error) {
+        if (error instanceof ContextServerError && error.status === 404) {
+          return {
+            content: [{ type: "text", text: `File "${path}" not found.` }],
+            isError: true
+          };
+        }
+        throw error;
+      }
+    }
+  );
+}
+function registerReadYamlTool(server, client) {
+  server.tool(
+    "read_yaml",
+    'Read a YAML file by key path. Omit `keyPath` to list top-level keys with types and previews. Provide a dot-separated `keyPath` (e.g. "database.host", "servers.0.port") to extract a specific value. Ideal for inspecting config files, workflow definitions, or catalog metadata without reading the whole file.',
+    {
+      path: z2.string().min(1).describe("VFS path to the YAML file."),
+      keyPath: z2.string().optional().describe(
+        'Dot-separated key path (e.g. "database.host", "items.0.name"). Omit to list top-level keys.'
+      )
+    },
+    { readOnlyHint: true },
+    async ({ path, keyPath }) => {
+      try {
+        const result = await client.readYaml(path, keyPath);
+        if (!result.exists) {
+          return {
+            content: [{ type: "text", text: `File "${path}" does not exist in the VFS.` }],
+            isError: true
+          };
+        }
+        if (!keyPath) {
+          if (result.keys.length === 0) {
+            return {
+              content: [
+                { type: "text", text: `File "${path}" is empty or not a valid YAML structure.` }
+              ]
+            };
+          }
+          const lines = result.keys.map(
+            (k) => `- **${k.key}** (${k.type}): ${k.preview}`
+          );
+          return {
+            content: [{ type: "text", text: `# Keys in ${path}
+
+${lines.join("\n")}` }]
+          };
+        }
+        if (!result.match) {
+          const available = result.keys.length > 0 ? ` Available keys: ${result.keys.map((k) => `"${k.key}"`).join(", ")}.` : " No keys found.";
+          return {
+            content: [
+              { type: "text", text: `Key path "${keyPath}" not found in "${path}".${available}` }
+            ],
+            isError: true
+          };
+        }
+        const { match } = result;
+        const childInfo = result.keys.length > 0 ? `
+
+Child keys: ${result.keys.map((k) => `${k.key} (${k.type})`).join(", ")}` : "";
+        const header = `# ${path} \u2192 ${match.keyPath} (${match.type})${childInfo}`;
+        return {
+          content: [{ type: "text", text: `${header}
+
+${match.content}` }]
+        };
+      } catch (error) {
+        if (error instanceof ContextServerError && error.status === 404) {
+          return {
+            content: [{ type: "text", text: `File "${path}" not found.` }],
+            isError: true
+          };
+        }
+        throw error;
+      }
+    }
+  );
+}
+var MAX_CSV_ROWS = 200;
+function registerReadCsvTool(server, client) {
+  server.tool(
+    "read_csv",
+    `Read a CSV file with optional filtering. Without filters, returns column headers and a preview of the first rows. With \`filterColumn\` + \`filterValue\`, returns rows where that column matches (case-insensitive substring). Use \`columns\` to select only specific columns and reduce output size. Max ${MAX_CSV_ROWS} rows per call.`,
+    {
+      path: z2.string().min(1).describe("VFS path to the CSV file."),
+      filterColumn: z2.string().optional().describe("Column name to filter on (case-insensitive)."),
+      filterValue: z2.string().optional().describe("Value to match in the filter column (case-insensitive substring)."),
+      columns: z2.array(z2.string()).optional().describe("Column names to include in the output. Omit for all columns."),
+      maxRows: z2.number().int().positive().max(MAX_CSV_ROWS).optional().describe(`Max rows to return (default 10, max ${MAX_CSV_ROWS}).`)
+    },
+    { readOnlyHint: true },
+    async ({ path, filterColumn, filterValue, columns, maxRows }) => {
+      try {
+        const result = await client.readCsv(path, { filterColumn, filterValue, columns, maxRows });
+        if (!result.exists) {
+          return {
+            content: [{ type: "text", text: `File "${path}" does not exist in the VFS.` }],
+            isError: true
+          };
+        }
+        if (result.headers.length === 0) {
+          return {
+            content: [{ type: "text", text: `File "${path}" is empty or has no CSV headers.` }]
+          };
+        }
+        const colList = result.headers.map((h) => h.name).join(", ");
+        const filterInfo = result.filterApplied ? ` | filter: ${result.filterApplied.column}="${result.filterApplied.value}" \u2192 ${result.filterApplied.matchedRows} matches` : "";
+        const truncInfo = result.truncated ? " (truncated)" : "";
+        const header = `# ${path} \u2014 ${result.totalRows} rows, ${result.headers.length} columns${filterInfo}${truncInfo}
+Columns: ${colList}`;
+        if (result.rows.length === 0) {
+          const msg = result.filterApplied ? `No rows matched filter ${result.filterApplied.column}="${result.filterApplied.value}".` : "No data rows found.";
+          return { content: [{ type: "text", text: `${header}
+
+${msg}` }] };
+        }
+        const displayCols = columns && columns.length > 0 ? result.headers.filter(
+          (h) => columns.some((c) => c.toLowerCase() === h.name.toLowerCase())
+        ).map((h) => h.name) : result.headers.map((h) => h.name);
+        const lines = result.rows.map(
+          (row) => displayCols.map((col) => `${col}: ${row[col] ?? ""}`).join(" | ")
+        );
+        const body = lines.join("\n");
+        return {
+          content: [{ type: "text", text: `${header}
+
+${body}` }]
+        };
+      } catch (error) {
+        if (error instanceof ContextServerError && error.status === 404) {
+          return {
+            content: [{ type: "text", text: `File "${path}" not found.` }],
+            isError: true
+          };
+        }
+        throw error;
+      }
+    }
+  );
+}
+
+// src/tools/search.ts
+import { z as z3 } from "zod";
+function registerGrepTool(server, client) {
+  server.tool(
+    "grep",
+    "Search file contents across the VFS with a regex (or a literal string if `fixedString` is true). Returns matching lines with their file path and line number. `path` accepts a source, a subfolder, or a single file \u2014 narrow the scope as much as you can. Prefer `browse` + catalog descriptions to narrow first; broad greps are cheap but noisy.",
+    {
+      pattern: z3.string().min(1).describe("The regex (ERE) or literal string to search for."),
+      path: z3.string().optional().describe(
+        'Scope the search to this VFS path (e.g. "my-source" or "my-source/tech"). Omit for the whole VFS.'
+      ),
+      maxResults: z3.number().int().positive().max(500).optional().describe("Max hits to return (default 50, hard cap 500)."),
+      fixedString: z3.boolean().optional().describe("Treat `pattern` as a literal string, not a regex (grep -F)."),
+      ignoreCase: z3.boolean().optional().describe("Case-insensitive match (grep -i).")
+    },
+    { readOnlyHint: true },
+    async (args) => {
+      const result = await client.grep(args);
+      if (result.results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No matches for /${args.pattern}/${args.ignoreCase ? "i" : ""}${args.path ? ` under "${args.path}"` : ""}.`
+            }
+          ]
+        };
+      }
+      const body = result.results.map((hit) => `${hit.path}:${hit.line}: ${hit.text}`).join("\n");
+      const footer = result.truncated ? `
+
+(truncated at ${result.results.length} hits \u2014 narrow the scope with \`path\` or tighten the pattern)` : "";
+      return {
+        content: [{ type: "text", text: body + footer }]
+      };
+    }
+  );
+}
+function registerFindTool(server, client) {
+  server.tool(
+    "find",
+    'Find files or directories by name across the VFS. `name` accepts find-style globs ("*.md", "foo?", "[ab]*"). Optionally scope with `path` and/or restrict to files ("f") or directories ("d"). Returns a list of VFS paths \u2014 use `read_file` / `browse` to inspect them.',
+    {
+      name: z3.string().min(1).describe('Filename glob. Examples: "*.md", "README*", "spec.*".'),
+      path: z3.string().optional().describe("Scope to this VFS path. Omit for the whole VFS."),
+      maxResults: z3.number().int().positive().max(500).optional().describe("Max paths to return (default 50, hard cap 500)."),
+      type: z3.enum(["f", "d"]).optional().describe('Restrict to files ("f") or directories ("d").')
+    },
+    { readOnlyHint: true },
+    async (args) => {
+      const result = await client.find(args);
+      if (result.results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No ${args.type === "d" ? "directories" : args.type === "f" ? "files" : "paths"} match "${args.name}"${args.path ? ` under "${args.path}"` : ""}.`
+            }
+          ]
+        };
+      }
+      const body = result.results.map((p) => `- ${p}`).join("\n");
+      const footer = result.truncated ? `
+
+(truncated at ${result.results.length} hits \u2014 narrow the scope with \`path\` or use a tighter name pattern)` : "";
+      return {
+        content: [{ type: "text", text: body + footer }]
+      };
+    }
+  );
+}
+
+// src/server.ts
+var BASE_INSTRUCTIONS = `
+Dudamel Context MCP \u2014 read-only access to the organization's knowledge base (the VFS).
+
+Call \`get_instructions\` on your first interaction for background on the .index.yaml
+catalog convention. Not required \u2014 the tools work without it, but it helps you
+understand the data model the first time.
+
+Typical workflow:
+  1. get_instructions          \u2014 understand the conventions
+  2. list_sources              \u2014 see what knowledge bases exist
+  3. browse <path>             \u2014 explore a source; read catalog descriptions
+  4. tree <path>               \u2014 compact recursive map of a subtree in one call
+  5. stat <path>               \u2014 check size / line count before reading large files
+  6. read_file <path>          \u2014 fetch actual content when it's relevant
+  7. read_section <path, h>    \u2014 pull one markdown section instead of the whole file
+  8. read_yaml <path, key>     \u2014 navigate a YAML file by dot-path key
+  9. read_csv <path, filter>   \u2014 query a CSV file with column filtering
+  10. tail <path>              \u2014 peek at the end of a file (logs, recent entries)
+  11. grep / find              \u2014 search content or filenames across the VFS
+
+Prefer reading catalog descriptions (via \`browse\`) over reading full files \u2014
+catalogs are dense summaries. Use \`grep\`/\`find\` to locate things you don't
+already have a path for; scope them with \`path\` when you can.
+`.trim();
+async function buildInstructions(client) {
+  try {
+    const catalog = await client.readDirectoryCatalog("");
+    const entries = catalog.entries ?? [];
+    if (entries.length === 0) return BASE_INSTRUCTIONS;
+    const sourceLines = entries.map(
+      (e) => `- **${e.path}** \u2014 ${e.description || "(no description yet \u2014 call browse for details)"}`
+    ).join("\n");
+    const discovery = `
+## Available knowledge sources
+
+This server is the authoritative source for the topics below. **When the user
+asks about anything that overlaps with these descriptions, use this server's
+tools before answering from memory** \u2014 call \`browse\`/\`grep\`/\`read_file\`
+to confirm the current state rather than guessing.
+
+${sourceLines}
+`.trim();
+    return `${BASE_INSTRUCTIONS}
+
+${discovery}`;
+  } catch {
+    return BASE_INSTRUCTIONS;
+  }
+}
+async function createContextServer(config) {
+  const httpClient = config.mode === "proxy" ? new ContextServerClient({ baseUrl: config.baseUrl, apiKey: config.apiKey }) : new ContextServerClient({ baseUrl: config.baseUrl });
+  const client = config.mode === "proxy" && config.cache ? new MirrorContextBackend(httpClient, config.cache) : httpClient;
+  const instructions = await buildInstructions(client);
+  const server = new McpServer(
+    { name: "dudamel-context", version: "0.1.0" },
+    {
+      capabilities: { tools: {} },
+      instructions
+    }
+  );
+  registerInstructionsTool(server, client);
+  registerListSourcesTool(server, client);
+  registerBrowseTool(server, client);
+  registerTreeTool(server, client);
+  registerReadFileTool(server, client);
+  registerReadSectionTool(server, client);
+  registerReadYamlTool(server, client);
+  registerReadCsvTool(server, client);
+  registerStatTool(server, client);
+  registerTailTool(server, client);
+  registerGrepTool(server, client);
+  registerFindTool(server, client);
+  return server;
+}
+export {
+  ContextServerClient,
+  ContextServerError,
+  createContextServer
+};