Documentation
¶
Overview ¶
Package bridge provides a reusable HTTP client wrapping all trace tool endpoints.
Description:
ToolBridge translates MCP tool calls into HTTP requests against the Trace service. It stores a graph_id after InitProject() and auto-injects it into all subsequent CallTool() requests so MCP callers never deal with graph_id directly.
Thread Safety: All exported methods are safe for concurrent use.
Index ¶
- Constants
- type Option
- type ToolBridge
- func (b *ToolBridge) CallTool(ctx context.Context, toolName string, params map[string]any) (*ToolResult, error)
- func (b *ToolBridge) GetGraphStats(ctx context.Context) (*ToolResult, error)
- func (b *ToolBridge) GraphID() string
- func (b *ToolBridge) HealthCheck(ctx context.Context) (*ToolResult, error)
- func (b *ToolBridge) InitProject(ctx context.Context, projectRoot string) (*ToolResult, error)
- type ToolResult
Constants ¶
const ( // DefaultTraceURL is the default URL for the Trace service. DefaultTraceURL = "http://localhost:12217" // DefaultTimeout is the default HTTP request timeout. DefaultTimeout = 30 * time.Second // DefaultMaxResultSize is the maximum number of characters returned in a tool result. DefaultMaxResultSize = 8192 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*ToolBridge)
Option configures a ToolBridge.
func WithHTTPClient ¶
WithHTTPClient sets a custom HTTP client for the bridge.
Description:
Allows injecting a custom *http.Client (useful for testing with httptest). When set, WithTimeout has no effect — the caller controls the client's timeout.
Inputs:
c - the HTTP client to use
func WithMaxResultSize ¶
WithMaxResultSize sets the maximum result size in characters.
Description:
Tool results exceeding this size are truncated with a "[truncated]" suffix.
Inputs:
n - max number of characters in the result
func WithTimeout ¶
WithTimeout sets the HTTP request timeout.
Description:
Overrides the default 30s timeout for HTTP requests to the Trace service. This sets a timeout field that is applied when the HTTP client is created inside NewToolBridge, so ordering with WithHTTPClient does not matter. If WithHTTPClient is also used, this option has no effect (the caller is responsible for configuring their own client's timeout).
Inputs:
d - timeout duration
func WithTraceURL ¶
WithTraceURL sets the base URL for the Trace service.
Description:
Overrides the default trace URL (http://localhost:12217).
Inputs:
url - the base URL including scheme and port (e.g., "http://remote:12217")
type ToolBridge ¶
type ToolBridge struct {
// contains filtered or unexported fields
}
ToolBridge is a reusable HTTP client that translates MCP tool calls into HTTP requests against the Trace service.
Description:
After InitProject() stores the graph_id, all subsequent CallTool() calls auto-inject it. GET tools map params to query strings; POST tools merge graph_id into the JSON body.
Thread Safety: All methods are safe for concurrent use. A sync.RWMutex guards the graphID field. httpClient is inherently safe.
func NewToolBridge ¶
func NewToolBridge(opts ...Option) *ToolBridge
NewToolBridge creates a new ToolBridge with the given options.
Description:
Creates a bridge with defaults (localhost:12217, 30s timeout, 8192 max chars) then applies any functional options. The HTTP client is created after all options are applied so that WithTimeout and WithHTTPClient do not conflict.
Inputs:
opts - functional options (WithTraceURL, WithTimeout, WithMaxResultSize, WithHTTPClient)
Outputs:
*ToolBridge - the configured bridge
func (*ToolBridge) CallTool ¶
func (b *ToolBridge) CallTool(ctx context.Context, toolName string, params map[string]any) (*ToolResult, error)
CallTool executes a trace tool by name with the given parameters.
Description:
Looks up the tool route, constructs an HTTP request (GET with query params or POST with JSON body), auto-injects graph_id, executes the request, decodes the response, and truncates if necessary.
Inputs:
ctx - context for cancellation and timeout toolName - the MCP tool name (e.g., "trace_find_callers") params - MCP parameter key-value pairs
Outputs:
*ToolResult - the tool result (may be truncated) error - wrapped error if the request fails or the tool is unknown
Limitations:
Results exceeding MaxResultSize are truncated with "[truncated]" suffix.
Thread Safety: Safe for concurrent use.
func (*ToolBridge) GetGraphStats ¶
func (b *ToolBridge) GetGraphStats(ctx context.Context) (*ToolResult, error)
GetGraphStats calls the graph stats debug endpoint.
Description:
Calls GET /v1/trace/debug/graph/stats and returns the response JSON.
Inputs:
ctx - context for cancellation and timeout
Outputs:
*ToolResult - the stats response JSON error - wrapped error if the request fails
Thread Safety: Safe for concurrent use.
func (*ToolBridge) GraphID ¶
func (b *ToolBridge) GraphID() string
GraphID returns the currently stored graph ID.
Description:
Returns the graph_id set by InitProject(). Empty if not yet initialized.
Thread Safety: Safe for concurrent use; acquires read lock.
func (*ToolBridge) HealthCheck ¶
func (b *ToolBridge) HealthCheck(ctx context.Context) (*ToolResult, error)
HealthCheck calls the trace health endpoint.
Description:
Calls GET /v1/trace/health and returns the response JSON.
Inputs:
ctx - context for cancellation and timeout
Outputs:
*ToolResult - the health response JSON error - wrapped error if the request fails
Thread Safety: Safe for concurrent use.
func (*ToolBridge) InitProject ¶
func (b *ToolBridge) InitProject(ctx context.Context, projectRoot string) (*ToolResult, error)
InitProject initializes a project graph and stores the graph_id.
Description:
Calls POST /v1/trace/init with the project_root, stores the returned graph_id for all subsequent tool calls. Returns the init response JSON.
Inputs:
ctx - context for cancellation and timeout projectRoot - absolute path to the project root directory
Outputs:
*ToolResult - the init response JSON error - wrapped error if the request fails
Thread Safety: Safe for concurrent use; acquires write lock on graphID.
type ToolResult ¶
type ToolResult struct {
// Content is the JSON text result from the tool endpoint.
Content string
// IsError is true if the tool call resulted in an error.
IsError bool
}
ToolResult holds the result of a tool call.
Description:
Contains the JSON text returned by the tool endpoint, truncated to MaxResultSize if the response exceeds it. IsError is true when the upstream returned an error status or the request failed.
Source Files