@thallylabs/mcp 0.8.0 → 0.8.1

package/README.md

@@ -1,9 +1,11 @@
 # @thallylabs/mcp
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI
-tools — Claude Code, Claude Desktop, Cursor, Windsurf — create, read, update,
-search, and migrate [Thally](https://github.com/thallylabs/thally) documentation projects
-through natural language.
+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.
 
 ## Setup
 
@@ -28,17 +30,22 @@ Or in a `mcp.json` / client config:
 
 ## Tools
 
-13 tools, including:
+15 tools, including:
 
 - **Authoring** — `create_project`, `add_page`, `update_page`, `read_page`, `list_pages`, `add_tab`
 - **Context & search** — `get_context`, `search_docs`, `semantic_search` (against a deployed site)
 - **Quality** — `lint_project`, `agent_readiness` (the Agent Readiness Score of a deployed site)
-- **Migration** — `migrate_docs`, `translate_docs`
+- **Migration** — `migrate_docs`, `import_docs`, `translate_docs`
+- **Product changes** — `sync_from_repo`
 
 `search_docs`, `read_page`, and `get_context` work against a local project on
 disk; `semantic_search` and `agent_readiness` run against any **deployed** Thally
 site over HTTP.
 
+`migrate_docs` always scaffolds a fresh canonical Thally template before it
+imports content. To preserve an existing Thally runtime and import content in
+place, the caller must explicitly choose `import_docs`.
+
 ## License
 
 MIT

package/dist/index.js

@@ -511,7 +511,23 @@ async function handleListPages(input) {
 import { z as z5 } from "zod";
 import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
 import { join as join4 } from "path";
+
+// src/lib/frontmatter.ts
 import matter from "gray-matter";
+var FRONTMATTER_OPTIONS = {
+  engines: {
+    javascript: () => ({}),
+    js: () => ({})
+  }
+};
+function parseFrontmatter(raw) {
+  return matter(raw, FRONTMATTER_OPTIONS);
+}
+function stringifyFrontmatter(body, data) {
+  return matter.stringify(body, data);
+}
+
+// src/tools/update-page.ts
 var updatePageSchema = z5.object({
   projectDir: z5.string().describe("Path to the Thally project root"),
   pageId: z5.string().describe('Page identifier (e.g. "guides/auth"). No .mdx extension.'),
@@ -541,7 +557,7 @@ async function handleUpdatePage(input) {
     );
   }
   const raw = readFileSync3(filePath, "utf8");
-  const parsed = matter(raw);
+  const parsed = parseFrontmatter(raw);
   const newFm = { ...parsed.data };
   if (input.title !== void 0) newFm["title"] = input.title;
   if (input.description !== void 0) newFm["description"] = input.description;
@@ -549,7 +565,7 @@ async function handleUpdatePage(input) {
     Object.assign(newFm, input.mergeFrontmatter);
   }
   const newBody = input.content !== void 0 ? stripEchoedPageHeader(input.content, pageId) : parsed.content;
-  const newContent = matter.stringify(newBody.trim(), newFm);
+  const newContent = stringifyFrontmatter(newBody.trim(), newFm);
   writeFileSync4(filePath, newContent, "utf8");
   return [
     `\u2705 Page updated: ${filePath}`,
@@ -563,22 +579,30 @@ async function handleUpdatePage(input) {
 // src/tools/migrate-docs.ts
 import { z as z6 } from "zod";
 import { migrateDocs } from "create-thally-docs/migrate";
-var migrateDocsSchema = z6.object({
+var migrationSourceShape = {
   sourceUrl: z6.string().describe("GitHub repository URL or public documentation URL to migrate"),
-  projectDir: z6.string().describe("Path for new project or existing project dir"),
-  into: z6.boolean().optional().default(false).describe("Migrate into existing project instead of scaffolding"),
   branch: z6.string().optional().describe("Git branch (default: auto-detect)"),
   docsDir: z6.string().optional().describe("Docs subdirectory in repo (default: auto-detect)"),
   apiKey: z6.string().optional().describe("Anthropic API key for non-Markdown file conversion"),
   maxPages: z6.number().int().min(1).max(1e3).optional().describe("Maximum public URL pages to import"),
   platform: z6.enum(["mintlify", "docusaurus"]).optional().describe("Source platform (default: auto-detect)")
+};
+var migrateDocsSchema = z6.object({
+  ...migrationSourceShape,
+  projectDir: z6.string().describe("Path for the new canonical Thally project; the directory must be absent or empty")
 });
-async function handleMigrateDocs(input) {
+var importDocsSchema = z6.object({
+  ...migrationSourceShape,
+  projectDir: z6.string().describe("Path to an existing Thally project whose runtime should be preserved")
+});
+async function runMigration(input, isInPlaceImport) {
   const apiKey = input.apiKey ?? process.env.ANTHROPIC_API_KEY;
-  const result = await migrateDocs({
+  return migrateDocs({
     sourceUrl: input.sourceUrl,
     projectDir: input.projectDir,
-    into: input.into ?? false,
+    // Keep this decision inside the adapter so stale or adversarial callers
+    // cannot turn a template-first migration into an in-place mutation.
+    into: isInPlaceImport,
     apiKey,
     branch: input.branch,
     docsDir: input.docsDir,
@@ -586,14 +610,20 @@ async function handleMigrateDocs(input) {
     platform: input.platform,
     yes: true
   });
-  return `Migration complete! ${result.pagesWritten} pages written to ${result.projectDir}/src/content/`;
+}
+async function handleMigrateDocs(input) {
+  const result = await runMigration(input, false);
+  return `Migration complete! Created a fresh Thally template at ${result.projectDir} and imported ${result.pagesWritten} pages.`;
+}
+async function handleImportDocs(input) {
+  const result = await runMigration(input, true);
+  return `Import complete! Imported ${result.pagesWritten} pages into the existing Thally project at ${result.projectDir}.`;
 }
 
 // src/tools/search-docs.ts
 import { z as z7 } from "zod";
 import { readdirSync as readdirSync2, statSync, readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
 import { join as join5, relative, extname } from "path";
-import matter2 from "gray-matter";
 var searchDocsSchema = z7.object({
   projectDir: z7.string().describe("Path to the Thally project root"),
   query: z7.string().describe("Search query"),
@@ -629,7 +659,7 @@ function scoreFiles(files, contentDir, query) {
     } catch {
       continue;
     }
-    const { data, content } = matter2(raw);
+    const { data, content } = parseFrontmatter(raw);
     const title = data.title ?? "";
     const description = data.description ?? "";
     const keywords = data.keywords ?? [];
@@ -748,7 +778,6 @@ async function handleAgentReadiness(input) {
 import { z as z10 } from "zod";
 import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
 import { join as join6 } from "path";
-import matter3 from "gray-matter";
 var readPageSchema = z10.object({
   projectDir: z10.string().describe("Path to the Thally project root"),
   pageId: z10.string().describe('Page ID, e.g. "guides/authentication"')
@@ -771,7 +800,7 @@ async function handleReadPage(input) {
     throw new Error(`Page not found: "${pageId}". No file at src/content/${pageId}.mdx`);
   }
   const raw = readFileSync5(filePath, "utf8");
-  const { data, content } = matter3(raw);
+  const { data, content } = parseFrontmatter(raw);
   const title = data.title ?? pageId;
   const description = data.description ?? "";
   const lines = [`id: ${pageId}`, `title: ${title}`];
@@ -784,7 +813,6 @@ async function handleReadPage(input) {
 import { z as z11 } from "zod";
 import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
 import { join as join7 } from "path";
-import matter4 from "gray-matter";
 var getContextSchema = z11.object({
   projectDir: z11.string().describe("Path to the Thally project root"),
   topic: z11.string().describe("Topic or question to find relevant docs for"),
@@ -814,7 +842,7 @@ async function handleGetContext(input) {
     for (const c of candidates) {
       if (existsSync6(c)) {
         const raw = readFileSync6(c, "utf8");
-        const { content: body } = matter4(raw);
+        const { content: body } = parseFrontmatter(raw);
         content = body.trim();
         break;
       }
@@ -840,7 +868,6 @@ async function handleGetContext(input) {
 import { z as z12 } from "zod";
 import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
 import { join as join8 } from "path";
-import matter5 from "gray-matter";
 var lintProjectSchema = z12.object({
   projectDir: z12.string().describe("Path to the Thally project root"),
   fix: z12.boolean().optional().default(false).describe("Auto-fix issues where possible (adds orphan pages to nav)")
@@ -923,7 +950,7 @@ async function handleLintProject(input) {
     let content = "";
     try {
       const raw = readFileSync7(filePath, "utf8");
-      const parsed = matter5(raw);
+      const parsed = parseFrontmatter(raw);
       data = parsed.data;
       content = parsed.content;
     } catch {
@@ -981,7 +1008,6 @@ async function handleLintProject(input) {
 import { z as z13 } from "zod";
 import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync3 } from "fs";
 import { join as join9, dirname as dirname2 } from "path";
-import matter6 from "gray-matter";
 import Anthropic from "@anthropic-ai/sdk";
 import pLimit from "p-limit";
 var translateDocsSchema = z13.object({
@@ -1121,7 +1147,7 @@ async function handleTranslateDocs(input) {
       ({ pageId, sourceFile, targetFile }) => limit(async () => {
         try {
           const sourceContent = readFileSync8(sourceFile, "utf8");
-          const parsed = matter6(sourceContent);
+          const parsed = parseFrontmatter(sourceContent);
           if (!parsed.data.title) {
             console.warn(`[translate] ${pageId}: missing title in frontmatter`);
           }
@@ -1476,11 +1502,18 @@ var tools = [
   }),
   defineTool({
     name: "migrate_docs",
-    description: "Crawl a docs site and migrate it into a Thally project",
+    description: "Create a fresh canonical Thally template, then migrate a GitHub repository or public docs site into it; the target must be new or empty",
     scope: "project",
     schema: migrateDocsSchema,
     handler: handleMigrateDocs
   }),
+  defineTool({
+    name: "import_docs",
+    description: "Import content into an existing Thally project without scaffolding; use only when an in-place import is explicitly requested",
+    scope: "project",
+    schema: importDocsSchema,
+    handler: handleImportDocs
+  }),
   defineTool({
     name: "search_docs",
     description: "Search documentation pages by keyword \u2014 returns ranked list of matching pages",

package/dist/tools.js

@@ -502,7 +502,23 @@ async function handleListPages(input) {
 import { z as z5 } from "zod";
 import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
 import { join as join4 } from "path";
+
+// src/lib/frontmatter.ts
 import matter from "gray-matter";
+var FRONTMATTER_OPTIONS = {
+  engines: {
+    javascript: () => ({}),
+    js: () => ({})
+  }
+};
+function parseFrontmatter(raw) {
+  return matter(raw, FRONTMATTER_OPTIONS);
+}
+function stringifyFrontmatter(body, data) {
+  return matter.stringify(body, data);
+}
+
+// src/tools/update-page.ts
 var updatePageSchema = z5.object({
   projectDir: z5.string().describe("Path to the Thally project root"),
   pageId: z5.string().describe('Page identifier (e.g. "guides/auth"). No .mdx extension.'),
@@ -532,7 +548,7 @@ async function handleUpdatePage(input) {
     );
   }
   const raw = readFileSync3(filePath, "utf8");
-  const parsed = matter(raw);
+  const parsed = parseFrontmatter(raw);
   const newFm = { ...parsed.data };
   if (input.title !== void 0) newFm["title"] = input.title;
   if (input.description !== void 0) newFm["description"] = input.description;
@@ -540,7 +556,7 @@ async function handleUpdatePage(input) {
     Object.assign(newFm, input.mergeFrontmatter);
   }
   const newBody = input.content !== void 0 ? stripEchoedPageHeader(input.content, pageId) : parsed.content;
-  const newContent = matter.stringify(newBody.trim(), newFm);
+  const newContent = stringifyFrontmatter(newBody.trim(), newFm);
   writeFileSync4(filePath, newContent, "utf8");
   return [
     `\u2705 Page updated: ${filePath}`,
@@ -554,22 +570,30 @@ async function handleUpdatePage(input) {
 // src/tools/migrate-docs.ts
 import { z as z6 } from "zod";
 import { migrateDocs } from "create-thally-docs/migrate";
-var migrateDocsSchema = z6.object({
+var migrationSourceShape = {
   sourceUrl: z6.string().describe("GitHub repository URL or public documentation URL to migrate"),
-  projectDir: z6.string().describe("Path for new project or existing project dir"),
-  into: z6.boolean().optional().default(false).describe("Migrate into existing project instead of scaffolding"),
   branch: z6.string().optional().describe("Git branch (default: auto-detect)"),
   docsDir: z6.string().optional().describe("Docs subdirectory in repo (default: auto-detect)"),
   apiKey: z6.string().optional().describe("Anthropic API key for non-Markdown file conversion"),
   maxPages: z6.number().int().min(1).max(1e3).optional().describe("Maximum public URL pages to import"),
   platform: z6.enum(["mintlify", "docusaurus"]).optional().describe("Source platform (default: auto-detect)")
+};
+var migrateDocsSchema = z6.object({
+  ...migrationSourceShape,
+  projectDir: z6.string().describe("Path for the new canonical Thally project; the directory must be absent or empty")
 });
-async function handleMigrateDocs(input) {
+var importDocsSchema = z6.object({
+  ...migrationSourceShape,
+  projectDir: z6.string().describe("Path to an existing Thally project whose runtime should be preserved")
+});
+async function runMigration(input, isInPlaceImport) {
   const apiKey = input.apiKey ?? process.env.ANTHROPIC_API_KEY;
-  const result = await migrateDocs({
+  return migrateDocs({
     sourceUrl: input.sourceUrl,
     projectDir: input.projectDir,
-    into: input.into ?? false,
+    // Keep this decision inside the adapter so stale or adversarial callers
+    // cannot turn a template-first migration into an in-place mutation.
+    into: isInPlaceImport,
     apiKey,
     branch: input.branch,
     docsDir: input.docsDir,
@@ -577,14 +601,20 @@ async function handleMigrateDocs(input) {
     platform: input.platform,
     yes: true
   });
-  return `Migration complete! ${result.pagesWritten} pages written to ${result.projectDir}/src/content/`;
+}
+async function handleMigrateDocs(input) {
+  const result = await runMigration(input, false);
+  return `Migration complete! Created a fresh Thally template at ${result.projectDir} and imported ${result.pagesWritten} pages.`;
+}
+async function handleImportDocs(input) {
+  const result = await runMigration(input, true);
+  return `Import complete! Imported ${result.pagesWritten} pages into the existing Thally project at ${result.projectDir}.`;
 }
 
 // src/tools/search-docs.ts
 import { z as z7 } from "zod";
 import { readdirSync as readdirSync2, statSync, readFileSync as readFileSync4, existsSync as existsSync4 } from "fs";
 import { join as join5, relative, extname } from "path";
-import matter2 from "gray-matter";
 var searchDocsSchema = z7.object({
   projectDir: z7.string().describe("Path to the Thally project root"),
   query: z7.string().describe("Search query"),
@@ -620,7 +650,7 @@ function scoreFiles(files, contentDir, query) {
     } catch {
       continue;
     }
-    const { data, content } = matter2(raw);
+    const { data, content } = parseFrontmatter(raw);
     const title = data.title ?? "";
     const description = data.description ?? "";
     const keywords = data.keywords ?? [];
@@ -739,7 +769,6 @@ async function handleAgentReadiness(input) {
 import { z as z10 } from "zod";
 import { existsSync as existsSync5, readFileSync as readFileSync5 } from "fs";
 import { join as join6 } from "path";
-import matter3 from "gray-matter";
 var readPageSchema = z10.object({
   projectDir: z10.string().describe("Path to the Thally project root"),
   pageId: z10.string().describe('Page ID, e.g. "guides/authentication"')
@@ -762,7 +791,7 @@ async function handleReadPage(input) {
     throw new Error(`Page not found: "${pageId}". No file at src/content/${pageId}.mdx`);
   }
   const raw = readFileSync5(filePath, "utf8");
-  const { data, content } = matter3(raw);
+  const { data, content } = parseFrontmatter(raw);
   const title = data.title ?? pageId;
   const description = data.description ?? "";
   const lines = [`id: ${pageId}`, `title: ${title}`];
@@ -775,7 +804,6 @@ async function handleReadPage(input) {
 import { z as z11 } from "zod";
 import { existsSync as existsSync6, readFileSync as readFileSync6 } from "fs";
 import { join as join7 } from "path";
-import matter4 from "gray-matter";
 var getContextSchema = z11.object({
   projectDir: z11.string().describe("Path to the Thally project root"),
   topic: z11.string().describe("Topic or question to find relevant docs for"),
@@ -805,7 +833,7 @@ async function handleGetContext(input) {
     for (const c of candidates) {
       if (existsSync6(c)) {
         const raw = readFileSync6(c, "utf8");
-        const { content: body } = matter4(raw);
+        const { content: body } = parseFrontmatter(raw);
         content = body.trim();
         break;
       }
@@ -831,7 +859,6 @@ async function handleGetContext(input) {
 import { z as z12 } from "zod";
 import { existsSync as existsSync7, readFileSync as readFileSync7 } from "fs";
 import { join as join8 } from "path";
-import matter5 from "gray-matter";
 var lintProjectSchema = z12.object({
   projectDir: z12.string().describe("Path to the Thally project root"),
   fix: z12.boolean().optional().default(false).describe("Auto-fix issues where possible (adds orphan pages to nav)")
@@ -914,7 +941,7 @@ async function handleLintProject(input) {
     let content = "";
     try {
       const raw = readFileSync7(filePath, "utf8");
-      const parsed = matter5(raw);
+      const parsed = parseFrontmatter(raw);
       data = parsed.data;
       content = parsed.content;
     } catch {
@@ -972,7 +999,6 @@ async function handleLintProject(input) {
 import { z as z13 } from "zod";
 import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync3 } from "fs";
 import { join as join9, dirname as dirname2 } from "path";
-import matter6 from "gray-matter";
 import Anthropic from "@anthropic-ai/sdk";
 import pLimit from "p-limit";
 var translateDocsSchema = z13.object({
@@ -1112,7 +1138,7 @@ async function handleTranslateDocs(input) {
       ({ pageId, sourceFile, targetFile }) => limit(async () => {
         try {
           const sourceContent = readFileSync8(sourceFile, "utf8");
-          const parsed = matter6(sourceContent);
+          const parsed = parseFrontmatter(sourceContent);
           if (!parsed.data.title) {
             console.warn(`[translate] ${pageId}: missing title in frontmatter`);
           }
@@ -1467,11 +1493,18 @@ var tools = [
   }),
   defineTool({
     name: "migrate_docs",
-    description: "Crawl a docs site and migrate it into a Thally project",
+    description: "Create a fresh canonical Thally template, then migrate a GitHub repository or public docs site into it; the target must be new or empty",
     scope: "project",
     schema: migrateDocsSchema,
     handler: handleMigrateDocs
   }),
+  defineTool({
+    name: "import_docs",
+    description: "Import content into an existing Thally project without scaffolding; use only when an in-place import is explicitly requested",
+    scope: "project",
+    schema: importDocsSchema,
+    handler: handleImportDocs
+  }),
   defineTool({
     name: "search_docs",
     description: "Search documentation pages by keyword \u2014 returns ranked list of matching pages",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thallylabs/mcp",
-  "version": "0.8.0",
-  "description": "MCP server for scaffolding and managing Thally documentation projects",
+  "version": "0.8.1",
+  "description": "MCP server for managing Thally knowledge surfaces and tracing product changes into documentation work.",
   "type": "module",
   "engines": {
     "node": ">=18"