Trace MCP

Instructions

Implementation Reference

• src/index.ts:478-551 (handler)

  Primary handler for the 'comment_contract' MCP tool. Parses input, extracts schemas from producer and consumer directories, validates the tool exists in both, prepares options, and dispatches to previewContractComments (dryRun) or addContractComments.

  case 'comment_contract': {
    const input = CommentContractInput.parse(args);
    log(`Commenting contract for tool: ${input.toolName}`);
    
    // Get both producer and consumer
    const producers = await extractProducerSchemas({ rootDir: input.producerDir });
    const consumers = await traceConsumerUsage({ rootDir: input.consumerDir });
    
    const producer = producers.find(p => p.toolName === input.toolName);
    const consumer = consumers.find(c => c.toolName === input.toolName);
    
    if (!producer) {
      throw new Error(`Tool "${input.toolName}" not found in producer at ${input.producerDir}`);
    }
    if (!consumer) {
      throw new Error(`Tool "${input.toolName}" not found in consumer at ${input.consumerDir}`);
    }
    
    const match = {
      toolName: input.toolName,
      producerLocation: producer.location,
      consumerLocation: consumer.callSite,
    };
    
    const commentOptions = {
      match,
      producer,
      consumer,
      style: input.style || 'block' as const,
      includeTimestamp: true,
    };
    
    if (input.dryRun !== false) {
      // Preview mode (default)
      const preview = previewContractComments(commentOptions);
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: true,
              mode: 'preview',
              toolName: input.toolName,
              producerPreview: preview.producerPreview,
              consumerPreview: preview.consumerPreview,
              note: 'Set dryRun: false to actually add these comments to files',
            }, null, 2),
          },
        ],
      };
    } else {
      // Actually add comments
      const result = await addContractComments(commentOptions);
      
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: result.success,
              mode: 'applied',
              toolName: input.toolName,
              producerFile: result.producerFile,
              consumerFile: result.consumerFile,
              producerComment: result.producerComment,
              consumerComment: result.consumerComment,
              error: result.error,
            }, null, 2),
          },
        ],
      };
    }
  }

• src/index.ts:87-93 (schema)

  Zod schema defining the input parameters for the comment_contract tool.

  const CommentContractInput = z.object({
    producerDir: z.string().describe('Path to MCP server source directory'),
    consumerDir: z.string().describe('Path to consumer source directory'),
    toolName: z.string().describe('Name of the validated tool'),
    dryRun: z.boolean().optional().describe('Preview comments without writing to files (default: true)'),
    style: z.enum(['jsdoc', 'inline', 'block']).optional().describe('Comment style (default: block)'),
  });

• src/index.ts:221-235 (registration)

  Registration of the comment_contract tool in the ListToolsRequest handler, providing name, description, and input schema.

  {
    name: 'comment_contract',
    description: 'Add cross-reference comments to validated producer/consumer pairs. Documents the contract relationship in both files.',
    inputSchema: {
      type: 'object',
      properties: {
        producerDir: { type: 'string', description: 'Path to MCP server source directory' },
        consumerDir: { type: 'string', description: 'Path to consumer source directory' },
        toolName: { type: 'string', description: 'Name of the validated tool' },
        dryRun: { type: 'boolean', description: 'Preview comments without writing to files (default: true)' },
        style: { type: 'string', enum: ['jsdoc', 'inline', 'block'], description: 'Comment style' },
      },
      required: ['producerDir', 'consumerDir', 'toolName'],
    },
  },

• src/tools/contract-comments.ts:94-141 (handler)

  Core implementation for adding contract comments to source files using ts-morph. Loads files, inserts comments before relevant nodes (tool definition and callTool), and saves changes.

  export async function addContractComments(options: ContractCommentOptions): Promise<CommentResult> {
    const { match, producer, consumer } = options;
    const { producerComment, consumerComment } = generateContractComments(options);
    
    const project = new Project({
      skipAddingFilesFromTsConfig: true,
    });
  
    try {
      // Add comment to producer file
      const producerFile = project.addSourceFileAtPath(producer.location.file);
      const producerNode = findNodeAtLine(producerFile, producer.location.line);
      
      if (producerNode) {
        // Add comment before the tool definition
        producerNode.replaceWithText(`${producerComment}\n${producerNode.getText()}`);
      }
  
      // Add comment to consumer file
      const consumerFile = project.addSourceFileAtPath(consumer.callSite.file);
      const consumerNode = findNodeAtLine(consumerFile, consumer.callSite.line);
      
      if (consumerNode) {
        // Add comment before the callTool invocation
        consumerNode.replaceWithText(`${consumerComment}\n${consumerNode.getText()}`);
      }
  
      // Save changes
      await project.save();
  
      return {
        success: true,
        producerFile: producer.location.file,
        consumerFile: consumer.callSite.file,
        producerComment,
        consumerComment,
      };
    } catch (error) {
      return {
        success: false,
        producerFile: producer.location.file,
        consumerFile: consumer.callSite.file,
        producerComment,
        consumerComment,
        error: error instanceof Error ? error.message : String(error),
      };
    }
  }

• src/tools/contract-comments.ts:37-71 (helper)

  Generates the actual comment strings for producer and consumer, formatting details like file locations, args/props used, and validation timestamp.

  export function generateContractComments(options: ContractCommentOptions): {
    producerComment: string;
    consumerComment: string;
  } {
    const { match, producer, consumer, style = 'block', includeTimestamp = true, prefix = '@trace-contract' } = options;
    const timestamp = includeTimestamp ? ` | Validated: ${new Date().toISOString().split('T')[0]}` : '';
    
    // Producer comment points to consumer
    const producerComment = formatComment({
      style,
      lines: [
        `${prefix} PRODUCER`,
        `Tool: ${match.toolName}`,
        `Consumer: ${consumer.callSite.file}:${consumer.callSite.line}`,
        `Args: ${Object.keys(consumer.argumentsProvided).join(', ')}`,
        `Expected Props: ${consumer.expectedProperties.slice(0, 5).join(', ')}${consumer.expectedProperties.length > 5 ? '...' : ''}`,
        timestamp ? `Validated: ${timestamp}` : '',
      ].filter(Boolean),
    });
  
    // Consumer comment points to producer  
    const consumerComment = formatComment({
      style,
      lines: [
        `${prefix} CONSUMER`,
        `Tool: ${match.toolName}`,
        `Producer: ${producer.location.file}:${producer.location.line}`,
        `Required Args: ${producer.inputSchema.required?.join(', ') || 'none'}`,
        `Schema Props: ${Object.keys(producer.inputSchema.properties || {}).join(', ')}`,
        timestamp ? `Validated: ${timestamp}` : '',
      ].filter(Boolean),
    });
  
    return { producerComment, consumerComment };
  }