mcp

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 18, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package mcp implements the Model Context Protocol (MCP) Streamable HTTP handler.

Index

Constants

This section is empty.

Variables

View Source
var ValidPhases = map[string]bool{
	"research":    true,
	"planning":    true,
	"design":      true,
	"development": true,
	"deployed":    true,
	"maintenance": true,
	"inactive":    true,
}

ValidPhases defines the allowed lifecycle phases for a project.

Functions

func NewHTTPHandler

func NewHTTPHandler(h *Handler) http.Handler

NewHTTPHandler creates an http.Handler that serves the MCP protocol over Streamable HTTP in stateless JSON response mode.

Types

type ClaimInfo added in v0.1.20

type ClaimInfo struct {
	WorkerID  string `json:"worker_id"`
	ClaimedAt string `json:"claimed_at"` // RFC3339
	Duration  string `json:"duration"`
}

ClaimInfo holds read-only info about a current claim.

type ClaimResult added in v0.1.20

type ClaimResult struct {
	IssueNumber int    `json:"issue_number"`
	Owner       string `json:"owner"`
	Repo        string `json:"repo"`
	WorkerID    string `json:"worker_id"`
	ClaimedAt   string `json:"claimed_at"` // RFC3339
	Phase       string `json:"phase,omitempty"`
}

ClaimResult is returned when an issue is successfully claimed.

type ForgeWorkCoordinator added in v0.1.20

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

ForgeWorkCoordinator implements WorkCoordinator using direct forge operations. This is used in the serve process where the dispatcher is not running. It manages claims in memory and transitions labels via the forge API.

func NewForgeWorkCoordinator added in v0.1.20

func NewForgeWorkCoordinator(projects *ProjectRegistry, logger *zap.Logger) *ForgeWorkCoordinator

NewForgeWorkCoordinator creates a ForgeWorkCoordinator backed by the project registry.

func (*ForgeWorkCoordinator) ClaimIssue added in v0.1.20

func (f *ForgeWorkCoordinator) ClaimIssue(ctx context.Context, owner, repo string, number int, workerID string) (*ClaimResult, error)

ClaimIssue claims a specific issue for an interactive worker.

func (*ForgeWorkCoordinator) CompleteIssue added in v0.1.20

func (f *ForgeWorkCoordinator) CompleteIssue(ctx context.Context, owner, repo string, number int, workerID string, prNumber int, summary string) error

CompleteIssue marks a claimed issue as done.

func (*ForgeWorkCoordinator) GetClaimInfo added in v0.1.20

func (f *ForgeWorkCoordinator) GetClaimInfo(owner, repo string, number int) *ClaimInfo

GetClaimInfo returns read-only claim information for an issue.

func (*ForgeWorkCoordinator) HeartbeatIssue added in v0.1.20

func (f *ForgeWorkCoordinator) HeartbeatIssue(_ context.Context, owner, repo string, number int, workerID string) (*HeartbeatResult, error)

HeartbeatIssue resets the heartbeat timer for a claimed issue.

func (*ForgeWorkCoordinator) ReleaseIssue added in v0.1.20

func (f *ForgeWorkCoordinator) ReleaseIssue(ctx context.Context, owner, repo string, number int, workerID, reason string) error

ReleaseIssue returns a claimed issue to the queue.

func (*ForgeWorkCoordinator) RequestWork added in v0.1.20

func (f *ForgeWorkCoordinator) RequestWork(ctx context.Context, workerID string, opts *WorkRequestOptions) (*ClaimResult, *forge.Issue, error)

RequestWork finds the next best queued issue and claims it.

type Handler

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

Handler holds dependencies for MCP tool handlers.

func NewHandler

func NewHandler(tracker forge.IssueTracker, costs digest.CostSource, s store.Store, policy autonomy.AutonomyPolicy, repo forge.RepoReader) *Handler

NewHandler creates a new MCP tool handler with its dependencies. The store, policy, and repo parameters are optional (may be nil) for graceful degradation.

func (*Handler) SetLogQuerier added in v0.1.21

func (h *Handler) SetLogQuerier(lq logQuerier)

SetLogQuerier attaches a log querier for the get_session_log tool.

func (*Handler) SetMetrics added in v0.1.11

func (h *Handler) SetMetrics(pool poolMetricsSource, disp dispatcherMetricsSource, sys systemMetricsSource)

SetMetrics attaches runtime metrics sources to the handler. Sources may be nil; only non-nil sources appear in the digest.

func (*Handler) SetPRManager

func (h *Handler) SetPRManager(prm forge.PullRequestManager)

SetPRManager attaches a PullRequestManager to the handler.

func (*Handler) SetProjects

func (h *Handler) SetProjects(reg *ProjectRegistry)

SetProjects attaches a project registry to the handler for multi-project support. When set, tools resolve tracker and repo through the active project.

func (*Handler) SetProviderHealth added in v0.1.21

func (h *Handler) SetProviderHealth(ph providerHealthSource)

SetProviderHealth attaches a provider health source for the get_provider_health tool.

func (*Handler) SetScalingEventReader added in v0.1.11

func (h *Handler) SetScalingEventReader(r scalingEventReader)

SetScalingEventReader attaches a scaling event reader for the digest. When set, recent scaling activity appears in the System Health section.

func (*Handler) SetWorkCoordinator added in v0.1.20

func (h *Handler) SetWorkCoordinator(wc WorkCoordinator)

SetWorkCoordinator attaches a work coordinator (dispatcher) for interactive work checkout/checkin tools.

func (*Handler) SetWorkerLister added in v0.1.11

func (h *Handler) SetWorkerLister(wl workerLister)

SetWorkerLister attaches a worker lister so the digest includes PC agent status.

func (*Handler) SetWriter added in v0.1.21

func (h *Handler) SetWriter(w forge.RepoWriter)

SetWriter attaches a RepoWriter for write operations (create_branch, write_file).

type HeartbeatResult added in v0.1.20

type HeartbeatResult struct {
	ClaimDuration string `json:"claim_duration"`
	Status        string `json:"status"`
}

HeartbeatResult is returned by HeartbeatIssue.

type PendingAction

type PendingAction struct {
	ID        string
	ToolName  string
	Execute   func() (*gosdk.CallToolResult, error) // closure captures handler + input
	CreatedAt time.Time
}

PendingAction represents an MCP tool call queued for user confirmation (Tier 3).

type Project

type Project struct {
	Name      string                   `json:"name" yaml:"name"`
	Owner     string                   `json:"owner" yaml:"owner"`
	Repo      string                   `json:"repo" yaml:"repo"`
	Phase     string                   `json:"phase" yaml:"phase"`
	Tags      []string                 `json:"tags,omitempty" yaml:"tags"`
	Tracker   forge.IssueTracker       `json:"-" yaml:"-"`
	Reader    forge.RepoReader         `json:"-" yaml:"-"`
	Writer    forge.RepoWriter         `json:"-" yaml:"-"`
	PRManager forge.PullRequestManager `json:"-" yaml:"-"`
}

Project represents a registered project with its forge connection.

type ProjectConfig

type ProjectConfig struct {
	Name       string   `yaml:"name"`
	Owner      string   `yaml:"owner"`
	Repo       string   `yaml:"repo"`
	Forge      string   `yaml:"forge"`       // "github" (default) or "gitea"
	GiteaURL   string   `yaml:"gitea_url"`   // required when forge = "gitea"
	GiteaToken string   `yaml:"gitea_token"` // optional; falls back to GITEA_TOKEN env var
	Phase      string   `yaml:"phase"`       // lifecycle phase; defaults to "development"
	Tags       []string `yaml:"tags"`        // optional classification tags
}

ProjectConfig is the YAML-serializable configuration for a project. Forge may be "github" (default) or "gitea". Gitea projects require GiteaURL and optionally GiteaToken (falls back to GITEA_TOKEN environment variable).

func LoadProjectConfig

func LoadProjectConfig(path string) ([]ProjectConfig, error)

LoadProjectConfig reads and parses a YAML projects configuration file.

type ProjectRegistry

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

ProjectRegistry manages the set of available projects.

func NewProjectRegistry

