Opik MCP Server

Instructions

Implementation Reference

• src/tools/trace.ts:117-163 (handler)

  Handler function that makes API request to fetch the specific trace by ID, formats the input/output fields as JSON strings if they are objects, and returns a formatted response with details.

  async (args: any) => {
    const { traceId, workspaceName } = args;
    const response = await makeApiRequest<SingleTraceResponse>(
      `/v1/private/traces/${traceId}`,
      {},
      workspaceName
    );
  
    if (!response.data) {
      return {
        content: [{ type: 'text', text: response.error || 'Failed to fetch trace' }],
      };
    }
  
    // Format the response for better readability
    const formattedResponse: any = { ...response.data };
  
    // Format input/output if they're large
    if (
      formattedResponse.input &&
      typeof formattedResponse.input === 'object' &&
      Object.keys(formattedResponse.input).length > 0
    ) {
      formattedResponse.input = JSON.stringify(formattedResponse.input, null, 2);
    }
  
    if (
      formattedResponse.output &&
      typeof formattedResponse.output === 'object' &&
      Object.keys(formattedResponse.output).length > 0
    ) {
      formattedResponse.output = JSON.stringify(formattedResponse.output, null, 2);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: `Trace Details for ID: ${traceId}`,
        },
        {
          type: 'text',
          text: JSON.stringify(formattedResponse, null, 2),
        },
      ],
    };
  }

• src/tools/trace.ts:107-116 (schema)

  Input schema for the get-trace-by-id tool using Zod validation: requires traceId (string, UUID), optional workspaceName (string).

    traceId: z
      .string()
      .describe(
        'ID of the trace to fetch (UUID format, e.g. "123e4567-e89b-12d3-a456-426614174000")'
      ),
    workspaceName: z
      .string()
      .optional()
      .describe('Workspace name to use instead of the default workspace'),
  },

• src/tools/trace.ts:103-164 (registration)

  Registration of the 'get-trace-by-id' tool within the loadTraceTools function, including name, description, input schema, and inline handler.

  server.tool(
    'get-trace-by-id',
    'Get detailed information about a specific trace including input, output, metadata, and timing information',
    {
      traceId: z
        .string()
        .describe(
          'ID of the trace to fetch (UUID format, e.g. "123e4567-e89b-12d3-a456-426614174000")'
        ),
      workspaceName: z
        .string()
        .optional()
        .describe('Workspace name to use instead of the default workspace'),
    },
    async (args: any) => {
      const { traceId, workspaceName } = args;
      const response = await makeApiRequest<SingleTraceResponse>(
        `/v1/private/traces/${traceId}`,
        {},
        workspaceName
      );
  
      if (!response.data) {
        return {
          content: [{ type: 'text', text: response.error || 'Failed to fetch trace' }],
        };
      }
  
      // Format the response for better readability
      const formattedResponse: any = { ...response.data };
  
      // Format input/output if they're large
      if (
        formattedResponse.input &&
        typeof formattedResponse.input === 'object' &&
        Object.keys(formattedResponse.input).length > 0
      ) {
        formattedResponse.input = JSON.stringify(formattedResponse.input, null, 2);
      }
  
      if (
        formattedResponse.output &&
        typeof formattedResponse.output === 'object' &&
        Object.keys(formattedResponse.output).length > 0
      ) {
        formattedResponse.output = JSON.stringify(formattedResponse.output, null, 2);
      }
  
      return {
        content: [
          {
            type: 'text',
            text: `Trace Details for ID: ${traceId}`,
          },
          {
            type: 'text',
            text: JSON.stringify(formattedResponse, null, 2),
          },
        ],
      };
    }
  );

• src/index.ts:91-93 (registration)

  Conditional registration of the trace tools module (including get-trace-by-id) by calling loadTraceTools(server) when 'traces' toolset is enabled.

  if (config.enabledToolsets.includes('traces')) {
    server = loadTraceTools(server);
    logToFile('Loaded traces toolset');