mcp

package
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Jul 23, 2026 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BuildPromptScriptHandler added in v0.16.1 

func BuildPromptScriptHandler(scriptPath string, cfg HandlerConfig) (mcplib.PromptHandler, error)

BuildPromptScriptHandler builds a PromptHandler that runs a Scriptling script. The script receives the prompt arguments as parameters and returns messages via mcp.tool.return_object({"messages": [{"role": ..., "content": ...}]}) (a bare string is treated as a single user message).

func BuildPromptScriptHandlerSource added in v0.18.0 

func BuildPromptScriptHandlerSource(src []byte, cfg HandlerConfig) mcplib.PromptHandler

BuildPromptScriptHandlerSource is BuildPromptScriptHandler for in-memory script source (e.g. from a pack bundle).

func BuildResourceScriptHandler added in v0.16.1 

func BuildResourceScriptHandler(scriptPath, mimeType string, cfg HandlerConfig) (mcplib.ResourceHandler, error)

BuildResourceScriptHandler builds a ResourceHandler that runs a Scriptling script. The script receives the request URI as "__uri" and any template variables as parameters (read via mcp.tool.get_string), and returns the resource content via mcp.tool.return_string / return_object.

func BuildResourceScriptHandlerSource added in v0.18.0 

func BuildResourceScriptHandlerSource(src []byte, mimeType string, cfg HandlerConfig) mcplib.ResourceHandler

BuildResourceScriptHandlerSource is BuildResourceScriptHandler for in-memory script source (e.g. from a pack bundle).

func BuildStaticPromptHandler added in v0.16.1 

func BuildStaticPromptHandler(read func() ([]byte, error)) mcplib.PromptHandler

BuildStaticPromptHandler returns a PromptHandler whose single user message is the content returned by read (called fresh each time).

func BuildStaticResourceHandler added in v0.16.1 

func BuildStaticResourceHandler(read func() ([]byte, error), uri, mimeType string) mcplib.ResourceHandler

BuildStaticResourceHandler serves content verbatim: text for UTF-8 data, base64 blob otherwise. read is called on every request so content is always current (e.g. FileReader for disk, a bundle read for packs).

func BuildToolHandler added in v0.16.1 

func BuildToolHandler(scriptPath string, cfg HandlerConfig) (mcplib.ToolHandler, error)

BuildToolHandler reads the script once at registration time and returns a ToolHandler that runs a fresh interpreter per invocation. The script receives its parameters via mcp.tool.get_* helpers and returns its result via mcp.tool.return_string / return_object / return_error.

Tool scripts resolve imports only via the configured library dirs (and pack loader); pass the tools dir in cfg.LibDirs if sibling imports are needed.

func BuildToolHandlerFunc added in v0.18.0 

func BuildToolHandlerFunc(src []byte, funcName string, cfg HandlerConfig) mcplib.ToolHandler

BuildToolHandlerFunc builds a ToolHandler for a decorated tool. Unlike BuildToolHandlerSource (which runs the entire script as a top-level program), this handler evaluates the source to define the function, then calls the named function with the MCP request parameters mapped to keyword arguments. The function's return value becomes the tool response:

  • string → text response
  • dict/list → JSON response
  • None/null → empty text response
  • tool.return_error("msg") → MCP error response (isError: true)
  • tool.return_string("msg") → text response
  • tool.return_object(obj) → JSON response
  • exception → error response

func BuildToolHandlerSource added in v0.18.0 

func BuildToolHandlerSource(src []byte, cfg HandlerConfig) mcplib.ToolHandler

BuildToolHandlerSource is BuildToolHandler for in-memory script source (e.g. from a pack bundle).

func DecodePromptScriptResponse added in v0.16.1 

func DecodePromptScriptResponse(response string) *mcplib.PromptResponse

DecodePromptScriptResponse interprets a prompt script's return value into a PromptResponse. Accepted shapes: a JSON object {"description":..., "messages": [{"role","content"}]}, a JSON array of messages, or a plain string (single user message).

func FileReader added in v0.18.0 

func FileReader(path string) func() ([]byte, error)

FileReader returns a read function over os.ReadFile, for use with the static handler builders.

func ScanPromptsFS added in v0.18.0 

func ScanPromptsFS(fsys fs.FS) ([]scannedPrompt, error)

ScanPromptsFS scans fsys for prompts. A prompt is dynamic when a name.toml (with sibling name.py) is present, or static when only a name.md/name.txt is present. If both exist for a name, the dynamic one wins. FilePath in the results is the slash path within fsys.

func ScanPromptsFolder added in v0.16.0 

func ScanPromptsFolder(dir string) ([]scannedPrompt, error)

ScanPromptsFolder scans a prompts folder on disk. FilePath in the results is a disk path.

func ScanResourcesFS added in v0.18.0 

func ScanResourcesFS(fsys fs.FS) ([]scannedResource, error)

ScanResourcesFS walks fsys and returns every resource (static or template) it describes. FilePath in the results is the slash path within fsys.

func ScanResourcesTree added in v0.16.0 

func ScanResourcesTree(dir string) ([]scannedResource, error)

ScanResourcesTree walks a resources directory on disk and returns every resource it describes. FilePath in the results is a disk path.

func ScanToolsFS added in v0.18.0 

func ScanToolsFS(fsys fs.FS) (map[string]*toolmetadata.ToolMetadata, error)

ScanToolsFS scans fsys (flat, root only) for .toml files and returns tool metadata keyed by tool name.

func ScanToolsFolder 

func ScanToolsFolder(toolsFolder string) (map[string]*toolmetadata.ToolMetadata, error)

ScanToolsFolder scans a tools folder on disk for .toml files and returns metadata.

