tools

Documentation

Overview

Cross-project node lookup used by trace and snippet handlers.

Split from tools.go without behaviour changes.

Tool registration: rationale, graph diff, similarity, ranking, localization, reports.

Split from tools.go without behaviour changes.

Tool registration: architecture and graph tools.

Split from tools.go without behaviour changes.

Tool registration: indexing, tracing, schema, and snippet tools.

Split from tools.go without behaviour changes.

Tool registration: project management and index status tools.

Split from tools.go without behaviour changes.

Tool registration: search and Cypher query tools.

Split from tools.go without behaviour changes.

Shared response and argument helpers used by every tool handler.

Split from tools.go without behaviour changes.

Index

• Constants
• Variables
• func ActiveToolset() string
• func CoreToolNames() []string
• func FreshnessFromProject(p *store.Project) (string, string)
• func RegisteredToolDefinitionsJSON() ([]byte, error)
• func SetVersion(v string)
• type MetadataBuilder
  • func NewMetadataBuilder() *MetadataBuilder
  • func (b *MetadataBuilder) Build() map[string]any
  • func (b *MetadataBuilder) WithActionOutcome(outcome string) *MetadataBuilder
  • func (b *MetadataBuilder) WithConfidence(band, rationale string) *MetadataBuilder
  • func (b *MetadataBuilder) WithFallback(reason string) *MetadataBuilder
  • func (b *MetadataBuilder) WithFreshness(state, indexedAt string) *MetadataBuilder
  • func (b *MetadataBuilder) WithGrammarVersions(versions map[string]string) *MetadataBuilder
  • func (b *MetadataBuilder) WithModel(model string) *MetadataBuilder
  • func (b *MetadataBuilder) WithProvenance(toolVersion, dataSource string) *MetadataBuilder
  • func (b *MetadataBuilder) WithStaleness(seconds int64) *MetadataBuilder
• type Server
  • func NewServer(r *store.StoreRouter, opts ...ServerOption) *Server
  • func (s *Server) AdvertisedToolNames() []string
  • func (s *Server) CallTool(ctx context.Context, name string, argsJSON json.RawMessage) (*mcp.CallToolResult, error)
  • func (s *Server) MCPServer() *mcp.Server
  • func (s *Server) Router() *store.StoreRouter
  • func (s *Server) SessionProject() string
  • func (s *Server) SetSessionRoot(rootPath string)
  • func (s *Server) StartWatcher(ctx context.Context)
  • func (s *Server) ToolNames() []string
  • func (s *Server) Toolset() string
• type ServerOption
  • func WithConfig(c *store.ConfigStore) ServerOption
  • func WithToolset(toolset string) ServerOption

Constants

const (
	ActionOutcomeCreated = "created"
	ActionOutcomeUpdated = "updated"
	ActionOutcomeDeleted = "deleted"
	ActionOutcomeNoOp    = "no_op"
	ActionOutcomeFailed  = "failed"
)

Action outcome values for write-tool responses.

const (
	// ToolsetCore advertises the tools the plugin skills, the benchmark arm
	// contracts, and the agent-effectiveness battery rely on, plus the
	// indexing, status, and evidence essentials.
	ToolsetCore = "core"
	// ToolsetFull advertises every registered tool.
	ToolsetFull = "full"
)

Toolsets control how many tools the MCP server advertises. Every tool is always registered internally (the CLI and the schema snapshot see all of them); the toolset only decides what tools/list returns to a client. Fewer advertised tools means less schema in every request and better tool selection by agents, which is why "core" is the default.

const ReportFileName = "ARCHITECTURE_REPORT.md"

ReportFileName is the name of the markdown orientation report written by generateOrientationReport. By default it lives under <cache>/reports/<project>/; callers may request a path inside the checkout explicitly. The PreToolUse hook shell script references this name, so it is exported for cross-language consistency.

const ServiceMapEnv = "CODE_GRAPH_SERVICE_MAP"

ServiceMapEnv names the environment variable holding an explicit service-map JSON path.

Variables

var Version = "dev"

Version is the current release version, set from main.version via SetVersion(). Defaults to "dev" for local builds.

Functions

func ActiveToolset

func ActiveToolset() string

ActiveToolset returns the toolset selected by CODE_GRAPH_TOOLSET, defaulting to core. Unknown values fall back to core so a typo never silently exposes the full surface.

func CoreToolNames

func CoreToolNames() []string

CoreToolNames returns the sorted core toolset.

func FreshnessFromProject

func FreshnessFromProject(p *store.Project) (string, string)

FreshnessFromProject reads the project's IndexedAt and returns the (state, indexedAt) pair suitable for WithFreshness. Returns ("unknown", "") if the project is nil.

