@thallylabs/mcp 0.10.25 → 0.10.28

package/README.md

@@ -2,10 +2,9 @@
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI
 tools — Claude Code, Claude Desktop, Cursor, Windsurf — manage
-[Thally](https://github.com/thallylabs/thally) knowledge surfaces through
-natural language. Tools can create, read, update, search, and migrate
-documentation, then trace a product-repository change into reviewable docs
-work.
+[Thally](https://github.com/thallylabs/thally) docs through natural language.
+Tools can create, read, update, search, and migrate documentation, then trace a
+product change into an evidence-backed update for human review.
 
 ## Setup
 

package/dist/index.js

@@ -243,19 +243,25 @@ function formatGroup(group, indent) {
   }
   return lines;
 }
+function formatPages(pages, indent) {
+  return pages.flatMap((page) => {
+    if (typeof page !== "string") return formatGroup(page, indent);
+    const href = page === "introduction" ? "/" : `/${page}`;
+    return [`${indent}- ${page.padEnd(30)} \u2192 ${href}`];
+  });
+}
 async function handleListPages(input) {
   const config = readDocsJson(input.projectDir);
   const lines = [];
   for (const tab of config.tabs) {
     lines.push(`Tab: ${tab.tab}`);
-    if (tab.href) {
+    const navigationPages = [...tab.pages ?? [], ...tab.groups ?? []];
+    if (tab.href && navigationPages.length === 0) {
       lines.push(`  \u2192 External: ${tab.href}`);
-    } else if (tab.api) {
+    } else if (tab.api && navigationPages.length === 0) {
       lines.push(`  \u2192 API Reference: ${tab.api.source}`);
-    } else if (tab.groups && tab.groups.length > 0) {
-      for (const group of tab.groups) {
-        lines.push(...formatGroup(group, "  "));
-      }
+    } else if (navigationPages.length > 0) {
+      lines.push(...formatPages(navigationPages, "  "));
     } else {
       lines.push("  (no pages)");
     }
@@ -270,18 +276,35 @@ import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync
 import { join as join3 } from "path";
 
 // src/lib/frontmatter.ts
-import matter from "gray-matter";
-var FRONTMATTER_OPTIONS = {
-  engines: {
-    javascript: () => ({}),
-    js: () => ({})
-  }
-};
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 function parseFrontmatter(raw) {
-  return matter(raw, FRONTMATTER_OPTIONS);
+  const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
+  const opening = /^---([^\r\n]*)\r?\n/.exec(source);
+  if (!opening || opening[1].startsWith("-")) return { content: source, data: {} };
+  const language = opening[1].trim().toLowerCase();
+  const remainder = source.slice(opening[0].length);
+  const closing = /^---[ \t]*\r?$/m.exec(remainder);
+  const matter = closing ? remainder.slice(0, closing.index) : remainder;
+  let content = closing ? remainder.slice(closing.index + closing[0].length) : "";
+  if (content.startsWith("\r\n")) content = content.slice(2);
+  else if (content.startsWith("\n")) content = content.slice(1);
+  if (matter.trim() === "" || !["", "yaml", "yml"].includes(language)) {
+    return { content, data: {} };
+  }
+  const parsed = parseYaml(matter);
+  return {
+    content,
+    data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+  };
 }
 function stringifyFrontmatter(body, data) {
-  return matter.stringify(body, data);
+  const normalizedBody = body.endsWith("\n") ? body : `${body}
+`;
+  const serialized = stringifyYaml(data, { lineWidth: 0 }).trimEnd();
+  return serialized === "{}" ? normalizedBody : `---
+${serialized}
+---
+${normalizedBody}`;
 }
 
 // src/tools/update-page.ts
@@ -884,8 +907,16 @@ function collectNavPageIds(groups, seen, duplicates) {
 }
 function addOrphanToNav(projectDir, pageId) {
   const config = readDocsJson(projectDir);
-  const tab = config.tabs.find((t) => !t.href && !t.api && t.groups && t.groups.length > 0);
-  if (!tab || !tab.groups) return;
+  const tab = config.tabs.find((candidate) => !candidate.href && !candidate.api && (candidate.pages?.length || candidate.groups?.length));
+  if (!tab) return;
+  if (tab.pages) {
+    if (!tab.pages.includes(pageId)) {
+      tab.pages.push(pageId);
+      writeDocsJson(projectDir, config);
+    }
+    return;
+  }
+  if (!tab.groups) return;
   const lastGroup = tab.groups[tab.groups.length - 1];
   const existing = lastGroup.pages.filter((p) => typeof p === "string");
   if (!existing.includes(pageId)) {
@@ -904,12 +935,14 @@ async function handleLintProject(input) {
   const navPageIds = /* @__PURE__ */ new Set();
   const duplicates = /* @__PURE__ */ new Set();
   for (const tab of config.tabs) {
-    if (tab.href || tab.api) continue;
-    if (!tab.groups || tab.groups.length === 0) {
+    const hasNavigationNodes = Boolean(tab.pages?.length || tab.groups?.length);
+    if ((tab.href || tab.api) && !hasNavigationNodes) continue;
+    if (!hasNavigationNodes) {
       issues.push({ severity: "error", message: `Tab "${tab.tab}" has no groups and no href \u2014 it will render empty` });
       continue;
     }
-    collectNavPageIds(tab.groups.map((g) => g), navPageIds, duplicates);
+    collectNavPageIds(tab.pages ?? [], navPageIds, duplicates);
+    collectNavPageIds(tab.groups ?? [], navPageIds, duplicates);
   }
   for (const dup of duplicates) {
     issues.push({ severity: "error", message: `[duplicate] "${dup}" appears more than once in docs.json` });
@@ -1003,7 +1036,7 @@ async function handleLintProject(input) {
 
 // src/tools/translate-docs.ts
 import { z as z14 } from "zod";
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync2 } from "fs";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync5, existsSync as existsSync8, mkdirSync as mkdirSync2 } from "fs";
 import { join as join9, dirname as dirname2 } from "path";
 import Anthropic from "@anthropic-ai/sdk";
 import pLimit from "p-limit";
@@ -1036,8 +1069,8 @@ function getAllPageIds(config) {
   const seen = /* @__PURE__ */ new Set();
   const hrefOnlyPages = [];
   for (const tab of config.tabs) {
-    if (tab.api && !tab.groups) continue;
-    if (!tab.groups && tab.href) {
+    if (tab.api && !tab.pages && !tab.groups) continue;
+    if (!tab.pages && !tab.groups && tab.href) {
       const pageId = tab.href.replace(/^\//, "");
       if (pageId && !seen.has(pageId)) {
         seen.add(pageId);
@@ -1046,13 +1079,10 @@ function getAllPageIds(config) {
       }
       continue;
     }
-    if (!tab.groups) continue;
-    for (const group of tab.groups) {
-      for (const id of collectPageIds(group.pages)) {
-        if (!seen.has(id)) {
-          seen.add(id);
-          ids.push(id);
-        }
+    for (const id of collectPageIds([...tab.pages ?? [], ...tab.groups ?? []])) {
+      if (!seen.has(id)) {
+        seen.add(id);
+        ids.push(id);
       }
     }
   }
@@ -1150,7 +1180,7 @@ async function handleTranslateDocs(input) {
           }
           const translated = await translatePage(sourceContent, targetLocale.label, locale, model, client);
           mkdirSync2(dirname2(targetFile), { recursive: true });
-          writeFileSync6(targetFile, translated + "\n", "utf8");
+          writeFileSync5(targetFile, translated + "\n", "utf8");
           results.push({ pageId, success: true });
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -1573,10 +1603,10 @@ async function handleReadApiSpec(input) {
 }
 
 // src/tools/update-api-spec.ts
-import { writeFileSync as writeFileSync7 } from "fs";
+import { writeFileSync as writeFileSync6 } from "fs";
 import { extname as extname2 } from "path";
 import { z as z17 } from "zod";
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml2 } from "yaml";
 var updateApiSpecSchema = z17.object({
   projectDir: z17.string().describe("Path to the Thally project root"),
   source: z17.string().optional().describe("Configured OpenAPI source; omit when the project has one"),
@@ -1584,7 +1614,7 @@ var updateApiSpecSchema = z17.object({
 });
 function parseDocument(source, content) {
   try {
-    return extname2(source).toLowerCase() === ".json" ? JSON.parse(content) : parseYaml(content);
+    return extname2(source).toLowerCase() === ".json" ? JSON.parse(content) : parseYaml2(content);
   } catch {
     throw new Error(
       `OpenAPI source is not valid ${extname2(source).toLowerCase() === ".json" ? "JSON" : "YAML"}.`
@@ -1599,7 +1629,7 @@ async function handleUpdateApiSpec(input) {
   }
   const content = input.content.endsWith("\n") ? input.content : `${input.content}
 `;
-  writeFileSync7(source.path, content, "utf8");
+  writeFileSync6(source.path, content, "utf8");
   return `\u2705 API source updated: ${source.source}`;
 }
 

package/dist/tools.d.ts

@@ -5,8 +5,8 @@ import { z } from 'zod';
  * - `project` — reads/writes a local Thally project directory (`projectDir`).
  * - `site` — queries a deployed Thally site over HTTP (`siteUrl`).
  *
- * The remote MCP endpoint (A6) exposes only what's safe over HTTP; the docs
- * agent (A1) drives the `project` tools against a checked-out docs repo. Both
+ * The remote MCP endpoint exposes only what's safe over HTTP; the docs
+ * agent drives the `project` tools against a checked-out docs repo. Both
  * consume this one registry instead of re-declaring the tools.
  */
 type ToolScope = "project" | "site";

package/dist/tools.js

@@ -234,19 +234,25 @@ function formatGroup(group, indent) {
   }
   return lines;
 }
+function formatPages(pages, indent) {
+  return pages.flatMap((page) => {
+    if (typeof page !== "string") return formatGroup(page, indent);
+    const href = page === "introduction" ? "/" : `/${page}`;
+    return [`${indent}- ${page.padEnd(30)} \u2192 ${href}`];
+  });
+}
 async function handleListPages(input) {
   const config = readDocsJson(input.projectDir);
   const lines = [];
   for (const tab of config.tabs) {
     lines.push(`Tab: ${tab.tab}`);
-    if (tab.href) {
+    const navigationPages = [...tab.pages ?? [], ...tab.groups ?? []];
+    if (tab.href && navigationPages.length === 0) {
       lines.push(`  \u2192 External: ${tab.href}`);
-    } else if (tab.api) {
+    } else if (tab.api && navigationPages.length === 0) {
       lines.push(`  \u2192 API Reference: ${tab.api.source}`);
-    } else if (tab.groups && tab.groups.length > 0) {
-      for (const group of tab.groups) {
-        lines.push(...formatGroup(group, "  "));
-      }
+    } else if (navigationPages.length > 0) {
+      lines.push(...formatPages(navigationPages, "  "));
     } else {
       lines.push("  (no pages)");
     }
@@ -261,18 +267,35 @@ import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync
 import { join as join3 } from "path";
 
 // src/lib/frontmatter.ts
-import matter from "gray-matter";
-var FRONTMATTER_OPTIONS = {
-  engines: {
-    javascript: () => ({}),
-    js: () => ({})
-  }
-};
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 function parseFrontmatter(raw) {
-  return matter(raw, FRONTMATTER_OPTIONS);
+  const source = raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw;
+  const opening = /^---([^\r\n]*)\r?\n/.exec(source);
+  if (!opening || opening[1].startsWith("-")) return { content: source, data: {} };
+  const language = opening[1].trim().toLowerCase();
+  const remainder = source.slice(opening[0].length);
+  const closing = /^---[ \t]*\r?$/m.exec(remainder);
+  const matter = closing ? remainder.slice(0, closing.index) : remainder;
+  let content = closing ? remainder.slice(closing.index + closing[0].length) : "";
+  if (content.startsWith("\r\n")) content = content.slice(2);
+  else if (content.startsWith("\n")) content = content.slice(1);
+  if (matter.trim() === "" || !["", "yaml", "yml"].includes(language)) {
+    return { content, data: {} };
+  }
+  const parsed = parseYaml(matter);
+  return {
+    content,
+    data: parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {}
+  };
 }
 function stringifyFrontmatter(body, data) {
-  return matter.stringify(body, data);
+  const normalizedBody = body.endsWith("\n") ? body : `${body}
+`;
+  const serialized = stringifyYaml(data, { lineWidth: 0 }).trimEnd();
+  return serialized === "{}" ? normalizedBody : `---
+${serialized}
+---
+${normalizedBody}`;
 }
 
 // src/tools/update-page.ts
@@ -875,8 +898,16 @@ function collectNavPageIds(groups, seen, duplicates) {
 }
 function addOrphanToNav(projectDir, pageId) {
   const config = readDocsJson(projectDir);
-  const tab = config.tabs.find((t) => !t.href && !t.api && t.groups && t.groups.length > 0);
-  if (!tab || !tab.groups) return;
+  const tab = config.tabs.find((candidate) => !candidate.href && !candidate.api && (candidate.pages?.length || candidate.groups?.length));
+  if (!tab) return;
+  if (tab.pages) {
+    if (!tab.pages.includes(pageId)) {
+      tab.pages.push(pageId);
+      writeDocsJson(projectDir, config);
+    }
+    return;
+  }
+  if (!tab.groups) return;
   const lastGroup = tab.groups[tab.groups.length - 1];
   const existing = lastGroup.pages.filter((p) => typeof p === "string");
   if (!existing.includes(pageId)) {
@@ -895,12 +926,14 @@ async function handleLintProject(input) {
   const navPageIds = /* @__PURE__ */ new Set();
   const duplicates = /* @__PURE__ */ new Set();
   for (const tab of config.tabs) {
-    if (tab.href || tab.api) continue;
-    if (!tab.groups || tab.groups.length === 0) {
+    const hasNavigationNodes = Boolean(tab.pages?.length || tab.groups?.length);
+    if ((tab.href || tab.api) && !hasNavigationNodes) continue;
+    if (!hasNavigationNodes) {
       issues.push({ severity: "error", message: `Tab "${tab.tab}" has no groups and no href \u2014 it will render empty` });
       continue;
     }
-    collectNavPageIds(tab.groups.map((g) => g), navPageIds, duplicates);
+    collectNavPageIds(tab.pages ?? [], navPageIds, duplicates);
+    collectNavPageIds(tab.groups ?? [], navPageIds, duplicates);
   }
   for (const dup of duplicates) {
     issues.push({ severity: "error", message: `[duplicate] "${dup}" appears more than once in docs.json` });
@@ -994,7 +1027,7 @@ async function handleLintProject(input) {
 
 // src/tools/translate-docs.ts
 import { z as z14 } from "zod";
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync2 } from "fs";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync5, existsSync as existsSync8, mkdirSync as mkdirSync2 } from "fs";
 import { join as join9, dirname as dirname2 } from "path";
 import Anthropic from "@anthropic-ai/sdk";
 import pLimit from "p-limit";
@@ -1027,8 +1060,8 @@ function getAllPageIds(config) {
   const seen = /* @__PURE__ */ new Set();
   const hrefOnlyPages = [];
   for (const tab of config.tabs) {
-    if (tab.api && !tab.groups) continue;
-    if (!tab.groups && tab.href) {
+    if (tab.api && !tab.pages && !tab.groups) continue;
+    if (!tab.pages && !tab.groups && tab.href) {
       const pageId = tab.href.replace(/^\//, "");
       if (pageId && !seen.has(pageId)) {
         seen.add(pageId);
@@ -1037,13 +1070,10 @@ function getAllPageIds(config) {
       }
       continue;
     }
-    if (!tab.groups) continue;
-    for (const group of tab.groups) {
-      for (const id of collectPageIds(group.pages)) {
-        if (!seen.has(id)) {
-          seen.add(id);
-          ids.push(id);
-        }
+    for (const id of collectPageIds([...tab.pages ?? [], ...tab.groups ?? []])) {
+      if (!seen.has(id)) {
+        seen.add(id);
+        ids.push(id);
       }
     }
   }
@@ -1141,7 +1171,7 @@ async function handleTranslateDocs(input) {
           }
           const translated = await translatePage(sourceContent, targetLocale.label, locale, model, client);
           mkdirSync2(dirname2(targetFile), { recursive: true });
-          writeFileSync6(targetFile, translated + "\n", "utf8");
+          writeFileSync5(targetFile, translated + "\n", "utf8");
           results.push({ pageId, success: true });
         } catch (err) {
           const msg = err instanceof Error ? err.message : String(err);
@@ -1564,10 +1594,10 @@ async function handleReadApiSpec(input) {
 }
 
 // src/tools/update-api-spec.ts
-import { writeFileSync as writeFileSync7 } from "fs";
+import { writeFileSync as writeFileSync6 } from "fs";
 import { extname as extname2 } from "path";
 import { z as z17 } from "zod";
-import { parse as parseYaml } from "yaml";
+import { parse as parseYaml2 } from "yaml";
 var updateApiSpecSchema = z17.object({
   projectDir: z17.string().describe("Path to the Thally project root"),
   source: z17.string().optional().describe("Configured OpenAPI source; omit when the project has one"),
@@ -1575,7 +1605,7 @@ var updateApiSpecSchema = z17.object({
 });
 function parseDocument(source, content) {
   try {
-    return extname2(source).toLowerCase() === ".json" ? JSON.parse(content) : parseYaml(content);
+    return extname2(source).toLowerCase() === ".json" ? JSON.parse(content) : parseYaml2(content);
   } catch {
     throw new Error(
       `OpenAPI source is not valid ${extname2(source).toLowerCase() === ".json" ? "JSON" : "YAML"}.`
@@ -1590,7 +1620,7 @@ async function handleUpdateApiSpec(input) {
   }
   const content = input.content.endsWith("\n") ? input.content : `${input.content}
 `;
-  writeFileSync7(source.path, content, "utf8");
+  writeFileSync6(source.path, content, "utf8");
   return `\u2705 API source updated: ${source.source}`;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thallylabs/mcp",
-  "version": "0.10.25",
-  "description": "MCP server for managing Thally knowledge surfaces and tracing product changes into documentation work.",
+  "version": "0.10.28",
+  "description": "MCP server for managing Thally docs and tracing product changes into evidence-backed updates for human review.",
   "type": "module",
   "engines": {
     "node": ">=18"
@@ -38,8 +38,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.36.0",
     "@modelcontextprotocol/sdk": "^1.15.0",
-    "create-thally-docs": "0.10.23",
-    "gray-matter": "^4.0.3",
+    "create-thally-docs": "0.10.26",
     "p-limit": "^6.1.0",
     "yaml": "^2.8.2",
     "zod": "^3.0.0"