Trace MCP

Instructions

Implementation Reference

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

  Main handler for the 'init_project' MCP tool. Parses input, loads TraceProject instance, initializes project directories and config if new, handles existing project error, logs and returns success response with config.

  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 input schema validation for the init_project tool parameters.

  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:238-251 (registration)

  Tool registration object returned by ListToolsRequestHandler, defining name, description, and inputSchema for init_project.

    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)

  Core initialization logic in TraceProject.init() method: creates .trace-mcp subdirectories (cache, contracts, reports), parses and writes config.json using ProjectConfigSchema, adds .gitignore. Called directly by the tool handler.

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