Trace MCP

Instructions

Implementation Reference

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

  MCP tool registration for 'compare', defining name, description, and input schema in the ListTools response.

  {
    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 schema (CompareInput) used for input validation in the 'compare' tool handler.

  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)

  Handler for the 'compare' MCP tool: parses input, invokes compareDirectories, formats result, and returns MCP content response.

  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)

  Core helper function compareDirectories: orchestrates schema extraction, usage tracing, and schema comparison.

  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);
  }