mcp

package
v0.5.7 Latest Latest
Warning

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

Go to latest
Published: Jul 28, 2026 License: AGPL-3.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrNeedsAuth = errors.New("mcp: server requires authentication")

ErrNeedsAuth signals that an OAuth MCP server has no usable token stored (or its refresh token is no longer valid). The user must (re-)run the interactive authorization flow (`vix mcp auth <server>` or the F4 tab).

Functions

func Authorize added in v0.5.7

func Authorize(ctx context.Context, cfg ServerConfig, store TokenStore, onURL func(url string)) error

Authorize runs the interactive OAuth flow using a self-hosted ephemeral loopback listener. It is the fallback used when no shared callback host (the mission-control web server) is available. It starts a listener, hands the auth URL to onURL, waits for the redirect, and completes the flow.

func WriteCallbackPage added in v0.5.7

func WriteCallbackPage(w http.ResponseWriter, ok bool, detail string)

WriteCallbackPage renders the minimal browser page shown after the redirect.

Types

type AuthFlow added in v0.5.7

type AuthFlow struct {
	Server  string // MCP server name
	State   string // opaque anti-CSRF token, also the registry key
	AuthURL string // URL to open in the browser
	// contains filtered or unexported fields
}

AuthFlow is an in-progress OAuth authorization. Create it with NewAuthFlow (which resolves endpoints and builds the authorization URL), hand AuthURL to a browser, then call Complete with the code + state delivered to the redirect URI. The same flow backs both the shared mission-control callback route and the ephemeral loopback listener (Authorize).

func NewAuthFlow added in v0.5.7

func NewAuthFlow(ctx context.Context, cfg ServerConfig, store TokenStore, redirectURL string) (*AuthFlow, error)

NewAuthFlow resolves cfg's OAuth endpoints, generates PKCE + state, and builds the authorization URL for the given redirect URI (where the provider will send the browser back).

func (*AuthFlow) Complete added in v0.5.7

func (f *AuthFlow) Complete(ctx context.Context, code, state string) error

Complete validates the returned state, exchanges the code for a token, and persists it.

func (*AuthFlow) Expired added in v0.5.7

func (f *AuthFlow) Expired() bool

Expired reports whether the flow is older than the authorization window.

type CallResult

type CallResult struct {
	Output  string
	IsError bool
}

CallResult is the outcome of a tools/call request.

type OAuthConfig added in v0.5.7

type OAuthConfig struct {
	ClientID     string   `json:"client_id"`
	ClientSecret string   `json:"client_secret,omitempty"`
	Scopes       []string `json:"scopes,omitempty"`
	AuthURL      string   `json:"auth_url,omitempty"`
	TokenURL     string   `json:"token_url,omitempty"`
	// RedirectPort pins the loopback callback port (0 = an ephemeral free port).
	RedirectPort int `json:"redirect_port,omitempty"`
}

OAuthConfig describes an OAuth 2.0 authorization-code flow for a url MCP server. ClientSecret may be given as "${VAR}" to read it from the environment. AuthURL/TokenURL are optional: when omitted, vix discovers them from the server via RFC 9728 (protected-resource metadata) and RFC 8414 (authorization- server metadata).

type Option added in v0.5.7

type Option func(*options)

Option configures NewPool/ProbeServers.

func WithTokenStore added in v0.5.7

func WithTokenStore(store TokenStore) Option

WithTokenStore supplies the OAuth token store used by url servers configured with `oauth`. Without it, such servers fail to connect (ErrNeedsAuth).

type Pool

type Pool struct {
	// contains filtered or unexported fields
}

Pool manages MCP server connections for a single thread. It is created in thread.initBrain and torn down when the thread context is cancelled (stdio child processes are killed via their exec.CommandContext).

func NewPool

func NewPool(ctx context.Context, configs []ServerConfig, opts ...Option) *Pool

NewPool connects to all configured MCP servers, runs the initialize+tools/list handshake for each, and returns a ready pool.

Servers that fail to start are logged and skipped so a single broken server does not prevent the rest from working.

The caller is responsible for deny-list URL filtering before passing configs; see thread.initBrain which calls isURLDenied before adding an entry.

func (*Pool) Call

func (p *Pool) Call(qualifiedName string, args map[string]any) (string, bool, error)

Call dispatches a tool call to the appropriate MCP server and returns the result. qualifiedName must be of the form "mcp__<server>__<tool>". Internal vix params (cwd, allowed_dirs, headless, _thread, confirmed) are stripped before forwarding to the server.

