Trace MCP

Instructions

Implementation Reference

• src/index.ts:554-600 (handler)

  Main handler logic for the 'init_project' tool within the CallToolRequestSchema switch statement. Parses input, loads project, initializes if new, and returns JSON response.

  case 'init_project': {
    const input = InitProjectInput.parse(args);
    log(`Initializing trace project at: ${input.projectDir}`);
    
    const project = loadProject(input.projectDir);
    
    if (project.exists()) {
      return {
        content: [{
          type: 'text',
          text: JSON.stringify({
            success: false,
            error: `Project already exists at ${input.projectDir}. Use get_project_status to view it.`,
          }, null, 2),
        }],
      };
    }
    
    const config = project.init({
      producer: {
        path: input.producerPath,
        language: input.producerLanguage || 'typescript',
        include: ['**/*.ts'],
        exclude: ['**/*.test.ts', '**/node_modules/**', '**/dist/**'],
      },
      consumer: {
        path: input.consumerPath,
        language: input.consumerLanguage || 'typescript',
        include: ['**/*.ts', '**/*.tsx'],
        exclude: ['**/*.test.ts', '**/node_modules/**', '**/dist/**'],
      },
    });
    
    log(`Project initialized with config:`, config);
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          success: true,
          projectDir: input.projectDir,
          traceDir: project.traceDir,
          config,
        }, null, 2),
      }],
    };
  }

• src/index.ts:96-102 (schema)

  Zod schema definition for init_project input validation, used in handler parse().

  const InitProjectInput = z.object({
    projectDir: z.string().describe('Root directory for the trace project'),
    producerPath: z.string().describe('Relative path to producer/server code'),
    consumerPath: z.string().describe('Relative path to consumer/client code'),
    producerLanguage: z.enum(['typescript', 'python', 'go', 'rust', 'json_schema']).optional().default('typescript'),
    consumerLanguage: z.enum(['typescript', 'python', 'go', 'rust', 'json_schema']).optional().default('typescript'),
  });

• src/index.ts:237-251 (registration)

  Registration of 'init_project' tool in ListToolsRequestSchema response, defining name, description, and JSON input schema.

  {
    name: 'init_project',
    description: 'Initialize a trace project with .trace-mcp config directory. Creates project structure for watch mode and caching.',
    inputSchema: {
      type: 'object',
      properties: {
        projectDir: { type: 'string', description: 'Root directory for the trace project' },
        producerPath: { type: 'string', description: 'Relative path to producer/server code' },
        consumerPath: { type: 'string', description: 'Relative path to consumer/client code' },
        producerLanguage: { type: 'string', enum: ['typescript', 'python', 'go', 'rust', 'json_schema'], description: 'Producer language (default: typescript)' },
        consumerLanguage: { type: 'string', enum: ['typescript', 'python', 'go', 'rust', 'json_schema'], description: 'Consumer language (default: typescript)' },
      },
      required: ['projectDir', 'producerPath', 'consumerPath'],
    },
  },

• src/watch/project.ts:76-97 (helper)

  TraceProject.init() method: core logic called by handler to create .trace-mcp directories, parse/write config.json, and .gitignore.

  init(config: Partial<ProjectConfig>): ProjectConfig {
    // Create directories
    mkdirSync(this.traceDir, { recursive: true });
    mkdirSync(this.cachePath, { recursive: true });
    mkdirSync(this.contractsPath, { recursive: true });
    mkdirSync(this.reportsPath, { recursive: true });
  
    // Create config with defaults
    const fullConfig = ProjectConfigSchema.parse(config);
    
    // Write config
    writeFileSync(this.configPath, JSON.stringify(fullConfig, null, 2));
    this._config = fullConfig;
  
    // Create .gitignore for cache
    writeFileSync(
      join(this.traceDir, '.gitignore'),
      '# Trace MCP cache (regenerated)\ncache/\nreports/\n'
    );
  
    return fullConfig;
  }

• src/watch/project.ts:14-34 (schema)

  ProjectConfigSchema: Zod schema for validating project configuration used in TraceProject.init().

  export const ProjectConfigSchema = z.object({
    version: z.string().default('1.0.0'),
    producer: z.object({
      path: z.string(),
      language: z.enum(['typescript', 'python', 'go', 'rust', 'json_schema']).default('typescript'),
      include: z.array(z.string()).optional().default(['**/*.ts']),
      exclude: z.array(z.string()).optional().default(['**/*.test.ts', '**/node_modules/**', '**/dist/**']),
    }),
    consumer: z.object({
      path: z.string(),
      language: z.enum(['typescript', 'python', 'go', 'rust', 'json_schema']).default('typescript'),
      include: z.array(z.string()).optional().default(['**/*.ts', '**/*.tsx']),
      exclude: z.array(z.string()).optional().default(['**/*.test.ts', '**/node_modules/**', '**/dist/**']),
    }),
    options: z.object({
      strict: z.boolean().default(false),
      direction: z.enum(['producer_to_consumer', 'consumer_to_producer', 'bidirectional']).default('producer_to_consumer'),
      debounceMs: z.number().default(300),
      autoWatch: z.boolean().default(true),
    }).default({}),
  });