registry

package
v0.7.0 Latest Latest
Warning

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

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

Documentation

Overview

Package registry decides which of an MCP server's tools a session gets, what each tells a client about itself, and what stands around every call.

Each tool is added with a kind: read, write, or delete for what cannot be put back. A read-only session gets the read tools; the delete tools wait for the operator to ask; toolsets, an allow list and a deny list narrow the rest. Around every call: a panic becomes an error, empty lists go out as [], a line is written for each write with its credentials blanked, and a failure's words and, when asked, an answer's are cleaned of what should not reach a model. The tools themselves are the application's (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; it is added to whatever a session asks for.

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 with its annotations set from its kind and hints, and wraps it: a panic becomes a tool error, an empty list or map goes out as [] or {} rather than null, and the answer is cleaned as the Config asks. A tool whose input is any takes no arguments and now says so in its schema, where the SDK's would accept anything.

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 go; nil is the shared log, on stderr, since stdout carries the protocol over stdio.
	LogError func(format string, args ...any)
	// LogWrite is where one line goes for every call of a write or a delete tool: the tool, what it was sent with credentials blanked, and how it
	// ended. nil is the shared log at info, which a tool does not show at its default level: the line is there for whoever sets the log to info.
	LogWrite func(format string, args ...any)
	// SecretArguments are argument names, at any depth, whose values the write line blanks whole, whatever their type: a file's text, a command and
	// its flags, an address whose path is the secret. Blanked unasked are arguments named as a credential (chttp.SecretName), everything under a
	// free-form object such as a settings map, and in any address the sign-in, the query values and the fragment.
	SecretArguments []string
	// ShownArguments are, by tool, the free-form arguments that hold no credential and are written as sent: a server's own settings, checked against
	// a list. They are shown only for a call the tool answered: one it refused or failed was never held to that list, so it is blanked like any
	// other. A credential-named field under one is always blanked.
	ShownArguments map[string][]string
	// CleanAnswers, when above 0, has every piece of text in every answer and refusal cleaned as text from outside is (outside.Text) and cut to this
	// many characters, once, here, rather than by each tool. It stays off until a server has named what to leave as it is.
	CleanAnswers int
	// LeaveAsIs are the answer fields, by JSON name, that a later call hands back: a path, a release's id. They must go back as they came, so they
	// and everything under them are left uncleaned (LeaveAsIsUnused finds a stale name).
	LeaveAsIs []string
	// BlankAddresses are the answer fields, by JSON name, that carry a server's own words for what went wrong: a failed test's failures, a health
	// check's message, a log's lines. A server quotes an address there with its stored key on it, so addresses under these names lose their sign-in,
	// query values and fragment (outside.BlankAddresses). Other answers are left alone: a link a caller follows needs its query. BlankAddressesUnused
	// finds a stale name.
	BlankAddresses []string
}

Config is the application's side of a registry.

type Hints

type Hints struct {
	// Additive is a write tool that only ever adds, a new library or playlist, and never changes or removes what was there.
	Additive bool
	// Idempotent is a write tool that changes nothing more when called again with the same arguments.
	Idempotent bool
	// SendsOut is a tool that itself sends something to a person or a service beyond the server: an email, a notification. Making the server fetch
	// from its own providers does not count. MCP calls this "open world".
	SendsOut bool
	// Installs is a tool that has the server bring something in from outside and run it, an app or a plug-in. MCP marks it "open world" too.
	Installs bool
	// WritesHere is a read tool that writes a file on the machine it runs on: still a read tool, kept in a read-only session, but not one that claims
	// to change nothing.
	WritesHere bool
}

Hints are what a tool tells a client about itself beyond its kind, as MCP annotations. The zero value warns: a write tool with no hints 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 is 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) BlankAddressesUnused added in v0.6.2

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

BlankAddressesUnused is the same check for Config.BlankAddresses.

func (*Registry) Describe

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

Describe lists what a selection would register without registering it, by the same choice Register makes, so help cannot drift from service.

func (*Registry) FamilyNames

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

FamilyNames lists the resource families, the part of each tool's name before its first underscore, sorted and read off the tools themselves.

func (*Registry) LeaveAsIsUnused added in v0.6.2

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

LeaveAsIsUnused is the names in Config.LeaveAsIs that no tool answers a field under, for a server's test to hold to none: a name left behind by a rename protects nothing. Only fields count; a name used as a map key is reported too.

func (*Registry) Names

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

Names is every tool added, in the order added.

func (*Registry) Register

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

Register adds the tools the selection permits and returns their names, sorted. A toolset or pattern that reaches no tool is an error, so a typo cannot quietly 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 ("library" for
	// library_*). None is every tool.
	Toolsets []string
	// Allow asks for tools by name: exact, a pattern with one "*" at either end, or Essential. With Toolsets it adds to them; alone it is only these,
	// with no Core. It lets nothing past ReadOnly or EnableDelete.
	Allow []string
	// Deny takes tools out, named the same way, from whatever was asked for.
	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