@vibescope/mcp-server 0.2.5 → 0.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",
@@ -46,6 +46,7 @@
     "vitest": "^4.0.17"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.2"
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "zod": "^3.25.0"
   }
 }

package/scripts/generate-docs.ts

@@ -1,212 +1,212 @@
-#!/usr/bin/env npx tsx
-/**
- * MCP Tools Documentation Generator
- *
- * Generates markdown documentation from the MCP tool definitions.
- * Run: npx tsx scripts/generate-docs.ts > docs/TOOLS.md
- *
- * Or use the npm script:
- * npm run docs:generate
- */
-
-import { tools } from '../src/tools.js';
-import { TOOL_CATEGORIES } from '../src/handlers/discovery.js';
-import * as fs from 'fs';
-import * as path from 'path';
-
-interface PropertySchema {
-	type?: string;
-	description?: string;
-	enum?: string[];
-	minimum?: number;
-	maximum?: number;
-	default?: unknown;
-	items?: { type?: string };
-}
-
-interface InputSchema {
-	type: string;
-	properties?: Record<string, PropertySchema>;
-	required?: string[];
-}
-
-interface Tool {
-	name: string;
-	description: string;
-	inputSchema: InputSchema;
-}
-
-/**
- * Format a parameter type for documentation
- */
-function formatType(prop: PropertySchema): string {
-	if (prop.enum) {
-		return prop.enum.map((v) => `"${v}"`).join(' | ');
-	}
-	if (prop.type === 'array' && prop.items?.type) {
-		return `${prop.items.type}[]`;
-	}
-	return prop.type || 'unknown';
-}
-
-/**
- * Format parameter constraints (min, max, default)
- */
-function formatConstraints(prop: PropertySchema): string[] {
-	const constraints: string[] = [];
-	if (prop.minimum !== undefined) constraints.push(`min: ${prop.minimum}`);
-	if (prop.maximum !== undefined) constraints.push(`max: ${prop.maximum}`);
-	if (prop.default !== undefined) constraints.push(`default: ${JSON.stringify(prop.default)}`);
-	return constraints;
-}
-
-/**
- * Generate documentation for a single tool
- */
-function generateToolDoc(tool: Tool): string {
-	const lines: string[] = [];
-	const schema = tool.inputSchema;
-
-	lines.push(`### ${tool.name}`);
-	lines.push('');
-
-	// Description (clean up multi-line descriptions)
-	const description = tool.description.trim().replace(/\n+/g, '\n\n');
-	lines.push(description);
-	lines.push('');
-
-	// Parameters
-	const properties = schema.properties || {};
-	const required = new Set(schema.required || []);
-	const paramNames = Object.keys(properties);
-
-	if (paramNames.length === 0) {
-		lines.push('**Parameters:** None');
-	} else {
-		lines.push('**Parameters:**');
-		lines.push('');
-		lines.push('| Parameter | Type | Required | Description |');
-		lines.push('|-----------|------|----------|-------------|');
-
-		for (const name of paramNames) {
-			const prop = properties[name];
-			const type = formatType(prop);
-			const isRequired = required.has(name);
-			const constraints = formatConstraints(prop);
-
-			let desc = prop.description || '';
-			if (constraints.length > 0) {
-				desc += desc ? ` (${constraints.join(', ')})` : `(${constraints.join(', ')})`;
-			}
-			// Escape pipe characters in description for table
-			desc = desc.replace(/\|/g, '\\|');
-
-			lines.push(`| \`${name}\` | \`${type}\` | ${isRequired ? 'Yes' : 'No'} | ${desc} |`);
-		}
-	}
-
-	lines.push('');
-	return lines.join('\n');
-}
-
-/**
- * Generate the full documentation
- */
-function generateDocumentation(): string {
-	const lines: string[] = [];
-
-	// Header
-	lines.push('# Vibescope MCP Tools Reference');
-	lines.push('');
-	lines.push('> Auto-generated from tool definitions. Do not edit manually.');
-	lines.push('>');
-	lines.push(`> Generated: ${new Date().toISOString().split('T')[0]}`);
-	lines.push('>');
-	lines.push(`> Total tools: ${tools.length}`);
-	lines.push('');
-
-	// Build tool lookup by name
-	const toolsByName = new Map<string, Tool>();
-	for (const tool of tools as Tool[]) {
-		toolsByName.set(tool.name, tool);
-	}
-
-	// Table of Contents
-	lines.push('## Table of Contents');
-	lines.push('');
-	for (const [categoryName, category] of Object.entries(TOOL_CATEGORIES)) {
-		const anchor = categoryName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
-		lines.push(`- [${categoryName}](#${anchor}) - ${category.description} (${category.tools.length} tools)`);
-	}
-	lines.push('');
-
-	// Generate documentation by category
-	for (const [categoryName, category] of Object.entries(TOOL_CATEGORIES)) {
-		lines.push(`## ${categoryName}`);
-		lines.push('');
-		lines.push(`*${category.description}*`);
-		lines.push('');
-
-		for (const toolRef of category.tools) {
-			const tool = toolsByName.get(toolRef.name);
-			if (tool) {
-				lines.push(generateToolDoc(tool));
-				lines.push('---');
-				lines.push('');
-			} else {
-				lines.push(`### ${toolRef.name}`);
-				lines.push('');
-				lines.push(`*Tool not found in definitions*`);
-				lines.push('');
-				lines.push('---');
-				lines.push('');
-			}
-		}
-	}
-
-	// Tools not in any category
-	const categorizedTools = new Set<string>();
-	for (const category of Object.values(TOOL_CATEGORIES)) {
-		for (const tool of category.tools) {
-			categorizedTools.add(tool.name);
-		}
-	}
-
-	const uncategorizedTools = (tools as Tool[]).filter((t) => !categorizedTools.has(t.name));
-	if (uncategorizedTools.length > 0) {
-		lines.push('## Uncategorized');
-		lines.push('');
-		lines.push('*Tools not yet assigned to a category*');
-		lines.push('');
-
-		for (const tool of uncategorizedTools) {
-			lines.push(generateToolDoc(tool));
-			lines.push('---');
-			lines.push('');
-		}
-	}
-
-	return lines.join('\n');
-}
-
-// Main execution
-const output = generateDocumentation();
-
-// Check if --output flag is provided
-const outputArg = process.argv.find((arg) => arg.startsWith('--output='));
-if (outputArg) {
-	const outputPath = outputArg.split('=')[1];
-	const fullPath = path.resolve(process.cwd(), outputPath);
-	const dir = path.dirname(fullPath);
-
-	// Ensure directory exists
-	if (!fs.existsSync(dir)) {
-		fs.mkdirSync(dir, { recursive: true });
-	}
-
-	fs.writeFileSync(fullPath, output, 'utf-8');
-	console.error(`Documentation written to: ${fullPath}`);
-} else {
-	// Output to stdout
-	console.log(output);
-}
+#!/usr/bin/env npx tsx
+/**
+ * MCP Tools Documentation Generator
+ *
+ * Generates markdown documentation from the MCP tool definitions.
+ * Run: npx tsx scripts/generate-docs.ts > docs/TOOLS.md
+ *
+ * Or use the npm script:
+ * npm run docs:generate
+ */
+
+import { tools } from '../src/tools.js';
+import { TOOL_CATEGORIES } from '../src/handlers/discovery.js';
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface PropertySchema {
+	type?: string;
+	description?: string;
+	enum?: string[];
+	minimum?: number;
+	maximum?: number;
+	default?: unknown;
+	items?: { type?: string };
+}
+
+interface InputSchema {
+	type: string;
+	properties?: Record<string, PropertySchema>;
+	required?: string[];
+}
+
+interface Tool {
+	name: string;
+	description: string;
+	inputSchema: InputSchema;
+}
+
+/**
+ * Format a parameter type for documentation
+ */
+function formatType(prop: PropertySchema): string {
+	if (prop.enum) {
+		return prop.enum.map((v) => `"${v}"`).join(' | ');
+	}
+	if (prop.type === 'array' && prop.items?.type) {
+		return `${prop.items.type}[]`;
+	}
+	return prop.type || 'unknown';
+}
+
+/**
+ * Format parameter constraints (min, max, default)
+ */
+function formatConstraints(prop: PropertySchema): string[] {
+	const constraints: string[] = [];
+	if (prop.minimum !== undefined) constraints.push(`min: ${prop.minimum}`);
+	if (prop.maximum !== undefined) constraints.push(`max: ${prop.maximum}`);
+	if (prop.default !== undefined) constraints.push(`default: ${JSON.stringify(prop.default)}`);
+	return constraints;
+}
+
+/**
+ * Generate documentation for a single tool
+ */
+function generateToolDoc(tool: Tool): string {
+	const lines: string[] = [];
+	const schema = tool.inputSchema;
+
+	lines.push(`### ${tool.name}`);
+	lines.push('');
+
+	// Description (clean up multi-line descriptions)
+	const description = tool.description.trim().replace(/\n+/g, '\n\n');
+	lines.push(description);
+	lines.push('');
+
+	// Parameters
+	const properties = schema.properties || {};
+	const required = new Set(schema.required || []);
+	const paramNames = Object.keys(properties);
+
+	if (paramNames.length === 0) {
+		lines.push('**Parameters:** None');
+	} else {
+		lines.push('**Parameters:**');
+		lines.push('');
+		lines.push('| Parameter | Type | Required | Description |');
+		lines.push('|-----------|------|----------|-------------|');
+
+		for (const name of paramNames) {
+			const prop = properties[name];
+			const type = formatType(prop);
+			const isRequired = required.has(name);
+			const constraints = formatConstraints(prop);
+
+			let desc = prop.description || '';
+			if (constraints.length > 0) {
+				desc += desc ? ` (${constraints.join(', ')})` : `(${constraints.join(', ')})`;
+			}
+			// Escape pipe characters in description for table
+			desc = desc.replace(/\|/g, '\\|');
+
+			lines.push(`| \`${name}\` | \`${type}\` | ${isRequired ? 'Yes' : 'No'} | ${desc} |`);
+		}
+	}
+
+	lines.push('');
+	return lines.join('\n');
+}
+
+/**
+ * Generate the full documentation
+ */
+function generateDocumentation(): string {
+	const lines: string[] = [];
+
+	// Header
+	lines.push('# Vibescope MCP Tools Reference');
+	lines.push('');
+	lines.push('> Auto-generated from tool definitions. Do not edit manually.');
+	lines.push('>');
+	lines.push(`> Generated: ${new Date().toISOString().split('T')[0]}`);
+	lines.push('>');
+	lines.push(`> Total tools: ${tools.length}`);
+	lines.push('');
+
+	// Build tool lookup by name
+	const toolsByName = new Map<string, Tool>();
+	for (const tool of tools as Tool[]) {
+		toolsByName.set(tool.name, tool);
+	}
+
+	// Table of Contents
+	lines.push('## Table of Contents');
+	lines.push('');
+	for (const [categoryName, category] of Object.entries(TOOL_CATEGORIES)) {
+		const anchor = categoryName.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+		lines.push(`- [${categoryName}](#${anchor}) - ${category.description} (${category.tools.length} tools)`);
+	}
+	lines.push('');
+
+	// Generate documentation by category
+	for (const [categoryName, category] of Object.entries(TOOL_CATEGORIES)) {
+		lines.push(`## ${categoryName}`);
+		lines.push('');
+		lines.push(`*${category.description}*`);
+		lines.push('');
+
+		for (const toolRef of category.tools) {
+			const tool = toolsByName.get(toolRef.name);
+			if (tool) {
+				lines.push(generateToolDoc(tool));
+				lines.push('---');
+				lines.push('');
+			} else {
+				lines.push(`### ${toolRef.name}`);
+				lines.push('');
+				lines.push(`*Tool not found in definitions*`);
+				lines.push('');
+				lines.push('---');
+				lines.push('');
+			}
+		}
+	}
+
+	// Tools not in any category
+	const categorizedTools = new Set<string>();
+	for (const category of Object.values(TOOL_CATEGORIES)) {
+		for (const tool of category.tools) {
+			categorizedTools.add(tool.name);
+		}
+	}
+
+	const uncategorizedTools = (tools as Tool[]).filter((t) => !categorizedTools.has(t.name));
+	if (uncategorizedTools.length > 0) {
+		lines.push('## Uncategorized');
+		lines.push('');
+		lines.push('*Tools not yet assigned to a category*');
+		lines.push('');
+
+		for (const tool of uncategorizedTools) {
+			lines.push(generateToolDoc(tool));
+			lines.push('---');
+			lines.push('');
+		}
+	}
+
+	return lines.join('\n');
+}
+
+// Main execution
+const output = generateDocumentation();
+
+// Check if --output flag is provided
+const outputArg = process.argv.find((arg) => arg.startsWith('--output='));
+if (outputArg) {
+	const outputPath = outputArg.split('=')[1];
+	const fullPath = path.resolve(process.cwd(), outputPath);
+	const dir = path.dirname(fullPath);
+
+	// Ensure directory exists
+	if (!fs.existsSync(dir)) {
+		fs.mkdirSync(dir, { recursive: true });
+	}
+
+	fs.writeFileSync(fullPath, output, 'utf-8');
+	console.error(`Documentation written to: ${fullPath}`);
+} else {
+	// Output to stdout
+	console.log(output);
+}