Documentation
¶
Overview ¶
Package mcp implements the Model Context Protocol (MCP) Streamable HTTP handler.
Index ¶
- Variables
- func NewHTTPHandler(h *Handler) http.Handler
- type ClaimInfo
- type ClaimResult
- type ForgeWorkCoordinator
- func (f *ForgeWorkCoordinator) ClaimIssue(ctx context.Context, owner, repo string, number int, workerID string) (*ClaimResult, error)
- func (f *ForgeWorkCoordinator) CompleteIssue(ctx context.Context, owner, repo string, number int, workerID string, ...) error
- func (f *ForgeWorkCoordinator) GetClaimInfo(owner, repo string, number int) *ClaimInfo
- func (f *ForgeWorkCoordinator) HeartbeatIssue(_ context.Context, owner, repo string, number int, workerID string) (*HeartbeatResult, error)
- func (f *ForgeWorkCoordinator) ReleaseIssue(ctx context.Context, owner, repo string, number int, workerID, reason string) error
- func (f *ForgeWorkCoordinator) RequestWork(ctx context.Context, workerID string, opts *WorkRequestOptions) (*ClaimResult, *forge.Issue, error)
- type Handler
- func (h *Handler) SetLogQuerier(lq logQuerier)
- func (h *Handler) SetMetrics(pool poolMetricsSource, disp dispatcherMetricsSource, sys systemMetricsSource)
- func (h *Handler) SetPRManager(prm forge.PullRequestManager)
- func (h *Handler) SetProjects(reg *ProjectRegistry)
- func (h *Handler) SetProviderHealth(ph providerHealthSource)
- func (h *Handler) SetScalingEventReader(r scalingEventReader)
- func (h *Handler) SetWorkCoordinator(wc WorkCoordinator)
- func (h *Handler) SetWorkerLister(wl workerLister)
- func (h *Handler) SetWriter(w forge.RepoWriter)
- type HeartbeatResult
- type PendingAction
- type Project
- type ProjectConfig
- type ProjectRegistry
- func (r *ProjectRegistry) Active() (*Project, error)
- func (r *ProjectRegistry) ActiveName() string
- func (r *ProjectRegistry) Get(name string) (*Project, bool)
- func (r *ProjectRegistry) List() []*Project
- func (r *ProjectRegistry) PhaseFor(owner, repo string) (string, bool)
- func (r *ProjectRegistry) Register(p *Project) error
- func (r *ProjectRegistry) SetActive(name string) error
- func (r *ProjectRegistry) SetConfigPath(path string)
- func (r *ProjectRegistry) SetPhase(name, phase string) error
- func (r *ProjectRegistry) TrackerFor(owner, repo string) (forge.IssueTracker, bool)
- type WorkCoordinator
- type WorkRequestOptions
- type WorkerInfo
Constants ¶
This section is empty.
Variables ¶
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 ¶
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
WorkRequestOptions are optional filters for RequestWork.