Documentation
¶
Overview ¶
Package mcp exposes a remote, RBAC-gated Model Context Protocol server over the application's existing HTTP listener.
Security model (this is load-bearing — read before adding tools):
- OFF by default. The whole feature is mounted only when DC_MCP_ENABLED is set; when off, none of these routes exist and the server returns a bare 404 with no hint the capability is present.
- Every request carries a bearer token, resolved to a LIVE user on every single request (never cached), so revoking a token or a section in the admin UI takes effect immediately.
- Tools are an explicit ALLOWLIST of narrow operations. This is never a passthrough to the Docker API. There is deliberately no tool that reads arbitrary files, exports/saves images, execs into containers, or browses volume contents — those exfiltration vectors simply do not exist here.
- Secret-bearing fields (notably container environment variables) are omitted from tool output.
- Each tool declares (section, write). Effective access is the token's narrowing (an optional sections subset + a read-only flag) AND the live user's RBAC via CheckAccess. A token can only ever shrink a user's rights.
Index ¶
Constants ¶
const ( ScopeFull = "mcp" ScopeReadOnly = "mcp:read" )
OAuth scopes advertised by both the protected-resource metadata and the authorization server, kept in one place so the two documents never disagree.
const AccessTokenTTL = 15 * time.Minute
AccessTokenTTL is the lifetime of an issued access token. Short by design — refresh tokens (rotated) cover longer sessions.
Variables ¶
This section is empty.
Functions ¶
func MintAccessToken ¶
func MintAccessToken(key []byte, issuer, resource string, userID int64, clientID, sessionID string, readOnly bool, ttl time.Duration) (string, time.Time, error)
MintAccessToken issues a signed, audience-bound access token for userID, bound to the OAuth client it was issued to and the connector session it belongs to.
Types ¶
type CheckAccessFunc ¶
type CheckAccessFunc func(ctx context.Context, u *store.User, section string, write bool, hostID int64) error
CheckAccessFunc is the host application's RBAC gate (api.Server.checkAccess). A nil error means the user may act on section with the given write intent, on the Docker host named by hostID (0 = the local daemon).
type Deps ¶
type Deps struct {
Store *store.Store
Docker *docker.Manager
History history.Store
CheckAccess CheckAccessFunc
Version string
// Managed-project control. These are provided by the host application
// (api.Server) because deploy/down run the `docker compose` CLI against the
// app's own project directories. Any may be nil, in which case the matching
// tool reports the feature as unavailable.
ListProjects func(ctx context.Context) ([]ManagedProject, error)
DeployProject func(ctx context.Context, id int64, profiles []string, confirmPolicyWarnings bool) (string, error)
DownProject func(ctx context.Context, id int64) (string, error)
// BeginStackOp claims the managed project that deploys a stack, if one
// does, so a stack action waits its turn like the project's own deploy or
// restore. Returns the release, or an error when the project is busy (or
// it can't be told). nil means no projects are managed: nothing to claim.
BeginStackOp func(ctx context.Context, hostID int64, stack, what string) (release func(), err error)
// PreviewProject reports what a deploy would change, without deploying.
PreviewProject func(ctx context.Context, id int64) (ProjectPreview, error)
// ResourceURL is the canonical absolute URI of the /mcp endpoint
// (e.g. https://host/mcp); empty when no public URL is configured.
ResourceURL string
// MetadataURL is the absolute URL of the protected-resource metadata doc.
MetadataURL string
// IssuerURL is the OAuth authorization-server issuer (the public base URL).
IssuerURL string
// SigningKey signs and verifies OAuth access tokens (HS256). Dedicated to
// MCP — separate from the app session secret. Nil disables the OAuth/JWT
// path (API-token bearer auth still works).
SigningKey []byte
}
Deps are the host-application dependencies the MCP server needs. The api package wires these from the running Server so there is no import cycle.
type ManagedProject ¶
type ManagedProject struct {
ID int64 `json:"id"`
Name string `json:"name"`
Slug string `json:"slug"`
// HostID is the Docker host the project deploys to (0 = the local daemon).
// Carried so the tool layer can drop projects on hosts the caller may not
// reach — the store row has it, and without it here the filter would have to
// re-read every project.
HostID int64 `json:"hostId"`
Deployed bool `json:"deployed"`
}
type ProjectPreview ¶ added in v1.6.0
type ProjectPreview struct {
Project string `json:"project,omitempty"`
Valid bool `json:"valid"`
Error string `json:"error,omitempty"`
Services []docker.ServiceSpec `json:"services,omitempty"`
Running []docker.ServiceSpec `json:"running,omitempty"`
Changes []docker.ServiceChange `json:"changes,omitempty"`
Unchanged int `json:"unchanged,omitempty"`
// Active is len(Changes) minus any marked Ignored (reviewed, accepted
// drift) — what still actually needs attention.
Active int `json:"active,omitempty"`
}
ManagedProject is a Compose project the application manages and can deploy. ProjectPreview is what deploying a managed project would change.