mcp

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package mcp manages Model Context Protocol server configuration and calls.

Package mcp implements Codog's Model Context Protocol client helpers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NormalizeNameForTooling 

func NormalizeNameForTooling(name string) string

NormalizeNameForTooling converts an MCP server or member name into the form used in Codog tool names.

func ServerConfigHash 

func ServerConfigHash(server config.MCPServerConfig) string

ServerConfigHash returns a stable hash for an MCP server configuration.

func ServerSignature 

func ServerSignature(server config.MCPServerConfig) string

ServerSignature returns a redacted, stable signature for a configured MCP server.

func ToolName 

func ToolName(serverName, toolName string) string

ToolName returns the fully qualified Codog tool name for an MCP tool.

func ToolPrefix 

func ToolPrefix(serverName string) string

ToolPrefix returns the Codog tool-name prefix for one MCP server.

func URLServerSignature 

func URLServerSignature(rawURL string) string

URLServerSignature returns the stable MCP server signature for a URL.

func UnwrapCCRProxyURL 

func UnwrapCCRProxyURL(rawURL string) string

UnwrapCCRProxyURL returns the upstream target URL embedded in a Claude Code remote proxy URL when one is present.

Types

type AuthStatusResult 

type AuthStatusResult struct {
	Server        string          `json:"server"`
	Status        string          `json:"status"`
	Lifecycle     LifecycleStatus `json:"lifecycle"`
	ServerInfo    json.RawMessage `json:"server_info,omitempty"`
	Capabilities  json.RawMessage `json:"capabilities,omitempty"`
	ToolCount     int             `json:"tool_count"`
	ResourceCount int             `json:"resource_count"`
	ResourceError string          `json:"resource_error,omitempty"`
	Error         string          `json:"error,omitempty"`
}

AuthStatusResult summarizes authentication and discovery health for an MCP server.

func InspectAuth 

func InspectAuth(ctx context.Context, serverName string, server config.MCPServerConfig) AuthStatusResult

InspectAuth checks initialize, tool discovery, and resource discovery health for one MCP server.

type ClientOptions added in v0.1.2 

type ClientOptions struct {
	Roots          []Root
	Elicit         func(context.Context, ElicitationRequest) (ElicitationResult, error)
	OnNotification func(Notification)
}

ClientOptions controls server-initiated MCP behavior. Without an elicitation handler, Codog declines requests so non-interactive commands never block.

type ClientPool added in v0.1.2 

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

ClientPool owns persistent MCP sessions for one Codog tool registry. A session is reused until its server configuration changes, the connection closes, or the pool is closed.

func NewClientPool added in v0.1.2 

func NewClientPool() *ClientPool

NewClientPool constructs an empty persistent MCP client pool.

func (*ClientPool) CallTool added in v0.1.2 

func (p *ClientPool) CallTool(ctx context.Context, name string, server config.MCPServerConfig, toolName string, arguments json.RawMessage, options ClientOptions) ToolCallResult

CallTool invokes a tool through a persistent server session.

func (*ClientPool) Close added in v0.1.2 

func (p *ClientPool) Close() error

Close gracefully closes every MCP session owned by the pool.

func (*ClientPool) GetPrompt added in v0.1.2 

func (p *ClientPool) GetPrompt(ctx context.Context, name string, server config.MCPServerConfig, promptName string, arguments json.RawMessage, options ClientOptions) PromptGetResult

GetPrompt renders one prompt through a persistent server session.

func (*ClientPool) ListPrompts added in v0.1.2 

func (p *ClientPool) ListPrompts(ctx context.Context, name string, server config.MCPServerConfig, options ClientOptions) PromptListResult

ListPrompts discovers every paginated prompt through a persistent session.

func (*ClientPool) ListResourceTemplates added in v0.1.2 

func (p *ClientPool) ListResourceTemplates(ctx context.Context, name string, server config.MCPServerConfig, options ClientOptions) ResourceTemplateListResult

ListResourceTemplates discovers every paginated template through a persistent session.

func (*ClientPool) ListResources added in v0.1.2 

func (p *ClientPool) ListResources(ctx context.Context, name string, server config.MCPServerConfig, options ClientOptions) ResourceListResult

ListResources discovers every paginated resource through a persistent session.

func (*ClientPool) ListTools added in v0.1.2 

func (p *ClientPool) ListTools(ctx context.Context, name string, server config.MCPServerConfig, options ClientOptions) ToolListResult