func (*Pool) RequiresConfirmation

func (p *Pool) RequiresConfirmation(qualifiedName string) bool

RequiresConfirmation reports whether the server that owns qualifiedName has require_confirmation: true.

func (*Pool) ServerCount

func (p *Pool) ServerCount() int

ServerCount returns the number of successfully connected MCP servers.

func (*Pool) Shutdown

func (p *Pool) Shutdown()

Shutdown closes all MCP server connections.

func (*Pool) ToolCount

func (p *Pool) ToolCount() int

ToolCount returns the total number of MCP tools available in the pool.

func (*Pool) ToolSchemas

func (p *Pool) ToolSchemas() []llm.ToolParam

ToolSchemas returns neutral llm.ToolParam definitions for every MCP tool in the pool. Tool names are the qualified form "mcp__<server>__<tool>".

type ServerConfig

type ServerConfig struct {
	// Name is a unique identifier used to prefix tool names: mcp__<name>__<tool>.
	Name string `json:"name"`
	// Type is the transport: "stdio" (default) or "url".
	Type string `json:"type,omitempty"`
	// Command and Args are used for stdio servers.
	Command string   `json:"command,omitempty"`
	Args    []string `json:"args,omitempty"`
	// Env adds extra environment variables for the stdio child process.
	Env map[string]string `json:"env,omitempty"`
	// URL is used for HTTP/SSE servers.
	URL string `json:"url,omitempty"`
	// Headers are sent with every HTTP request (e.g. Authorization).
	// Values of the form "${VAR}" are expanded from the environment at connect time.
	Headers map[string]string `json:"headers,omitempty"`
	// OAuth, when set on a url server, enables an OAuth 2.0 authorization-code
	// flow: the access token is injected as an Authorization: Bearer header and
	// refreshed automatically. Endpoints are auto-discovered (RFC 9728 + RFC
	// 8414) unless AuthURL/TokenURL are set explicitly.
	OAuth *OAuthConfig `json:"oauth,omitempty"`
	// AllowedTools, when non-empty, restricts which tools from this server are
	// exposed to the LLM. Unlisted tools are silently dropped after tools/list.
	AllowedTools []string `json:"allowed_tools,omitempty"`
	// RequireConfirmation makes every tool call from this server require explicit
	// user approval via the standard confirm_request / thread.confirm flow.
	RequireConfirmation bool `json:"require_confirmation,omitempty"`
	// Enabled gates whether the server is connected at all. A nil pointer (field
	// omitted from settings.json) means enabled — the opt-out default — so
	// existing configs keep working. The MCP tab's Space toggle writes this.
	Enabled *bool `json:"enabled,omitempty"`
}

ServerConfig describes a single MCP server entry from settings.json.

func (ServerConfig) IsEnabled added in v0.5.6

func (c ServerConfig) IsEnabled() bool

IsEnabled reports whether the server should be connected. A missing `enabled` field (nil pointer) defaults to true.

func (ServerConfig) UsesOAuth added in v0.5.7

func (c ServerConfig) UsesOAuth() bool

UsesOAuth reports whether this server authenticates via the OAuth 2.0 flow.

type ServerStatus added in v0.5.6

type ServerStatus struct {
	Name      string
	Type      string // "stdio" or "url"
	Connected bool
	ToolCount int
	Error     string
}

ServerStatus is a per-server probe result: whether it connected, how many tools it exposed (after the AllowedTools filter), and any connection error.

func ProbeServers added in v0.5.6

func ProbeServers(ctx context.Context, configs []ServerConfig, opts ...Option) []ServerStatus

ProbeServers connects to each configured server, records whether it came up and how many tools it exposes, then tears the connection down. It is used by the MCP tab to report status without an active chat thread. Servers with an empty name are skipped. The probe respects ctx for cancellation/timeout.

type TokenStore added in v0.5.7

type TokenStore interface {
	Load(server string) (*oauth2.Token, error)
	Save(server string, tok *oauth2.Token) error
	Delete(server string) error
}

TokenStore persists OAuth tokens per MCP server. Implementations are backed by the vix credential store (OS keyring, with a 0600 auth.json fallback). Load returns (nil, nil) when no token is stored.

type ToolDef

type ToolDef struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"inputSchema"`
}

ToolDef is a tool discovered from an MCP server via tools/list.

Jump to

Keyboard shortcuts

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