Documentation
¶
Overview ¶
Package registry is how a katbyte MCP tool decides which of its tools a session gets, and what each tells a client about itself.
Tools are named resource-first (library_*, item_*, audit_*) and each is added with a kind: a read tool never changes what the server holds, a write tool does, and a delete tool removes what cannot be put back. A read-only session gets the read tools alone; the delete tools are held back until the operator asks for them; toolsets pick the groups a session needs, so a client loads a working subset rather than every definition; an allow list adds tools by name to whatever the toolsets hold; and a deny list takes tools out of what is left.
What is shared is the machinery. The tools, the toolsets they sit in and the hints each carries are the application's, given in a Config.
Index ¶
Constants ¶
const All = "all"
All is the toolset name that asks for every tool.
const Core = "core"
Core is the toolset every other assumes - enough to find things and open them - and is added to whatever sets a session asks for, when the application has one of that name.
const Essential = "essential"
Essential is the name an allow list asks for the application's preset by.
Variables ¶
This section is empty.
Functions ¶
func Add ¶
Add queues a typed tool. It sets the tool's MCP annotations from its kind and its hints, so a client can tell a read from a destructive write without parsing descriptions; turns a panic in the handler into an ordinary tool error; and sends every empty collection in an answer as [] rather than null, which a client cannot tell from "not fetched".
Types ¶
type Config ¶
type Config struct {
// Toolsets are the curated groups by name, each tool in one of them.
// The one named Core is added to whatever else is asked for.
Toolsets map[string][]string
// Essential is the preset an allow list names as "essential".
Essential []string
// Hints are the tools' hints by name.
Hints map[string]Hints
// LogError is where a handler's panic and its stack are written; nil is
// clog.Log.Errorf, which writes to stderr - stdout carries the protocol
// itself when serving stdio.
LogError func(format string, args ...any)
}
Config is the application's side of a registry.
type Hints ¶
type Hints struct {
// Additive is for a write tool that only ever adds - a new library, a
// new playlist - and never changes or takes away what was there: a
// value written over, a file replaced, a history cleared. MCP reads
// "not destructive" as exactly that.
Additive bool
// Idempotent is for a write tool that changes nothing more when called
// again with the same arguments.
Idempotent bool
// SendsOut is for a tool that itself sends something to a person or a
// service beyond the server it works on: an email, a notification. A
// tool that makes the server fetch from its own providers, or hand
// work to its own download client, does not. MCP's name for the hint
// is "open world".
SendsOut bool
// WritesHere is for a read tool that writes a file on the machine it
// runs on. The server is only read, so it stays a read tool and a
// read-only session keeps it, but it does not claim to change nothing.
WritesHere bool
}
Hints are what a tool tells a client about itself beyond its kind, in the terms of the MCP annotations. The zero value is the answer that warns: a write tool with no hints of its own is marked destructive.
type Info ¶
type Info struct {
Name string
// Kind is read, write or delete
Kind string
// Toolset is the curated set the tool belongs to
Toolset string
Description string
}
Info describes a tool a selection would register.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry collects an application's tools before any is registered, so a selection can be checked against all of them: a pattern that names no tool is refused rather than quietly hiding one.
func (*Registry) Describe ¶
Describe lists the tools a selection would register, by name, with nothing registered: the same choice Register makes, so what a tool says it would serve cannot drift from what it serves.
func (*Registry) FamilyNames ¶
FamilyNames lists the resource families a toolset entry may name - the part of each tool's name before its first underscore - sorted. They are read off the tools added, so they cannot go stale.
func (*Registry) Names ¶
Names is every tool added, whatever a selection would make of it, in the order added.
func (*Registry) Register ¶
Register adds every tool the selection permits to the server and answers with the names registered, sorted. It fails when the selection names a toolset or a pattern that reaches no tool, so a typo cannot hide one.
func (*Registry) ToolsetNames ¶
ToolsetNames lists the curated toolsets, sorted, for help output.
type Selection ¶
type Selection struct {
// ReadOnly keeps the read tools alone.
ReadOnly bool
// EnableDelete lets the delete tools in.
EnableDelete bool
// Toolsets are the sets asked for, each entry a name or several joined
// by commas: a curated set, All, or a resource family (every tool whose
// name begins with it, "library" for library_*). None is every tool.
Toolsets []string
// Allow asks for tools by name: exact names, a pattern with one "*" at
// either end (library_*, *_delete), or Essential. Beside Toolsets it
// adds to them, "these sets and these tools as well"; on its own it is
// only the tools it names, with no Core added. It lets nothing past
// ReadOnly or EnableDelete.
Allow []string
// Deny takes out the tools it names, the same way, from whatever the
// toolsets and the allow list asked for: it is how a toolset is
// narrowed.
Deny []string
}
Selection is what one session asks for.