ListTools discovers every paginated tool while preserving the server session.

func (*ClientPool) ReadResource added in v0.1.2 

func (p *ClientPool) ReadResource(ctx context.Context, name string, server config.MCPServerConfig, uri string, options ClientOptions) ResourceReadResult

ReadResource reads one resource through a persistent server session.

type ElicitationRequest added in v0.1.2 

type ElicitationRequest struct {
	Mode            string         `json:"mode,omitempty"`
	Message         string         `json:"message"`
	RequestedSchema map[string]any `json:"requestedSchema,omitempty"`
	URL             string         `json:"url,omitempty"`
	ElicitationID   string         `json:"elicitationId,omitempty"`
}

ElicitationRequest is a server-initiated request for user input.

type ElicitationResult added in v0.1.2 

type ElicitationResult struct {
	Action  string         `json:"action"`
	Content map[string]any `json:"content,omitempty"`
}

ElicitationResult is returned to an MCP server after user interaction.

type InitializeResult 

type InitializeResult struct {
	Server          string          `json:"server"`
	Status          string          `json:"status"`
	Lifecycle       LifecycleStatus `json:"lifecycle"`
	ProtocolVersion string          `json:"protocol_version,omitempty"`
	Capabilities    json.RawMessage `json:"capabilities,omitempty"`
	ServerInfo      json.RawMessage `json:"server_info,omitempty"`
	Error           string          `json:"error,omitempty"`
}

InitializeResult records the outcome of an MCP initialize handshake.

func Initialize 

func Initialize(ctx context.Context, serverName string, server config.MCPServerConfig) InitializeResult

Initialize performs the MCP initialize handshake for one configured server.

type LifecycleError 

type LifecycleError struct {
	Phase       string            `json:"phase"`
	Message     string            `json:"message"`
	Context     map[string]string `json:"context,omitempty"`
	Recoverable bool              `json:"recoverable"`
}

LifecycleError describes a structured MCP lifecycle failure.

type LifecycleStatus 

type LifecycleStatus struct {
	Phase               string          `json:"phase"`
	LastSuccessfulPhase string          `json:"last_successful_phase,omitempty"`
	Error               *LifecycleError `json:"error,omitempty"`
}

LifecycleStatus reports the current MCP lifecycle phase and the last recoverable or fatal error surfaced by that lifecycle.

type Notification added in v0.1.2 

type Notification struct {
	Method string          `json:"method"`
	Params json.RawMessage `json:"params,omitempty"`
}

Notification reports a server capability or inventory change observed while an MCP request is active.

type PromptGetResult 

type PromptGetResult struct {
	Server    string          `json:"server"`
	Prompt    string          `json:"prompt"`
	Lifecycle LifecycleStatus `json:"lifecycle"`
	Result    json.RawMessage `json:"result,omitempty"`
	Error     string          `json:"error,omitempty"`
}

PromptGetResult records the result of rendering one MCP prompt.

func GetPrompt 

func GetPrompt(ctx context.Context, serverName string, server config.MCPServerConfig, promptName string, arguments json.RawMessage) PromptGetResult

GetPrompt renders one MCP prompt after initializing the server connection.

func GetPromptWithOptions added in v0.1.2 

func GetPromptWithOptions(ctx context.Context, serverName string, server config.MCPServerConfig, promptName string, arguments json.RawMessage, opts ClientOptions) PromptGetResult

GetPromptWithOptions renders a prompt with server-request handling.

type PromptListResult 

type PromptListResult struct {
	Server    string          `json:"server"`
	Lifecycle LifecycleStatus `json:"lifecycle"`
	Prompts   json.RawMessage `json:"prompts,omitempty"`
	Error     string          `json:"error,omitempty"`
}

PromptListResult records prompts discovered from one MCP server.

func ListPrompts 

func ListPrompts(ctx context.Context, serverName string, server config.MCPServerConfig) PromptListResult

ListPrompts discovers prompts exposed by one MCP server.

func ListPromptsWithOptions added in v0.1.2 

func ListPromptsWithOptions(ctx context.Context, serverName string, server config.MCPServerConfig, opts ClientOptions) PromptListResult

ListPromptsWithOptions discovers prompts with server-request handling.

type ResourceListResult 

type ResourceListResult struct {
	Server    string          `json:"server"`
	Lifecycle LifecycleStatus `json:"lifecycle"`
	Resources json.RawMessage `json:"resources,omitempty"`
	Error     string          `json:"error,omitempty"`
}

