@vibescope/mcp-server 0.2.9 → 0.3.1

package/src/tools.test.ts

@@ -0,0 +1,416 @@
+/**
+ * Tests for MCP Tool Schema Definitions
+ *
+ * Validates that all tool schemas are correctly defined with required fields,
+ * proper types, and no duplicates. These tests ensure the MCP API contract
+ * remains valid and consistent.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { tools } from './tools.js';
+
+// Valid JSON Schema types
+const VALID_SCHEMA_TYPES = ['string', 'number', 'boolean', 'object', 'array', 'null', 'integer'];
+
+describe('MCP Tool Definitions', () => {
+	// ============================================================================
+	// Basic Structure Tests
+	// ============================================================================
+
+	describe('basic structure', () => {
+		it('should export a non-empty array of tools', () => {
+			expect(Array.isArray(tools)).toBe(true);
+			expect(tools.length).toBeGreaterThan(0);
+		});
+
+		it('should have at least 100 tools defined', () => {
+			// Sanity check - we know there are ~150 tools
+			expect(tools.length).toBeGreaterThanOrEqual(100);
+		});
+	});
+
+	// ============================================================================
+	// Required Fields Tests
+	// ============================================================================
+
+	describe('required fields', () => {
+		it('all tools should have a name', () => {
+			tools.forEach((tool, index) => {
+				expect(tool.name, `Tool at index ${index} missing name`).toBeDefined();
+				expect(typeof tool.name, `Tool at index ${index} name should be string`).toBe('string');
+				expect(tool.name.length, `Tool at index ${index} name should not be empty`).toBeGreaterThan(0);
+			});
+		});
+
+		it('all tools should have a description', () => {
+			tools.forEach((tool) => {
+				expect(tool.description, `Tool "${tool.name}" missing description`).toBeDefined();
+				expect(typeof tool.description, `Tool "${tool.name}" description should be string`).toBe('string');
+				expect(tool.description.length, `Tool "${tool.name}" description should not be empty`).toBeGreaterThan(0);
+			});
+		});
+
+		it('all tools should have an inputSchema', () => {
+			tools.forEach((tool) => {
+				expect(tool.inputSchema, `Tool "${tool.name}" missing inputSchema`).toBeDefined();
+				expect(typeof tool.inputSchema, `Tool "${tool.name}" inputSchema should be object`).toBe('object');
+			});
+		});
+
+		it('all inputSchemas should have type "object"', () => {
+			tools.forEach((tool) => {
+				expect(
+					tool.inputSchema.type,
+					`Tool "${tool.name}" inputSchema.type should be "object"`
+				).toBe('object');
+			});
+		});
+
+		it('all inputSchemas should have properties object', () => {
+			tools.forEach((tool) => {
+				expect(
+					tool.inputSchema.properties,
+					`Tool "${tool.name}" inputSchema missing properties`
+				).toBeDefined();
+				expect(
+					typeof tool.inputSchema.properties,
+					`Tool "${tool.name}" inputSchema.properties should be object`
+				).toBe('object');
+			});
+		});
+	});
+
+	// ============================================================================
+	// Uniqueness Tests
+	// ============================================================================
+
+	describe('uniqueness', () => {
+		it('all tool names should be unique', () => {
+			const names = tools.map((t) => t.name);
+			const uniqueNames = new Set(names);
+
+			if (names.length !== uniqueNames.size) {
+				// Find duplicates for better error message
+				const counts = new Map<string, number>();
+				names.forEach((name) => {
+					counts.set(name, (counts.get(name) ?? 0) + 1);
+				});
+				const duplicates = [...counts.entries()].filter(([, count]) => count > 1);
+				throw new Error(`Duplicate tool names found: ${duplicates.map(([name]) => name).join(', ')}`);
+			}
+
+			expect(names.length).toBe(uniqueNames.size);
+		});
+
+		it('tool names should follow snake_case convention', () => {
+			const snakeCaseRegex = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+
+			tools.forEach((tool) => {
+				expect(
+					snakeCaseRegex.test(tool.name),
+					`Tool name "${tool.name}" should be snake_case`
+				).toBe(true);
+			});
+		});
+	});
+
+	// ============================================================================
+	// Property Schema Tests
+	// ============================================================================
+
+	describe('property schemas', () => {
+		it('all properties should have valid types', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, { type?: string | string[] }>;
+
+				Object.entries(properties).forEach(([propName, propSchema]) => {
+					if (propSchema.type) {
+						const types = Array.isArray(propSchema.type) ? propSchema.type : [propSchema.type];
+						types.forEach((type) => {
+							expect(
+								VALID_SCHEMA_TYPES.includes(type),
+								`Tool "${tool.name}" property "${propName}" has invalid type "${type}"`
+							).toBe(true);
+						});
+					}
+				});
+			});
+		});
+
+		it('all properties should have descriptions', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, { description?: string }>;
+
+				Object.entries(properties).forEach(([propName, propSchema]) => {
+					expect(
+						propSchema.description,
+						`Tool "${tool.name}" property "${propName}" missing description`
+					).toBeDefined();
+					expect(
+						typeof propSchema.description,
+						`Tool "${tool.name}" property "${propName}" description should be string`
+					).toBe('string');
+				});
+			});
+		});
+
+		it('required fields should exist in properties', () => {
+			tools.forEach((tool) => {
+				const required = tool.inputSchema.required as string[] | undefined;
+				const properties = tool.inputSchema.properties as Record<string, unknown>;
+
+				if (required) {
+					required.forEach((fieldName) => {
+						expect(
+							properties[fieldName],
+							`Tool "${tool.name}" has required field "${fieldName}" not defined in properties`
+						).toBeDefined();
+					});
+				}
+			});
+		});
+
+		it('enum properties should have valid enum arrays', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, { enum?: unknown[] }>;
+
+				Object.entries(properties).forEach(([propName, propSchema]) => {
+					if (propSchema.enum !== undefined) {
+						expect(
+							Array.isArray(propSchema.enum),
+							`Tool "${tool.name}" property "${propName}" enum should be array`
+						).toBe(true);
+						expect(
+							propSchema.enum.length,
+							`Tool "${tool.name}" property "${propName}" enum should not be empty`
+						).toBeGreaterThan(0);
+					}
+				});
+			});
+		});
+
+		it('numeric constraints should be valid', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, {
+					minimum?: number;
+					maximum?: number;
+					type?: string;
+				}>;
+
+				Object.entries(properties).forEach(([propName, propSchema]) => {
+					if (propSchema.minimum !== undefined && propSchema.maximum !== undefined) {
+						expect(
+							propSchema.minimum <= propSchema.maximum,
+							`Tool "${tool.name}" property "${propName}" minimum (${propSchema.minimum}) should not exceed maximum (${propSchema.maximum})`
+						).toBe(true);
+					}
+				});
+			});
+		});
+	});
+
+	// ============================================================================
+	// Specific Tool Existence Tests
+	// ============================================================================
+
+	describe('critical tools exist', () => {
+		const criticalTools = [
+			'start_work_session',
+			'get_next_task',
+			'add_task',
+			'update_task',
+			'complete_task',
+			'get_project_context',
+			'create_project',
+			'update_project',
+			'add_blocker',
+			'resolve_blocker',
+			'log_progress',
+			'validate_task',
+			'heartbeat',
+			'end_work_session',
+		];
+
+		criticalTools.forEach((toolName) => {
+			it(`should have "${toolName}" tool defined`, () => {
+				const tool = tools.find((t) => t.name === toolName);
+				expect(tool, `Critical tool "${toolName}" not found`).toBeDefined();
+			});
+		});
+	});
+
+	// ============================================================================
+	// Tool Categories Tests
+	// ============================================================================
+
+	describe('tool categories', () => {
+		it('should have session management tools', () => {
+			const sessionTools = tools.filter((t) =>
+				t.name.includes('session') || t.name === 'heartbeat'
+			);
+			expect(sessionTools.length).toBeGreaterThanOrEqual(3);
+		});
+
+		it('should have task management tools', () => {
+			const taskTools = tools.filter((t) => t.name.includes('task'));
+			expect(taskTools.length).toBeGreaterThanOrEqual(5);
+		});
+
+		it('should have project management tools', () => {
+			const projectTools = tools.filter((t) => t.name.includes('project'));
+			expect(projectTools.length).toBeGreaterThanOrEqual(3);
+		});
+
+		it('should have blocker management tools', () => {
+			const blockerTools = tools.filter((t) => t.name.includes('blocker'));
+			expect(blockerTools.length).toBeGreaterThanOrEqual(3);
+		});
+
+		it('should have deployment tools', () => {
+			const deploymentTools = tools.filter((t) => t.name.includes('deployment'));
+			expect(deploymentTools.length).toBeGreaterThanOrEqual(3);
+		});
+	});
+
+	// ============================================================================
+	// Input Schema Consistency Tests
+	// ============================================================================
+
+	describe('schema consistency', () => {
+		it('project_id fields should have consistent description', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, { description?: string }>;
+
+				if (properties.project_id) {
+					expect(
+						properties.project_id.description?.toLowerCase().includes('project') ||
+						properties.project_id.description?.toLowerCase().includes('uuid'),
+						`Tool "${tool.name}" project_id description should mention project or UUID`
+					).toBe(true);
+				}
+			});
+		});
+
+		it('task_id fields should have consistent type', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, { type?: string }>;
+
+				if (properties.task_id) {
+					expect(
+						properties.task_id.type,
+						`Tool "${tool.name}" task_id should be string type`
+					).toBe('string');
+				}
+			});
+		});
+
+		it('limit fields should have numeric constraints', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, {
+					type?: string;
+					minimum?: number;
+					maximum?: number;
+				}>;
+
+				if (properties.limit) {
+					expect(
+						properties.limit.type,
+						`Tool "${tool.name}" limit should be number type`
+					).toBe('number');
+				}
+			});
+		});
+
+		it('offset fields should be number type', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, { type?: string }>;
+
+				if (properties.offset) {
+					expect(
+						properties.offset.type,
+						`Tool "${tool.name}" offset should be number type`
+					).toBe('number');
+				}
+			});
+		});
+
+		it('priority fields should have valid constraints', () => {
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, {
+					type?: string;
+					minimum?: number;
+					maximum?: number;
+				}>;
+
+				if (properties.priority) {
+					expect(
+						properties.priority.type,
+						`Tool "${tool.name}" priority should be number type`
+					).toBe('number');
+
+					if (properties.priority.minimum !== undefined) {
+						expect(
+							properties.priority.minimum,
+							`Tool "${tool.name}" priority minimum should be 1`
+						).toBe(1);
+					}
+
+					if (properties.priority.maximum !== undefined) {
+						expect(
+							properties.priority.maximum,
+							`Tool "${tool.name}" priority maximum should be 5`
+						).toBe(5);
+					}
+				}
+			});
+		});
+
+		it('status enum fields should have consistent values for tasks', () => {
+			const expectedTaskStatuses = ['backlog', 'pending', 'in_progress', 'completed', 'cancelled'];
+
+			tools.forEach((tool) => {
+				const properties = tool.inputSchema.properties as Record<string, {
+					enum?: string[];
+					description?: string;
+				}>;
+
+				// Only check status fields that are clearly for tasks
+				if (properties.status?.enum && properties.status.description?.toLowerCase().includes('task')) {
+					const hasValidStatuses = properties.status.enum.every(
+						(s) => expectedTaskStatuses.includes(s)
+					);
+					expect(
+						hasValidStatuses,
+						`Tool "${tool.name}" status enum should only contain valid task statuses`
+					).toBe(true);
+				}
+			});
+		});
+	});
+
+	// ============================================================================
+	// Description Quality Tests
+	// ============================================================================
+
+	describe('description quality', () => {
+		it('descriptions should not be too short', () => {
+			tools.forEach((tool) => {
+				expect(
+					tool.description.length,
+					`Tool "${tool.name}" description is too short (${tool.description.length} chars)`
+				).toBeGreaterThanOrEqual(10);
+			});
+		});
+
+		it('descriptions should start with a capital letter or special character', () => {
+			tools.forEach((tool) => {
+				const firstChar = tool.description.charAt(0);
+				const isValidStart = /[A-Z\[]/.test(firstChar);
+				expect(
+					isValidStart,
+					`Tool "${tool.name}" description should start with capital letter (got "${firstChar}")`
+				).toBe(true);
+			});
+		});
+	});
+});