feat(mcp): add Model Context Protocol server implementation

Add MCP server for tool exposure to AI assistants like Claude Code.
Implements JSON-RPC 2.0 protocol with stdio transport.

Features:
- Tool listing and execution via tools/list and tools/call
- Session lifecycle management (initialize, initialized, ping)
- Graceful shutdown handling
- Extensible tool registration

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: grokify

mcp/protocol.go

@@ -0,0 +1,239 @@
+// Package mcp provides Model Context Protocol (MCP) server implementation
+// for exposing agent teams to CLI assistants like Gemini CLI and Codex.
+package mcp
+
+import (
+	"encoding/json"
+)
+
+// JSON-RPC 2.0 types
+
+// Request represents a JSON-RPC 2.0 request.
+type Request struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id,omitempty"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params,omitempty"`
+}
+
+// Response represents a JSON-RPC 2.0 response.
+type Response struct {
+	JSONRPC string          `json:"jsonrpc"`
+	ID      json.RawMessage `json:"id,omitempty"`
+	Result  interface{}     `json:"result,omitempty"`
+	Error   *ErrorResponse  `json:"error,omitempty"`
+}
+
+// ErrorResponse represents a JSON-RPC 2.0 error.
+type ErrorResponse struct {
+	Code    int         `json:"code"`
+	Message string      `json:"message"`
+	Data    interface{} `json:"data,omitempty"`
+}
+
+// Standard JSON-RPC error codes
+const (
+	ErrParseError     = -32700
+	ErrInvalidRequest = -32600
+	ErrMethodNotFound = -32601
+	ErrInvalidParams  = -32602
+	ErrInternalError  = -32603
+)
+
+// MCP Protocol types
+
+// ServerInfo represents MCP server information.
+type ServerInfo struct {
+	Name    string `json:"name"`
+	Version string `json:"version"`
+}
+
+// InitializeParams represents the initialize request parameters.
+type InitializeParams struct {
+	ProtocolVersion string       `json:"protocolVersion"`
+	Capabilities    Capabilities `json:"capabilities"`
+	ClientInfo      ClientInfo   `json:"clientInfo"`
+}
+
+// ClientInfo represents MCP client information.
+type ClientInfo struct {
+	Name    string `json:"name"`
+	Version string `json:"version"`
+}
+
+// Capabilities represents MCP server capabilities.
+type Capabilities struct {
+	Tools     *ToolsCapability     `json:"tools,omitempty"`
+	Resources *ResourcesCapability `json:"resources,omitempty"`
+	Prompts   *PromptsCapability   `json:"prompts,omitempty"`
+}
+
+// ToolsCapability indicates tool support.
+type ToolsCapability struct {
+	ListChanged bool `json:"listChanged,omitempty"`
+}
+
+// ResourcesCapability indicates resource support.
+type ResourcesCapability struct {
+	Subscribe   bool `json:"subscribe,omitempty"`
+	ListChanged bool `json:"listChanged,omitempty"`
+}
+
+// PromptsCapability indicates prompt support.
+type PromptsCapability struct {
+	ListChanged bool `json:"listChanged,omitempty"`
+}
+
+// InitializeResult represents the initialize response.
+type InitializeResult struct {
+	ProtocolVersion string       `json:"protocolVersion"`
+	Capabilities    Capabilities `json:"capabilities"`
+	ServerInfo      ServerInfo   `json:"serverInfo"`
+}
+
+// ToolInfo represents a tool definition.
+type ToolInfo struct {
+	Name        string      `json:"name"`
+	Description string      `json:"description,omitempty"`
+	InputSchema InputSchema `json:"inputSchema"`
+}
+
+// InputSchema represents the JSON Schema for tool input.
+type InputSchema struct {
+	Type       string              `json:"type"`
+	Properties map[string]Property `json:"properties,omitempty"`
+	Required   []string            `json:"required,omitempty"`
+}
+
+// Property represents a JSON Schema property.
+type Property struct {
+	Type        string   `json:"type"`
+	Description string   `json:"description,omitempty"`
+	Enum        []string `json:"enum,omitempty"`
+}
+
+// ListToolsResult represents the tools/list response.
+type ListToolsResult struct {
+	Tools []ToolInfo `json:"tools"`
+}
+
+// CallToolParams represents the tools/call request parameters.
+type CallToolParams struct {
+	Name      string                 `json:"name"`
+	Arguments map[string]interface{} `json:"arguments,omitempty"`
+}
+
+// CallToolResult represents the tools/call response.
+type CallToolResult struct {
+	Content []ContentBlock `json:"content"`
+	IsError bool           `json:"isError,omitempty"`
+}
+
+// ContentBlock represents a content block in a tool result.
+type ContentBlock struct {
+	Type string `json:"type"` // "text" or "image"
+	Text string `json:"text,omitempty"`
+	// For images (not used in this implementation)
+	Data     string `json:"data,omitempty"`
+	MimeType string `json:"mimeType,omitempty"`
+}
+
+// NewTextContent creates a text content block.
+func NewTextContent(text string) ContentBlock {
+	return ContentBlock{
+		Type: "text",
+		Text: text,
+	}
+}
+
+// NewErrorContent creates an error text content block.
+func NewErrorContent(err error) ContentBlock {
+	return ContentBlock{
+		Type: "text",
+		Text: "Error: " + err.Error(),
+	}
+}
+
+// ResourceInfo represents a resource definition.
+type ResourceInfo struct {
+	URI         string `json:"uri"`
+	Name        string `json:"name"`
+	Description string `json:"description,omitempty"`
+	MimeType    string `json:"mimeType,omitempty"`
+}
+
+// ListResourcesResult represents the resources/list response.
+type ListResourcesResult struct {
+	Resources []ResourceInfo `json:"resources"`
+}
+
+// ReadResourceParams represents the resources/read request parameters.
+type ReadResourceParams struct {
+	URI string `json:"uri"`
+}
+
+// ReadResourceResult represents the resources/read response.
+type ReadResourceResult struct {
+	Contents []ResourceContent `json:"contents"`
+}
+
+// ResourceContent represents resource content.
+type ResourceContent struct {
+	URI      string `json:"uri"`
+	MimeType string `json:"mimeType,omitempty"`
+	Text     string `json:"text,omitempty"`
+	Blob     string `json:"blob,omitempty"` // Base64 encoded
+}
+
+// PromptInfo represents a prompt definition.
+type PromptInfo struct {
+	Name        string           `json:"name"`
+	Description string           `json:"description,omitempty"`
+	Arguments   []PromptArgument `json:"arguments,omitempty"`
+}
+
+// PromptArgument represents a prompt argument.
+type PromptArgument struct {
+	Name        string `json:"name"`
+	Description string `json:"description,omitempty"`
+	Required    bool   `json:"required,omitempty"`
+}
+
+// ListPromptsResult represents the prompts/list response.
+type ListPromptsResult struct {
+	Prompts []PromptInfo `json:"prompts"`
+}
+
+// GetPromptParams represents the prompts/get request parameters.
+type GetPromptParams struct {
+	Name      string            `json:"name"`
+	Arguments map[string]string `json:"arguments,omitempty"`
+}
+
+// GetPromptResult represents the prompts/get response.
+type GetPromptResult struct {
+	Description string          `json:"description,omitempty"`
+	Messages    []PromptMessage `json:"messages"`
+}
+
+// PromptMessage represents a message in a prompt.
+type PromptMessage struct {
+	Role    string       `json:"role"` // "user" or "assistant"
+	Content ContentBlock `json:"content"`
+}
+
+// Notification types
+
+// Notification represents a JSON-RPC notification (no response expected).
+type Notification struct {
+	JSONRPC string          `json:"jsonrpc"`
+	Method  string          `json:"method"`
+	Params  json.RawMessage `json:"params,omitempty"`
+}
+
+// ProgressParams represents progress notification parameters.
+type ProgressParams struct {
+	ProgressToken interface{} `json:"progressToken"`
+	Progress      float64     `json:"progress"`
+	Total         float64     `json:"total,omitempty"`
+}