ResourceListResult records resources discovered from one MCP server.

func ListResources 

func ListResources(ctx context.Context, serverName string, server config.MCPServerConfig) ResourceListResult

ListResources discovers the resources exposed by one MCP server.

func ListResourcesWithOptions added in v0.1.2 

func ListResourcesWithOptions(ctx context.Context, serverName string, server config.MCPServerConfig, opts ClientOptions) ResourceListResult

ListResourcesWithOptions discovers resources with server-request handling.

type ResourceReadResult 

type ResourceReadResult struct {
	Server    string          `json:"server"`
	URI       string          `json:"uri"`
	Lifecycle LifecycleStatus `json:"lifecycle"`
	Result    json.RawMessage `json:"result,omitempty"`
	Error     string          `json:"error,omitempty"`
}

ResourceReadResult records the result of reading one MCP resource.

func ReadResource 

func ReadResource(ctx context.Context, serverName string, server config.MCPServerConfig, uri string) ResourceReadResult

ReadResource reads one MCP resource by URI after initializing the server connection.

func ReadResourceWithOptions added in v0.1.2 

func ReadResourceWithOptions(ctx context.Context, serverName string, server config.MCPServerConfig, uri string, opts ClientOptions) ResourceReadResult

ReadResourceWithOptions reads a resource with server-request handling.

type ResourceTemplateListResult 

type ResourceTemplateListResult struct {
	Server    string          `json:"server"`
	Lifecycle LifecycleStatus `json:"lifecycle"`
	Templates json.RawMessage `json:"templates,omitempty"`
	Error     string          `json:"error,omitempty"`
}

ResourceTemplateListResult records resource templates discovered from one MCP server.

func ListResourceTemplates 

func ListResourceTemplates(ctx context.Context, serverName string, server config.MCPServerConfig) ResourceTemplateListResult

ListResourceTemplates discovers resource templates exposed by one MCP server.

func ListResourceTemplatesWithOptions added in v0.1.2 

func ListResourceTemplatesWithOptions(ctx context.Context, serverName string, server config.MCPServerConfig, opts ClientOptions) ResourceTemplateListResult

ListResourceTemplatesWithOptions discovers resource templates with server-request handling.

type Root added in v0.1.2 

type Root struct {
	URI  string `json:"uri"`
	Name string `json:"name,omitempty"`
}

Root describes a workspace root exposed to an MCP server.

func RootForPath added in v0.1.2 

func RootForPath(path string) (Root, error)

RootForPath converts a local directory into an MCP file root.

type ServerDescriptor 

type ServerDescriptor struct {
	Name      string          `json:"name"`
	Valid     bool            `json:"valid"`
	Required  bool            `json:"required"`
	Transport ServerTransport `json:"transport"`
	Summary   string          `json:"summary"`
	Details   ServerDetails   `json:"details"`
}

ServerDescriptor is a redacted, user-facing description of one MCP server.

func DescribeServer 

func DescribeServer(name string, server config.MCPServerConfig) ServerDescriptor

DescribeServer returns a redacted descriptor for one configured MCP server.

type ServerDetails 

type ServerDetails struct {
	Command                    string   `json:"command,omitempty"`
	URL                        string   `json:"url,omitempty"`
	ArgsSummary                []string `json:"args_summary,omitempty"`
	ArgsCount                  int      `json:"args_count"`
	ToolCallTimeoutMS          int      `json:"tool_call_timeout_ms,omitempty"`
	EnvKeys                    []string `json:"env_keys,omitempty"`
	HeaderKeys                 []string `json:"header_keys,omitempty"`
	HeadersHelperConfigured    bool     `json:"headers_helper_configured,omitempty"`
	OAuthConfigured            bool     `json:"oauth_configured,omitempty"`
	OAuthClientIDConfigured    bool     `json:"oauth_client_id_configured,omitempty"`
	OAuthCallbackPort          int      `json:"oauth_callback_port,omitempty"`
	OAuthAuthServerMetadataURL string   `json:"oauth_auth_server_metadata_url,omitempty"`
	OAuthXAA                   *bool    `json:"oauth_xaa,omitempty"`
}

ServerDetails contains redacted transport-specific configuration details.

type ServerStatus 