"current" is reported when the project record exists; "stale" is not distinguished here (would require comparing IndexedAt against the source-tree mtime, which the tool layer doesn't have access to from this call site). Tools that need finer-grained staleness should compute it themselves and call WithStaleness directly.

func RegisteredToolDefinitionsJSON

func RegisteredToolDefinitionsJSON() ([]byte, error)

RegisteredToolDefinitionsJSON returns the canonical JSON representation of the MCP tool definitions registered by the server. Registration only builds in-memory definitions: it does not start a transport, create a store, access the network, or invoke any tool handler.

func SetVersion

func SetVersion(v string)

SetVersion sets the package version from the build-injected main.version.

Types

type MetadataBuilder

type MetadataBuilder struct {
	// contains filtered or unexported fields
}

MetadataBuilder accumulates metadata fields for a single tool response. Use NewMetadataBuilder() to start; chain field setters; call Build() to produce the map for embedding.

Zero-valued fields are omitted from the output map so consumers don't see misleading "null" when the tool simply didn't compute that signal.

func NewMetadataBuilder

func NewMetadataBuilder() *MetadataBuilder

NewMetadataBuilder returns a fresh builder. All fields default to zero (omitted from output).

func (*MetadataBuilder) Build

func (b *MetadataBuilder) Build() map[string]any

Build produces the metadata map for embedding under "_metadata" in a tool's response. Only non-zero fields are included; the consumer sees exactly the signals the tool authentically produced.

func (*MetadataBuilder) WithActionOutcome

func (b *MetadataBuilder) WithActionOutcome(outcome string) *MetadataBuilder

WithActionOutcome records the outcome of a write-tool invocation. Use one of the ActionOutcome* constants. Empty string omits the field.

Plan 3 Phase C addition for write-tool metadata coverage (delete_project, index_repository, manage_adr write modes, ingest_traces).

func (*MetadataBuilder) WithConfidence

func (b *MetadataBuilder) WithConfidence(band, rationale string) *MetadataBuilder

WithConfidence records the confidence band ("high"/"medium"/"low"/ "speculative"/"unknown") and an optional rationale string.

func (*MetadataBuilder) WithFallback

func (b *MetadataBuilder) WithFallback(reason string) *MetadataBuilder

WithFallback records the reason a graceful-fallback path fired. Pass empty string to omit (no fallback occurred).

func (*MetadataBuilder) WithFreshness

func (b *MetadataBuilder) WithFreshness(state, indexedAt string) *MetadataBuilder

WithFreshness records when the underlying data was indexed. The state label is one of "current", "stale", or "unknown" (see schema).

If indexedAt is empty (project not found, or tool doesn't track index time), the freshness block is omitted from the output.

func (*MetadataBuilder) WithGrammarVersions

func (b *MetadataBuilder) WithGrammarVersions(versions map[string]string) *MetadataBuilder

WithGrammarVersions records the tree-sitter grammar SHAs that contributed to this result. Omit for tools that don't depend on tree-sitter parsing.

func (*MetadataBuilder) WithModel

func (b *MetadataBuilder) WithModel(model string) *MetadataBuilder

WithModel records the LLM model used by the tool, if any. Omit for non-LLM tools.

func (*MetadataBuilder) WithProvenance

func (b *MetadataBuilder) WithProvenance(toolVersion, dataSource string) *MetadataBuilder

WithProvenance records the tool version and data source. tool_version is typically the build's git SHA or semver; data_source is one of "index", "live-graph", or "external-api".

func (*MetadataBuilder) WithStaleness

func (b *MetadataBuilder) WithStaleness(seconds int64) *MetadataBuilder

WithStaleness records the staleness in seconds explicitly. Use this when the tool has a more precise signal than just indexed_at (e.g., computed against an mtime-based check).

type Server

type Server struct {
	// contains filtered or unexported fields
}

Server wraps the MCP server with tool handlers.

func NewServer

func NewServer(r *store.StoreRouter, opts ...ServerOption) *Server

NewServer creates a new MCP server with all tools registered.

func (*Server) AdvertisedToolNames

func (s *Server) AdvertisedToolNames() []string

AdvertisedToolNames returns the sorted tool names this server advertises over MCP under its toolset.

func (*Server) CallTool

func (s *Server) CallTool(ctx context.Context, name string, argsJSON json.RawMessage) (*mcp.CallToolResult, error)

CallTool invokes a tool handler directly by name, bypassing MCP transport.

func (*Server) MCPServer

func (s *Server) MCPServer() *mcp.Server

MCPServer returns the underlying MCP server.

func (*Server) Router

func (s *Server) Router() *store.StoreRouter

Router returns the underlying StoreRouter for direct access (e.g. CLI mode).

func (*Server) SessionProject

func (s *Server) SessionProject() string

SessionProject returns the auto-detected session project name (may be empty).

func (*Server) SetSessionRoot

func (s *Server) SetSessionRoot(rootPath string)

SetSessionRoot sets the session root path directly (for CLI mode).

func (*Server) StartWatcher

func (s *Server) StartWatcher(ctx context.Context)

StartWatcher launches the background file-change polling goroutine. It stores ctx for use by startAutoIndex and stops when ctx is cancelled.

func (*Server) ToolNames

func (s *Server) ToolNames() []string

ToolNames returns all registered tool names in sorted order.

func (*Server) Toolset

func (s *Server) Toolset() string

Toolset reports which toolset this server advertises.

type ServerOption

type ServerOption func(*Server)

ServerOption configures a Server.

func WithConfig

func WithConfig(c *store.ConfigStore) ServerOption

func WithToolset

func WithToolset(toolset string) ServerOption

WithConfig attaches a ConfigStore for reading runtime settings. WithToolset overrides CODE_GRAPH_TOOLSET for this server instance.