Documentation
¶
Overview ¶
Package mcp is the Dexaflow Model Context Protocol server (ADR 0050). It exposes the control plane to an LLM agent as read tools over the official modelcontextprotocol/go-sdk, talking to /api/v2 only through pkg/client — it imports no other internal/ package and holds no privilege of its own (the caller's token is passed through by the client).
Index ¶
Constants ¶
const PlanKeyMinBytes = 32
PlanKeyMinBytes is the shortest plan key LoadPlanKey accepts.
Variables ¶
This section is empty.
Functions ¶
func HTTPHandler ¶ added in v0.5.3
func HTTPHandler(srv *mcpsdk.Server, p ProtectedResource) http.Handler
HTTPHandler serves srv over stateless Streamable HTTP at /mcp, with GET /healthz. With p enabled it also serves the metadata document, at the RFC 9728 path and at the bare well-known path, and answers an /mcp request that carries no bearer with 401 and a WWW-Authenticate pointing at it.
func LoadPlanKey ¶ added in v0.5.3
LoadPlanKey reads the HMAC key that signs plans (ADR 0067) from path: at least PlanKeyMinBytes bytes once a trailing newline is dropped. Every replica of the HTTP transport must load the same key, so a plan made on one applies on another.
func NewServer ¶
func NewServer(api *apiclient.ClientWithResponses, serverURL, version string, requireBearer bool, opts ...Option) *mcpsdk.Server
NewServer builds a read-only Dexaflow MCP server. api is the base control-plane client; serverURL is the control-plane URL used to build per-request clients. requireBearer selects the identity policy (true for the HTTP transport, where each request carries its own token; false for stdio) — see handlers. It registers the read tools + resources; the caller runs it over a transport (stdio for Lite dev, Streamable HTTP for Pro). Tools that mutate state are deliberately absent (ADR 0050 D7). It also sends serverInstructions on initialize and registers the read-only prompts (#1471).
func ValidateUIBaseURL ¶ added in v0.5.3
ValidateUIBaseURL checks a UI base URL before it is used: absolute http or https, with a host and no query or fragment, since every link appends a path to it. Empty is valid and turns links off.
Types ¶
type Option ¶ added in v0.5.3
type Option func(*handlers)
Option configures NewServer.
func WithRunControl ¶ added in v0.5.3
WithRunControl registers the run control tools (ADR 0067, ADR 0050 D7 phase 4): trigger_run, clear_task, pause_dag, unpause_dag and apply_plan. key signs plans; nil draws a random key, which suits stdio only, since every HTTP replica must share the key (LoadPlanKey). Without this option the tools are not registered at all.
A non-nil key shorter than PlanKeyMinBytes panics: an empty or short HMAC key would let anyone sign a plan, so it is a programming error, never a configuration the server runs with. Load operator keys with LoadPlanKey.
func WithUIBaseURL ¶ added in v0.5.3
WithUIBaseURL turns on web_url links into the Dexaflow UI served at base (#1471). Validate base with ValidateUIBaseURL first; "" leaves links off.
type ProtectedResource ¶ added in v0.5.3
type ProtectedResource struct {
// Resource is this MCP endpoint's URL as clients reach it, such as
// https://dexaflow.example.com/mcp.
Resource string
// AuthorizationServers are the issuer URLs of the OAuth authorization
// servers that mint tokens for Resource.
AuthorizationServers []string
// Scopes are the scopes advertised as scopes_supported; empty omits it.
Scopes []string
}
ProtectedResource is the OAuth protected resource metadata (RFC 9728) the HTTP transport advertises, so an MCP client that signs in with OAuth (the MCP authorization specification) can find the authorization server (#1470). The zero value turns it off.
It only points clients at the authorization server. The tokens they bring are verified by /api/v2 on every call, as any other bearer (ADR 0050 D9).
func (ProtectedResource) Enabled ¶ added in v0.5.3
func (p ProtectedResource) Enabled() bool
Enabled reports whether a resource is configured.
func (ProtectedResource) MetadataURL ¶ added in v0.5.3
func (p ProtectedResource) MetadataURL() string
MetadataURL is the absolute URL of the metadata document, the one a 401 names in its WWW-Authenticate challenge.
func (ProtectedResource) Validate ¶ added in v0.5.3
func (p ProtectedResource) Validate() error
Validate checks a configured resource: an absolute https URL (http only on a loopback host) without query or fragment, at least one authorization server of the same form, and no empty scope. The zero value is valid.
Source Files