Documentation
¶
Index ¶
- func CanonicalToolName(serverName, name string) string
- type Admission
- type BleveIndex
- func (b *BleveIndex) BatchIndex(tools []*config.ToolMetadata) error
- func (b *BleveIndex) Close() error
- func (b *BleveIndex) DeleteAll() error
- func (b *BleveIndex) DeleteServerTools(serverName string) error
- func (b *BleveIndex) DeleteTool(serverName, toolName string) error
- func (b *BleveIndex) GetAllIndexedServerNames() ([]string, error)
- func (b *BleveIndex) GetDocumentCount() (uint64, error)
- func (b *BleveIndex) GetToolsByServer(serverName string) ([]*config.ToolMetadata, error)
- func (b *BleveIndex) IndexTool(toolMeta *config.ToolMetadata) error
- func (b *BleveIndex) RebuildIndex() error
- func (b *BleveIndex) ScopedDocumentCount(inScope func(serverName string) bool) (uint64, error)
- func (b *BleveIndex) SearchTools(queryStr string, limit int) ([]*config.SearchResult, error)
- func (b *BleveIndex) SearchToolsAdmitted(queryStr string, limit int, admit func(Hit) Admission) (results []*config.SearchResult, hiddenByPolicy int, err error)
- func (b *BleveIndex) SearchToolsScoped(queryStr string, limit int, inScope func(serverName string) bool) ([]*config.SearchResult, error)
- type Hit
- type Manager
- func (m *Manager) BatchIndexTools(tools []*config.ToolMetadata) error
- func (m *Manager) ClearAll() error
- func (m *Manager) Close() error
- func (m *Manager) DeleteServerTools(serverName string) error
- func (m *Manager) DeleteTool(serverName, toolName string) error
- func (m *Manager) DropProfile(slug string) error
- func (m *Manager) ExistingProfileDirs() ([]string, error)
- func (m *Manager) ForProfile(slug string) (*Manager, error)
- func (m *Manager) GetAllIndexedServerNames() ([]string, error)
- func (m *Manager) GetDocumentCount() (uint64, error)
- func (m *Manager) GetStats() (map[string]interface{}, error)
- func (m *Manager) GetToolsByServer(serverName string) ([]*config.ToolMetadata, error)
- func (m *Manager) IndexTool(toolMeta *config.ToolMetadata) error
- func (m *Manager) ProfileSlugs() []string
- func (m *Manager) RebuildIndex() error
- func (m *Manager) RebuildProfileFromShared(slug string, servers []string) error
- func (m *Manager) ScopedDocumentCount(inScope func(serverName string) bool) (uint64, error)
- func (m *Manager) Search(query string, limit int) ([]*config.SearchResult, error)
- func (m *Manager) SearchTools(query string, limit int) ([]*config.SearchResult, error)
- func (m *Manager) SearchToolsAdmitted(query string, limit int, admit func(Hit) Admission) ([]*config.SearchResult, int, error)
- func (m *Manager) SearchToolsScoped(query string, limit int, inScope func(serverName string) bool) ([]*config.SearchResult, error)
- type ToolDocument
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CanonicalToolName ¶ added in v0.52.0
CanonicalToolName returns the tool's full "server:tool" identity. Discovery stores the bare tool name in the index (ToolMetadata{ServerName:"github", Name:"create_issue"}), so the read seams must reattach the server prefix for consumers (retrieve_tools/describe_tool/call_tool_*) that require it (#871). The double-prefix guard is mandatory: legacy index data and test fixtures may already store a prefixed name — those pass through unchanged.
Types ¶
type Admission ¶ added in v0.70.0
type Admission int
Admission is admit's per-hit verdict for SearchToolsAdmitted.
const ( // Admit means the hit is visible to this caller and counts toward limit. Admit Admission = iota // RejectScope means the hit's server is outside the caller's effective // scope (agent-token allowed_servers, profile server set). Never counted // in hiddenByPolicy — an out-of-scope tool must stay invisible, not merely // "hidden by profile" (FR-011). RejectScope // RejectPolicy means the hit's server was in scope but the tool policy // (Spec 108 CompiledPolicy.Decide) excluded it. Counted in hiddenByPolicy. RejectPolicy )
type BleveIndex ¶
type BleveIndex struct {
// contains filtered or unexported fields
}
BleveIndex wraps Bleve index operations
func NewBleveIndex ¶
func NewBleveIndex(dataDir string, logger *zap.Logger) (*BleveIndex, error)
NewBleveIndex creates (or opens) the shared default Bleve index at <dataDir>/index.bleve.
func (*BleveIndex) BatchIndex ¶
func (b *BleveIndex) BatchIndex(tools []*config.ToolMetadata) error
BatchIndex indexes multiple tools in a single batch
func (*BleveIndex) DeleteAll ¶ added in v0.46.0
func (b *BleveIndex) DeleteAll() error
DeleteAll removes every document from the index, leaving an empty index in place. Used to rebuild a per-profile index from scratch without recreating its on-disk directory.
func (*BleveIndex) DeleteServerTools ¶
func (b *BleveIndex) DeleteServerTools(serverName string) error
DeleteServerTools removes all tools from a specific server
func (*BleveIndex) DeleteTool ¶
func (b *BleveIndex) DeleteTool(serverName, toolName string) error
DeleteTool removes a tool from the index, addressed by its exact raw name.
func (*BleveIndex) GetAllIndexedServerNames ¶ added in v0.16.6
func (b *BleveIndex) GetAllIndexedServerNames() ([]string, error)
GetAllIndexedServerNames returns the unique set of server names present in the index.
func (*BleveIndex) GetDocumentCount ¶
func (b *BleveIndex) GetDocumentCount() (uint64, error)
GetDocumentCount returns the number of documents in the index
func (*BleveIndex) GetToolsByServer ¶
func (b *BleveIndex) GetToolsByServer(serverName string) ([]*config.ToolMetadata, error)
GetToolsByServer retrieves all tools from a specific server
func (*BleveIndex) IndexTool ¶
func (b *BleveIndex) IndexTool(toolMeta *config.ToolMetadata) error
IndexTool indexes a tool document
func (*BleveIndex) RebuildIndex ¶
func (b *BleveIndex) RebuildIndex() error
RebuildIndex re-creates the index with the current mapping and re-indexes every document it holds.
The source is the index's own stored fields, not BBolt storage: every ToolDocument field except searchable_text is stored (and searchable_text is derived from stored fields), whereas storage keeps no annotations or index hash. Copying the stored fields also keeps full_tool_name byte-for-byte — round-tripping through config.ToolMetadata would rewrite it to the canonical id and move scores (see toolDocument).
The new index is built completely in a sibling directory and only then swapped in (swapIndexDir), so a failure before the swap leaves the current index untouched and open. The caller must hold exclusive access (Manager.RebuildIndex takes its write lock).
func (*BleveIndex) ScopedDocumentCount ¶ added in v0.68.0
func (b *BleveIndex) ScopedDocumentCount(inScope func(serverName string) bool) (uint64, error)
ScopedDocumentCount returns the number of indexed documents belonging to servers inScope admits (Spec 105 FR-005 G4): a `server_name` facet term count, summed over only the terms inScope admits, so a scoped caller's `debug.total_indexed_tools` counts its own authorized population rather than the whole index regardless of which physical index (shared or per-profile) backs the search that produced the response. A nil inScope admits nothing (fail closed, matching SearchToolsScoped).
The facet's term size is the document count itself, never a fixed constant: a `server_name` facet returns at most that many distinct terms (one document contributes to exactly one term), so this is a PROVEN exact upper bound rather than a "should be big enough" guess — a fixed cap (the pattern GetAllIndexedServerNames uses) can silently spill excess servers into Bleve's "Other" bucket and undercount an authorized population once the fleet exceeds it (Spec 105 PR C review finding).
func (*BleveIndex) SearchTools ¶
func (b *BleveIndex) SearchTools(queryStr string, limit int) ([]*config.SearchResult, error)
SearchTools searches for tools using multiple query strategies for better results
func (*BleveIndex) SearchToolsAdmitted ¶ added in v0.70.0
func (b *BleveIndex) SearchToolsAdmitted(queryStr string, limit int, admit func(Hit) Admission) (results []*config.SearchResult, hiddenByPolicy int, err error)
SearchToolsAdmitted is SearchToolsScoped's hit-level counterpart (Spec 108 FR-011, data-model.md §2): the pre-limit predicate sees the hit's canonical (server, tool) identity — never a stored annotation, the index carries none — and returns one of three verdicts instead of a bool, so the caller can tell an out-of-scope rejection (never counted, stays invisible) from a policy-only one (counted in hiddenByPolicy, the FR-011 `hidden_by_profile` figure) over the SAME exhaustive pre-limit scan SearchToolsScoped already runs. limit is applied to ADMITTED hits only — a rejected top hit, whatever its reason, never shortens the page — and hiddenByPolicy accumulates over the full match set, not merely the hits collected before the cut, so a caller whose page filled up before scanning every match still gets an accurate count.
Identical to SearchToolsScoped in query construction (incl. the underscore-segment enhancement) and score-then-id sort. It differs in ONE respect, precisely because of the counting requirement above: SearchToolsScoped returns as soon as its page fills, while this method keeps paging to the end of the exhaustive match set regardless (zcode review round 1 — an early return there silently undercounted hiddenByPolicy for any RejectPolicy hit ranked below the cut). A predicate that only ever returns Admit/RejectScope (never RejectPolicy) still makes this method's RESULT SET equal SearchToolsScoped(query, limit, func(s string) bool { admit still sees the server only })'s exactly (T016a) — the extra scanning costs work, never a different admitted page.
func (*BleveIndex) SearchToolsScoped ¶ added in v0.68.0
func (b *BleveIndex) SearchToolsScoped(queryStr string, limit int, inScope func(serverName string) bool) ([]*config.SearchResult, error)
SearchToolsScoped is SearchTools for a caller who may see only some servers (Spec 107 T075a; Spec 105 "Ranking under scope"): the result is the top- `limit` of the SAME ranked search, filtered to servers `inScope` admits BEFORE the cut, with the unfiltered scores. It runs the identical boolean query — including the underscore-segment enhancement SearchTools(queryStr, limit) would apply for the same query and limit (augmentedToolSearchQuery; Spec 105 FR-005 G1 review finding — a scoped caller's ranking for an identifier-style query must not silently miss the boost an equal-limit unscoped call would have used), and never a Must term on server_name (that would change scores) — and the identical score-then-id sort, and pages through the ranked result EXHAUSTIVELY with From/Size: each page is filtered through inScope, and paging stops only when `limit` in-scope hits have been collected or the window has passed searchResult.Total. There is deliberately NO result cap: any cap would let a hidden population larger than the cap displace an entitled hit, and make membership and `total` differ between a corpus that contains the hidden servers and one that does not — the existence oracle FR-010 forbids. A caller whose predicate is nil sees nothing (fail closed) without a search.
type Hit ¶ added in v0.70.0
Hit is the canonical registration identity SearchToolsAdmitted hands to its predicate (Spec 108 FR-011, data-model.md §2): the exact (server, raw tool) pair a hit resolves to, NEVER a stored annotation — the index carries no annotation field and gains none (ToolDocument/readToolMetadata are unchanged; research.md "Annotation source for SearchToolsAdmitted"). A caller that needs the tool's effective annotations resolves them itself, through the same identity seam every dispatch path already uses (profile.EffectiveAnnotations = resolveExactToolIdentity), keeping discovery and execution classifying from one source.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager provides a unified interface for indexing operations.
A root Manager (created via NewManager) owns the shared default index at <dataDir>/index.bleve plus a lazily-populated map of per-profile sub-Managers (Profiles v2, Spec 057). Each sub-Manager, obtained via ForProfile, wraps its own index at <dataDir>/index.bleve/profiles/<slug>/ and reuses the full Manager method surface. Sub-Managers do not themselves nest further (their profiles map is nil), so ForProfile is only meaningful on the root.
func NewManager ¶
NewManager creates a new root index manager backed by the shared default index.
func (*Manager) BatchIndexTools ¶
func (m *Manager) BatchIndexTools(tools []*config.ToolMetadata) error
BatchIndexTools indexes multiple tools efficiently
func (*Manager) ClearAll ¶ added in v0.46.0
ClearAll removes every document from this index, leaving it empty.
func (*Manager) DeleteServerTools ¶
DeleteServerTools removes all tools from a specific server
func (*Manager) DeleteTool ¶
DeleteTool removes a tool from the index
func (*Manager) DropProfile ¶ added in v0.46.0
DropProfile closes the named profile's index (if open) and removes its on-disk directory. It is a no-op if the profile was never opened and its directory does not exist. The empty (default) slug cannot be dropped.
func (*Manager) ExistingProfileDirs ¶ added in v0.46.0
ExistingProfileDirs returns the slugs of every per-profile index directory present on disk under <dataDir>/index.bleve/profiles/, regardless of whether it is currently open. Only valid, filesystem-safe slug directories are returned. Used to reclaim orphaned profile indexes left by a prior run.
func (*Manager) ForProfile ¶ added in v0.46.0
ForProfile returns the index Manager scoped to the named profile, backed by a physically separate index at <dataDir>/index.bleve/profiles/<slug>/. The per-profile index is opened (or created) lazily on first use and cached, so repeated calls for the same slug return the same handle. An empty slug returns the root (shared default) Manager. The slug must be a valid, filesystem-safe profile slug (see config.IsValidProfileSlug) — invalid slugs are rejected to prevent path traversal. Only valid on a root Manager.
func (*Manager) GetAllIndexedServerNames ¶ added in v0.16.6
GetAllIndexedServerNames returns all unique server names in the index.
func (*Manager) GetDocumentCount ¶
GetDocumentCount returns the number of indexed documents
func (*Manager) GetToolsByServer ¶
func (m *Manager) GetToolsByServer(serverName string) ([]*config.ToolMetadata, error)
GetToolsByServer retrieves all tools from a specific server
func (*Manager) IndexTool ¶
func (m *Manager) IndexTool(toolMeta *config.ToolMetadata) error
IndexTool indexes a single tool
func (*Manager) ProfileSlugs ¶ added in v0.46.0
ProfileSlugs returns the slugs of all currently open per-profile indexes.
func (*Manager) RebuildIndex ¶
RebuildIndex re-creates this Manager's index with the current mapping, keeping every document (see BleveIndex.RebuildIndex).
On the root, the rebuild renames the shared index directory, which also holds the per-profile indexes. Open profile indexes are closed and dropped first — Windows cannot rename a directory with open files inside — and ForProfile reopens them lazily, unchanged. A caller still holding a dropped sub-Manager gets errors from its closed index, as after DropProfile.
func (*Manager) RebuildProfileFromShared ¶ added in v0.46.0
RebuildProfileFromShared (re)builds the named profile's index to contain exactly the tools of the given servers, sourced from the shared default index. The profile index is cleared first, so the operation is idempotent and only ever touches the named profile — other profiles are left untouched (reload isolation). Servers with no indexed tools contribute nothing; an empty server list yields an empty profile index.
func (*Manager) ScopedDocumentCount ¶ added in v0.68.0
ScopedDocumentCount is GetDocumentCount filtered to servers inScope admits (Spec 105 FR-005 G4). See BleveIndex.ScopedDocumentCount.
func (*Manager) SearchTools ¶
SearchTools searches for tools matching the query
func (*Manager) SearchToolsAdmitted ¶ added in v0.70.0
func (m *Manager) SearchToolsAdmitted(query string, limit int, admit func(Hit) Admission) ([]*config.SearchResult, int, error)
SearchToolsAdmitted is SearchToolsScoped's hit-level counterpart (Spec 108 FR-011): the predicate resolves per-hit Admission (Admit/RejectScope/ RejectPolicy) over the canonical (server, tool) identity. See BleveIndex.SearchToolsAdmitted.
func (*Manager) SearchToolsScoped ¶ added in v0.68.0
func (m *Manager) SearchToolsScoped(query string, limit int, inScope func(serverName string) bool) ([]*config.SearchResult, error)
SearchToolsScoped is SearchTools filtered to the servers inScope admits BEFORE the ranked cut (Spec 107 T075a). See BleveIndex.SearchToolsScoped.
type ToolDocument ¶
type ToolDocument struct {
ToolName string `json:"tool_name"` // Just the tool name (without server prefix)
FullToolName string `json:"full_tool_name"` // Complete server:tool format
ServerName string `json:"server_name"`
Description string `json:"description"`
ParamsJSON string `json:"params_json"`
OutputSchemaJSON string `json:"output_schema_json,omitempty"`
Hash string `json:"hash"`
Tags string `json:"tags"`
SearchableText string `json:"searchable_text"` // Combined searchable content
// AnnotationsJSON is the tool's MCP behavior-hint annotations
// (config.ToolAnnotations), marshaled once at index time. Stored but not
// indexed for search, same as Hash — it exists so a search hit's tier
// (Spec 109 FR-028) reflects the tool's real annotations instead of
// always reading TierUnannotated (review round 1: GET /index/search never
// stored annotations at all, so a search hit's tier could not agree with
// the same tool's tier on GET /servers/{id}/tools).
AnnotationsJSON string `json:"annotations_json,omitempty"`
}
ToolDocument represents a tool document in the index