type ServerStatus struct {
	Name            string          `json:"name"`
	Status          string          `json:"status"`
	Required        bool            `json:"required"`
	Lifecycle       LifecycleStatus `json:"lifecycle"`
	Command         string          `json:"command,omitempty"`
	URL             string          `json:"url,omitempty"`
	Signature       string          `json:"signature,omitempty"`
	ConfigHash      string          `json:"config_hash,omitempty"`
	ResolvedPath    string          `json:"resolved_path,omitempty"`
	ProtocolVersion string          `json:"protocol_version,omitempty"`
	ServerInfo      json.RawMessage `json:"server_info,omitempty"`
	ToolCount       int             `json:"tool_count,omitempty"`
	Tools           []string        `json:"tools,omitempty"`
	Error           string          `json:"error,omitempty"`
}

ServerStatus reports the local inspection status for one configured MCP server.

func Inspect 

func Inspect(ctx context.Context, name string, server config.MCPServerConfig) ServerStatus

Inspect preflights one MCP server and discovers its tool list when initialization succeeds.

func InspectAll 

func InspectAll(ctx context.Context, servers map[string]config.MCPServerConfig) []ServerStatus

InspectAll inspects all configured MCP servers in deterministic name order.

func Preflight 

func Preflight(ctx context.Context, name string, server config.MCPServerConfig) ServerStatus

Preflight validates one MCP server configuration and performs its initialize handshake.

func PreflightAll 

func PreflightAll(ctx context.Context, servers map[string]config.MCPServerConfig) []ServerStatus

PreflightAll preflights all configured MCP servers in deterministic name order.

type ServerTransport 

type ServerTransport struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

ServerTransport identifies the MCP transport configured for a server.

type StartupFailure 

type StartupFailure struct {
	Name        string `json:"name"`
	Status      string `json:"status"`
	Required    bool   `json:"required"`
	Phase       string `json:"phase,omitempty"`
	Recoverable bool   `json:"recoverable"`
	Error       string `json:"error,omitempty"`
}

StartupFailure records the redacted failure surface for one MCP server in a startup report.

type StartupReport 

type StartupReport struct {
	Status              string           `json:"status"`
	Total               int              `json:"total"`
	OKCount             int              `json:"ok_count"`
	ErrorCount          int              `json:"error_count"`
	RequiredCount       int              `json:"required_count"`
	RequiredOKCount     int              `json:"required_ok_count"`
	RequiredFailedCount int              `json:"required_failed_count"`
	OptionalCount       int              `json:"optional_count"`
	OptionalOKCount     int              `json:"optional_ok_count"`
	OptionalFailedCount int              `json:"optional_failed_count"`
	FailedRequired      []StartupFailure `json:"failed_required_servers,omitempty"`
	FailedOptional      []StartupFailure `json:"failed_optional_servers,omitempty"`
}

StartupReport summarizes whether the configured MCP set is usable at session startup time. Required server failures are fatal; optional failures degrade startup but keep the rest of the MCP inventory usable.

func BuildStartupReport 

func BuildStartupReport(statuses []ServerStatus) StartupReport

BuildStartupReport aggregates server statuses into a startup gate result.

type ToolCallResult 

type ToolCallResult struct {
	Server    string          `json:"server"`
	Tool      string          `json:"tool"`
	Lifecycle LifecycleStatus `json:"lifecycle"`
	Result    json.RawMessage `json:"result,omitempty"`
	Error     string          `json:"error,omitempty"`
}

ToolCallResult records the result of invoking one MCP tool.

func CallTool 

func CallTool(ctx context.Context, serverName string, server config.MCPServerConfig, toolName string, arguments json.RawMessage) ToolCallResult

CallTool invokes one MCP tool after initializing the server connection.

func CallToolWithOptions added in v0.1.2 

func CallToolWithOptions(ctx context.Context, serverName string, server config.MCPServerConfig, toolName string, arguments json.RawMessage, opts ClientOptions) ToolCallResult

CallToolWithOptions invokes one MCP tool and handles server-initiated requests and notifications while the call is active.

type ToolInfo 

type ToolInfo struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	InputSchema map[string]any `json:"input_schema,omitempty"`
}

ToolInfo describes one MCP tool exposed by a server.

type ToolListResult 

type ToolListResult struct {
	Server string     `json:"server"`
	Tools  []ToolInfo `json:"tools,omitempty"`
	Error  string     `json:"error,omitempty"`
}

ToolListResult records the tools discovered from one MCP server.

func ListTools 

func ListTools(ctx context.Context, serverName string, server config.MCPServerConfig) ToolListResult

ListTools discovers the tools exposed by one MCP server.

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.