Documentation
¶
Overview ¶
Package mcpinstall resolves and installs the MCP servers a QuickAgent declares: resolution turns each manifest pin into the exact registry artifact (npm / PyPI metadata, integrity recorded); installation materializes the dependency closure into the signature's server store inside a pinned runtime container. The store lives under the release's profile directory, which is what makes every isolation property hold: attachment is derived from the signature, so no other QuickAgent, user, or version can ever reference it.
Index ¶
- Constants
- func EnsureInstalled(ctx context.Context, d dockerx.Client, resolved []Resolved, storeDir string, ...) error
- func IDFor(srv manifest.MCPServer) string
- func Installed(storeDir string, srv manifest.MCPServer) bool
- func Installing(storeDir, id string) bool
- func LockServer(ctx context.Context, storeDir, id string) (unlock func(), err error)
- func NormalizePyPIName(pkg string) string
- func PackageOf(srv manifest.MCPServer) string
- func Packages(servers []manifest.MCPServer) []manifest.MCPServer
- func RuntimeMismatch(r Resolved, node, python string) string
- func Specs(resolved []Resolved, servers []manifest.MCPServer, images policy.Images) []spec.MCPServerSpec
- func StoreDir(profileDir string) string
- func Summary(statuses []VulnStatus) string
- type PinError
- type Resolved
- type VulnAdvisory
- type VulnStatus
Constants ¶
const StatusRemote = "remote"
StatusRemote is a remote server's status: not looked up, since it is a service its vendor runs, not a package version.
Variables ¶
This section is empty.
Functions ¶
func EnsureInstalled ¶
func EnsureInstalled(ctx context.Context, d dockerx.Client, resolved []Resolved, storeDir string, regs policy.MCPRegistries, images policy.Images, docker policy.DockerPolicy, logw io.Writer, ) error
EnsureInstalled materializes every resolved server into the store. A server whose recorded resolution matches is reused without network or docker; a recorded resolution that DISAGREES with the fresh one refuses — the pin is the trust decision, drift is the attack. Builder output streams to logw.
func IDFor ¶
IDFor is the store/catalog id a declared server resolves under — exported so callers can check the store before resolving.
func Installed ¶
Installed says the store holds the pin srv names: a record of its install for that package and version. A remote server is never installed and needs nothing, so it is always held.
func Installing ¶
Installing says another holder has the lock of the server id in the store: an install is writing it. It tries the lock and lets it go, which leaves the server's lock file in the store. A store that does not exist has no install under way.
func LockServer ¶
LockServer takes the lock of the server id in the store, waiting while another holder has it, until ctx ends. unlock lets it go.
func NormalizePyPIName ¶
NormalizePyPIName applies PEP 503 normalization: lower-case, with every run of '-', '_' or '.' collapsed to a single '-'.
func Packages ¶
Packages is the declared servers that are packages: what is resolved against the registries and installed into the store. A remote server has neither; Specs renders it as it is declared.
func RuntimeMismatch ¶
RuntimeMismatch says why a resolved server's own declared runtime range (Resolved.DeclaredRuntime: npm's engines.node, PyPI's requires_python) excludes the runtime it would run on, node or python being that runtime's version (policy.DefaultNodeVersion, policy.DefaultPythonVersion), or "" when the range admits it or the release declares none. An npm range that cannot be read admits nothing, as npm's engine-strict treats one; a requires_python that cannot be read admits everything, as pip ignores one ("Ignoring invalid Requires-Python"). The reason quotes the declared range only when it is a plain range (plainRange): the text is the package author's, and the reason reaches the Drafter's model. It reads the registry's metadata, not the artifact: the npm builder's check at install reads the tarball itself.
func Specs ¶
func Specs(resolved []Resolved, servers []manifest.MCPServer, images policy.Images) []spec.MCPServerSpec
Specs turns resolutions into the plan's server specs, and each declared remote server into its own: an address, its auth, its tools and its one host, which the compiler runs the runner image's bridge for.
func Summary ¶
func Summary(statuses []VulnStatus) string
Summary is the one-line receipt/log form of a check.
Types ¶
type PinError ¶
type PinError struct{ Err error }
PinError is a resolution that failed because of the pin itself, not the network or the registry's health: the release is not there, has no launchable entry or nothing to download, or its name or version is not one the builder passes on. A Drafter's rule refuses a draft for one; any other resolution error is the computer's.
type Resolved ¶
type Resolved struct {
// Source is "npm" or "pypi"; Package/Version echo the manifest pin.
Source string `json:"source"`
Package string `json:"package"`
Version string `json:"version"`
// ID is the store subdirectory and catalog-name stem: source plus the
// sanitized package name.
ID string `json:"id"`
// BinName is the launchable entry: the npm bin name, or the PyPI console
// script. For PyPI the JSON API does not expose entry points, so resolution
// starts from the normalized project name and EnsureInstalled replaces it
// with the console script the installed distribution actually declares
// (entry_points.txt); the recorded resolution carries the resolved name.
BinName string `json:"binName"`
// Integrity is what the registry advertised for the artifact (npm SRI
// or "sha256:<hex>" for PyPI — the pure-Python wheel when one exists).
Integrity string `json:"integrity,omitempty"`
// Artifacts (PyPI) maps every advertised filename to its sha256 hex,
// so the builder can verify whichever wheel pip picks for its platform
// against what the registry's metadata said.
Artifacts map[string]string `json:"artifacts,omitempty"`
// InstalledAt is stamped by EnsureInstalled.
InstalledAt string `json:"installedAt,omitempty"`
// StoreDigest is the server store's tree as the install left it
// (storeDigest); a reuse that finds anything else refuses. The runs mount
// the store read-only, so nothing legitimate changes it after the install.
StoreDigest string `json:"storeDigest,omitempty"`
// FetchHosts are the hosts, other than the registry's own, that the
// registry's metadata said the pinned artifact is downloaded from (the
// npm tarball's host; PyPI's file host, files.pythonhosted.org for
// pypi.org). They join the install proxy's allowlist.
FetchHosts []string `json:"fetchHosts,omitempty"`
// InstallEgress is the allowlist the install's proxy enforced, as
// host:port, stamped by EnsureInstalled; the proxy's own decisions are
// in <id>.install-proxy.log beside this record.
InstallEgress []string `json:"installEgress,omitempty"`
// DeclaredRuntime is the language range the release declares for
// itself, as the registry's metadata gives it: npm's engines.node,
// PyPI's requires_python; "" when it declares none (RuntimeMismatch).
DeclaredRuntime string `json:"declaredRuntime,omitempty"`
// Dependencies are the release's direct dependencies, by name, as the
// metadata the resolution already fetched gives them: npm's
// dependencies, PyPI's requires_dist less the extras' (normalized,
// PEP 503). InstallScripts are the npm lifecycle scripts an install
// would run (preinstall, install, postinstall), which a run's install
// skips. Both are read by the Drafter's server check
// and are not part of the recorded resolution.
Dependencies []string `json:"-"`
InstallScripts []string `json:"-"`
}
Resolved is one manifest pin turned into exact artifacts.
func ResolveAll ¶
func ResolveAll(ctx context.Context, client *http.Client, regs policy.MCPRegistries, servers []manifest.MCPServer) ([]Resolved, error)
ResolveAll resolves every declared server against the configured registries. Pure metadata: no artifacts are fetched and no docker is touched, so --dry-run can afford it.
func StoredOrResolved ¶
func StoredOrResolved(ctx context.Context, errOut io.Writer, storeDir string, regs policy.MCPRegistries, servers []manifest.MCPServer) ([]Resolved, error)
StoredOrResolved returns the resolutions for every package server among servers. When the store already records a resolution for each pin, those are reused verbatim, with no network, so cached installs run offline; otherwise the registries are consulted (and EnsureInstalled later refuses if a recorded pin disagrees with what came back).
func (Resolved) Command ¶
Command is the argv that launches the server inside its runtime container (stdio transport).
func (Resolved) ServerName ¶
ServerName is the gateway catalog name for a resolved server.
type VulnAdvisory ¶
type VulnAdvisory struct {
ID string `json:"id"`
Aliases []string `json:"aliases,omitempty"`
// Severity is the advisory's own word (the database's, else the band
// of its CVSS score).
Severity string `json:"severity"`
// GateSeverity is the registry gate's rating of the finding this
// advisory makes: Critical is critical, High is high
// from a CVSS base score of 8.5 (or with no usable score) and medium
// below it, any other its own. Empty from a registry that does not
// serve it.
GateSeverity string `json:"gateSeverity,omitempty"`
// CVSSScore is the advisory's highest CVSS base score, when the
// registry serves one.
CVSSScore *float64 `json:"cvssScore,omitempty"`
Summary string `json:"summary"`
FixedIn []string `json:"fixedIn,omitempty"`
}
VulnAdvisory is one advisory the registry reports for a server version.
func (VulnAdvisory) Label ¶
func (a VulnAdvisory) Label() string
Label names the advisory for a person: its id and, where the registry serves the gate's rating, the advisory's own severity and CVSS score, and the gate's rating where it differs, so a High the gate rates medium reads as both.
func (VulnAdvisory) Rating ¶
func (a VulnAdvisory) Rating() string
Rating is the severity the runner weighs this advisory at: the gate's rating where the registry serves one the runner knows, else the advisory's own. A Critical is critical whatever was served: the gate never rates one lower, so a lower answer is a registry fault the runner does not inherit.
func (VulnAdvisory) Refuses ¶
func (a VulnAdvisory) Refuses() bool
Refuses reports whether this advisory refuses a run by default: one rated high or critical.
type VulnStatus ¶
type VulnStatus struct {
// Ref is "npm:pkg@1.2.3" / "pypi:pkg@1.2.3".
Ref string `json:"ref"`
// Server is the declared server's id without its version
// ("npm:pkg"), the name a refusal's reason gives.
Server string `json:"-"`
// Status is the registry's word — "safe" (no known advisories at
// CheckedAt), "vulnerable", "error" (its last lookup failed; Advisories
// are the last known) — or the runner's: "unknown" (the registry has
// never seen this version) or "unreachable" (no answer; Err says why),
// or StatusRemote for a remote server, which is never looked up.
Status string `json:"status"`
MaxSeverity string `json:"maxSeverity,omitempty"`
Advisories []VulnAdvisory `json:"advisories,omitempty"`
CheckedAt time.Time `json:"checkedAt,omitempty"`
Err string `json:"error,omitempty"`
}
VulnStatus is the registry's answer for one declared server.
func CheckVulnerabilities ¶
func CheckVulnerabilities(ctx context.Context, client *http.Client, registry string, servers []manifest.MCPServer) []VulnStatus
CheckVulnerabilities asks the registry about each declared server. It never returns an error: a registry that cannot answer yields "unreachable" statuses, and the caller decides what that means.
func (VulnStatus) Describe ¶
func (s VulnStatus) Describe(advs []VulnAdvisory) string
Describe is the clause a refusal, doctor and the receipt name advisories with: "a known critical vulnerability (GHSA-…)" from a registry that serves no rating, "an advisory the gate rates high (GHSA-… [advisory high, CVSS 8.7])" from one that does.
func (VulnStatus) FixedIn ¶
func (s VulnStatus) FixedIn() []string
FixedIn is the union of the fixed versions the refusing advisories name.
func (VulnStatus) Refuses ¶
func (s VulnStatus) Refuses() bool
Refuses reports whether this status refuses a run by default.
func (VulnStatus) Refusing ¶
func (s VulnStatus) Refusing() []VulnAdvisory
Refusing is the advisories that refuse a run by default: those rated high or critical, on a record that lists advisories ("vulnerable", or "error" with the last known).
func (VulnStatus) Words ¶
func (s VulnStatus) Words() string
Words is the status as a person reads it. The registry's word "safe" means no known advisories when it last looked, and claims nothing more, so it is never shown as a word; neither is any other status word. The JSON keeps Status, the wire value, unchanged.