@ahmedrowaihi/8n 0.5.17 → 0.5.19

package/dist/index.mjs

@@ -5,7 +5,7 @@ import path, { basename, delimiter, dirname, extname, join, normalize, relative,
 import fs, { appendFileSync, cpSync, existsSync, mkdirSync, promises, readFileSync, readdirSync, realpathSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import process$1, { cwd } from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { parseTarGzip } from "nanotar";
 import { PassThrough } from "node:stream";
@@ -16,7 +16,7 @@ import v8 from "node:v8";
 import { format, inspect } from "node:util";
 import { z } from "zod";
 import { createInterface } from "node:readline/promises";
-import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 //#region \0rolldown/runtime.js
@@ -11600,7 +11600,7 @@ async function checkSelfUpdate() {
 		});
 		if (!res.ok) return;
 		const { version: latest } = await res.json();
-		const current = "0.5.17";
+		const current = "0.5.19";
 		if (latest !== current) console.log(import_picocolors.default.yellow("⚠") + import_picocolors.default.dim(` new CLI version available: `) + import_picocolors.default.cyan(latest) + import_picocolors.default.dim(` (current: ${current}) — run `) + import_picocolors.default.cyan("npm i -g @ahmedrowaihi/8n") + import_picocolors.default.dim(" to update"));
 	} catch {}
 }
