Ultra MCP

Instructions

Implementation Reference

• src/server.ts:384-392 (registration)

  Registers the 'tracer' tool with MCP server, specifying title, description, input schema, and delegates execution to aiHandlers.handleTracer

  // Register tracer tool
  server.registerTool("tracer", {
    title: "Tracer",
    description: "Trace execution flow and debug complex issues",
    inputSchema: TracerSchema.shape,
  }, async (args) => {
    const aiHandlers = await getHandlers();
    return await aiHandlers.handleTracer(args);
  });

• src/server.ts:119-125 (schema)

  Zod schema defining input parameters for the tracer tool: task, traceMode, targetDescription, files, provider.

  const TracerSchema = z.object({
    task: z.string().describe("What to trace and WHY you need this analysis (e.g., 'trace User.login() execution flow', 'map UserService dependencies', 'understand payment processing call chain')"),
    traceMode: z.enum(["precision", "dependencies", "ask"]).default("ask").describe("Type of tracing: 'ask' (prompts user to choose), 'precision' (execution flow), 'dependencies' (structural relationships)"),
    targetDescription: z.string().optional().describe("Detailed description of what to trace - method, function, class, or module name and context"),
    files: z.array(z.string()).optional().describe("Relevant files to focus tracing on (optional)"),
    provider: z.enum(["openai", "gemini", "azure", "grok"]).optional().default("gemini").describe("AI provider to use"),
  });

• src/handlers/ai-tools.ts:1199-1363 (handler)

  Core handler implementation for 'tracer' tool. Generates specialized AI prompts for code tracing in 'precision' (execution flow) or 'dependencies' (structural mapping) modes, analyzes codebase, and returns structured tracing results with status and code references.

    async handleTracer(params: z.infer<typeof TracerSchema>) {
      const providerName = params.provider || (await this.providerManager.getPreferredProvider(['openai', 'gemini', 'azure', 'grok']));
      const provider = await this.providerManager.getProvider(providerName);
      
      // Build trace mode specific system prompt
      const traceModePrompts = {
        ask: "STEP 1: Ask the user to choose between 'precision' or 'dependencies' tracing mode. Explain: PRECISION MODE traces execution flow, call chains, and usage patterns (best for methods/functions). DEPENDENCIES MODE maps structural relationships and bidirectional dependencies (best for classes/modules). Wait for user selection before proceeding.",
        precision: "Focus on execution flow analysis: trace method calls, function invocations, call chains, usage patterns, execution paths, conditional branches, and data flow through the system. Best for understanding how specific methods or functions work.",
        dependencies: "Focus on structural relationship analysis: map class dependencies, module relationships, inheritance hierarchies, interface implementations, import/export chains, and bidirectional dependencies. Best for understanding how components relate to each other.",
      };
  
      const systemPrompt = `You are an expert code tracer specializing in systematic code analysis and relationship mapping. Your role is to conduct thorough code tracing using structured investigation workflows.
  
  TRACING MODE: ${traceModePrompts[params.traceMode]}
  
  TRACE ANALYSIS METHODOLOGY:
  1. **Target Identification**: Locate and understand the target method/function/class/module
  2. **Context Analysis**: Understand the purpose, signature, and implementation details
  3. **Relationship Mapping**: ${params.traceMode === 'precision' ? 'Trace execution flow and call chains' : 'Map structural dependencies and relationships'}
  4. **Pattern Recognition**: Identify architectural patterns and design decisions
  5. **Comprehensive Documentation**: Document findings with precise file references and line numbers
  
  ${params.traceMode === 'precision' ? `
  PRECISION TRACING FOCUS:
  - Execution flow and call sequence
  - Method invocation patterns
  - Conditional execution paths
  - Data flow and transformations
  - Side effects and state changes
  - Entry points and usage scenarios
  ` : params.traceMode === 'dependencies' ? `
  DEPENDENCIES TRACING FOCUS:
  - Incoming dependencies (what depends on this)
  - Outgoing dependencies (what this depends on)
  - Type relationships (inheritance, implementation)
  - Structural patterns and architecture
  - Bidirectional relationship mapping
  - Module and package relationships
  ` : ''}
  
  INVESTIGATION WORKFLOW:
  This is a step-by-step analysis tool. You will:
  1. Start with systematic code investigation
  2. Gather evidence from actual code examination
  3. Build comprehensive understanding through multiple investigation steps
  4. Present findings in structured format with precise code references
  
  RESPONSE FORMAT:
  Provide detailed tracing analysis including:
  - **Target Analysis**: Complete understanding of what is being traced
  - **${params.traceMode === 'precision' ? 'Execution Flow' : 'Dependency Map'}**: ${params.traceMode === 'precision' ? 'Call chains and execution paths' : 'Structural relationships and dependencies'}
  - **Code References**: Specific file paths and line numbers
  - **Patterns and Insights**: Architectural observations and design patterns
  - **Usage Context**: How the traced element is used in the broader system`;
  
      // Build the tracing prompt
      let prompt = `Code Tracing Task: ${params.task}`;
      
      if (params.targetDescription) {
        prompt += `\n\nTarget Description: ${params.targetDescription}`;
      }
      
      prompt += `\n\nTracing Mode: ${params.traceMode}`;
      
      // Add file context if provided
      if (params.files && params.files.length > 0) {
        prompt += `\n\nFiles to focus on: ${params.files.join(", ")}`;
      } else {
        prompt += `\n\nPlease analyze all relevant files in the codebase to understand the target.`;
      }
  
      if (params.traceMode === 'ask') {
        prompt += `\n\nPLEASE START BY ASKING THE USER TO CHOOSE A TRACING MODE:
  - **PRECISION MODE**: Traces execution flow, call chains, and usage patterns (best for methods/functions)
  - **DEPENDENCIES MODE**: Maps structural relationships and bidirectional dependencies (best for classes/modules)
  
  Explain these options clearly and wait for the user to specify which mode to use before proceeding with the actual tracing analysis.`;
      } else {
        prompt += `\n\nPlease conduct systematic ${params.traceMode} tracing analysis. Examine the code thoroughly, trace all relevant relationships, and provide comprehensive findings with specific file references and line numbers.`;
      }
  
      try {
        const response = await provider.generateText({
          prompt,
          systemPrompt,
          temperature: 0.2, // Lower temperature for systematic analysis
          reasoningEffort: (providerName === "openai" || providerName === "azure" || providerName === "grok") ? "high" : undefined,
          useSearchGrounding: false, // Tracing focuses on local code analysis
          toolName: 'tracer',
        });
  
        // Build structured response
        const trace = {
          task: params.task,
          trace_mode: params.traceMode,
          target_description: params.targetDescription,
          files_analyzed: params.files || "comprehensive codebase analysis",
          trace_analysis: response.text,
          provider_used: providerName,
          model_used: response.model,
        };
  
        // Analyze response to determine trace completion status
        const analysisText = response.text.toLowerCase();
        const isAskingForMode = params.traceMode === 'ask' || analysisText.includes("choose") || analysisText.includes("which mode") || analysisText.includes("precision or dependencies");
        const hasCodeReferences = analysisText.includes("line") || analysisText.includes("file") || analysisText.includes(".js") || analysisText.includes(".ts") || analysisText.includes(".py");
        const hasTraceFindings = analysisText.includes("trace") || analysisText.includes("calls") || analysisText.includes("dependencies") || analysisText.includes("flow");
  
        let traceStatus = "in_progress";
        if (isAskingForMode) {
          traceStatus = "awaiting_mode_selection";
        } else if (hasCodeReferences && hasTraceFindings) {
          traceStatus = "analysis_complete";
        } else {
          traceStatus = "needs_more_investigation";
        }
  
        const result = {
          trace,
          trace_status: traceStatus,
          mode_selection_required: isAskingForMode,
          has_code_references: hasCodeReferences,
          has_trace_findings: hasTraceFindings,
          next_steps: isAskingForMode 
            ? "User must select tracing mode (precision or dependencies) before proceeding with analysis"
            : traceStatus === "needs_more_investigation"
            ? "Continue systematic code investigation to gather more tracing evidence"
            : "Tracing analysis complete with comprehensive findings",
          analysis_quality: hasCodeReferences && hasTraceFindings ? "comprehensive" : hasTraceFindings ? "moderate" : "preliminary",
        };
  
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(result, null, 2),
            },
          ],
          metadata: {
            toolName: "tracer",
            traceMode: params.traceMode,
            traceStatus: traceStatus,
            provider: providerName,
            model: response.model,
            usage: response.usage,
            ...response.metadata,
          },
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify({
                error: "Code tracing failed",
                message: error instanceof Error ? error.message : "Unknown error",
                task: params.task,
                traceMode: params.traceMode,
              }, null, 2),
            },
          ],
          isError: true,
        };
      }
    }

