mcptools

package
v0.8.5 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: Apache-2.0 Imports: 27 Imported by: 0

Documentation

Overview

Package mcptools builds the MCP tool server every levelrail-mcp transport (stdio, network, and the in-process transport an embedded caller like internal/ai uses) shares: one *mcp.Server with every tool registered against the same apiclient.Client. Pulled out of cmd/levelrail-mcp (which cannot be imported, being package main) so a non-CLI caller can build the identical tool server without spawning a subprocess.

Index

Constants

View Source
const (

	// MetaSensitiveKey is the tool _meta key set on sensitive tools.
	MetaSensitiveKey = "levelrail/sensitive"
	// MetaUntrustedKey is the tool _meta key set on tools whose result carries untrusted text.
	MetaUntrustedKey = "levelrail/untrusted-output"
)
View Source
const (
	// ModeReadOnly registers read tools only.
	ModeReadOnly Mode = "read-only"
	// ModeStandard registers read and mutating tools, not destructive ones.
	ModeStandard Mode = "standard"
	// ModeFull registers every tool.
	ModeFull Mode = "full"

	// EnvMode names the env var that selects the Mode.
	EnvMode = "APP_MCP_MODE"
	// EnvToolsets names the env var that selects the toolsets.
	EnvToolsets = "APP_MCP_TOOLSETS"
	// EnvAllowWrite names the env var that exposes the confirm-gated write tools.
	EnvAllowWrite = "APP_MCP_ALLOW_WRITE"
	// EnvOutputSchemas names the env var that keeps outputSchema in tools/list
	// for levelrail-mcp, which omits it by default.
	EnvOutputSchemas = "APP_MCP_OUTPUT_SCHEMAS"
	// EnvToolProfile names the env var that selects the tool profile.
	EnvToolProfile = "APP_MCP_TOOL_PROFILE"

	// ProfileAgentCore is a small allowlist of the tools an agent needs to
	// ship and debug an app.
	ProfileAgentCore = "agent-core"
)
View Source
const (
	EnvWaitWindow   = "APP_MCP_WAIT_WINDOW_SECONDS"
	EnvWaitInterval = "APP_MCP_WAIT_POLL_SECONDS"
)

Env vars bounding one wait_for_deploy call, in seconds.

View Source
const (

	// EnvAllTools names the env var that restores the static, everything
	// listed at once tools/list for clients without list_changed support.
	EnvAllTools = "APP_MCP_ALL"
)
View Source
const EnvResourceMaxBytes = "APP_MCP_RESOURCE_MAX_BYTES"

EnvResourceMaxBytes names the env var capping a docs resource's size.

Variables

This section is empty.

Functions

func AgentCoreTools

func AgentCoreTools() []string

AgentCoreTools returns the sorted agent-core allowlist.

func DynamicCoreTools

func DynamicCoreTools() []string

DynamicCoreTools returns the sorted always-listed core of a progressive session.

func Groups

func Groups() []string

Groups returns every toolset name, sorted.

func NewServer

func NewServer(client *apiclient.Client) *mcp.Server

NewServer builds the MCP server and registers every tool against client. Callers can connect to it directly over an in-memory transport (mcp.NewInMemoryTransports), without spawning a real process or touching stdio.

func ParseToolProfile

func ParseToolProfile(s string) (string, error)

ParseToolProfile validates a tool profile name; empty means no profile.

func ParseToolsets

func ParseToolsets(s string) ([]string, error)

ParseToolsets parses a comma separated toolset list; empty means all.

func PlannableTools

func PlannableTools() []string

PlannableTools returns the sorted names of mutating tools plan_change can plan.

Types

type AppEnvView

type AppEnvView struct {
	Name          string            `json:"name"`
	Env           map[string]string `json:"env"`
	SensitiveKeys []string          `json:"sensitive_keys"`
	SecretKeys    []string          `json:"secret_keys"`
}

AppEnvView is an app's visible plain env vars, plus the names, never values, of its secrets and of its sensitive plain vars.

type Class

type Class int

Class is a tool's blast radius, the single source for its MCP annotations, the server modes, and the assistant's confirmation gate.