@@ -11973,133 +11973,149 @@ async function prune() {
 
 //#endregion
 //#region src/commands/mcp.ts
-async function walkMd(dir) {
-	const files = [];
-	async function walk(d) {
-		let entries;
-		try {
-			entries = await readdir(d, { withFileTypes: true });
-		} catch {
-			return;
-		}
-		for (const e of entries) {
-			const full = join(d, e.name);
-			if (e.isDirectory()) await walk(full);
-			else if (e.name.endsWith(".mdx") || e.name.endsWith(".md")) files.push(full);
-		}
+async function listMdFiles(dir) {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return [];
 	}
-	await walk(dir);
-	return files;
-}
-function extractTitle(raw, fallback) {
-	const m = raw.match(/^---[\s\S]*?\ntitle:\s*(.+)/m);
-	return m ? m[1].trim().replace(/^["']|["']$/g, "") : fallback;
-}
-function safeAbsPath(base, rel) {
-	const abs = join(base, rel);
-	return abs.startsWith(base) ? abs : null;
+	return entries.filter((e) => !e.isDirectory() && (e.name.endsWith(".mdx") || e.name.endsWith(".md"))).map((e) => e.name);
 }
 async function mcp() {
-	let contentDir = join(process.cwd(), "content");
-	try {
-		contentDir = (await resolveProject()).contentDir;
-	} catch {}
+	const starterDir = findAnyCachedStarterDir();
+	const mcpDir = starterDir ? join(starterDir, "content", "mcp", "en") : null;
 	const server = new McpServer({
 		name: "8n",
-		version: "0.5.17"
+		version: "0.5.19"
 	});
-	const knowledgeFiles = await walkMd(join(contentDir, "mcp"));
-	for (const file of knowledgeFiles) {
-		const name = basename(file, extname(file));
-		const uri = `8n://knowledge/${name}`;
-		server.registerResource(`knowledge-${name}`, uri, {
-			title: name,
-			mimeType: "text/markdown"
-		}, async () => {
-			return { contents: [{
-				uri,
-				text: await readFile(file, "utf-8"),
-				mimeType: "text/markdown"
-			}] };
-		});
-	}
-	server.registerResource("project-config", "8n://project/config", {
-		title: "8n.config.ts",
-		mimeType: "text/plain"
+	server.registerTool("read_me", {
+		description: "Returns how to use the 8n MCP tools. Call this BEFORE documenting anything with 8n.",
+		inputSchema: {}
+	}, async () => ({ content: [{
+		type: "text",
+		text: `# 8n MCP
+
+Use these tools to learn how to write documentation for an 8n project before creating any content.
+
+## Tools
+
+### list_components
+Lists all available reference topics (config, structure, frontmatter, components).
+Call this first to discover what topics are available.
+
+### get_component
+Reads a specific topic by name (without extension).
+Example: get_component({ name: "components" }) returns all available MDX components with usage examples.
+
+## Workflow
+1. Call list_components to see available topics
+2. Call get_component for the topics relevant to your task
+3. Use that knowledge to write correct MDX content for the user's project
+`
+	}] }));
+	server.registerTool("list_components", {
+		description: "Lists all available 8n reference topics (config, structure, frontmatter, MDX components).",
+		inputSchema: {}
 	}, async () => {
-		const configPath = join(process.cwd(), "8n.config.ts");
-		return { contents: [{
-			uri: "8n://project/config",
-			text: existsSync(configPath) ? await readFile(configPath, "utf-8") : "No 8n.config.ts found in current directory.",
-			mimeType: "text/plain"
+		if (!mcpDir || !existsSync(mcpDir)) return { content: [{
+			type: "text",
+			text: "8n starter not cached. Run `8n dev` first."
 		}] };
-	});
-	const pagesTemplate = new ResourceTemplate("8n://pages/{path}", { list: async () => {
-		const pageFiles = (await walkMd(contentDir)).filter((f) => !relative(contentDir, f).startsWith("mcp/"));
-		return { resources: await Promise.all(pageFiles.map(async (f) => {
-			const rel = relative(contentDir, f);
-			const raw = await readFile(f, "utf-8");
-			return {
-				uri: `8n://pages/${rel}`,
-				name: extractTitle(raw, rel),
-				mimeType: "text/markdown"
-			};
-		})) };
-	} });
-	server.registerResource("pages", pagesTemplate, {
-		title: "Project pages",
-		mimeType: "text/markdown"
-	}, async (uri, { path }) => {
-		if (!path) return { contents: [{
-			uri: uri.href,
-			text: "Missing path.",
-			mimeType: "text/plain"
+		return { content: [{
+			type: "text",
+			text: (await listMdFiles(mcpDir)).map((f) => basename(f, extname(f))).join("\n")
 		}] };
-		const rel = Array.isArray(path) ? path[0] : path;
-		const abs = safeAbsPath(contentDir, rel);
-		if (!abs) return { contents: [{
-			uri: uri.href,
-			text: "Invalid path.",
-			mimeType: "text/plain"
+	});
+	server.registerTool("get_component", {
+		description: "Reads a specific 8n reference topic by name. Use list_components first to discover available names.",
+		inputSchema: { name: z.string().describe("Topic name without extension, e.g. components, config, structure, frontmatter") }
+	}, async ({ name }) => {
+		if (!mcpDir || !existsSync(mcpDir)) return { content: [{
+			type: "text",
+			text: "8n starter not cached. Run `8n dev` first."
 		}] };
-		try {
-			const text = await readFile(abs, "utf-8");
-			return { contents: [{
-				uri: uri.href,
-				text,
-				mimeType: "text/markdown"
-			}] };
-		} catch {
-			return { contents: [{
-				uri: uri.href,
-				text: `File not found: ${rel}`,
-				mimeType: "text/plain"
+		for (const ext of [".mdx", ".md"]) {
+			const file = join(mcpDir, `${name}${ext}`);
+			if (existsSync(file)) return { content: [{
+				type: "text",
+				text: await readFile(file, "utf-8")
 			}] };
 		}
-	});
-	server.tool("create_page", "Create a new MDX page in the content directory", {
-		path: z.string().describe("Path relative to content dir, e.g. docs/en/my-page.mdx"),
-		title: z.string().describe("Page title (used in frontmatter and sidebar)"),
-		description: z.string().optional().describe("Short description shown below the heading"),
-		body: z.string().optional().describe("MDX body content (everything after the frontmatter)")
-	}, async ({ path: p, title, description, body }) => {
-		const abs = safeAbsPath(contentDir, p);
-		if (!abs) return { content: [{
+		return { content: [{
 			type: "text",
-			text: "Invalid path."
+			text: `Unknown topic: ${name}. Call list_components to see available topics.`
 		}] };
-		if (existsSync(abs)) return { content: [{
+	});
+	server.registerTool("analyze", {
+		description: "Runs static analysis on the user's content directory and reports issues that may break the documentation site.",
+		inputSchema: {}
+	}, async () => {
+		let contentDir = join(process.cwd(), "content");
+		let locales = ["en"];
+		try {
+			const project = await resolveProject();
+			contentDir = project.contentDir;
+			locales = project.config.locales ?? ["en"];
+		} catch {}
+		const issues = [];
+		async function walkAll(dir) {
+			const results = [];
+			let entries;
+			try {
+				entries = await readdir(dir, { withFileTypes: true });
+			} catch {
+				return results;
+			}
+			for (const e of entries) {
+				const full = join(dir, e.name);
+				if (e.isDirectory()) results.push(...await walkAll(full));
+				else results.push(full);
+			}
+			return results;
+		}
+		const allFiles = await walkAll(contentDir);
+		const mdxFiles = allFiles.filter((f) => f.endsWith(".mdx") || f.endsWith(".md"));
+		const metaFiles = allFiles.filter((f) => f.endsWith("meta.json"));
+		for (const file of mdxFiles) {
+			const raw = await readFile(file, "utf-8").catch(() => "");
+			const rel = relative(contentDir, file);
+			if (!raw.match(/^---[\s\S]*?\ntitle:/m)) issues.push(`Missing title in frontmatter: ${rel}`);
+			if (rel.startsWith("changelog/")) {
+				if (!raw.match(/\nversion:/)) issues.push(`Changelog page missing version: ${rel}`);
+				if (!raw.match(/\ndate:/)) issues.push(`Changelog page missing date: ${rel}`);
+			}
+			const bodyMatch = raw.match(/^---[\s\S]*?---\s*([\s\S]*)$/m);
+			if (bodyMatch && bodyMatch[1].trim() === "") issues.push(`Empty page body: ${rel}`);
+		}
+		for (const file of metaFiles) {
+			const rel = relative(contentDir, file);
+			const raw = await readFile(file, "utf-8").catch(() => "");
+			let meta;
+			try {
+				meta = JSON.parse(raw);
+			} catch {
+				issues.push(`Malformed JSON: ${rel}`);
+				continue;
+			}
+			if (meta.pages) {
+				const dir = join(file, "..");
+				for (const page of meta.pages) if (![".mdx", ".md"].some((ext) => existsSync(join(dir, `${page}${ext}`)))) issues.push(`meta.json references missing page "${page}": ${rel}`);
+			}
+		}
+		const defaultLocale = locales[0];
+		const otherLocales = locales.slice(1);
+		for (const locale of otherLocales) {
+			const defaultFiles = mdxFiles.filter((f) => f.includes(`/${defaultLocale}/`)).map((f) => relative(contentDir, f).replace(`${defaultLocale}/`, `${locale}/`));
+			for (const expected of defaultFiles) if (!existsSync(join(contentDir, expected))) issues.push(`Missing ${locale} translation: ${expected}`);
+		}
+		if (issues.length === 0) return { content: [{
 			type: "text",
-			text: `Already exists: ${p}`
+			text: "✓ No issues found."
 		}] };
-		const fm = ["---", `title: ${title}`];
-		if (description) fm.push(`description: ${description}`);
-		fm.push("---", "", body ?? "");
-		await mkdir(dirname(abs), { recursive: true });
-		await writeFile(abs, fm.join("\n"));
 		return { content: [{
 			type: "text",
-			text: `Created: ${p}`
+			text: `Found ${issues.length} issue${issues.length === 1 ? "" : "s"}:\n\n${issues.map((i) => `- ${i}`).join("\n")}`
 		}] };
 	});
 	const transport = new StdioServerTransport();
@@ -12108,7 +12124,7 @@ async function mcp() {
 
 //#endregion
 //#region src/index.ts
-const program = new Command().name("8n").description("Run your 8n docs site").version("0.5.17").addOption(new Option("--debug").hideHelp()).hook("preAction", (cmd) => {
+const program = new Command().name("8n").description("Run your 8n docs site").version("0.5.19").addOption(new Option("--debug").hideHelp()).hook("preAction", (cmd) => {
 	if (cmd.opts().debug) process.env.DEBUG_8N = "1";
 });
 program.command("init").description("Scaffold a new docs project in the current directory").action(init);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahmedrowaihi/8n",
-  "version": "0.5.17",
+  "version": "0.5.19",
   "description": "Thmanyah Docs — run your docs site from your content directory",
   "type": "module",
   "bin": {