registry

type Category ¶

type Category string

Category enumerates the canonical groupings. New categories require code review — adding one without thinking through the existing seven leads to single-tool buckets that no UI can surface.

const (
	CategoryShell      Category = "shell"      // Bash, BashOutput, BashKill, Verify
	CategoryFile       Category = "file"       // Read, Edit, Write, Glob, Grep
	CategoryWeb        Category = "web"        // WebFetch, WebSearch, BrowserFetch, BrowserScrape, Portal*
	CategoryDispatch   Category = "dispatch"   // SendMessage, AgentList, Task*, TaskNotify
	CategoryAuthoring  Category = "authoring"  // McpNew/Run/Build/Install/List, SkillNew, AgentNew
	CategorySetup      Category = "setup"      // Recipe*, Bridge*, Sandbox*
	CategoryDiscovery  Category = "discovery"  // ToolSearch, SemanticSearch
	CategoryCheckpoint Category = "checkpoint" // Commit, RulesCheck (future: Snapshot, Restore)
)

type Manifest ¶

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

Manifest is the ordered collection of ToolSpec entries. Order matters for two reasons:

• server.go's RegisterX call order today is preserved during incremental migration so behaviour change is observable per-tool.
• tools/list output groups by Category but ties break on manifest order; deterministic output simplifies test fixtures.

func New() *Manifest

func (m *Manifest) Append(spec ToolSpec)

func (m *Manifest) Apply(s *server.MCPServer, rt Runtime, pred func(toolName string) bool)

func (m *Manifest) Names() []string

func (m *Manifest) SearchDocs(pred func(toolName string) bool) []search.Doc

func (m *Manifest) SortedNames() []string

func (m *Manifest) Specs() []ToolSpec

type RegisterFn ¶

type RegisterFn func(s *server.MCPServer, rt Runtime)

RegisterFn is the shape every typed register callback adopts. Mirrors mcp-go's AddTool but receives Runtime so register-time dependencies stay explicit — no package-level singletons leak into tool implementations.

type Runtime ¶

type Runtime struct {
	// Index is the bleve search index ToolSearch closes over.
	// Step 4 wires ToolSearch through the manifest, so this
	// field becomes load-bearing rather than aspirational.
	Index *search.Index

	// Secrets is the secrets store WebSearch reads its API key
	// from at registration time. Typed as *secrets.Store at the
	// importer's site (server.go / core); registry stays a leaf
	// by holding it as `any` and letting the per-tool register
	// fn type-assert. The trade-off (slightly worse type safety
	// at registration) is preferable to having registry depend
	// on internal/secrets — keeps the import graph linear.
	Secrets any
}

Runtime carries the cross-cutting dependencies a register fn might need. Passed by value (struct of pointers / interfaces) so the manifest stays composable and tests can stub fields independently. Add fields as new tools demand them; never remove without a deprecation cycle.

type ToolSpec ¶

type ToolSpec struct {
	// Name is the canonical MCP tool name. PascalCase per ADR-006.
	// MUST be unique within a Manifest; duplicates are a load-time
	// error.
	Name string

	// Description is the one-paragraph human form. Same string the
	// tool surfaces via tools/list AND ToolSearch.
	Description string

	// Keywords feed the bleve BM25 index. Lowercase, single words,
	// 3-12 entries is the sweet spot.
	Keywords []string

	// Category groups tools for introspection / grouping in
	// tools/list and the README. See package-level Category*
	// constants for the canonical set.
	Category Category

	// Gate names the config.IsEnabled key for this tool. Empty =
	// always-on (BridgeAdd / Verify / SemanticSearch / etc.).
	// "Bash" gate also covers BashOutput + BashKill (companions).
	Gate string

	// Register is the MCP wiring callback. Receives the server +
	// per-tool runtime dependencies (search index, secrets store,
	// sources manager) via the Runtime struct. Empty when the
	// tool is documented in the manifest but registered through
	// a legacy direct path — useful during incremental migration.
	Register RegisterFn
}

ToolSpec is the typed manifest entry for one MCP tool. Every shipped tool is described by exactly one ToolSpec. The fields match the four planes of the shipping contract (docs/feature-shipping-contract.md):

• Name + Description + Keywords → search index + ToolSearch
• Category → introspection + grouping
• Gate → config.IsEnabled subset
• Register → the actual MCP wiring

Slash command + skill row don't live on the spec because they're *file*-shaped (commands/clawtool-X.md, skills/clawtool/SKILL.md routing rows). The surface drift test (internal/server/surface_drift_test.go) cross-references the manifest against those files at test time.