@docxkit/mcp 0.3.0

package/dist/index.js

@@ -0,0 +1,793 @@
+import { BUILTIN_TEMPLATES } from "@docxkit/ai";
+//#region src/resources/schema.ts
+/**
+* MCP resource: DocxSchema JSON Schema.
+*
+* Provides a complete JSON Schema for the DocxSchema type,
+* enabling LLMs to understand the expected document structure.
+*
+* @module mcp-server/resources/schema
+*/
+/**
+* DocxSchema JSON Schema for MCP resource exposure.
+*
+* This schema describes the expected structure of a
+* docx-kit document schema, suitable for LLM reference.
+*/
+const docxSchemaResource = {
+	mimeType: "application/json",
+	name: "docx-kit://schema",
+	description: "The complete docx-kit DocxSchema JSON Schema. Describes all node types, their required fields, and how they combine to form a document.",
+	schema: {
+		$id: "docx-kit://schema",
+		$schema: "http://json-schema.org/draft-07/schema#",
+		description: "A docx-kit document schema",
+		required: ["content"],
+		title: "DocxSchema",
+		type: "object",
+		definitions: {
+			blockNode: { oneOf: [
+				{
+					description: "A bullet list",
+					required: ["type", "items"],
+					type: "object",
+					properties: {
+						type: { const: "bulletList" },
+						items: {
+							items: { type: "string" },
+							type: "array"
+						}
+					}
+				},
+				{
+					description: "A heading (h1–h6)",
+					required: [
+						"type",
+						"level",
+						"text"
+					],
+					type: "object",
+					properties: {
+						className: { type: "string" },
+						level: {
+							enum: [
+								1,
+								2,
+								3,
+								4,
+								5,
+								6
+							],
+							type: "number"
+						},
+						style: {
+							additionalProperties: true,
+							type: "object"
+						},
+						text: { type: "string" },
+						type: { const: "heading" }
+					}
+				},
+				{
+					description: "A hyperlink",
+					required: [
+						"type",
+						"url",
+						"children"
+					],
+					type: "object",
+					properties: {
+						type: { const: "hyperlink" },
+						url: { type: "string" },
+						children: {
+							items: { type: "string" },
+							type: "array"
+						}
+					}
+				},
+				{
+					description: "An image",
+					required: ["type", "data"],
+					type: "object",
+					properties: {
+						alt: { type: "string" },
+						data: { type: "string" },
+						height: { type: "number" },
+						type: { const: "image" },
+						width: { type: "number" },
+						imageType: {
+							enum: [
+								"png",
+								"jpeg",
+								"jpg",
+								"gif",
+								"bmp"
+							],
+							type: "string"
+						}
+					}
+				},
+				{
+					description: "A numbered list",
+					required: ["type", "items"],
+					type: "object",
+					properties: {
+						type: { const: "numberedList" },
+						items: {
+							items: { type: "string" },
+							type: "array"
+						}
+					}
+				},
+				{
+					description: "A page break",
+					properties: { type: { const: "pageBreak" } },
+					required: ["type"],
+					type: "object"
+				},
+				{
+					description: "A paragraph of text",
+					required: ["type"],
+					type: "object",
+					properties: {
+						className: { type: "string" },
+						style: {
+							additionalProperties: true,
+							type: "object"
+						},
+						text: { type: "string" },
+						type: { const: "paragraph" },
+						children: {
+							items: {
+								additionalProperties: true,
+								type: "object"
+							},
+							type: "array"
+						}
+					}
+				},
+				{
+					description: "A plugin invocation",
+					required: [
+						"type",
+						"name",
+						"options"
+					],
+					type: "object",
+					properties: {
+						name: { type: "string" },
+						options: {
+							additionalProperties: true,
+							type: "object"
+						},
+						type: { const: "plugin" }
+					}
+				},
+				{
+					description: "A section break",
+					required: ["type"],
+					type: "object",
+					properties: {
+						config: {
+							additionalProperties: true,
+							type: "object"
+						},
+						type: { const: "sectionBreak" }
+					}
+				},
+				{
+					description: "A data table",
+					required: [
+						"type",
+						"columns",
+						"data"
+					],
+					type: "object",
+					properties: {
+						header: { type: "boolean" },
+						striped: { type: "boolean" },
+						type: { const: "table" },
+						columns: {
+							type: "array",
+							items: {
+								required: ["key", "title"],
+								type: "object",
+								properties: {
+									key: { type: "string" },
+									title: { type: "string" },
+									width: { type: "string" },
+									align: {
+										enum: [
+											"left",
+											"center",
+											"right"
+										],
+										type: "string"
+									}
+								}
+							}
+						},
+						data: {
+							items: {
+								additionalProperties: true,
+								type: "object"
+							},
+							type: "array"
+						}
+					}
+				}
+			] },
+			styleRule: {
+				additionalProperties: true,
+				description: "CSS-like style properties for a node",
+				type: "object",
+				properties: {
+					backgroundColor: { type: "string" },
+					borderBottom: { type: "string" },
+					borderLeft: { type: "string" },
+					borderRight: { type: "string" },
+					borderTop: { type: "string" },
+					color: { type: "string" },
+					fontFamily: { type: "string" },
+					fontSize: { type: "number" },
+					fontWeight: {
+						enum: [
+							"bold",
+							"normal",
+							"semibold"
+						],
+						type: "string"
+					},
+					lineHeight: { type: "number" },
+					marginBottom: { type: "number" },
+					marginLeft: { type: "number" },
+					marginTop: { type: "number" },
+					textAlign: {
+						enum: [
+							"center",
+							"justify",
+							"left",
+							"right"
+						],
+						type: "string"
+					}
+				}
+			}
+		},
+		properties: {
+			content: {
+				description: "Ordered array of block nodes",
+				items: { $ref: "#/definitions/blockNode" },
+				type: "array"
+			},
+			page: {
+				description: "Page configuration",
+				type: "object",
+				properties: {
+					margin: { type: "string" },
+					orientation: {
+						enum: ["landscape", "portrait"],
+						type: "string"
+					},
+					size: {
+						enum: [
+							"A3",
+							"A4",
+							"Legal",
+							"Letter"
+						],
+						type: "string"
+					}
+				}
+			},
+			plugins: {
+				description: "Plugin sources to load before rendering",
+				type: "array",
+				items: {
+					required: ["type"],
+					type: "object",
+					properties: {
+						plugin: {
+							description: "Inline plugin instance",
+							type: "object"
+						},
+						type: {
+							enum: [
+								"inline",
+								"npm",
+								"url",
+								"local"
+							],
+							type: "string"
+						}
+					}
+				}
+			},
+			styles: {
+				additionalProperties: { $ref: "#/definitions/styleRule" },
+				description: "Named stylesheet entries",
+				type: "object"
+			}
+		}
+	}
+};
+//#endregion
+//#region src/tools/applyTemplate.ts
+/**
+* MCP tool: generate a document from a template + data.
+*
+* @module mcp-server/tools/applyTemplate
+*/
+/**
+* MCP tool definition for `apply_template`.
+*
+* Generates a DocxSchema from a named template + data params.
+*/
+const applyTemplateToolDefinition = {
+	name: "apply_template",
+	description: "Generate a docx-kit document schema from an AI template and provided data parameters.",
+	inputSchema: {
+		required: ["template", "data"],
+		type: "object",
+		properties: {
+			data: {
+				description: "Template parameter values (must match template schema)",
+				type: "object"
+			},
+			template: {
+				type: "string",
+				description: "Name of the template to apply (report, invoice, resume, letter)"
+			}
+		}
+	}
+};
+/**
+* Apply a template with given data to produce a DocxSchema.
+*
+* @param templateName - — Template name (e.g. 'report')
+* @param data - — Template parameters
+* @returns Generated DocxSchema and template name, or null if template not found
+*/
+function applyTemplate(templateName, data) {
+	const template = BUILTIN_TEMPLATES.find((t) => t.name === templateName);
+	if (!template) return null;
+	return {
+		schema: template.generate(data),
+		templateName
+	};
+}
+//#endregion
+//#region src/tools/createDocx.ts
+/**
+* MCP tool definition for `create_document`.
+*
+* Creates a new .docx file from a docx-kit JSON schema.
+* Takes an `outputPath` and a `schema` (DocxSchema JSON object).
+*
+* @remarks Used by the MCP server as a tool registration.
+*/
+const createDocxToolDefinition = {
+	name: "create_document",
+	description: "Create a new .docx document from a docx-kit JSON schema. The schema defines content nodes, styles, and page configuration.",
+	inputSchema: {
+		required: ["schema", "outputPath"],
+		type: "object",
+		properties: {
+			outputPath: {
+				description: "File path for the output .docx file",
+				type: "string"
+			},
+			schema: {
+				type: "object",
+				description: "A docx-kit DocxSchema object with content, styles, and page config"
+			}
+		}
+	}
+};
+//#endregion
+//#region src/tools/getPluginHelp.ts
+/**
+* MCP tool definition for `get_plugin_help`.
+*
+* Returns usage help and option schema for a named plugin.
+*/
+const getPluginHelpToolDefinition = {
+	name: "get_plugin_help",
+	description: "Get usage help and option details for a specific docx-kit plugin.",
+	inputSchema: {
+		required: ["pluginName"],
+		type: "object",
+		properties: { pluginName: {
+			description: "The name of the plugin to get help for",
+			type: "string"
+		} }
+	}
+};
+/**
+* Build help info for a plugin.
+*
+* Provides a usage example based on the plugin name,
+* referencing a built-in map of known plugins.
+*
+* @param plugin - — The DocxPlugin to build help for
+* @returns PluginHelpInfo with description, name, and usage example
+*/
+function buildPluginHelp(plugin) {
+	return {
+		description: `Built-in docx-kit plugin: ${plugin.name}. Renders ${plugin.name} content in the document.`,
+		name: plugin.name,
+		usageExample: {
+			pageNumber: "{ type: \"plugin\", name: \"pageNumber\", options: {} }",
+			callout: "{ type: \"plugin\", name: \"callout\", options: { title: \"Note\", variant: \"info\", text: \"Important message\" } }",
+			codeBlock: "{ type: \"plugin\", name: \"codeBlock\", options: { code: \"console.log('hello')\", language: \"javascript\" } }",
+			coverPage: "{ type: \"plugin\", name: \"coverPage\", options: { title: \"Annual Report\", author: \"John Doe\", date: \"2026-06-12\" } }",
+			dataTable: "{ type: \"plugin\", name: \"dataTable\", options: { columns: [...], data: [...], striped: true } }",
+			echarts: "{ type: \"plugin\", name: \"echarts\", options: { option: { ...echarts config... }, width: 400, height: 300 } }",
+			meetingMinutes: "{ type: \"plugin\", name: \"meetingMinutes\", options: { title: \"Team Meeting\", date: \"2026-06-12\", attendees: [\"Alice\", \"Bob\"] } }",
+			propertyTable: "{ type: \"plugin\", name: \"propertyTable\", options: { items: [{ key: \"Name\", value: \"Alice\" }] } }",
+			qrcode: "{ type: \"plugin\", name: \"qrcode\", options: { text: \"https://example.com\", width: 100 } }",
+			signatureBlock: "{ type: \"plugin\", name: \"signatureBlock\", options: { parties: [{ name: \"Alice\", role: \"Manager\" }] } }",
+			timeline: "{ type: \"plugin\", name: \"timeline\", options: { events: [{ date: \"2026-01\", title: \"Kickoff\" }] } }",
+			watermark: "{ type: \"plugin\", name: \"watermark\", options: { text: \"CONFIDENTIAL\", opacity: 0.3 } }"
+		}[plugin.name] ?? `{ type: "plugin", name: "${plugin.name}", options: { ... } }`
+	};
+}
+//#endregion
+//#region src/tools/listPlugins.ts
+/**
+* MCP tool definition for `list_plugins`.
+*
+* Returns metadata for all registered plugins.
+*/
+const listPluginsToolDefinition = {
+	name: "list_plugins",
+	description: "List all available docx-kit plugins with their names and descriptions.",
+	inputSchema: {
+		type: "object",
+		properties: { filter: {
+			description: "Optional name filter pattern",
+			type: "string"
+		} }
+	}
+};
+/**
+* Build plugin info from a list of DocxPlugin instances.
+*
+* Optionally filters by a case-insensitive name substring.
+*
+* @param plugins - — Registered plugins
+* @param filter - — Optional name filter pattern (case-insensitive)
+* @returns Array of PluginInfo objects
+*/
+function buildPluginInfoList(plugins, filter) {
+	const allInfo = plugins.map((p) => ({
+		description: `Built-in docx-kit plugin: ${p.name}`,
+		name: p.name
+	}));
+	if (filter) return allInfo.filter((p) => p.name.toLowerCase().includes(filter.toLowerCase()));
+	return allInfo;
+}
+//#endregion
+//#region src/tools/listTemplates.ts
+/**
+* MCP tool: list and apply AI templates.
+*
+* @module mcp-server/tools/listTemplates
+*/
+/**
+* MCP tool definition for `list_templates`.
+*
+* Returns all available docx-kit AI templates.
+*/
+const listTemplatesToolDefinition = {
+	name: "list_templates",
+	description: "List all available docx-kit AI templates for document generation.",
+	inputSchema: {
+		properties: {},
+		type: "object"
+	}
+};
+/**
+* Build template info list from built-in templates.
+*
+* @returns Array of template info (without generator)
+*/
+function buildTemplateInfoList() {
+	return BUILTIN_TEMPLATES.map((t) => ({
+		description: t.description,
+		name: t.name,
+		schema: t.schema,
+		systemPrompt: t.systemPrompt
+	}));
+}
+//#endregion
+//#region src/tools/validateSchema.ts
+/**
+* MCP tool definition for `validate_schema`.
+*
+* Validates a docx-kit JSON schema and returns
+* detailed error information.
+*/
+const validateSchemaToolDefinition = {
+	name: "validate_schema",
+	description: "Validate a docx-kit JSON schema. Checks node types, required fields, and structural correctness.",
+	inputSchema: {
+		required: ["schema"],
+		type: "object",
+		properties: { schema: {
+			description: "The DocxSchema JSON object to validate",
+			type: "object"
+		} }
+	}
+};
+/**
+* Validate a DocxSchema object.
+*
+* Checks for:
+* - Required `content` array
+* - Valid node types in content
+* - Required fields per node type
+*
+* @param schema - — The schema to validate
+* @returns Validation result with errors
+*/
+function validateSchema(schema) {
+	const errors = [];
+	const content = schema?.content;
+	if (!content) errors.push({
+		message: "Required field \"content\" is missing",
+		path: "/content"
+	});
+	else if (Array.isArray(content)) {
+		const validNodeTypes = new Set([
+			"bulletList",
+			"heading",
+			"hyperlink",
+			"image",
+			"numberedList",
+			"pageBreak",
+			"paragraph",
+			"plugin",
+			"sectionBreak",
+			"table"
+		]);
+		for (const [i, element] of content.entries()) {
+			const node = element;
+			if (typeof node !== "object" || node === null) {
+				errors.push({
+					message: `Node at index ${i} must be an object`,
+					path: `/content/${i}`
+				});
+				continue;
+			}
+			const nodeType = node.type;
+			if (!nodeType) {
+				errors.push({
+					message: `Node at index ${i} missing required "type" field`,
+					path: `/content/${i}/type`
+				});
+				continue;
+			}
+			if (!validNodeTypes.has(nodeType)) errors.push({
+				message: `Invalid node type "${nodeType}" at index ${i}`,
+				path: `/content/${i}/type`
+			});
+			if (nodeType === "heading" && !node.text) errors.push({
+				message: `Heading node at index ${i} missing required "text" field`,
+				path: `/content/${i}/text`
+			});
+			if (nodeType === "heading" && !node.level) errors.push({
+				message: `Heading node at index ${i} missing required "level" field`,
+				path: `/content/${i}/level`
+			});
+			if (nodeType === "paragraph" && !node.text && !node.children) errors.push({
+				message: `Paragraph node at index ${i} must have "text" or "children"`,
+				path: `/content/${i}`
+			});
+			if (nodeType === "plugin" && !node.name) errors.push({
+				message: `Plugin node at index ${i} missing required "name" field`,
+				path: `/content/${i}/name`
+			});
+			if (nodeType === "table" && !node.columns) errors.push({
+				message: `Table node at index ${i} missing required "columns" field`,
+				path: `/content/${i}/columns`
+			});
+			if (nodeType === "table" && !node.data) errors.push({
+				message: `Table node at index ${i} missing required "data" field`,
+				path: `/content/${i}/data`
+			});
+		}
+	} else errors.push({
+		message: "Field \"content\" must be an array",
+		path: "/content"
+	});
+	return {
+		errors,
+		valid: errors.length === 0
+	};
+}
+//#endregion
+//#region src/index.ts
+/**
+* docx-kit MCP server — AI agent integration via
+* Model Context Protocol.
+*
+* Provides tools for document creation, validation,
+* plugin discovery, template application, and schema resources.
+*
+* The server uses `@modelcontextprotocol/sdk` (optional peer dep)
+* for MCP protocol handling. If the SDK is not installed,
+* individual tool/resource definitions and execution logic
+* can still be used programmatically.
+*
+* @module mcp-server
+*/
+/**
+* All MCP tool definitions for docx-kit.
+*/
+const TOOL_DEFINITIONS = [
+	applyTemplateToolDefinition,
+	createDocxToolDefinition,
+	getPluginHelpToolDefinition,
+	listPluginsToolDefinition,
+	listTemplatesToolDefinition,
+	validateSchemaToolDefinition
+];
+/**
+* All MCP resource definitions for docx-kit.
+*/
+const RESOURCE_DEFINITIONS = [docxSchemaResource];
+/**
+* Create a docx-kit MCP server.
+*
+* Uses `@modelcontextprotocol/sdk` to create a fully compliant
+* MCP server with all docx-kit tools and resources registered.
+*
+* Requires `@modelcontextprotocol/sdk` to be installed.
+* Connect via `StdioServerTransport` for CLI usage or
+* `StreamableHTTPServerTransport` for HTTP access.
+*
+* @returns An MCP server instance ready to connect
+*
+* @example
+* ```ts
+* import { createDocxKitServer } from 'docx-kit/mcp'
+* import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+*
+* const server = createDocxKitServer()
+* const transport = new StdioServerTransport()
+* await server.connect(transport)
+* ```
+*/
+async function createDocxKitServer() {
+	const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+	const { z } = await import("zod");
+	const server = new McpServer({
+		name: "docx-kit",
+		version: "0.2.0"
+	});
+	server.registerTool("create_document", {
+		description: "Create a new .docx document from a docx-kit JSON schema",
+		inputSchema: {
+			outputPath: z.string().describe("File path for the output .docx file"),
+			schema: z.record(z.string(), z.unknown()).describe("A docx-kit DocxSchema JSON object")
+		}
+	}, async (input) => {
+		const docSchema = input.schema;
+		const validation = validateSchema(docSchema);
+		if (!validation.valid) return {
+			isError: true,
+			content: [{
+				text: `Schema validation failed:\n${validation.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`,
+				type: "text"
+			}]
+		};
+		return { content: [{
+			text: `Document schema is valid. Use renderDocx() to generate the document and save to: ${input.outputPath}`,
+			type: "text"
+		}] };
+	});
+	server.registerTool("validate_schema", {
+		description: "Validate a docx-kit JSON schema for correctness",
+		inputSchema: { schema: z.record(z.string(), z.unknown()).describe("The DocxSchema JSON object to validate") }
+	}, async (input) => {
+		const result = validateSchema(input.schema);
+		return { content: [{
+			type: "text",
+			text: result.valid ? "Schema is valid ✓" : `Validation errors:\n${result.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n")}`
+		}] };
+	});
+	server.registerTool("list_plugins", {
+		description: "List all available docx-kit plugins",
+		inputSchema: { filter: z.string().optional().describe("Optional name filter pattern") }
+	}, async (input) => {
+		const infoList = [
+			"callout",
+			"codeBlock",
+			"coverPage",
+			"dataTable",
+			"echarts",
+			"meetingMinutes",
+			"pageNumber",
+			"propertyTable",
+			"qrcode",
+			"signatureBlock",
+			"timeline",
+			"watermark"
+		].map((name) => ({
+			description: `Built-in docx-kit plugin: ${name}`,
+			name
+		}));
+		const filtered = input.filter ? infoList.filter((p) => p.name.toLowerCase().includes(input.filter.toLowerCase())) : infoList;
+		return { content: [{
+			text: JSON.stringify(filtered, null, 2),
+			type: "text"
+		}] };
+	});
+	server.registerTool("get_plugin_help", {
+		description: "Get usage help for a specific docx-kit plugin",
+		inputSchema: { pluginName: z.string().describe("The plugin name") }
+	}, async (input) => {
+		const helpInfo = {
+			description: `Built-in docx-kit plugin: ${input.pluginName}`,
+			name: input.pluginName,
+			usageExample: `{ type: "plugin", name: "${input.pluginName}", options: { ... } }`
+		};
+		const usageExamples = {
+			pageNumber: "{ type: \"plugin\", name: \"pageNumber\", options: {} }",
+			callout: "{ type: \"plugin\", name: \"callout\", options: { title: \"Note\", variant: \"info\", text: \"Important message\" } }",
+			codeBlock: "{ type: \"plugin\", name: \"codeBlock\", options: { code: \"console.log('hello')\", language: \"javascript\" } }",
+			coverPage: "{ type: \"plugin\", name: \"coverPage\", options: { title: \"Annual Report\", author: \"John Doe\", date: \"2026-06-12\" } }",
+			dataTable: "{ type: \"plugin\", name: \"dataTable\", options: { columns: [...], data: [...], striped: true } }",
+			echarts: "{ type: \"plugin\", name: \"echarts\", options: { option: { ...echarts config... }, width: 400, height: 300 } }",
+			meetingMinutes: "{ type: \"plugin\", name: \"meetingMinutes\", options: { title: \"Team Meeting\", date: \"2026-06-12\", attendees: [\"Alice\", \"Bob\"] } }",
+			propertyTable: "{ type: \"plugin\", name: \"propertyTable\", options: { items: [{ key: \"Name\", value: \"Alice\" }] } }",
+			qrcode: "{ type: \"plugin\", name: \"qrcode\", options: { text: \"https://example.com\", width: 100 } }",
+			signatureBlock: "{ type: \"plugin\", name: \"signatureBlock\", options: { parties: [{ name: \"Alice\", role: \"Manager\" }] } }",
+			timeline: "{ type: \"plugin\", name: \"timeline\", options: { events: [{ date: \"2026-01\", title: \"Kickoff\" }] } }",
+			watermark: "{ type: \"plugin\", name: \"watermark\", options: { text: \"CONFIDENTIAL\", opacity: 0.3 } }"
+		};
+		if (usageExamples[input.pluginName]) helpInfo.usageExample = usageExamples[input.pluginName];
+		return { content: [{
+			text: JSON.stringify(helpInfo, null, 2),
+			type: "text"
+		}] };
+	});
+	server.registerTool("list_templates", { description: "List all available docx-kit AI templates" }, async () => {
+		const templates = buildTemplateInfoList();
+		return { content: [{
+			text: JSON.stringify(templates, null, 2),
+			type: "text"
+		}] };
+	});
+	server.registerTool("apply_template", {
+		description: "Generate a document schema from an AI template + data",
+		inputSchema: {
+			data: z.record(z.string(), z.unknown()).describe("Template parameter values"),
+			template: z.string().describe("Template name (report, invoice, resume, letter)")
+		}
+	}, async (input) => {
+		const result = applyTemplate(input.template, input.data);
+		if (!result) return {
+			isError: true,
+			content: [{
+				text: `Template "${input.template}" not found. Available: report, invoice, resume, letter`,
+				type: "text"
+			}]
+		};
+		return { content: [{
+			text: JSON.stringify(result.schema, null, 2),
+			type: "text"
+		}] };
+	});
+	server.registerResource("docx-kit-schema", "docx-kit://schema", {}, async (uri) => {
+		return { contents: [{
+			mimeType: "application/json",
+			text: JSON.stringify(docxSchemaResource.schema, null, 2),
+			uri: uri.href
+		}] };
+	});
+	return server;
+}
+//#endregion
+export { RESOURCE_DEFINITIONS, TOOL_DEFINITIONS, applyTemplate, applyTemplateToolDefinition, buildPluginHelp, buildPluginInfoList, buildTemplateInfoList, createDocxKitServer, createDocxToolDefinition, docxSchemaResource, getPluginHelpToolDefinition, listPluginsToolDefinition, listTemplatesToolDefinition, validateSchema, validateSchemaToolDefinition };