@czi-sds/mcp 0.16.0 → 0.17.0

package/dist/stdio.js

@@ -20,70 +20,73 @@ const server = new McpServer({
 });
 //#endregion
 //#region src/lib/fetch.ts
-const filename$1 = fileURLToPath(import.meta.url);
-const dirname$2 = path.dirname(filename$1);
+const filename = fileURLToPath(import.meta.url);
+const dirname$1 = path.dirname(filename);
+/**
+* Locates a file under `data/`. The server runs both from source via tsx and
+* from the bundle in `dist/`, which sit at different depths, and may also be
+* started from the package root.
+*/
+function resolveDataPath(relativePath) {
+	return [
+		path.join(dirname$1, "../../data", relativePath),
+		path.join(dirname$1, "../data", relativePath),
+		path.join(process.cwd(), "data", relativePath)
+	].find((candidate) => fs.existsSync(candidate)) ?? null;
+}
+function readDataFile(relativePath, missingHint) {
+	const dataPath = resolveDataPath(relativePath);
+	if (!dataPath) throw new Error(`${relativePath} not found in any expected location. ${missingHint}`);
+	return fs.readFileSync(dataPath, "utf-8");
+}
 /**
 * Gets all component names from both packages
 */
 async function getAllComponentNames() {
 	try {
-		const possiblePaths = [
-			path.join(dirname$2, "../../data/component-list.json"),
-			path.join(dirname$2, "../data/component-list.json"),
-			path.join(process.cwd(), "data/component-list.json")
-		];
-		let dataPath = "";
-		for (const p of possiblePaths) if (fs.existsSync(p)) {
-			dataPath = p;
-			break;
-		}
-		if (!dataPath) throw new Error("Component list not found in any expected location. Please run 'yarn generate:components-list' first.");
-		const fileContent = fs.readFileSync(dataPath, "utf-8");
-		return JSON.parse(fileContent);
+		return JSON.parse(readDataFile("component-list.json", "Please run 'yarn generate:components-list' first."));
 	} catch (error) {
 		throw new Error(`Failed to load component list: ${error instanceof Error ? error.message : `Unknown error ${error}`}`);
 	}
 }
 async function fetchComponentProps(component) {
 	try {
-		const propsPaths = [
-			path.join(dirname$2, `../../data/component-props/${component}.json`),
-			path.join(dirname$2, `../data/component-props/${component}.json`),
-			path.join(process.cwd(), `data/component-props/${component}.json`)
-		];
-		let propsPath = "";
-		for (const p of propsPaths) if (fs.existsSync(p)) {
-			propsPath = p;
-			break;
-		}
+		const propsPath = resolveDataPath(`component-props/${component}.json`);
 		if (!propsPath) return { [component]: {
 			message: "Props information not available for this component. Run 'yarn generate:component-props' to generate props data.",
 			props: {}
 		} };
-		const fileContent = fs.readFileSync(propsPath, "utf-8");
-		return JSON.parse(fileContent);
+		return JSON.parse(fs.readFileSync(propsPath, "utf-8"));
 	} catch (error) {
 		throw new Error(`Failed to load props for ${component}: ${error instanceof Error ? error.message : "Unknown error"}`);
 	}
 }
 /**
+* Gets the index of components that have generated documentation
+*/
+async function getComponentDocsIndex() {
+	try {
+		return JSON.parse(readDataFile("component-docs/index.json", "Please run 'yarn generate:component-docs' first."));
+	} catch (error) {
+		throw new Error(`Failed to load component docs index: ${error instanceof Error ? error.message : `Unknown error ${error}`}`);
+	}
+}
+/**
+* Fetches the generated documentation markdown for a specific component
+*/
+async function fetchComponentDocs(file) {
+	try {
+		return readDataFile(`component-docs/${file}`, "Please run 'yarn generate:component-docs' first.");
+	} catch (error) {
+		throw new Error(`Failed to load documentation from ${file}: ${error instanceof Error ? error.message : "Unknown error"}`);
+	}
+}
+/**
 * Gets all component names from both packages
 */
 async function fetchTailwindTokens() {
 	try {
-		const possiblePaths = [
-			path.join(dirname$2, "../../data/tailwind.json"),
-			path.join(dirname$2, "../data/tailwind.json"),
-			path.join(process.cwd(), "data/tailwind.json")
-		];
-		let dataPath = "";
-		for (const p of possiblePaths) if (fs.existsSync(p)) {
-			dataPath = p;
-			break;
-		}
-		if (!dataPath) throw new Error("Component list not found in any expected location. Please run 'yarn generate:tailwind-tokens' first.");
-		const fileContent = fs.readFileSync(dataPath, "utf-8");
-		return JSON.parse(fileContent);
+		return JSON.parse(readDataFile("tailwind.json", "Please run 'yarn generate:tailwind-tokens' first."));
 	} catch (error) {
 		throw new Error(`Failed to load tailwind tokens: ${error instanceof Error ? error.message : `Unknown error ${error}`}`);
 	}
@@ -396,199 +399,100 @@ colors: This category can be used for formatting colors in the tailwind.config.j
 	return output;
 }
 //#endregion