• src/server.ts:791-809 (registration)

  Registers the prompt template for the 'tracer' tool, enabling natural language invocation with args mapping to structured tool calls.

  server.registerPrompt("tracer", {
    title: "Code Tracer",
    description: "Trace execution flow and debug complex code relationships", 
    argsSchema: {
      task: z.string(),
      traceMode: z.string().optional(),
      targetDescription: z.string().optional(),
      files: z.string().optional(),
      provider: z.string().optional(),
    },
  }, (args) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Trace this code: ${args.task}${args.traceMode ? ` (trace mode: ${args.traceMode})` : ''}${args.targetDescription ? `\n\nTarget to trace: ${args.targetDescription}` : ''}${args.files ? `\n\nFocus on files: ${args.files}` : ''}${args.provider ? ` (using ${args.provider} provider)` : ''}`
      }
    }]
  }));

• src/handlers/ai-tools.ts:126-132 (schema)

  Zod schema for tracer tool inputs, used for type inference in the handler function (duplicate of server.ts schema).

  const TracerSchema = z.object({
    task: z.string().describe("What to trace and WHY you need this analysis (e.g., 'trace User.login() execution flow', 'map UserService dependencies', 'understand payment processing call chain')"),
    traceMode: z.enum(["precision", "dependencies", "ask"]).default("ask").describe("Type of tracing: 'ask' (prompts user to choose), 'precision' (execution flow), 'dependencies' (structural relationships)"),
    targetDescription: z.string().optional().describe("Detailed description of what to trace - method, function, class, or module name and context"),
    files: z.array(z.string()).optional().describe("Relevant files to focus tracing on (optional)"),
    provider: z.enum(["openai", "gemini", "azure", "grok"]).optional().default("gemini").describe("AI provider to use"),
  });