mcp

Documentation

Overview

Package mcp implements the focus MCP server (`focus mcp serve`).

Tools are thin wrappers over internal/board so the MCP surface and the CLI surface never drift — designs/focus-issue-001.md §"CLI/MCP shared logic placement". The server runs over stdio and resolves the .focus/ board the same way the CLI does: ancestor-walk from the calling agent's working directory.

Index

• func Serve(ctx context.Context, version string) error
• type BoardResult
• type CardSummary
• type EditBodyArgs
• type EmptyArgs
• type EpicAddArgs
• type EpicAddResult
• type EpicListResult
• type EpicProgress
• type IDArgs
• type IDForceArgs
• type ListArgs
• type ListResult
• type NewArgs
• type NewResult
• type ReindexResult
• type ShowResult
• type TransitionResult

Functions

func Serve

func Serve(ctx context.Context, version string) error

Serve runs the MCP server over stdio until the client disconnects or ctx is cancelled. version is stamped into the initialize-time implementation info; the CLI passes its own Version constant in.

At startup the server resolves a default focus dir using FOCUS_DIR and the upward walk from the server's CWD. Per-tool `focus_dir` arguments override that default.

Types

type BoardResult

type BoardResult struct {
	Active  []CardSummary `json:"active"`
	Backlog []CardSummary `json:"backlog"`
	Epics   []CardSummary `json:"epics"`
}

BoardResult is the focus_board output: active, backlog, epics.

type CardSummary

type CardSummary struct {
	ID       int      `json:"id"`
	UUID     string   `json:"uuid"`
	Title    string   `json:"title"`
	Type     string   `json:"type"`
	Status   string   `json:"status"`
	Priority string   `json:"priority"`
	Project  string   `json:"project"`
	Epic     *int     `json:"epic,omitempty"`
	Tags     []string `json:"tags,omitempty"`
	Owner    string   `json:"owner,omitempty"`
	Created  string   `json:"created"`
	Dir      string   `json:"dir"`
}

CardSummary is the per-card payload shape returned by every list-y tool. We mirror the index.Entry fields directly because that's the shape internal/board already produces; keeping them aligned avoids an extra translation layer.

type EditBodyArgs

type EditBodyArgs struct {
	ID       int    `json:"id"`
	Body     string `json:"body" jsonschema:"new markdown body; replaces the existing body verbatim"`
	FocusDir string `` /* 130-byte string literal not displayed */
}

EditBodyArgs replaces a card's markdown body.

type EmptyArgs

type EmptyArgs struct {
	FocusDir string `` /* 130-byte string literal not displayed */
}

EmptyArgs is the input type for tools that take no arguments other than the optional focus_dir override.

type EpicAddArgs

type EpicAddArgs struct {
	EpicID   int    `json:"epic_id"`
	CardID   int    `json:"card_id"`
	Force    bool   `json:"force,omitempty" jsonschema:"skip the epic-id existence check"`
	FocusDir string `` /* 130-byte string literal not displayed */
}

EpicAddArgs links a card to an epic.

type EpicAddResult

type EpicAddResult struct {
	EpicID int `json:"epic_id"`
	CardID int `json:"card_id"`
}

EpicAddResult confirms the link.

type EpicListResult

type EpicListResult struct {
	Epics []EpicProgress `json:"epics"`
}

EpicListResult wraps the per-epic progress summary.

type EpicProgress

type EpicProgress struct {
	CardSummary
	Active   int `json:"active"`
	Backlog  int `json:"backlog"`
	Done     int `json:"done"`
	Archived int `json:"archived"`
	Total    int `json:"total"`
}

EpicProgress is the summary returned for one epic.

type IDArgs

type IDArgs struct {
	ID       int    `json:"id" jsonschema:"the card id (board-local integer)"`
	FocusDir string `` /* 130-byte string literal not displayed */
}

IDArgs is the input type for tools that accept exactly one id.

type IDForceArgs

type IDForceArgs struct {
	ID       int    `json:"id" jsonschema:"the card id (board-local integer)"`
	Force    bool   `json:"force,omitempty" jsonschema:"bypass from-status validation"`
	FocusDir string `` /* 130-byte string literal not displayed */
}

IDForceArgs adds the force flag for transitions that allow it.

type ListArgs

type ListArgs struct {
	Status   string `json:"status,omitempty"`
	Project  string `json:"project,omitempty"`
	Priority string `json:"priority,omitempty"`
	Owner    string `json:"owner,omitempty"`
	Tag      string `json:"tag,omitempty"`
	Type     string `json:"type,omitempty"`
	Epic     int    `json:"epic,omitempty"`
	FocusDir string `` /* 130-byte string literal not displayed */
}

ListArgs filters a focus_list call. All fields are optional.

type ListResult

type ListResult struct {
	Cards []CardSummary `json:"cards"`
}

ListResult wraps a flat card list.

type NewArgs

type NewArgs struct {
	Title    string `json:"title" jsonschema:"card title (free-form)"`
	Project  string `json:"project,omitempty" jsonschema:"project tag; defaults to the board's parent dir name"`
	Priority string `json:"priority,omitempty" jsonschema:"priority p0|p1|p2|p3; defaults to p2"`
	Type     string `json:"type,omitempty" jsonschema:"card or epic; defaults to card"`
	Epic     int    `json:"epic,omitempty" jsonschema:"parent epic id (omit for none)"`
	Slug     string `json:"slug,omitempty" jsonschema:"override the auto-derived folder slug"`
	FocusDir string `` /* 130-byte string literal not displayed */
}

NewArgs is the input type for focus_new. Mirrors NewCardOpts but uses primitives the JSON schema generator can describe.

type NewResult

type NewResult struct {
	ID   int    `json:"id"`
	UUID string `json:"uuid"`
	Dir  string `json:"dir"`
}

NewResult is focus_new's output: the assigned id, uuid, and dir.

type ReindexResult

type ReindexResult struct {
	Cards  int `json:"cards"`
	NextID int `json:"next_id"`
}

ReindexResult reports the rebuilt index size + next_id.

type ShowResult

type ShowResult struct {
	CardSummary
	Description string   `json:"description,omitempty"`
	Area        string   `json:"area,omitempty"`
	Contract    []string `json:"contract,omitempty"`
	DependsOn   []int    `json:"depends_on,omitempty"`
	Body        string   `json:"body"`
}

ShowResult is focus_show: full card frontmatter + body.

type TransitionResult

type TransitionResult struct {
	ID     int    `json:"id"`
	Status string `json:"status"`
}

TransitionResult is the standard output for transition tools.