mcp

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: May 4, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultCacheTTL is the default time-to-live for cached tool discovery.
	DefaultCacheTTL = 1 * time.Hour
	// EnvCacheTTL controls the cache TTL. Set to "0" to disable caching.
	EnvCacheTTL = "ITERION_MCP_CACHE_TTL"
)
View Source 
const (
	// EnvAutoLoad controls automatic project .mcp.json loading.
	EnvAutoLoad = "ITERION_MCP_AUTOLOAD"
	// EnvHealthCheck controls MCP pre-execution health checks (default: enabled).
	EnvHealthCheck = "ITERION_MCP_HEALTHCHECK"
)
View Source 
const DefaultProtocolVersion = "2025-06-18"

DefaultProtocolVersion is the MCP version advertised by Iterion.

Variables

This section is empty.

Functions

func AutoLoadProjectEnabled 

func AutoLoadProjectEnabled() bool

func HealthCheckEnabled 

func HealthCheckEnabled() bool

HealthCheckEnabled returns true unless ITERION_MCP_HEALTHCHECK is "false" or "0".

func PrepareAuth 

func PrepareAuth(catalog map[string]*ServerConfig, broker *OAuthBroker) error

PrepareAuth populates AuthFunc on every server in the catalog whose Auth.Type == "oauth2", using broker as the token source. Servers without an Auth block are left untouched. A non-nil error is returned if any server's Auth block is malformed (missing URLs, unsupported type).

Pass nil broker to disable OAuth wiring entirely (returns nil).

func PrepareWorkflow 

func PrepareWorkflow(wf *ir.Workflow, projectDir string) error

PrepareWorkflow resolves the final MCP catalog and active server sets for a compiled workflow. It merges project .mcp.json, top-level `mcp_server` declarations, and built-in presets, then applies workflow/node filters.

func ResolveCacheTTL 

func ResolveCacheTTL() time.Duration

ResolveCacheTTL reads the cache TTL from environment. Returns 0 to disable.

Types

type AuthConfig 

type AuthConfig struct {
	Type      string   // "oauth2" (only supported value today)
	AuthURL   string   // OAuth authorization endpoint
	TokenURL  string   // OAuth token endpoint
	RevokeURL string   // optional RFC 7009 revocation endpoint
	ClientID  string   // OAuth client ID
	Scopes    []string // requested scopes
}

AuthConfig describes authentication for an MCP server. Only the OAuth2 authorization-code + PKCE flow is wired; future schemes extend the same struct.

func FromIRAuth 

func FromIRAuth(auth *ir.MCPAuth) *AuthConfig

FromIRAuth converts an ir.MCPAuth (workflow-level config) into a runtime AuthConfig. Returns nil if auth is nil.

type AuthFunc 

type AuthFunc = func(ctx context.Context) (string, error)

AuthFunc is the closure shape SSE/HTTP transports invoke on every outbound request to fetch a fresh "Authorization" header value.

type ClawProvider 

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

ClawProvider satisfies clawmcp.Provider on top of iterion's *Manager (and an optional OAuthBroker for AuthStatus). Constructed via (*Manager).ClawProvider; passed into ClawDefaults so claw's list_mcp_resources / read_mcp_resource / mcp_auth tools see the same MCP servers iterion has connected — no double-connection.

func (*ClawProvider) GetResourceClient 

func (p *ClawProvider) GetResourceClient(name string) (clawmcp.ResourceClient, bool)

func (*ClawProvider) ServerNames 

func (p *ClawProvider) ServerNames() []string

func (*ClawProvider) ServerStatus 

func (p *ClawProvider) ServerStatus(name string) (clawmcp.ServerStatus, bool)

type FatalToolError 

type FatalToolError struct {
	Message string
}

FatalToolError wraps MCP tool errors that should not be retried or absorbed by the LLM tool loop (e.g. rate limits, credit exhaustion). Implements llmtypes.FatalToolError so the generation loop stops.

func (*FatalToolError) Error 

func (e *FatalToolError) Error() string

func (*FatalToolError) IsFatal 

func (e *FatalToolError) IsFatal() bool

IsFatal implements llmtypes.FatalToolError.

type FingerprintStore 

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

FingerprintStore persists and compares schema fingerprints across runs.

func NewFingerprintStore 

func NewFingerprintStore(dir string) *FingerprintStore

NewFingerprintStore loads (or creates) a fingerprint store. Stored at dir/mcp-cache/schema-fingerprints.json

func (*FingerprintStore) Check 

func (fs *FingerprintStore) Check(qualifiedName, server, toolName string, schema json.RawMessage) *SchemaChange

Check compares current schema against stored fingerprint. Returns SchemaChange if different/new, nil if unchanged. Updates in-memory state but does NOT persist — call Save().

func (*FingerprintStore) Save 

func (fs *FingerprintStore) Save() error

Save persists fingerprints to disk.

type Manager 

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

Manager lazily connects to MCP servers, caches clients and tool discovery, and bridges discovered tools into a tool.Registry.

func NewManager 

func NewManager(catalog map[string]*ServerConfig, opts ...ManagerOption) *Manager

NewManager creates an MCP manager from a resolved server catalog.

func (*Manager) ClawProvider 

func (m *Manager) ClawProvider(oauth *OAuthBroker) *ClawProvider

ClawProvider returns a Provider backed by this Manager. `oauth` may be nil; in that case AuthStatus reports "disconnected"/"auth_required" for HTTP/SSE transports and "stdio" for stdio servers (which don't authenticate).

func (*Manager) Close 

func (m *Manager) Close() error

Close closes any open MCP clients held by the manager.

func (*Manager) EnsureServers 

func (m *Manager) EnsureServers(ctx context.Context, registry *tool.Registry, servers []string) error

EnsureServers discovers tools for the given servers and registers them into the provided registry. Connections and tool catalogs are opened lazily and cached for the lifetime of the manager. If some servers fail, discovery continues for the remaining servers and a combined error is returned.

func (*Manager) HealthCheck 

func (m *Manager) HealthCheck(ctx context.Context, servers []string) error

HealthCheck verifies that each listed server is reachable by connecting and sending an MCP ping. Connections are cached, so a subsequent EnsureServers call reuses the same client (no double-spawn for stdio servers).

func (*Manager) ListResources 

func (m *Manager) ListResources(ctx context.Context, server string) ([]ResourceInfo, error)

ListResources connects (lazily) to `server` and returns the resources it exposes. The connection is shared with subsequent CallTool / ReadResource calls.

func (*Manager) ReadResource 

func (m *Manager) ReadResource(ctx context.Context, server, uri string) (ResourceContent, error)

ReadResource connects (lazily) to `server` and returns the body of the resource at `uri`.

func (*Manager) ServerConfig 

func (m *Manager) ServerConfig(name string) (*ServerConfig, bool)

ServerConfig returns a clone of the catalog entry for `name`. The boolean is false when the server is unknown.

func (*Manager) ServerNames 

func (m *Manager) ServerNames() []string

ServerNames returns the names of every server known to the catalog (whether or not it has been connected yet). The order is stable but unspecified.

type ManagerOption 

type ManagerOption func(*Manager)

ManagerOption configures a Manager.

func WithFingerprintStore 

func WithFingerprintStore(fs *FingerprintStore) ManagerOption

WithFingerprintStore sets the fingerprint store on the manager.

func WithLogger 

func WithLogger(l *iterlog.Logger) ManagerOption

WithLogger sets a leveled logger on the manager.

func WithSanitizationRules 

func WithSanitizationRules(rules []SanitizationRule) ManagerOption

WithSanitizationRules replaces the default sanitization rules.

func WithToolCache 

func WithToolCache(cache *ToolCache) ManagerOption

WithToolCache sets the tool discovery cache on the manager.

type OAuthBroker 

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

OAuthBroker is the iterion-side wrapper around claw's OAuth broker. It owns the persistent token cache (storage path lives under the run's store dir so a workflow restart can reuse refresh tokens) and hands out per-server BearerHeaderFunc closures.

The zero value is not usable; construct via NewOAuthBroker.

Concurrency: the underlying clawoauth.Broker is safe for concurrent use; this wrapper holds no mutable state of its own and adds no further locking.

func NewOAuthBroker 

func NewOAuthBroker(storeDir string) (*OAuthBroker, error)

NewOAuthBroker builds an OAuth broker rooted at the given store directory. Tokens are persisted under <storeDir>/mcp_oauth.json so the same broker can be re-instantiated by a later run.

