registry

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: GPL-3.0 Imports: 18 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.

func LimitOr added in v0.8.0

func LimitOr(limit, def int) int

LimitOr is the page size a call asked for, or def when it asked for none.

func NextOffset added in v0.8.0

func NextOffset(offset, n, total int) int

NextOffset is where the page after one of n rows from offset starts, out of total, or 0 when that page was the last.

func WaitFor added in v0.8.0

func WaitFor(seconds int, def time.Duration) time.Duration

WaitFor is how long a call asked to wait for a job it started, in seconds: def when it did not say, and no wait at all when it asked for less than none.

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 (httpc.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