registry

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: GPL-3.0 Imports: 9 Imported by: 1

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

View Source
const All = "all"

All is the toolset name that asks for every tool.

View Source
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.

View Source
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

func Add[In, Out any](r *Registry, kind Kind, t *mcp.Tool, h mcp.ToolHandlerFor[In, Out])

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
	// OpenWorld is for a tool that reaches past the server it works on:
	// one that sends an email.
	OpenWorld 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 Kind

type Kind int

Kind is what a tool does to the server it works on.

const (
	// Read never changes what the server holds.
	Read Kind = iota
	// Write changes it, and is left out of a read-only session.
	Write
	// Delete removes what cannot be put back, and is registered only when
	// the operator asks for the delete tools.
	Delete
)

func (Kind) String

func (k Kind) String() string

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 New

func New(cfg Config) *Registry

New makes an empty registry.

func (*Registry) Describe

func (r *Registry) Describe(sel Selection) ([]Info, error)

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

func (r *Registry) FamilyNames() []string

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

func (r *Registry) Names() []string

Names is every tool added, whatever a selection would make of it, in the order added.

func (*Registry) Register

func (r *Registry) Register(server *mcp.Server, sel Selection) ([]string, error)

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

func (r *Registry) ToolsetNames() []string

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL