mcp

Documentation

Overview

Package mcp implements the MCP (Model Context Protocol) server for Stapler Squad. Activated by the --mcp flag; communicates over stdio transport.

Index

• Constants
• func InitMCPLogging()
• func NewCore(store session.InstanceStore, svc *services.SessionService, ...) *mcpserver.MCPServer
• func NewHTTPHandler(store session.InstanceStore, svc *services.SessionService, ...) *mcpserver.StreamableHTTPServer
• func RunServer(ctx context.Context, store session.InstanceStore, svc *services.SessionService, ...) error
• type BranchInfo
• type CreateSessionResult
• type DiffStats
• type GetSessionDiffResult
• type GetSessionResult
• type ListSessionBranchesResult
• type ListSessionsResult
• type MCPError
• type MCPResult
• type ReadSessionOutputResult
• type RunCommandResult
• type SearchSessionsResult
• type SendControlResult
• type SessionDetail
• type SessionSummary
• type WaitForOutputResult
• type WriteSessionResult

Constants

const (
	ErrSessionNotFound       = "SESSION_NOT_FOUND"
	ErrInvalidArgument       = "INVALID_ARGUMENT"
	ErrInternalError         = "INTERNAL_ERROR"
	ErrConfirmationRequired  = "CONFIRMATION_REQUIRED"
	ErrInvalidStatusTrans    = "INVALID_STATUS_TRANSITION"
	ErrSessionNotRunning     = "SESSION_NOT_RUNNING"
	ErrRateLimitExceeded     = "RATE_LIMIT_EXCEEDED"
	ErrSessionStartupTimeout = "SESSION_STARTUP_TIMEOUT"
	ErrInvalidPath           = "INVALID_PATH"
	ErrPTYWriteTimeout       = "PTY_WRITE_TIMEOUT"
)

Error code constants — machine-readable identifiers for all tool failures.

Functions

func InitMCPLogging

func InitMCPLogging()

InitMCPLogging redirects all application loggers to stderr so that log lines do not pollute the MCP stdio channel (stdout). Must be called before RunServer.

func NewCore

func NewCore(store session.InstanceStore, svc *services.SessionService, sbMgr *scrollback.ScrollbackManager) *mcpserver.MCPServer

NewCore creates an MCPServer with all 15 tools registered. Shared by the stdio path (RunServer) and the HTTP path (NewHTTPHandler).

func NewHTTPHandler

func NewHTTPHandler(store session.InstanceStore, svc *services.SessionService, sbMgr *scrollback.ScrollbackManager) *mcpserver.StreamableHTTPServer

NewHTTPHandler returns an http.Handler that serves the MCP protocol over Streamable HTTP (the MCP 2025-03-26 transport). Mount it at /mcp on the existing HTTP server so Claude sessions can connect without spawning a subprocess.

func RunServer

func RunServer(ctx context.Context, store session.InstanceStore, svc *services.SessionService, sbMgr *scrollback.ScrollbackManager) error

RunServer initializes and starts the MCP stdio server. It blocks until the context is cancelled or stdin is closed. store is used for read-only discovery tools. svc provides lifecycle operations. sbMgr provides read access to terminal scrollback data persisted on disk.

Types

type BranchInfo

type BranchInfo struct {
	Name    string `json:"name"`
	Current bool   `json:"current"`
}

BranchInfo holds branch metadata for list_session_branches.

type CreateSessionResult

type CreateSessionResult struct {
	MCPResult
	Session            *SessionDetail `json:"session,omitempty"`
	MCPInjectionFailed bool           `json:"mcp_injection_failed,omitempty"`
}

CreateSessionResult is returned by create_session.

type DiffStats

type DiffStats struct {
	FilesChanged int `json:"files_changed"`
	Insertions   int `json:"insertions"`
	Deletions    int `json:"deletions"`
}

DiffStats mirrors git.DiffStats for JSON output.

type GetSessionDiffResult

type GetSessionDiffResult struct {
	MCPResult
	Diff      string    `json:"diff"`
	Stats     DiffStats `json:"stats"`
	Truncated bool      `json:"truncated"`
}

GetSessionDiffResult is the response for get_session_diff.

type GetSessionResult

type GetSessionResult struct {
	MCPResult
	Session *SessionDetail `json:"session,omitempty"`
}

GetSessionResult is returned by get_session.

type ListSessionBranchesResult

type ListSessionBranchesResult struct {
	MCPResult
	Branches      []BranchInfo `json:"branches"`
	CurrentBranch string       `json:"current_branch"`
}

ListSessionBranchesResult is the response for list_session_branches.

type ListSessionsResult

type ListSessionsResult struct {
	MCPResult
	Sessions   []SessionSummary `json:"sessions"`
	TotalCount int              `json:"total_count"`
	NextCursor *string          `json:"next_cursor"`
}

ListSessionsResult is returned by list_sessions.

type MCPError

type MCPError struct {
	Code        string `json:"code"`
	Message     string `json:"message"`
	Remediation string `json:"remediation,omitempty"`
}

MCPError is the structured error returned in every tool result on failure.

type MCPResult

type MCPResult struct {
	Success bool      `json:"success"`
	Error   *MCPError `json:"error,omitempty"`
}

MCPResult is the top-level wrapper for all tool responses. On success, Success=true and Error is nil. On failure, Success=false and Error is set.

type ReadSessionOutputResult

type ReadSessionOutputResult struct {
	MCPResult
	Output     string `json:"output,omitempty"`
	TotalLines int    `json:"total_lines"`
	Truncated  bool   `json:"truncated"`
}

ReadSessionOutputResult is the response type for read_session_output.

type RunCommandResult

type RunCommandResult struct {
	MCPResult
	Output       string `json:"output"`
	Truncated    bool   `json:"truncated"`
	TimedOut     bool   `json:"timed_out"`
	LastSequence uint64 `json:"last_sequence"`
}

RunCommandResult is the response for run_command.

type SearchSessionsResult

type SearchSessionsResult struct {
	MCPResult
	Sessions   []SessionSummary `json:"sessions"`
	TotalCount int              `json:"total_count"`
}

SearchSessionsResult is returned by search_sessions.

type SendControlResult

type SendControlResult struct {
	MCPResult
	Sent string `json:"sent"`
}

SendControlResult is the response for send_control.

type SessionDetail

type SessionDetail struct {
	SessionSummary
	Program     string `json:"program"`
	SessionType string `json:"session_type"`
	WorkingDir  string `json:"working_dir,omitempty"`
}

SessionDetail extends SessionSummary with additional fields returned by get_session.

type SessionSummary

type SessionSummary struct {
	ID             string    `json:"id"`
	Title          string    `json:"title"`
	Status         string    `json:"status"`
	Tags           []string  `json:"tags"`
	Branch         string    `json:"branch,omitempty"`
	Path           string    `json:"path"`
	CreatedAt      time.Time `json:"created_at"`
	LastActivityAt time.Time `json:"last_activity_at"`
}

SessionSummary is returned by list_sessions and search_sessions.

type WaitForOutputResult

type WaitForOutputResult struct {
	MCPResult
	Matched     bool   `json:"matched"`
	MatchedLine string `json:"matched_line,omitempty"`
	Output      string `json:"output"`
	Truncated   bool   `json:"truncated"`
}

WaitForOutputResult is the response for wait_for_output.

type WriteSessionResult

type WriteSessionResult struct {
	MCPResult
	BytesWritten int `json:"bytes_written"`
}

WriteSessionResult is the response for write_to_session.