Types

type DecoratedTool added in v0.18.0 

type DecoratedTool struct {
	Name     string
	Meta     *toolmetadata.ToolMetadata
	FuncName string // function to call within the source
	Source   []byte // the full .py file source
}

DecoratedTool represents a tool discovered via the @mcp.tool() decorator in a .py file (no .toml sidecar).

func ScanDecoratedTools added in v0.18.0 

func ScanDecoratedTools(src []byte, cfg HandlerConfig) ([]DecoratedTool, error)

ScanDecoratedTools evaluates a .py source in a fresh interpreter with runtime.mcp registered, then reads __mcp_registry to discover decorated tools. For each entry it builds ToolMetadata by cross-referencing the decorator's params dict with the function's signature (name from __name__, required from presence of defaults).

type HandlerConfig added in v0.16.1 

type HandlerConfig struct {
	LibDirs        []string
	AllowedPaths   []string                     // nil = unrestricted
	DisabledLibs   []string                     // nil = all built-ins enabled
	SecretRegistry *secretprovider.Registry     // nil = empty registry
	Logger         logger.Logger                // nil = null logger
	PackLoader     *pack.Loader                 // nil = no pack loader
	PluginManager  *scriptlingplugin.Manager    // nil = no plugins
	DockerSock     string                       // empty = default socket
	PodmanSock     string                       // empty = default socket
	Argv           []string                     // extra CLI args for sys.argv (nil = skip sys registration)
	SetupHook      func(*scriptling.Scriptling) // optional extra setup applied after standard libs
}

HandlerConfig bundles the runtime context needed to build script-backed MCP tool, resource, and prompt handlers. With the exception of LibDirs, every field is optional: a nil SecretRegistry uses an empty one, a nil Logger uses a null logger, and a nil PackLoader / PluginManager simply skips pack / plugin wiring. Built-in libraries can be selectively disabled via DisabledLibs and the filesystem access of os/pathlib/glob/fs/grep/sed can be constrained with AllowedPaths (nil means unrestricted, matching scriptling-cli/server's default).

func NewHandlerConfig added in v0.16.1 

func NewHandlerConfig(libDirs []string, opts ...HandlerOption) HandlerConfig

NewHandlerConfig builds a HandlerConfig from the given lib dirs plus any number of options. It is the recommended entry point for hosts constructing tool/resource/prompt handlers.

type HandlerOption added in v0.16.1 

type HandlerOption func(*HandlerConfig)

HandlerOption configures a HandlerConfig.

func WithAllowedPaths added in v0.16.1 

func WithAllowedPaths(paths []string) HandlerOption

WithAllowedPaths returns an option that constrains os/pathlib/glob/fs/grep/sed to the given paths. nil means unrestricted, an empty slice denies all.

func WithArgv added in v0.18.0 

func WithArgv(argv []string) HandlerOption

WithArgv returns an option that sets the extra CLI args exposed via sys.argv in every handler's evaluator.

func WithDisabledLibs added in v0.16.1 

func WithDisabledLibs(names []string) HandlerOption

WithDisabledLibs returns an option that disables the named built-in libraries.

func WithDockerSock added in v0.18.0 

func WithDockerSock(sock string) HandlerOption

WithDockerSock returns an option that sets the Docker socket path used by the container library inside the script interpreter.

func WithLogger added in v0.16.1 

func WithLogger(l logger.Logger) HandlerOption

WithLogger returns an option that supplies the logger used by the logging library inside the script interpreter.

func WithPackLoader added in v0.16.1 

func WithPackLoader(pl *pack.Loader) HandlerOption

WithPackLoader returns an option that chains a pack loader behind the filesystem library loader of every handler's interpreter.

func WithPlugins added in v0.16.1 

func WithPlugins(pm *scriptlingplugin.Manager) HandlerOption

WithPlugins returns an option that attaches a plugin manager to every handler built from the resulting HandlerConfig.

func WithPodmanSock added in v0.18.0 

func WithPodmanSock(sock string) HandlerOption

WithPodmanSock returns an option that sets the Podman socket path used by the container library inside the script interpreter.

func WithSecrets added in v0.16.1 

func WithSecrets(r *secretprovider.Registry) HandlerOption

WithSecrets returns an option that supplies the secret registry exposed to scripts via the secret library.

func WithSetupHook added in v0.16.1 

func WithSetupHook(fn func(*scriptling.Scriptling)) HandlerOption

WithSetupHook returns an option that registers a callback invoked after the standard library set is registered on each fresh interpreter. Hosts use this to expose their own libraries to served scripts.

type PromptArgument added in v0.16.0 

type PromptArgument struct {
	Name        string
	Description string
	Required    bool
}

PromptArgument describes one argument a dynamic prompt accepts.

type ScannedToolEntry added in v0.18.0 

type ScannedToolEntry struct {
	Name     string
	Meta     *toolmetadata.ToolMetadata
	Source   []byte // script source (.py content)
	FuncName string // non-empty for decorated tools; empty for legacy
	Legacy   bool   // true = legacy .toml+.py format
}

ScannedToolEntry is a unified entry produced by the dual-format scanner. It covers both legacy (.toml+.py) and decorated (.py-only) tools.

func ScanToolsFSDual added in v0.18.0 

func ScanToolsFSDual(fsys fs.FS, cfg HandlerConfig) ([]ScannedToolEntry, error)

ScanToolsFSDual scans fsys for tools in both formats:

  • Legacy: .toml file with a sibling .py (existing behavior).
  • Decorated: .py file with no sibling .toml; evaluated to discover @mcp.tool() registrations.

cfg is used to configure the interpreter for decorated tool discovery. Files prefixed with _ are skipped.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.