Uptrace MCP Server

Instructions

Implementation Reference

• src/uptrace_mcp/server.py:494-568 (handler)

  The handler for 'uptrace_get_trace' that parses arguments, calls the client to fetch spans, and returns formatted text or JSON.

  elif name == "uptrace_get_trace":
      trace_id = arguments.get("trace_id")
      output_format = arguments.get("format", "text")  # "text" or "json"
  
      if not trace_id:
          return [TextContent(type="text", text="Error: trace_id is required")]
  
      logger.info(f"Fetching trace: {trace_id}")
      spans = client.get_trace(trace_id)
  
      if not spans:
          return [TextContent(type="text", text=f"No spans found for trace ID: {trace_id}")]
  
      # Return JSON format if requested
      if output_format == "json":
          import json
  
          # Convert spans to dict with all attributes
          spans_data = []
          for span in spans:
              span_dict = {
                  "id": span.id,
                  "parent_id": span.parent_id,
                  "trace_id": span.trace_id,
                  "project_id": span.project_id,
                  "group_id": span.group_id,
                  "type": span.type,
                  "system": span.system,
                  "kind": span.kind,
                  "name": span.name,
                  "display_name": span.display_name,
                  "time": span.time,
                  "duration": span.duration,
                  "status_code": span.status_code,
                  "status_message": span.status_message,
                  "attrs": span.attrs or {},
                  "events": [
                      {"name": event.name, "time": event.time, "attrs": event.attrs or {}}
                      for event in span.events
                  ],
                  "links": span.links or [],
              }
              spans_data.append(span_dict)
  
          result = {"trace_id": trace_id, "total_spans": len(spans), "spans": spans_data}
  
          return [
              TextContent(
                  type="text",
                  text=json.dumps(result, indent=2, ensure_ascii=False, default=str),
              )
          ]
  
      # Return text format (default)
      lines = [
          f"# Trace: {trace_id}",
          f"**Total Spans**: {len(spans)}",
          "",
      ]
  
      # Build tree structure
      root_spans = [s for s in spans if not s.parent_id or s.parent_id == "0"]
  
      def format_tree(span: Any, indent: int = 0) -> None:
          prefix = "  " * indent + ("└─ " if indent > 0 else "")
          duration_ms = round(span.duration / 1000, 2) if span.duration else 0
          status = "❌" if span.status_code == "error" else "✓"
          lines.append(f"{prefix}{status} {span.display_name} ({duration_ms}ms) [{span.id}]")
  
          # Find children
          children = [s for s in spans if s.parent_id == span.id]
          for child in children:
              format_tree(child, indent + 1)
  
      lines.append("## Span Tree")

• src/uptrace_mcp/server.py:203-220 (schema)

  The MCP tool definition and input schema for 'uptrace_get_trace'.

  Tool(
      name="uptrace_get_trace",
      description="Get all spans for a specific trace ID. Useful for debugging and understanding request flows.",
      inputSchema={
          "type": "object",
          "properties": {
              "trace_id": {
                  "type": "string",
                  "description": "Trace ID to retrieve",
              },
              "format": {
                  "type": "string",
                  "enum": ["text", "json"],
                  "description": "Output format: 'text' for human-readable format, 'json' for structured JSON with all attributes",
                  "default": "text",
              },
          },
          "required": ["trace_id"],