mcp

Documentation

Overview

Package mcp implements a Model Context Protocol server over stdio.

MCP (https://modelcontextprotocol.io) is a standard protocol that allows AI agents (Claude Code, Cursor, etc.) to discover and invoke tools. This package implements an MCP server that exposes kode's built-in tools via the stdio transport — the protocol Claude Code uses natively.

Architecture:

MCP Client (Claude Code)          kode mcp (this package)
┌─────────────────────┐           ┌──────────────────────┐
│  tools/list ──────────────►   │  Responds with       │
│                     │           │  tool schemas         │
│  tools/call ──────────────►   │  Executes tool,       │
│                     │           │  returns result       │
│  ◄────── result ────│           │                      │
└─────────────────────┘           └──────────────────────┘
       stdin/stdout                   stdin/stdout

Security: uses the same DangerousConfig + Approver system as CLI mode. In MCP mode there's no TTY — the NonInteractiveAction fallback applies.

Index

• Constants
• type CallToolParams
• type CallToolResult
• type ContentItem
• type InitializeRequest
• type InitializeResult
• type JSONRPCError
• type JSONRPCRequest
• type JSONRPCResponse
• type ListToolsResult
• type NativeTool
  • func BuildNativeTools(callers []ToolCaller) []NativeTool
• type Server
  • func NewServer(version string, tools []NativeTool, reader io.Reader, writer io.Writer) *Server
  • func (s *Server) Run(ctx context.Context) error
• type Tool
• type ToolCaller

Constants

const (
	ErrCodeParse          = -32700
	ErrCodeInvalidReq     = -32600
	ErrCodeMethodNotFound = -32601
	ErrCodeInvalidParams  = -32602
	ErrCodeInternal       = -32603
)

Standard JSON-RPC error codes.

const (
	ProtocolVersion = "2025-03-26"
)

Types

type CallToolParams

type CallToolParams struct {
	Name      string `json:"name"`
	Arguments any    `json:"arguments"`
}

CallToolParams is the params for tools/call.

type CallToolResult

type CallToolResult struct {
	Content []ContentItem `json:"content"`
	IsError bool          `json:"isError,omitempty"`
}

CallToolResult is the response to tools/call.

type ContentItem

type ContentItem struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

ContentItem is a single piece of content in a tool result.

type InitializeRequest

type InitializeRequest struct {
	ProtocolVersion string         `json:"protocolVersion"`
	Capabilities    map[string]any `json:"capabilities"`
	ClientInfo      struct {
		Name    string `json:"name"`
		Version string `json:"version"`
	} `json:"clientInfo"`
}

InitializeRequest is the MCP initialize method params.

type InitializeResult

type InitializeResult struct {
	ProtocolVersion string         `json:"protocolVersion"`
	Capabilities    map[string]any `json:"capabilities"`
	ServerInfo      struct {
		Name    string `json:"name"`
		Version string `json:"version"`
	} `json:"serverInfo"`
}

InitializeResult is the response to initialize.

type JSONRPCError

type JSONRPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

JSONRPCError represents a JSON-RPC error object.

type JSONRPCRequest

type JSONRPCRequest struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id"` // can be string, number, or null (notifications)
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

JSONRPCRequest is a generic incoming JSON-RPC 2.0 request.

type JSONRPCResponse

type JSONRPCResponse struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id"`
	Result  any             `json:"result,omitempty"`
	Error   *JSONRPCError   `json:"error,omitempty"`
}

JSONRPCResponse is a generic outgoing JSON-RPC 2.0 response.

type ListToolsResult

type ListToolsResult struct {
	Tools []Tool `json:"tools"`
}

ListToolsResult is the response to tools/list.

type NativeTool

type NativeTool struct {
	Name        string
	Description string
	Schema      any
	CallFn      func(args string) (string, error)
}

NativeTool wraps a kode Tool interface for MCP exposure.

func BuildNativeTools

func BuildNativeTools(callers []ToolCaller) []NativeTool

BuildNativeTools wraps a slice of kode.Tool-compatible values as MCP NativeTool entries for the server. Skips tools that don't make sense in MCP context (delegate_tasks, memory).

type Server

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

Server implements the MCP protocol over stdio transport. It reads JSON-RPC requests from stdin and writes responses to stdout.

func NewServer

func NewServer(version string, tools []NativeTool, reader io.Reader, writer io.Writer) *Server

NewServer creates an MCP server that reads from the given reader and writes responses to the given writer. For stdio transport, pass os.Stdin and os.Stdout. Tests can pass pipes or buffers.

func (*Server) Run

func (s *Server) Run(ctx context.Context) error

Run reads requests from stdin and processes them until EOF.

type Tool

type Tool struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	InputSchema any    `json:"inputSchema"`
}

Tool is an MCP tool definition returned by tools/list.

type ToolCaller

type ToolCaller interface {
	Name() string
	Description() string
	Schema() any
	Call(args string) (string, error)
}

ToolCaller is the interface a tool must implement to be exposed via MCP.