Pass an empty storeDir to fall back to the platform default (claw's $XDG_DATA_HOME path).

func (*OAuthBroker) AuthFuncFor 

func (b *OAuthBroker) AuthFuncFor(cfg *AuthConfig, serverName string) (AuthFunc, error)

AuthFuncFor returns a closure that resolves to a "Bearer <token>" header for an SSE/HTTP MCP transport. The closure is safe to call concurrently; the broker handles refresh and storage.

Returns an error if cfg is missing required fields (Type, AuthURL, TokenURL, ClientID).

func (*OAuthBroker) AuthStatus 

func (b *OAuthBroker) AuthStatus(serverName string) clawmcp.ServerStatus

AuthStatus reports the persisted OAuth token state for `serverName`. Returns "connected" when a non-expired token is on file, "auth_required" when a token is missing, and "expired" when the cache holds a stale token. The returned struct keeps Server/Type/Scopes/ExpiresAt fields so the mcp_auth tool can format a complete report.

type ResourceContent 

type ResourceContent struct {
	URI         string
	Name        string
	Description string
	MimeType    string
	Text        string
}

ResourceContent is the body returned by resources/read.

type ResourceInfo 

type ResourceInfo struct {
	URI         string `json:"uri"`
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	MimeType    string `json:"mimeType,omitempty"`
}

ResourceInfo describes a resource exposed by an MCP server.

type SanitizationRule 

type SanitizationRule struct {
	// Name identifies this rule for logging/debugging.
	Name string
	// Match returns true if this rule applies to the given tool.
	Match func(toolName string) bool
	// Apply modifies args in-place.
	Apply func(toolName string, args map[string]interface{}, workDir string)
}

SanitizationRule defines a tool argument fixup applied before MCP tool calls. Rules are applied in order; each matching rule modifies args in-place.

func DefaultSanitizationRules 

func DefaultSanitizationRules() []SanitizationRule

DefaultSanitizationRules returns the built-in sanitization rules that fix common mistakes made by LLMs when calling MCP tools.

type SchemaChange 

type SchemaChange struct {
	QualifiedName       string
	Server              string
	ToolName            string
	PreviousFingerprint string
	CurrentFingerprint  string
	IsNew               bool
}

SchemaChange describes a detected change in an MCP tool's input schema.

type ServerConfig 

type ServerConfig struct {
	Name      string
	Transport Transport
	Command   string
	Args      []string
	URL       string
	Headers   map[string]string
	WorkDir   string            // working directory for stdio server processes
	Env       map[string]string // extra environment variables for stdio server processes
	Auth      *AuthConfig       // authentication (OAuth2, etc.) for SSE/HTTP servers

	// AuthFunc, when set, is invoked on every outbound HTTP request
	// to obtain a fresh "Authorization" header value. Populated by
	// PrepareAuth from Auth (OAuth2 → broker.BearerHeaderFunc).
	//
	// Excluded from JSON serialization (function values can't
	// marshal, and the cache fingerprint must remain stable).
	AuthFunc AuthFunc `json:"-"`
}

ServerConfig is the runtime MCP server definition used by the manager.

type ToolCache 

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

ToolCache provides persistent caching of MCP tool discovery results. Cache files are stored as JSON in a subdirectory, keyed by server name and a hash of the server configuration.

func NewToolCache 

func NewToolCache(dir string, ttl time.Duration) *ToolCache

NewToolCache creates a cache that stores tool schemas under dir/mcp-cache/.

func (*ToolCache) Get 

func (c *ToolCache) Get(serverName string, cfg *ServerConfig) ([]ToolInfo, bool)

Get returns cached tool info for the given server if available and fresh. The config hash is encoded in the filename, so a config change automatically maps to a different (nonexistent) cache file.

func (*ToolCache) Set 

func (c *ToolCache) Set(serverName string, cfg *ServerConfig, tools []ToolInfo) error

Set persists tool info for the given server.

type ToolCallResult 

type ToolCallResult struct {
	Content           []ToolContent `json:"content,omitempty"`
	StructuredContent interface{}   `json:"structuredContent,omitempty"`
	IsError           bool          `json:"isError,omitempty"`
}

ToolCallResult is the MCP result returned by tools/call.

type ToolContent 

type ToolContent struct {
	Type string `json:"type,omitempty"`
	Text string `json:"text,omitempty"`
}

ToolContent is one MCP content item.

type ToolInfo 

type ToolInfo struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"inputSchema,omitempty"`
}

ToolInfo is the MCP tool description returned by tools/list.

type Transport 

type Transport string

Transport identifies the transport used by an MCP server. 

const (
	TransportStdio Transport = "stdio"
	TransportHTTP  Transport = "http"
	TransportSSE   Transport = "sse"
)

func FromIRTransport 

func FromIRTransport(t ir.MCPTransport) Transport

FromIRTransport converts an IR MCP transport to a runtime transport.

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.