func NewProjectRegistry() *ProjectRegistry

NewProjectRegistry creates a new empty project registry.

func (*ProjectRegistry) Active

func (r *ProjectRegistry) Active() (*Project, error)

Active returns the currently active project. Returns an error if no projects are registered or no project is active.

func (*ProjectRegistry) ActiveName

func (r *ProjectRegistry) ActiveName() string

ActiveName returns the name of the currently active project.

func (*ProjectRegistry) Get

func (r *ProjectRegistry) Get(name string) (*Project, bool)

Get retrieves a project by name.

func (*ProjectRegistry) List

func (r *ProjectRegistry) List() []*Project

List returns all registered projects sorted by name.

func (*ProjectRegistry) PhaseFor added in v0.1.21

func (r *ProjectRegistry) PhaseFor(owner, repo string) (string, bool)

PhaseFor returns the lifecycle phase for the project matching the given owner/repo pair. Returns ("", false) if no matching project is registered. This method satisfies the dispatcher.ProjectResolver interface.

func (*ProjectRegistry) Register

func (r *ProjectRegistry) Register(p *Project) error

Register adds a project to the registry. Returns an error if the name is empty or already registered. The first registered project becomes active.

func (*ProjectRegistry) SetActive

func (r *ProjectRegistry) SetActive(name string) error

SetActive switches the active project context. Returns an error if the named project is not registered.

func (*ProjectRegistry) SetConfigPath added in v0.1.21

func (r *ProjectRegistry) SetConfigPath(path string)

SetConfigPath records the path to the server.yaml file so that SetPhase can persist phase changes back to disk. Call this after loading configs.

func (*ProjectRegistry) SetPhase added in v0.1.21

func (r *ProjectRegistry) SetPhase(name, phase string) error

SetPhase updates the lifecycle phase of the named project in memory and, if a config path is set, persists the change to the server.yaml file. Returns an error if the project is not found or the phase is invalid.

func (*ProjectRegistry) TrackerFor added in v0.1.16

func (r *ProjectRegistry) TrackerFor(owner, repo string) (forge.IssueTracker, bool)

TrackerFor returns the IssueTracker for the project matching the given owner/repo pair. Returns nil, false if no matching project is registered. This method satisfies the dispatcher.ProjectResolver interface.

type WorkCoordinator added in v0.1.20

type WorkCoordinator interface {
	// ClaimIssue claims a specific issue for an interactive worker.
	ClaimIssue(ctx context.Context, owner, repo string, number int, workerID string) (*ClaimResult, error)

	// RequestWork finds the next best queued issue matching filters and claims it.
	RequestWork(ctx context.Context, workerID string, opts *WorkRequestOptions) (*ClaimResult, *forge.Issue, error)

	// CompleteIssue marks a claimed issue as done (status:claimed -> status:needs-qc).
	CompleteIssue(ctx context.Context, owner, repo string, number int, workerID string, prNumber int, summary string) error

	// ReleaseIssue returns a claimed issue to the queue without completing it.
	ReleaseIssue(ctx context.Context, owner, repo string, number int, workerID string, reason string) error

	// HeartbeatIssue resets the heartbeat timer for a claimed issue.
	HeartbeatIssue(ctx context.Context, owner, repo string, number int, workerID string) (*HeartbeatResult, error)

	// GetClaimInfo returns claim info for an issue, or nil if not claimed.
	GetClaimInfo(owner, repo string, number int) *ClaimInfo
}

WorkCoordinator defines the dispatcher interface for MCP work tools. The dispatcher implements this; the MCP package depends only on the interface.

type WorkRequestOptions added in v0.1.20

type WorkRequestOptions struct {
	Project    string
	Labels     []string
	Priority   string
	Complexity string
}

WorkRequestOptions are optional filters for RequestWork.

type WorkerInfo added in v0.1.11

type WorkerInfo struct {
	AgentID         string
	Hostname        string
	Status          string
	CurrentTask     *int
	ActiveWorktrees int
	CPUPercent      float64
	MemoryPercent   float64
}

WorkerInfo is a summary of a registered PC agent worker for digest output.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL