Help us shape the future of Go! Take the 2026 Go Developer Survey

mcpkit

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Nov 3, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

README

MCPKit

mcpkit contains a minimal adapter layer between Model Context Protocol style tool descriptors and goagent tools.

It does not implement an MCP transport, server, authorization layer, resource browser, or prompt registry. Hosts provide a Client that can list tools and call one tool. mcpkit maps those tool descriptors into goagent/tools.Tool instances with schema, permission, execution mode, timeout, and bounded result projection.

Use

registry := tools.NewRegistry()

_, err := mcpkit.RegisterTools(ctx, registry, client, mcpkit.RegisterOptions{
    Permission:  policy.PermissionRead,
    MaxLLMChars: 1000,
})
if err != nil {
    return err
}

agent, err := agentcore.NewAgent(
    agentcore.WithLLM(llm),
    agentcore.WithToolRegistry(registry),
)

RegisterOptions.Permission always takes precedence. Without an explicit permission, annotations from an MCP server are ignored by default and tools keep an empty permission, so the default goagent policy denies execution.

Set TrustServerAnnotations: true only after the host has explicitly verified the MCP server identity and configuration. In that trusted case, readOnlyHint maps to read and destructiveHint maps to write. Annotations are hints for host policy; they are not an authorization boundary.

Boundary

mcpkit owns:

  • MCP-style tool descriptor DTOs
  • tool call result DTOs
  • mapping descriptors to goagent tool specs
  • bounding model-visible MCP tool output

It does not own:

  • JSON-RPC sessions
  • stdio, HTTP, SSE, or Streamable HTTP transports
  • MCP resources or prompts
  • OAuth or remote authorization
  • tool approval UI

Those concerns stay in host applications or transport-specific adapter modules.

Transport Adapters

The first transport-specific adapter is github.com/eruca/goagents/mcpkit/officialsdk in mcpkit/officialsdk/. It uses the official MCP Go SDK to connect to stdio and Streamable HTTP MCP servers, then exposes the existing mcpkit.Client interface.

Streamable HTTP defaults to request/response mode by disabling standalone SSE. Enable SSE explicitly only when a host needs server-initiated notifications and has designed the associated session lifecycle.

Verify

go test ./...

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterTools 

func RegisterTools(ctx context.Context, registry Registry, client Client, options RegisterOptions) ([]tools.Spec, error)

RegisterTools lists MCP tools once and registers goagent tool adapters for each descriptor. Hosts can refresh by calling it again with their own registry lifecycle policy.

Types

type Client 

type Client interface {
	ListTools(context.Context) ([]ToolDescriptor, error)
	CallTool(ctx context.Context, name string, arguments json.RawMessage) (*ToolCallResult, error)
}

Client is the host-provided boundary to an MCP implementation. mcpkit does not own stdio, HTTP, authorization, or JSON-RPC lifecycle handling.

type ContentPart 

type ContentPart struct {
	Type     string `json:"type"`
	Text     string `json:"text,omitempty"`
	MIMEType string `json:"mimeType,omitempty"`
	Data     []byte `json:"data,omitempty"`
}

type RegisterOptions 

type RegisterOptions struct {
	Permission    policy.Permission
	ExecutionMode ports.ExecutionMode
	Timeout       time.Duration
	MaxLLMChars   int
	// TrustServerAnnotations must be set only after host-side server verification.
	// Untrusted MCP annotations are hints, never an authorization source.
	TrustServerAnnotations bool
}

RegisterOptions controls how MCP descriptors become goagent tool specs.

type Registry 

type Registry interface {
	Register(tools.Tool)
}

type Tool 

type Tool struct {
	Client     Client
	Descriptor ToolDescriptor
	Options    RegisterOptions
}

func (Tool) Execute 

func (t Tool) Execute(ctx context.Context, input json.RawMessage, env tools.Env) (*tools.Result, error)

func (Tool) Spec 

func (t Tool) Spec() tools.Spec

type ToolAnnotations 

type ToolAnnotations struct {
	ReadOnlyHint    bool `json:"readOnlyHint,omitempty"`
	DestructiveHint bool `json:"destructiveHint,omitempty"`
	IdempotentHint  bool `json:"idempotentHint,omitempty"`
	OpenWorldHint   bool `json:"openWorldHint,omitempty"`
}

ToolAnnotations follows MCP-style safety hints. Unknown tools remain permissionless so goagent policy denies them unless the host opts in.

type ToolCallResult 

type ToolCallResult struct {
	Content           []ContentPart   `json:"content,omitempty"`
	StructuredContent json.RawMessage `json:"structuredContent,omitempty"`
	IsError           bool            `json:"isError,omitempty"`
	Ref               string          `json:"ref,omitempty"`
	Metadata          map[string]any  `json:"metadata,omitempty"`
}

ToolCallResult is a transport-neutral MCP tool result. Content is projected separately for model-visible and user-visible goagent tool fields.

type ToolDescriptor 

type ToolDescriptor struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	InputSchema json.RawMessage `json:"inputSchema,omitempty"`
	Annotations ToolAnnotations `json:"annotations,omitempty"`
	Metadata    map[string]any  `json:"metadata,omitempty"`
}

ToolDescriptor is the subset of an MCP tool descriptor needed to expose the tool through goagent. Transport and session fields intentionally stay out.

Source Files

View all Source files

Directories

Path Synopsis
examples/goagent-mcp-http command
examples/http-smoke command
examples/stdio-smoke command

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.