mcp

Documentation

Overview

Package mcp implements a minimal stdio MCP (Model Context Protocol) server that exposes codag's log-tail tools to any MCP-aware agent — Claude Code, Cursor, Codex, Continue, Cline, etc.

Transport: line-delimited JSON-RPC 2.0 over stdin/stdout. Methods supported:

• initialize ⟶ negotiate capabilities
• tools/list ⟶ enumerate registered tools
• tools/call ⟶ invoke a tool by name with args
• notifications/initialized (notification — no response)

We deliberately don't pull in a third-party MCP SDK. The protocol surface is small enough that a focused 200-line implementation is clearer than dragging a dep, and gives us full control over framing + error shaping.

Index

• Constants
• func RegisterAll(s *Server)
• type Server
  • func NewServer(version string) *Server
  • func (s *Server) Register(t Tool)
  • func (s *Server) Serve() error
• type Tool
• type ToolCtx
  • func (c ToolCtx) Progress(progress float64, total float64, message string)

Constants

const ProtocolVersion = "2025-03-26"

MCP wire version we advertise. MCP went 1.0 in late 2024; minor revs since are backward-compatible at the level of methods we use.

Functions

func RegisterAll

func RegisterAll(s *Server)

Types

type Server

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

Server holds the tool registry and dispatch logic.

func NewServer

func NewServer(version string) *Server

NewServer wires stdin/stdout. Diagnostics go to stderr — never stdout, which is reserved for JSON-RPC frames. version is the CLI build version (passed in because internal/mcp cannot import cmd).

func (*Server) Register

func (s *Server) Register(t Tool)

Register adds a tool to the server's registry.

func (*Server) Serve

func (s *Server) Serve() error

Serve runs the read loop until stdin closes. Each incoming request is handed to a goroutine so a slow tool call doesn't block reading further messages from the host (which is required to handle notifications/cancelled, ping, etc. mid-flight).

type Tool

type Tool struct {
	Name        string                                                 `json:"name"`
	Description string                                                 `json:"description"`
	InputSchema map[string]interface{}                                 `json:"inputSchema"`
	Annotations map[string]interface{}                                 `json:"annotations,omitempty"`
	Handler     func(ctx ToolCtx, args map[string]any) (string, error) `json:"-"`
}

Tool is what we register; the server exposes it via tools/list.

type ToolCtx

type ToolCtx struct {
	context.Context
	// contains filtered or unexported fields
}

ToolCtx is passed to every handler. It exposes a way to send `notifications/progress` updates back to the client during a long-running tool call. Clients that opt in by supplying a `_meta.progressToken` in the tools/call params get heartbeat updates; clients that didn't opt in see no-op (the helper silently drops).

The embedded context.Context is the cancellation channel. When the client sends `notifications/cancelled` for this tool call, the context is canceled — handlers should respect it (e.g. `exec.CommandContext` kills the child process) so the tool returns promptly instead of hanging until completion. Clients that DON'T explicitly cancel still get a fresh context.

func (ToolCtx) Progress

func (c ToolCtx) Progress(progress float64, total float64, message string)

Progress emits a notifications/progress event. progress is the current step (e.g. seconds elapsed); total is the expected max (or 0 for unbounded). message is human-readable.