@vibescope/mcp-server 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibescope/mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "MCP server for Vibescope - AI project tracking tools",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,8 @@
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
+    "docs:generate": "npx tsx scripts/generate-docs.ts --output=docs/TOOLS.md",
+    "docs:preview": "npx tsx scripts/generate-docs.ts",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -34,6 +36,7 @@
   "license": "MIT",
   "devDependencies": {
     "@types/node": "^22.10.0",
+    "tsx": "^4.7.0",
     "typescript": "^5.7.0",
     "vitest": "^4.0.17"
   },

package/scripts/generate-docs.ts

@@ -0,0 +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);
+}