@kaddo/mcp 3.19.0

package/README.md

@@ -0,0 +1,90 @@
+# @kaddo/mcp
+
+A **read-only** [Model Context Protocol](https://modelcontextprotocol.io) server for
+[Kaddo](https://kaddo.trycatch.tv). It exposes your project's curated Kaddo knowledge —
+context pack, explain, understand, knowledge graph, graph hints, Work Items, roadmap, Knowledge
+Capsules and installed agent prompts — to any MCP-compatible client (IDE or agent), so the agent
+gets structured context instead of scanning your whole repository.
+
+> Read-only by design. The server never modifies knowledge, edits files, runs git, calls an LLM
+> or scans your source code.
+
+## Install & run
+
+No install needed — run it with `npx`:
+
+```bash
+npx @kaddo/mcp
+```
+
+The server speaks MCP over **stdio** and operates on the project in its working directory (or the
+directory set via the `KADDO_PROJECT_DIR` environment variable).
+
+## Configure an MCP client
+
+```json
+{
+  "mcpServers": {
+    "kaddo": {
+      "command": "npx",
+      "args": ["@kaddo/mcp"],
+      "cwd": "/absolute/path/to/your/project"
+    }
+  }
+}
+```
+
+`cwd` must point to the project that contains `.kaddo/`, `knowledge/` and (optionally) `external/`.
+
+## Resources
+
+| URI | Reads | Purpose |
+|---|---|---|
+| `kaddo://context-pack` | `.kaddo/context-pack.md` | curated LLM context |
+| `kaddo://explain` | `.kaddo/explain.md` | what Kaddo knows |
+| `kaddo://understand` | `.kaddo/understand.md` | current phase + next step |
+| `kaddo://graph` | `.kaddo/graph.json` + `.mmd` | knowledge graph |
+| `kaddo://graph-hints` | `.kaddo/graph-hints.md` + `.json` | weak/missing relationships |
+| `kaddo://work-items` | `knowledge/delivery/work-items/` | summarized Work Items |
+| `kaddo://roadmap` | `knowledge/delivery/roadmap.md` | delivery roadmap |
+| `kaddo://capsules` | `.kaddo/external.yml` + `external/` | external Knowledge Capsules |
+| `kaddo://agents` | `knowledge/agents/` | installed agent prompts |
+| `kaddo://skills` | `knowledge/skills/` | installed skills (empty if none) |
+
+## Tools (read-only)
+
+- `kaddo_project_status` — compact project status (state, work items, ownership, graph quality, capsules).
+- `kaddo_list_work_items` — filter by `status` / `type` / `knowledge_level`.
+- `kaddo_get_work_item` — a Work Item by `id` (summary + full markdown).
+- `kaddo_list_capsules` / `kaddo_get_capsule` — external Knowledge Capsules.
+- `kaddo_list_agents` / `kaddo_get_agent_prompt` — installed agent prompts.
+- `kaddo_list_graph_hints` — graph hints, filter by `artifact_type` / `severity` / `active_only`.
+
+## Prompts
+
+Every installed agent prompt (`knowledge/agents/**`) is exposed as an MCP prompt
+(`business-agent`, `work-item-agent`, `implementation-agent`, `graph-agent`, …) with its full
+content and recommended inputs.
+
+## What it does NOT do
+
+No writes, no Work Item creation, no `kaddo scan`/`context`/`graph export`/`learn`/`owners suggest`,
+no git, no remote sync, no GitHub API, no HTTP server, no auth, no RAG, no vector database. If a
+derived file is missing, the server returns a clear instruction to run the matching CLI command —
+it never generates files.
+
+## Security
+
+The server only reads `.kaddo/`, `knowledge/` and `external/`. It never reads `src/`, `.git/`,
+`node_modules/`, `dist/`, `build/` or `coverage/`, blocks path traversal, and never exposes
+secrets, tokens, env values, source code or PII.
+
+## Troubleshooting
+
+- **"Kaddo project not found. Run `kaddo init` first."** — `cwd` is not a Kaddo project. Point it
+  at the directory containing `.kaddo/config.yml`.
+- **"… not found. Run `kaddo …` first."** — the derived file hasn't been generated yet. Run the
+  named CLI command (e.g. `kaddo context`, `kaddo graph export`).
+- **No prompts listed** — install agents with `kaddo add agents`.
+
+Same version as `@kaddo/cli`. See the [MCP Server docs](https://kaddo.trycatch.tv/mcp-server/).

package/dist/index.js

@@ -0,0 +1,606 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+// src/catalog.ts
+import matter from "gray-matter";
+
+// src/project.ts
+import fs from "fs";
+import path from "path";
+import { parse as parseYaml } from "yaml";
+var ALLOWED_ROOTS = [".kaddo", "knowledge", "external"];
+var KaddoMcpError = class extends Error {
+};
+function projectRoot() {
+  const fromEnv = process.env.KADDO_PROJECT_DIR;
+  return path.resolve(fromEnv && fromEnv.trim() ? fromEnv : process.cwd());
+}
+function hasKaddoConfig(root) {
+  return fs.existsSync(path.join(root, ".kaddo", "config.yml"));
+}
+function hasKnowledge(root) {
+  return fs.existsSync(path.join(root, "knowledge"));
+}
+function assertKaddoProject(root) {
+  if (!hasKaddoConfig(root)) {
+    throw new KaddoMcpError("Kaddo project not found. Run `kaddo init` first.");
+  }
+}
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+function safeResolve(root, relPath) {
+  const rel = toPosix(relPath).replace(/^\/+/, "");
+  if (path.isAbsolute(relPath) || rel.split("/").some((seg) => seg === "..")) {
+    throw new KaddoMcpError(`Path is not allowed: ${relPath}`);
+  }
+  const top = rel.split("/")[0];
+  if (!ALLOWED_ROOTS.includes(top)) {
+    throw new KaddoMcpError(
+      `Path is outside the readable Kaddo directories (${ALLOWED_ROOTS.join(", ")}): ${relPath}`
+    );
+  }
+  const resolved = path.resolve(root, rel);
+  const base = toPosix(root).replace(/\/+$/, "");
+  if (resolved !== root && !toPosix(resolved).startsWith(base + "/")) {
+    throw new KaddoMcpError(`Path traversal blocked: ${relPath}`);
+  }
+  return resolved;
+}
+function readText(root, relPath) {
+  const abs = safeResolve(root, relPath);
+  if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) return null;
+  return fs.readFileSync(abs, "utf-8");
+}
+function readJson(root, relPath) {
+  const raw = readText(root, relPath);
+  if (raw === null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function readYaml(root, relPath) {
+  const raw = readText(root, relPath);
+  if (raw === null) return null;
+  try {
+    return parseYaml(raw) ?? null;
+  } catch {
+    return null;
+  }
+}
+function listFiles(root, relDir, filterExt) {
+  let absDir;
+  try {
+    absDir = safeResolve(root, relDir);
+  } catch {
+    return [];
+  }
+  if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory()) return [];
+  const out = [];
+  const walk = (abs) => {
+    for (const entry of fs.readdirSync(abs)) {
+      if (entry.startsWith(".")) continue;
+      const full = path.join(abs, entry);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        walk(full);
+      } else if (stat.isFile() && (!filterExt || entry.endsWith(filterExt))) {
+        out.push(toPosix(path.relative(root, full)));
+      }
+    }
+  };
+  walk(absDir);
+  return out.sort();
+}
+
+// src/catalog.ts
+function sectionParagraph(md, title) {
+  const lines = md.split(/\r?\n/);
+  const re = new RegExp(`^##\\s+${title}\\s*$`, "i");
+  const start = lines.findIndex((l) => re.test(l));
+  if (start < 0) return "";
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) break;
+    const t = lines[i].trim();
+    if (t && !/^_.*_$/.test(t)) return t;
+  }
+  return "";
+}
+function listCapsules(root) {
+  const registry = readYaml(root, ".kaddo/external.yml");
+  const entries = Array.isArray(registry?.external) ? registry.external : [];
+  return entries.map((e) => {
+    const md = e.path ? readText(root, e.path) : null;
+    let system;
+    let updated_at;
+    let purpose;
+    if (md) {
+      try {
+        const { data } = matter(md);
+        system = data.system ? String(data.system) : void 0;
+        updated_at = data.updated_at ? String(data.updated_at) : void 0;
+      } catch {
+      }
+      purpose = sectionParagraph(md, "Purpose") || void 0;
+    }
+    return { id: e.id, path: e.path, owner: e.owner, system, updated_at, purpose };
+  });
+}
+function getCapsule(root, id) {
+  const entry = listCapsules(root).find((c) => c.id === id);
+  if (!entry) return null;
+  const content = readText(root, entry.path);
+  if (content === null) return null;
+  return { id: entry.id, path: entry.path, content };
+}
+function firstHeadingOrLine(md) {
+  for (const line of md.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    return t.replace(/\s+/g, " ").slice(0, 200);
+  }
+  return "";
+}
+function listAgents(root) {
+  const files = listFiles(root, "knowledge/agents", "-agent.md");
+  return files.map((rel) => {
+    const segs = rel.split("/");
+    const file = segs[segs.length - 1];
+    const group = segs.length >= 3 ? segs[segs.length - 2] : "agents";
+    const md = readText(root, rel) ?? "";
+    return {
+      name: file.replace(/\.md$/, ""),
+      path: rel,
+      group,
+      description: firstHeadingOrLine(md)
+    };
+  });
+}
+function getAgentPrompt(root, name) {
+  const want = name.replace(/\.md$/, "");
+  const info = listAgents(root).find((a) => a.name === want);
+  if (!info) return null;
+  const content = readText(root, info.path);
+  if (content === null) return null;
+  return { ...info, content };
+}
+
+// src/workitems.ts
+import matter2 from "gray-matter";
+var ACTIVE_STATES = /* @__PURE__ */ new Set(["draft", "ready", "in-progress", "blocked"]);
+function strArray(v) {
+  return Array.isArray(v) ? v.map((x) => String(x)).filter(Boolean) : [];
+}
+function lifecycleOf(data, relPath) {
+  const status = String(data.status ?? "").trim();
+  if (status) return status;
+  const segs = relPath.split("/");
+  const folder = segs[segs.length - 2];
+  return ACTIVE_STATES.has(folder) || folder === "completed" || folder === "archived" ? folder : "ready";
+}
+function firstParagraph(body) {
+  for (const block of body.split(/\n\s*\n/)) {
+    const t = block.trim();
+    if (t && !t.startsWith("#") && !t.startsWith(">")) return t.replace(/\s+/g, " ");
+  }
+  return "";
+}
+function listWorkItems(root) {
+  const files = listFiles(root, "knowledge/delivery/work-items", ".md");
+  const items = [];
+  for (const rel of files) {
+    const raw = readText(root, rel);
+    if (raw === null) continue;
+    let parsed;
+    try {
+      parsed = matter2(raw);
+    } catch {
+      continue;
+    }
+    const data = parsed.data;
+    if (!data.type) continue;
+    items.push({
+      id: String(data.id ?? "") || rel,
+      title: String(data.title ?? ""),
+      status: lifecycleOf(data, rel),
+      type: String(data.type ?? ""),
+      knowledge_level: String(data.knowledge_level ?? ""),
+      path: rel,
+      summary: String(data.summary ?? "") || firstParagraph(parsed.content),
+      code: strArray(data.code),
+      capabilities: strArray(data.capabilities),
+      decisions: strArray(data.decisions),
+      capsules: strArray(data.capsules)
+    });
+  }
+  return items.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+// src/resources.ts
+function text(uri, body, mimeType = "text/markdown") {
+  return [{ uri, text: body, mimeType }];
+}
+function fileOrHint(root, uri, rel, hint, mimeType = "text/markdown") {
+  const body = readText(root, rel);
+  return text(uri, body ?? hint, body ? mimeType : "text/plain");
+}
+var RESOURCES = [
+  {
+    uri: "kaddo://context-pack",
+    name: "Kaddo context pack",
+    description: "Curated LLM context pack (.kaddo/context-pack.md).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://context-pack",
+      ".kaddo/context-pack.md",
+      "Context pack not found. Run `kaddo context` in the project first."
+    )
+  },
+  {
+    uri: "kaddo://explain",
+    name: "Kaddo explain",
+    description: "What Kaddo knows about the project (.kaddo/explain.md).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://explain",
+      ".kaddo/explain.md",
+      "Explain output not found. Run `kaddo explain` first."
+    )
+  },
+  {
+    uri: "kaddo://understand",
+    name: "Kaddo understand",
+    description: "Current phase and recommended next step (.kaddo/understand.md).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://understand",
+      ".kaddo/understand.md",
+      "Understand output not found. Run `kaddo understand` first."
+    )
+  },
+  {
+    uri: "kaddo://graph",
+    name: "Kaddo knowledge graph",
+    description: "Knowledge graph (.kaddo/graph.json + .kaddo/graph.mmd).",
+    mimeType: "application/json",
+    read: (root) => {
+      const json = readText(root, ".kaddo/graph.json");
+      const mmd = readText(root, ".kaddo/graph.mmd");
+      if (!json && !mmd) {
+        return text("kaddo://graph", "Knowledge graph not found. Run `kaddo graph export` first.", "text/plain");
+      }
+      const parts = [];
+      if (json) parts.push({ uri: "kaddo://graph", text: json, mimeType: "application/json" });
+      if (mmd) parts.push({ uri: "kaddo://graph.mmd", text: mmd, mimeType: "text/vnd.mermaid" });
+      return parts;
+    }
+  },
+  {
+    uri: "kaddo://graph-hints",
+    name: "Kaddo graph hints",
+    description: "Graph relationship-quality hints (.kaddo/graph-hints.md + .json).",
+    mimeType: "text/markdown",
+    read: (root) => {
+      const md = readText(root, ".kaddo/graph-hints.md");
+      const json = readText(root, ".kaddo/graph-hints.json");
+      if (!md && !json) {
+        return text("kaddo://graph-hints", "Graph hints not found. Run `kaddo graph export` first.", "text/plain");
+      }
+      const parts = [];
+      if (md) parts.push({ uri: "kaddo://graph-hints", text: md, mimeType: "text/markdown" });
+      if (json) parts.push({ uri: "kaddo://graph-hints.json", text: json, mimeType: "application/json" });
+      return parts;
+    }
+  },
+  {
+    uri: "kaddo://work-items",
+    name: "Kaddo work items",
+    description: "Summarized Work Items from knowledge/delivery/work-items/.",
+    mimeType: "application/json",
+    read: (root) => {
+      if (!hasKnowledge(root)) {
+        return text("kaddo://work-items", "Knowledge repository not found. Run `kaddo bootstrap` first.", "text/plain");
+      }
+      return [
+        {
+          uri: "kaddo://work-items",
+          text: JSON.stringify(listWorkItems(root), null, 2),
+          mimeType: "application/json"
+        }
+      ];
+    }
+  },
+  {
+    uri: "kaddo://roadmap",
+    name: "Kaddo roadmap",
+    description: "Delivery roadmap (knowledge/delivery/roadmap.md).",
+    mimeType: "text/markdown",
+    read: (root) => fileOrHint(
+      root,
+      "kaddo://roadmap",
+      "knowledge/delivery/roadmap.md",
+      "Roadmap not found. Create knowledge/delivery/roadmap.md (e.g. via the roadmap-agent) first."
+    )
+  },
+  {
+    uri: "kaddo://capsules",
+    name: "Kaddo knowledge capsules",
+    description: "External Knowledge Capsules from .kaddo/external.yml and external/.",
+    mimeType: "application/json",
+    read: (root) => [
+      {
+        uri: "kaddo://capsules",
+        text: JSON.stringify(listCapsules(root), null, 2),
+        mimeType: "application/json"
+      }
+    ]
+  },
+  {
+    uri: "kaddo://agents",
+    name: "Kaddo agents",
+    description: "Installed agent prompts from knowledge/agents/.",
+    mimeType: "application/json",
+    read: (root) => [
+      {
+        uri: "kaddo://agents",
+        text: JSON.stringify(listAgents(root), null, 2),
+        mimeType: "application/json"
+      }
+    ]
+  },
+  {
+    uri: "kaddo://skills",
+    name: "Kaddo skills",
+    description: "Installed skills from knowledge/skills/ (empty if none).",
+    mimeType: "application/json",
+    read: (root) => {
+      const files = listFiles(root, "knowledge/skills", ".md");
+      return [
+        {
+          uri: "kaddo://skills",
+          text: JSON.stringify({ skills: files }, null, 2),
+          mimeType: "application/json"
+        }
+      ];
+    }
+  }
+];
+
+// src/prompts.ts
+var EXTRA_INPUTS = {
+  "graph-agent": [".kaddo/graph.json", ".kaddo/graph-hints.md"],
+  "ownership-agent": ["knowledge/delivery/work-items/", "knowledge/inventory.md"],
+  "capsule-agent": ["knowledge/product/capabilities.md", "knowledge/tech/decisions/"],
+  "work-item-agent": ["knowledge/delivery/roadmap.md"],
+  "implementation-agent": ["knowledge/tech/git-strategy.md"]
+};
+function recommendedInputs(name) {
+  return [".kaddo/context-pack.md", ...EXTRA_INPUTS[name] ?? []];
+}
+function listPrompts(root) {
+  return listAgents(root).map((a) => ({
+    name: a.name,
+    description: a.description || `Kaddo ${a.name}`,
+    content: "",
+    recommended_inputs: recommendedInputs(a.name)
+  }));
+}
+function getPrompt(root, name) {
+  const agent = getAgentPrompt(root, name);
+  if (!agent) return null;
+  return {
+    name: agent.name,
+    description: agent.description || `Kaddo ${agent.name}`,
+    content: agent.content,
+    recommended_inputs: recommendedInputs(agent.name)
+  };
+}
+
+// src/tools.ts
+var ok = (data) => ({ ok: true, data });
+var fail = (message) => ({ ok: false, message });
+function projectStatus(root) {
+  const explain = readJson(root, ".kaddo/explain.json");
+  const hints = readJson(root, ".kaddo/graph-hints.json");
+  const capsules = listCapsules(root);
+  if (!explain) {
+    return fail("Project status needs `.kaddo/explain.json`. Run `kaddo explain` first.");
+  }
+  const maturity = (explain.layers ?? []).map((l) => `${l.layer}: ${l.status}`);
+  return ok({
+    project: explain.project?.name ?? "unknown",
+    state: explain.project?.state ?? "unknown",
+    knowledgeMaturity: maturity,
+    workItems: {
+      total: explain.workItems?.total ?? 0,
+      byState: explain.workItems?.byState ?? {},
+      byType: explain.workItems?.byType ?? {}
+    },
+    ownership: {
+      withOwnership: explain.ownership?.workItemsWithOwnership ?? 0,
+      total: explain.ownership?.workItemsTotal ?? 0
+    },
+    graphQuality: hints?.quality ?? "unknown (run `kaddo graph export`)",
+    graphHints: hints?.summary?.hints ?? 0,
+    capsules: capsules.length
+  });
+}
+function listWorkItemsTool(root, filter = {}) {
+  let items = listWorkItems(root);
+  if (filter.status) items = items.filter((w) => w.status === filter.status);
+  if (filter.type) items = items.filter((w) => w.type === filter.type);
+  if (filter.knowledge_level) items = items.filter((w) => w.knowledge_level === filter.knowledge_level);
+  return ok(items);
+}
+function getWorkItem(root, id) {
+  const item = listWorkItems(root).find((w) => w.id === id);
+  if (!item) return fail(`Work Item "${id}" not found.`);
+  const content = readText(root, item.path);
+  return ok({ ...item, content: content ?? "" });
+}
+function listCapsulesTool(root) {
+  return ok(listCapsules(root));
+}
+function getCapsuleTool(root, id) {
+  const cap = getCapsule(root, id);
+  if (!cap) return fail(`Knowledge Capsule "${id}" not found.`);
+  return ok(cap);
+}
+function listAgentsTool(root) {
+  return ok(listAgents(root));
+}
+function getAgentPromptTool(root, name) {
+  const agent = getAgentPrompt(root, name);
+  if (!agent) return fail(`Agent "${name}" is not installed. Run \`kaddo add agents\` first.`);
+  return ok(agent);
+}
+function listGraphHints(root, filter = {}) {
+  const report = readJson(root, ".kaddo/graph-hints.json");
+  if (!report) return fail("Graph hints not found. Run `kaddo graph export` first.");
+  let hints = Array.isArray(report.hints) ? report.hints : [];
+  if (filter.artifact_type) hints = hints.filter((h) => h.artifact_type === filter.artifact_type);
+  if (filter.severity) hints = hints.filter((h) => h.severity === filter.severity);
+  if (filter.active_only) hints = hints.filter((h) => h.artifact_type === "work-item");
+  return ok({ quality: report.quality ?? "unknown", count: hints.length, hints });
+}
+
+// src/server.ts
+var SERVER_NAME = "kaddo";
+var SERVER_VERSION = "3.19.0";
+function toolText(result) {
+  if (!result.ok) {
+    return { content: [{ type: "text", text: result.message }], isError: true };
+  }
+  const text2 = typeof result.data === "string" ? result.data : JSON.stringify(result.data, null, 2);
+  return { content: [{ type: "text", text: text2 }] };
+}
+function guarded(root, fn) {
+  try {
+    assertKaddoProject(root);
+    return fn();
+  } catch (err) {
+    if (err instanceof KaddoMcpError) return { ok: false, message: err.message };
+    throw err;
+  }
+}
+function createServer(root) {
+  const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+  for (const r of RESOURCES) {
+    server.registerResource(
+      r.name,
+      r.uri,
+      { title: r.name, description: r.description, mimeType: r.mimeType },
+      async (uri) => {
+        try {
+          assertKaddoProject(root);
+        } catch (err) {
+          const message = err instanceof KaddoMcpError ? err.message : String(err);
+          return { contents: [{ uri: uri.href, text: message, mimeType: "text/plain" }] };
+        }
+        const parts = r.read(root);
+        return { contents: parts.map((p) => ({ uri: p.uri, text: p.text, mimeType: p.mimeType })) };
+      }
+    );
+  }
+  server.registerTool(
+    "kaddo_project_status",
+    { title: "Kaddo project status", description: "Compact project status (state, phase, work items, ownership, graph quality, capsules).", inputSchema: {} },
+    async () => toolText(guarded(root, () => projectStatus(root)))
+  );
+  server.registerTool(
+    "kaddo_list_work_items",
+    {
+      title: "List Work Items",
+      description: "List Work Items with optional status/type/knowledge_level filters.",
+      inputSchema: {
+        status: z.string().optional(),
+        type: z.string().optional(),
+        knowledge_level: z.string().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => listWorkItemsTool(root, args)))
+  );
+  server.registerTool(
+    "kaddo_get_work_item",
+    { title: "Get Work Item", description: "Get a Work Item by ID (summary + full markdown).", inputSchema: { id: z.string() } },
+    async (args) => toolText(guarded(root, () => getWorkItem(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_list_capsules",
+    { title: "List Knowledge Capsules", description: "List registered external Knowledge Capsules.", inputSchema: {} },
+    async () => toolText(guarded(root, () => listCapsulesTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_capsule",
+    { title: "Get Knowledge Capsule", description: "Get an external Knowledge Capsule by ID.", inputSchema: { id: z.string() } },
+    async (args) => toolText(guarded(root, () => getCapsuleTool(root, args.id)))
+  );
+  server.registerTool(
+    "kaddo_list_agents",
+    { title: "List agents", description: "List installed agent prompts.", inputSchema: {} },
+    async () => toolText(guarded(root, () => listAgentsTool(root)))
+  );
+  server.registerTool(
+    "kaddo_get_agent_prompt",
+    { title: "Get agent prompt", description: "Get an installed agent prompt by name.", inputSchema: { name: z.string() } },
+    async (args) => toolText(guarded(root, () => getAgentPromptTool(root, args.name)))
+  );
+  server.registerTool(
+    "kaddo_list_graph_hints",
+    {
+      title: "List graph hints",
+      description: "List knowledge-graph relationship hints with optional filters.",
+      inputSchema: {
+        artifact_type: z.string().optional(),
+        severity: z.string().optional(),
+        active_only: z.boolean().optional()
+      }
+    },
+    async (args) => toolText(guarded(root, () => listGraphHints(root, args)))
+  );
+  let prompts = [];
+  try {
+    assertKaddoProject(root);
+    prompts = listPrompts(root);
+  } catch {
+    prompts = [];
+  }
+  for (const p of prompts) {
+    server.registerPrompt(
+      p.name,
+      { title: p.name, description: p.description },
+      async () => {
+        const full = getPrompt(root, p.name);
+        const content = full?.content ?? `Agent "${p.name}" is not installed.`;
+        return { messages: [{ role: "user", content: { type: "text", text: content } }] };
+      }
+    );
+  }
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const root = projectRoot();
+  const server = createServer(root);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`[kaddo-mcp] read-only server ready (project: ${root})
+`);
+}
+main().catch((err) => {
+  process.stderr.write(`[kaddo-mcp] fatal: ${err instanceof Error ? err.stack ?? err.message : String(err)}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@kaddo/mcp",
+  "version": "3.19.0",
+  "description": "Read-only MCP server for Kaddo project knowledge.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kaddo-kdd/kaddo.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://kaddo.trycatch.tv",
+  "bugs": {
+    "url": "https://github.com/Kaddo-kdd/kaddo/issues"
+  },
+  "keywords": [
+    "kdd",
+    "knowledge",
+    "mcp",
+    "model-context-protocol",
+    "kaddo"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "kaddo-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "gray-matter": "^4.0.3",
+    "yaml": "^2.4.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.4.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}