const (
	// ClassUnset is the zero value of an unclassified tool.
	ClassUnset Class = iota
	// ClassRead tools change nothing.
	ClassRead
	// ClassMutate tools change state but can be undone or re-run.
	ClassMutate
	// ClassDestructive tools delete, roll back or tear down state.
	ClassDestructive
)

func (Class) String

func (c Class) String() string

type EnvChangeResult

type EnvChangeResult struct {
	Name           string `json:"name"`
	Key            string `json:"key"`
	Secret         bool   `json:"secret"`
	RedeployNeeded bool   `json:"redeploy_needed"`
	Hint           string `json:"hint"`
}

EnvChangeResult reports which key changed, never any value.

type Meta

type Meta struct {
	Class Class
	Group string
	// contains filtered or unexported fields
}

Meta is one tool's classification.

func Lookup

func Lookup(name string) (Meta, bool)

Lookup returns a tool's classification.

func (Meta) Outbound

func (m Meta) Outbound() bool

Outbound reports whether the tool reaches outside the control plane.

func (Meta) Sensitive

func (m Meta) Sensitive() bool

Sensitive reports whether the tool touches credentials, secrets or command output.

func (Meta) Untrusted

func (m Meta) Untrusted() bool

Untrusted reports whether the tool's result carries attacker-influenced text.

func (Meta) WriteGated

func (m Meta) WriteGated() bool

WriteGated reports whether the tool is hidden unless the server runs with AllowWrite.

type Mode

type Mode string

Mode bounds which tool classes a server registers. The API token's own abilities still apply on top: a mode only shrinks what the model sees.

func ParseMode

func ParseMode(s string) (Mode, error)

ParseMode parses a mode name, defaulting an empty value to standard.

type Options

type Options struct {
	Mode     Mode
	Toolsets []string
	// Profile, when set, replaces the mode's class filter with an allowlist.
	// Read-only mode still hides every non-read tool.
	Profile string
	// AllowWrite exposes the confirm-gated write tools. Off by default.
	AllowWrite bool
	// Dynamic starts the session with only the core tools plus the
	// list_toolsets, enable_toolset and disable_toolset meta tools.
	// Profile and Toolsets are ignored: enabling a toolset adds its tools
	// and sends tools/list_changed.
	Dynamic bool
	// OmitOutputSchemas drops outputSchema from tools/list. Results still
	// carry structured content; only the schema advertisement is left out.
	OmitOutputSchemas bool
	// contains filtered or unexported fields
}

Options selects the tools a server exposes.

type PlanChange

type PlanChange struct {
	Field  string `json:"field"`
	Before string `json:"before"`
	After  string `json:"after"`
}

PlanChange is one field a planned call would change. Values for secrets and env are never included, only whether they are set.

type PlanResult

type PlanResult struct {
	Tool      string       `json:"tool"`
	DryRun    bool         `json:"dry_run"`
	Executed  bool         `json:"executed"`
	Plannable bool         `json:"plannable"`
	Summary   string       `json:"summary"`
	Changes   []PlanChange `json:"changes,omitempty"`
	// Blocked is true when a freeze window or a required approval would stop
	// the call from taking effect now.
	Blocked  bool     `json:"blocked"`
	Blockers []string `json:"blockers,omitempty"`
	Note     string   `json:"note,omitempty"`
	// Detail carries a richer plan when one already exists (a resource plan,
	// a promotion preview).
	Detail map[string]any `json:"detail,omitempty"`
}

PlanResult is what plan_change returns: what a mutating tool call would do, computed from reads only. Executed is always false.

type Summary

type Summary struct {
	Dynamic  bool
	Mode     Mode
	Toolsets []string
	Profile  string
	Total    int
	Read     int
	Mutate   int
	Destruct int
}

Summary reports what a server exposes.

func NewServerWithOptions

func NewServerWithOptions(client *apiclient.Client, opts Options) (*mcp.Server, Summary)

NewServerWithOptions builds the MCP server and then unregisters every tool the mode and toolsets exclude, so a hidden tool costs no model context and cannot be called.

Source Files

Jump to

Keyboard shortcuts

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