-//#region src/tools/get-tailwind-tokens.ts
-const getTailwindTokensTool = {
-	name: "get_tailwind_tokens",
-	description: "Get all available Tailwind tokens from the SDS design system. Available design tokens include fontFamily, fontSize, fontVariantNumeric, letterSpacing, lineHeight, textDecoration, textTransform, typography, height, width, borderRadius, boxShadow, breakpoints, colors, spacing, and more.",
-	async ctx() {
-		try {
-			return { tailwindTokens: await fetchTailwindTokens() };
-		} catch (error) {
-			throw new Error(`Failed to initialize tailwind tokens tool: ${error instanceof Error ? error.message : "Unknown error"}`);
-		}
-	},
-	exec(server, { ctx, name, description }) {
-		server.tool(name, description, { category: z.enum([
-			"all",
-			"fontFamily",
-			"fontSize",
-			"fontVariantNumeric",
-			"letterSpacing",
-			"lineHeight",
-			"textDecoration",
-			"textTransform",
-			"typography",
-			"height",
-			"width",
-			"borderRadius",
-			"boxShadow",
-			"breakpoints",
-			"colors",
-			"spacing"
-		]).optional().describe("Optional category of tokens to retrieve. If not specified, returns all tokens.") }, async ({ category }) => {
-			try {
-				const tokens = ctx.tailwindTokens;
-				let result;
-				if (!category || category === "all") result = tokens;
-				else result = tokens[category] || {};
-				const responseContent = [];
-				const guidance = getTokenGuidance(category);
-				responseContent.push({
-					type: "text",
-					text: guidance
-				});
-				responseContent.push({
-					type: "text",
-					text: JSON.stringify(result, null, 2)
-				});
-				return { content: responseContent };
-			} catch (error) {
-				return { content: [{
-					type: "text",
-					text: `Failed to get Tailwind tokens: ${error instanceof Error ? error.message : "Unknown error"}`
-				}] };
-			}
-		});
-	}
-};
-//#endregion
-//#region src/tools/get-component-docs.ts
-const filename = fileURLToPath(import.meta.url);
-const dirname$1 = path.dirname(filename);
-/**
-* Maps a component name to the corresponding Zeroheight file using manual mapping
-*/
-function mapComponentToFile(componentName, exportedFiles) {
-	const mappedFile = {
-		Button: "Buttons",
-		ButtonDropdown: "Buttons",
-		ButtonIcon: "Buttons",
-		ButtonToggle: "Buttons",
-		TableHeader: "Table",
-		TableRow: "Table",
-		InputCheckbox: "Control-Inputs",
-		InputRadio: "Control-Inputs",
-		InputToggle: "Control-Inputs",
-		InputText: "Field-Inputs",
-		InputDropdown: "Dropdown-Input",
-		InputSearch: "Search-Input",
-		InputSlider: "Control-Inputs",
-		Dropdown: "Dropdown-Menu",
-		DropdownMenu: "Dropdown-Menu",
-		ContentCard: "Content-Card",
-		LoadingIndicator: "Loading-Indicator",
-		NavigationFooter: "Navigation",
-		NavigationHeader: "Navigation",
-		NavigationJumpTo: "Navigation",
-		SegmentedControl: "Segmented-Control",
-		List: "Lists",
-		Menu: "Dropdown-Menu",
-		MenuItem: "Dropdown-Menu",
-		MenuSelect: "Dropdown-Menu",
-		Tag: "Tags",
-		TagFilter: "Tags",
-		Tooltip: "Tooltips",
-		TooltipCondensed: "Tooltips",
-		TooltipTable: "Tooltips",
-		CellBasic: "Table",
-		CellComponent: "Table",
-		CellHeader: "Table",
-		ComplexFilter: "Filters",
-		Icon: "Icons",
-		Chip: "Tags",
-		Pagination: "Navigation"
-	}[componentName];
-	if (mappedFile && exportedFiles.includes(mappedFile)) return `${mappedFile}.md`;
-	if (exportedFiles.includes(componentName)) return `${componentName}.md`;
-	return null;
-}
-/**
-* Get list of exported documentation files
-*/
-function getExportedFiles() {
-	try {
-		const possiblePaths = [
-			path.join(dirname$1, "../../data/zeroheight-exports"),
-			path.join(dirname$1, "../data/zeroheight-exports"),
-			path.join(process.cwd(), "data/zeroheight-exports")
-		];
-		let exportDir = "";
-		for (const p of possiblePaths) if (fs.existsSync(p)) {
-			exportDir = p;
-			break;
-		}
-		if (!exportDir) {
-			console.warn("Export directory not found in any expected location. Please run Zeroheight export first.");
-			return [];
-		}
-		return fs.readdirSync(exportDir).filter((file) => file.endsWith(".md") && file !== "README.md").map((file) => file.replace(".md", ""));
-	} catch (error) {
-		console.warn("Could not read exported files:", error);
-		return [];
-	}
-}
-/**
-* Get list of components that have documentation available
-*/
-function getComponentsWithDocs(allComponents, exportedFiles) {
-	return allComponents.filter((component) => {
-		return mapComponentToFile(component, exportedFiles) !== null;
-	});
-}
-//#endregion
 //#region src/tools/index.ts
 const tools = [
 	getComponentPropsTool,
 	{
 		name: "get_component_docs",
-		description: "Get design system documentation for a specific component. Retrieves the corresponding Zeroheight documentation file for the given component name. Supports all SDS components and maps them to their appropriate documentation files.",
+		description: "Get design system documentation for a specific SDS component. Returns the component's full documentation, including how it differs from the underlying MUI component, its props, and runnable code examples for each supported variation.",
 		async ctx() {
 			try {
-				const componentList = await getAllComponentNames();
-				const allComponents = [...componentList.components, ...componentList["data-viz"]];
-				const exportedFiles = getExportedFiles();
+				const index = await getComponentDocsIndex();
 				return {
-					componentsWithDocs: getComponentsWithDocs(allComponents, exportedFiles),
-					exportedFiles
+					index,
+					documented: Object.keys(index)
 				};
 			} catch (error) {
 				throw new Error(`Failed to initialize get component docs tool: ${error instanceof Error ? error.message : "Unknown error"}`);
 			}
 		},
 		exec(server, { ctx, name, description }) {
-			server.tool(name, description, { component: z.enum(ctx.componentsWithDocs).describe("The name of the SDS component to get documentation for") }, async ({ component }) => {
+			server.tool(name, description, { component: z.enum(ctx.documented).describe("The name of the SDS component to get documentation for") }, async ({ component }) => {
 				try {
-					const mappedFile = mapComponentToFile(component, ctx.exportedFiles);
-					if (!mappedFile) return { content: [{
+					const entry = ctx.index[component];
+					if (!entry) return { content: [{
 						type: "text",
 						text: `No documentation found for component '${component}'. This component may not have design system documentation available.`
 					}] };
-					const possiblePaths = [
-						path.join(dirname$1, "../../data/zeroheight-exports", mappedFile),
-						path.join(dirname$1, "../data/zeroheight-exports", mappedFile),
-						path.join(process.cwd(), "data/zeroheight-exports", mappedFile)
-					];
-					let filePath = "";
-					for (const p of possiblePaths) if (fs.existsSync(p)) {
-						filePath = p;
-						break;
-					}
-					if (!filePath) throw new Error(`Documentation file ${mappedFile} not found`);
+					const documentation = await fetchComponentDocs(entry.file);
 					return { content: [{
 						type: "text",
-						text: `# Documentation for ${component}\n\nSource: ${mappedFile}\n\n${fs.readFileSync(filePath, "utf8")}`
+						text: `Package: ${entry.package}\nSource: ${entry.source}\n\n${documentation}`
 					}] };
 				} catch (error) {
 					return { content: [{
 						type: "text",
-						text: `Error reading documentation file for '${component}': ${error instanceof Error ? error.message : "Unknown error"}`
+						text: `Error reading documentation for '${component}': ${error instanceof Error ? error.message : "Unknown error"}`
 					}] };
 				}
 			});
 		}
 	},
 	listComponentsTool,
-	getTailwindTokensTool
+	{
+		name: "get_tailwind_tokens",
+		description: "Get all available Tailwind tokens from the SDS design system. Available design tokens include fontFamily, fontSize, fontVariantNumeric, letterSpacing, lineHeight, textDecoration, textTransform, typography, height, width, borderRadius, boxShadow, breakpoints, colors, spacing, and more.",
+		async ctx() {
+			try {
+				return { tailwindTokens: await fetchTailwindTokens() };
+			} catch (error) {
+				throw new Error(`Failed to initialize tailwind tokens tool: ${error instanceof Error ? error.message : "Unknown error"}`);
+			}
+		},
+		exec(server, { ctx, name, description }) {
+			server.tool(name, description, { category: z.enum([
+				"all",
+				"fontFamily",
+				"fontSize",
+				"fontVariantNumeric",
+				"letterSpacing",
+				"lineHeight",
+				"textDecoration",
+				"textTransform",
+				"typography",
+				"height",
+				"width",
+				"borderRadius",
+				"boxShadow",
+				"breakpoints",
+				"colors",
+				"spacing"
+			]).optional().describe("Optional category of tokens to retrieve. If not specified, returns all tokens.") }, async ({ category }) => {
+				try {
+					const tokens = ctx.tailwindTokens;
+					let result;
+					if (!category || category === "all") result = tokens;
+					else result = tokens[category] || {};
+					const responseContent = [];
+					const guidance = getTokenGuidance(category);
+					responseContent.push({
+						type: "text",
+						text: guidance
+					});
+					responseContent.push({
+						type: "text",
+						text: JSON.stringify(result, null, 2)
+					});
+					return { content: responseContent };
+				} catch (error) {
+					return { content: [{
+						type: "text",
+						text: `Failed to get Tailwind tokens: ${error instanceof Error ? error.message : "Unknown error"}`
+					}] };
+				}
+			});
+		}
+	}
 ];
 const registeredToolCache = /* @__PURE__ */ new Map();
 const initializeTools = async (server, config) => {
@@ -654,19 +558,19 @@ function initializeResources(server) {
 			throw new Error("Failed to read component rules: " + message);
 		}
 	});
-	server.resource("Zeroheight Documentation Rules", "sds://rules/zeroheight", {
+	server.resource("SDS Documentation Rules", "sds://rules/documentation", {
 		mimeType: MIME_TYPE_MARKDOWN,
-		description: "Rules for following Zeroheight documentation"
+		description: "Rules for following the SDS component documentation"
 	}, async () => {
 		try {
 			return { contents: [{
-				uri: "sds://rules/zeroheight",
+				uri: "sds://rules/documentation",
 				mimeType: MIME_TYPE_MARKDOWN,
-				text: readFileSync(findResourceFile("zeroheight-rules.md"), "utf-8")
+				text: readFileSync(findResourceFile("documentation-rules.md"), "utf-8")
 			}] };
 		} catch (err) {
 			const message = err instanceof Error ? err.message : UNKNOWN_ERROR;
-			throw new Error("Failed to read Zeroheight rules: " + message);
+			throw new Error("Failed to read documentation rules: " + message);
 		}
 	});
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@czi-sds/mcp",
   "description": "The official MCP server for SDS",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "main": "dist/stdio.js",
   "files": [
     "dist",
@@ -22,13 +22,14 @@
     "generate:tailwind-tokens": "mkdir -p data && cp ../components/src/common/styles-dictionary/json/tailwind.json data/tailwind.json && echo '✓ Copied tailwind.json to data folder'",
     "generate:components-list": "tsx scripts/generate-component-list.ts",
     "generate:component-props": "tsx scripts/generate-component-props.ts",
-    "generate:zeroheight-export": "tsx scripts/export-zeroheight-pages.ts",
-    "generate:all": "yarn generate:tailwind-tokens && yarn generate:components-list && yarn generate:component-props",
+    "generate:component-docs": "tsx scripts/generate-component-docs.ts",
+    "generate:all": "yarn generate:tailwind-tokens && yarn generate:components-list && yarn generate:component-props && yarn generate:component-docs && npx prettier --write 'data/**/*.{md,json}'",
+    "audit:docs": "tsx scripts/audit-docs.ts",
     "prebuild": "yarn generate:all",
     "build": "yarn prebuild && rolldown -c && chmod 755 dist/stdio.js",
     "dev": "rolldown -c --watch",
     "inspect": "node scripts/inspect.js",
-    "inspect:dev": "npx @modelcontextprotocol/inspector npx tsx src/stdio.ts",
+    "inspect:dev": "npx -y @modelcontextprotocol/inspector@latest npx tsx src/stdio.ts",
     "serve": "tsx --watch src/http.ts"
   },
   "bin": {
@@ -57,10 +58,13 @@
     "@tsconfig/node22": "^22.0.1",
     "@types/express": "^5.0.3",
     "@types/fs-extra": "^11.0.4",
+    "@types/turndown": "^5.0.6",
+    "node-html-parser": "^9.0.1",
     "react-docgen-typescript": "^2.4.0",
     "rolldown": "^1.0.1",
     "tsx": "^4.20.3",
+    "turndown": "^7.2.4",
     "typescript": "^5.9.2"
   },
-  "gitHead": "ccf2cae77a8b5748a247f2349d06be28d3097ade"
+  "gitHead": "86ab08f76d3b95b09ac6709b17f6c6d65b10d9e5"
 }

package/data/component-props/ButtonDropdownV2.json

@@ -1,34 +0,0 @@
-{
-  "ButtonDropdownV2": {
-    "props": {
-      "backgroundOnHover": {
-        "type": "any",
-        "isRequired": false
-      },
-      "children": {
-        "type": "any",
-        "isRequired": false
-      },
-      "disabled": {
-        "type": "any",
-        "isRequired": false
-      },
-      "startIcon": {
-        "type": "any",
-        "isRequired": false
-      },
-      "size": {
-        "type": "any",
-        "isRequired": false
-      },
-      "sdsStyle": {
-        "type": "any",
-        "isRequired": false
-      },
-      "sdsType": {
-        "type": "any",
-        "isRequired": false
-      }
-    }
-  }
-}

package/data/component-props/ButtonNew.json

@@ -1,47 +0,0 @@
-{
-  "ButtonNew": {
-    "props": {
-      "backgroundOnHover": {
-        "type": "\"false\" | \"true\"",
-        "isRequired": false
-      },
-      "children": {
-        "type": "ReactNode",
-        "isRequired": false,
-        "description": "The content of the component."
-      },
-      "endIcon": {
-        "type": "ReactNode",
-        "isRequired": false,
-        "description": "Element placed after the children."
-      },
-      "icon": {
-        "type": "any",
-        "isRequired": false
-      },
-      "onClick": {
-        "type": "function",
-        "isRequired": false
-      },
-      "size": {
-        "type": "\"small\" | \"medium\" | \"large\"",
-        "isRequired": false,
-        "description": "The size of the component.\n`small` is equivalent to the dense button styling.",
-        "defaultValue": "medium"
-      },
-      "sdsStyle": {
-        "type": "\"outline\" | \"solid\" | \"minimal\"",
-        "isRequired": false
-      },
-      "sdsType": {
-        "type": "\"primary\" | \"secondary\" | \"destructive\"",
-        "isRequired": false
-      },
-      "startIcon": {
-        "type": "ReactNode",
-        "isRequired": false,
-        "description": "Element placed before the children."
-      }
-    }
-  }
-}

package/data/component-props/ButtonToggleV2.json

@@ -1,44 +0,0 @@
-{
-  "ButtonToggleV2": {
-    "props": {
-      "backgroundOnHover": {
-        "type": "\"false\" | \"true\"",
-        "isRequired": false
-      },
-      "children": {
-        "type": "ReactNode",
-        "isRequired": false,
-        "description": "The content of the component."
-      },
-      "disabled": {
-        "type": "\"false\" | \"true\"",
-        "isRequired": false,
-        "description": "If `true`, the component is disabled.",
-        "defaultValue": "false\nfalse"
-      },
-      "startIcon": {
-        "type": "ReactElement",
-        "isRequired": true,
-        "description": "Element placed before the children."
-      },
-      "size": {
-        "type": "\"small\" | \"medium\" | \"large\"",
-        "isRequired": false,
-        "description": "The size of the component.\n`small` is equivalent to the dense button styling.",
-        "defaultValue": "medium"
-      },
-      "sdsType": {
-        "type": "\"primary\" | \"secondary\" | \"destructive\"",
-        "isRequired": false
-      },
-      "sdsStyle": {
-        "type": "\"outline\" | \"solid\" | \"minimal\"",
-        "isRequired": false
-      },
-      "sdsStage": {
-        "type": "\"off\" | \"on\"",
-        "isRequired": false
-      }
-    }
-  }
-}

package/data/component-props/ButtonV2.json

@@ -1,43 +0,0 @@
-{
-  "ButtonV2": {
-    "props": {
-      "backgroundOnHover": {
-        "type": "\"false\" | \"true\"",
-        "isRequired": false
-      },
-      "children": {
-        "type": "ReactNode",
-        "isRequired": false,
-        "description": "The content of the component."
-      },
-      "endIcon": {
-        "type": "ReactNode",
-        "isRequired": false,
-        "description": "Element placed after the children."
-      },
-      "onClick": {
-        "type": "function",
-        "isRequired": false
-      },
-      "size": {
-        "type": "\"small\" | \"medium\" | \"large\"",
-        "isRequired": false,
-        "description": "The size of the component.\n`small` is equivalent to the dense button styling.",
-        "defaultValue": "medium"
-      },
-      "sdsStyle": {
-        "type": "\"outline\" | \"solid\" | \"minimal\"",
-        "isRequired": false
-      },
-      "sdsType": {
-        "type": "\"primary\" | \"secondary\" | \"destructive\"",
-        "isRequired": false
-      },
-      "startIcon": {
-        "type": "ReactNode",
-        "isRequired": false,
-        "description": "Element placed before the children."
-      }
-    }
-  }
-}