Documentation
¶
Overview ¶
Package mcp implements the local `hatchet mcp` stdio server that lets AI coding agents verify their work against a running Hatchet deployment, plus the grant store that controls which CLI profiles the server may use.
Index ¶
Constants ¶
const EmbeddedProfileName = "embedded"
EmbeddedProfileName is the reserved profile name for the embedded instance. Embedded engines register themselves in the profile store under this name; a stored profile with this name is never treated as a regular profile. It is only usable through detection, which verifies the engine is live and reports embedded: true, and grants it implicitly. A registration whose engine is dead is treated as absent (see detectEmbedded).
const GrantFileName = "mcp-grants.yaml"
GrantFileName is the grants file stored next to the CLI profile store.
const GrantWildcard = "*"
GrantWildcard grants every profile, including profiles created in the future.
Variables ¶
var ( // PosthogAPIKey is the public capture-only project key for cli_mcp_feedback // events (safe to commit: it can ingest events but never read data, like the // keys shipped in browser bundles). Overridable at build time via // ldflags: -X .../cli/internal/mcp.PosthogAPIKey=phc_xxx. The key and // endpoint are pinned at build time: if the key is somehow empty, // submit_feedback reports that feedback cannot be sent. It never falls // back to a key or host chosen by a connected engine. PosthogAPIKey = "phc_Nd6kn74LHMatXkF0OHVJMiq1qp2iu7xUIzRaipZAZY1" // #nosec G101 -- public capture-only project key, not a secret; same class as keys shipped in browser bundles // PosthogEndpoint is the PostHog ingestion host used with PosthogAPIKey. PosthogEndpoint = "https://us.i.posthog.com" )
Functions ¶
This section is empty.
Types ¶
type Deps ¶
type Deps struct {
// Version is the CLI version reported to MCP clients.
Version string
// Profiles provides read access to the CLI profile store.
Profiles ProfileSource
// Grants is the MCP grant store.
Grants *GrantStore
// NewEngine builds an Engine for a resolved profile.
NewEngine EngineFactory
// DetectEmbedded looks for a running embedded instance. Defaults to
// detectEmbedded over Profiles when nil.
DetectEmbedded func(ctx context.Context) *EmbeddedDetection
// Feedback delivers submit_feedback events.
Feedback FeedbackSender
// AnonymousID is the CLI's anonymous telemetry ID, used as the feedback
// distinct ID. Never a user identifier.
AnonymousID string
}
Deps are the injectable dependencies of the MCP server. Everything the tool handlers touch goes through these, so handlers are testable with fakes.
type EmbeddedDetection ¶
type EmbeddedDetection struct {
// Profile is the live-verified connection profile of the embedded
// instance, nil when none was found.
Profile *cliconfig.Profile
// Note explains a stale registration that was skipped.
Note string
}
EmbeddedDetection is the outcome of looking for a running embedded instance via its profile-store registration.
func (*EmbeddedDetection) Detected ¶
func (d *EmbeddedDetection) Detected() bool
Detected reports whether a live embedded instance was found.
type Engine ¶
type Engine interface {
// TenantID returns the tenant the engine's credentials are scoped to.
TenantID() string
// TriggerWorkflow triggers a workflow run and returns the new run ID.
TriggerWorkflow(ctx context.Context, workflow string, input map[string]any, meta map[string]any) (string, error)
// GetRun fetches details for a run (task or DAG) by external ID.
GetRun(ctx context.Context, runID string) (*rest.V1WorkflowRunDetails, error)
// ListTaskEvents lists lifecycle events for a single task run.
ListTaskEvents(ctx context.Context, taskID string) ([]rest.V1TaskEvent, error)
// ListWorkers lists the workers registered with the tenant.
ListWorkers(ctx context.Context) ([]rest.Worker, error)
// ReplayRun replays an existing run in place (same run ID).
ReplayRun(ctx context.Context, runID string) error
// WorkflowName resolves a workflow ID to its name.
WorkflowName(ctx context.Context, workflowID string) (string, error)
// Meta fetches the unauthenticated server metadata.
Meta(ctx context.Context) (*rest.APIMeta, error)
// Version fetches the engine version, if the endpoint is available.
Version(ctx context.Context) (string, error)
}
Engine is the narrow slice of the Hatchet clients that the MCP tools need. Tool handlers depend on this interface so they can be tested with fakes.
func NewClientEngine ¶
NewClientEngine wraps an SDK client in the Engine interface.
type EngineFactory ¶
EngineFactory builds an Engine for a profile. The CLI wires this to NewClientFromProfile; tests substitute fakes.
type FeedbackEvent ¶
type FeedbackEvent struct {
Category string
Summary string
Detail string
Context string
DeploymentType string
CLIVersion string
}
FeedbackEvent is the payload of a single submit_feedback invocation. It must never contain tokens or workflow payloads.
type FeedbackSender ¶
type FeedbackSender interface {
Send(ctx context.Context, target FeedbackTarget, distinctID string, event FeedbackEvent) error
}
FeedbackSender delivers feedback events. Interfaced so tool handlers can be tested without network access.
func NewHTTPFeedbackSender ¶
func NewHTTPFeedbackSender() FeedbackSender
NewHTTPFeedbackSender returns the production feedback sender. Its HTTP client never follows redirects: the capture endpoint is pinned, and a redirect answer must not re-post the event to a different destination (it surfaces as a non-success status instead).
type FeedbackTarget ¶
FeedbackTarget identifies the PostHog project a feedback event is sent to.
type Grant ¶
type Grant struct {
Profile string `yaml:"profile"`
}
Grant is a single grant entry. It is an object rather than a bare string so that future per-grant options (e.g. a readonly flag) can be added without a format change.
type GrantStore ¶
type GrantStore struct {
// contains filtered or unexported fields
}
GrantStore reads and writes the grant file.
func NewGrantStore ¶
func NewGrantStore(dir string) *GrantStore
NewGrantStore returns a store for the grant file inside dir (the directory that also holds the CLI profile store, typically ~/.hatchet).
func (*GrantStore) Load ¶
func (s *GrantStore) Load() (*Grants, error)
Load reads the grant file. A missing file yields an empty grant set.
func (*GrantStore) Path ¶
func (s *GrantStore) Path() string
Path returns the location of the grant file.
func (*GrantStore) Save ¶
func (s *GrantStore) Save(grants *Grants) error
Save writes the grant file with owner-only permissions.
type Grants ¶
type Grants struct {
Entries []Grant `yaml:"grants"`
}
Grants is the parsed contents of the grant file.
func (*Grants) HasWildcard ¶
HasWildcard reports whether the wildcard entry is present.
func (*Grants) IsGranted ¶
IsGranted reports whether the named profile is granted for MCP use, either directly or via the wildcard entry.
type ProfileSource ¶
type ProfileSource struct {
// Profiles returns all configured profiles keyed by name.
Profiles func() map[string]cliconfig.Profile
// DefaultProfile returns the configured default profile name ("" if unset).
DefaultProfile func() string
}
ProfileSource provides read access to the CLI profile store.
Source Files