Trace MCP

Instructions

Implementation Reference

• src/index.ts:178-192 (registration)

  Registration of the 'compare' tool in the MCP ListTools response, defining name, description, and input schema.
  { name: 'compare', description: 'Full analysis pipeline: extract producer schemas, trace consumer usage, and compare them to find mismatches. Returns a detailed report.', inputSchema: { type: 'object', properties: { producerDir: { type: 'string', description: 'Path to MCP server source directory' }, consumerDir: { type: 'string', description: 'Path to consumer/client source directory' }, format: { type: 'string', enum: ['json', 'markdown', 'summary'], description: 'Output format' }, strict: { type: 'boolean', description: 'Strict mode for comparison' }, direction: { type: 'string', enum: ['producer_to_consumer', 'consumer_to_producer', 'bidirectional'], description: 'Data flow direction (default: producer_to_consumer)' }, }, required: ['producerDir', 'consumerDir'], }, },
• src/index.ts:57-63 (schema)

  Zod input schema (CompareInput) used for validating 'compare' tool arguments.
  const CompareInput = z.object({ producerDir: z.string().describe('Path to MCP server source directory'), consumerDir: z.string().describe('Path to consumer/client source directory'), format: z.enum(['json', 'markdown', 'summary']).optional().describe('Output format (default: json)'), strict: z.boolean().optional().describe('Strict mode: treat missing optional properties as warnings'), direction: z.enum(['producer_to_consumer', 'consumer_to_producer', 'bidirectional']).optional().describe('Data flow direction for compatibility checking (default: producer_to_consumer)'), });
• src/index.ts:377-403 (handler)

  Tool handler in CallToolRequest: parses input, invokes compareDirectories, formats and returns the result.
  case 'compare': { const input = CompareInput.parse(args); log(`Comparing: ${input.producerDir} vs ${input.consumerDir}`); const result = await compareDirectories( input.producerDir, input.consumerDir, { strict: input.strict, direction: input.direction } ); const format = (input.format || 'json') as OutputFormat; const output = formatResult(result, format); log(`Analysis complete: ${result.summary.matchCount} matches, ${result.summary.mismatchCount} mismatches`); return { content: [ { type: 'text', text: output, }, ], }; }
• src/compare/index.ts:321-337 (helper)

  Convenience helper: orchestrates extraction from directories and calls compareSchemas.
  export async function compareDirectories( backendDir: string, frontendDir: string, options: CompareOptions = {} ): Promise<TraceResult> { // Import dynamically to avoid circular deps const { extractProducerSchemas } = await import('../extract/index.js'); const { traceConsumerUsage } = await import('../trace/index.js'); console.log(`\n[Compare] Backend: ${backendDir}`); console.log(`[Compare] Frontend: ${frontendDir}\n`); const producers = await extractProducerSchemas({ rootDir: backendDir }); const consumers = await traceConsumerUsage({ rootDir: frontendDir }); return compareSchemas(producers, consumers, options); }
• src/compare/index.ts:27-93 (helper)

  Core comparison function: matches producers and consumers, detects argument and property mismatches.
  export function compareSchemas( producers: ProducerSchema[], consumers: ConsumerSchema[], options: CompareOptions = {} ): TraceResult { // Default to producer_to_consumer (API response pattern) const direction = options.direction || 'producer_to_consumer'; console.log(`[Comparator] Comparing ${producers.length} producers vs ${consumers.length} consumers`); console.log(`[Comparator] Direction: ${direction}`); const matches: Match[] = []; const mismatches: Mismatch[] = []; // Index producers by tool name for quick lookup const producerMap = new Map<string, ProducerSchema>(); for (const producer of producers) { producerMap.set(producer.toolName, producer); } // Analyze each consumer usage for (const consumer of consumers) { const producer = producerMap.get(consumer.toolName); if (!producer) { // Tool not found in producer definitions mismatches.push({ toolName: consumer.toolName, issueType: 'UNKNOWN_TOOL', description: `Tool "${consumer.toolName}" is called but not defined in producer`, consumerLocation: consumer.callSite, }); continue; } // Check argument mismatches (consumer → producer direction) const argMismatches = checkArgumentMismatches(producer, consumer, direction); mismatches.push(...argMismatches); // Check expected property mismatches (producer → consumer direction) const propMismatches = checkPropertyMismatches(producer, consumer, options, direction); mismatches.push(...propMismatches); // If no mismatches for this call, it's a match if (argMismatches.length === 0 && propMismatches.length === 0) { matches.push({ toolName: consumer.toolName, producerLocation: producer.location, consumerLocation: consumer.callSite, }); } } return { timestamp: new Date().toISOString(), producerSource: producers.length > 0 ? producers[0].location.file : '', consumerSource: consumers.length > 0 ? consumers[0].callSite.file : '', matches, mismatches, summary: { totalTools: producers.length, totalCalls: consumers.length, matchCount: matches.length, mismatchCount: mismatches.length, }, }; }