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
- func Add[In, Out any](r *Registry, kind Kind, t *mcp.Tool, h mcp.ToolHandlerFor[In, Out])
- type Config
- type Hints
- type Info
- type Kind
- type Registry
- func (r *Registry) BlankAddressesUnused() []string
- func (r *Registry) Describe(sel Selection) ([]Info, error)
- func (r *Registry) FamilyNames() []string
- func (r *Registry) LeaveAsIsUnused() []string
- func (r *Registry) Names() []string
- func (r *Registry) Register(server *mcp.Server, sel Selection) ([]string, error)
- func (r *Registry) ToolsetNames() []string
- type Selection
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; it is added to whatever a session asks for.
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 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.
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. A credential-named field under one is still 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 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 (*Registry) BlankAddressesUnused ¶ added in v0.6.2
BlankAddressesUnused is the same check for Config.BlankAddresses.
func (*Registry) Describe ¶
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 ¶
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
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) Register ¶
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 ¶
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.