mcpinstall

package
v0.7.44-dev.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 33 Imported by: 0

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.

A PyPI server installs and runs on the policy's Python runtime (images.pythonRuntime, Python 3.15 by default). When the release's own requires_python excludes that Python but admits the previous line, it installs and runs on images.pythonFallbackRuntime (Python 3.14 by default) instead, and the choice is recorded with the install so the store's virtual environment always runs on the Python it was built for. A release that admits neither is refused before anything is fetched, and a policy that sets images.pythonRuntime to its own image gets exactly that image (ChoosePython).

Index

Constants

View Source
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 AssignRuntimes added in v0.6.1009

func AssignRuntimes(resolved []Resolved, images policy.Images) error

AssignRuntimes records, on each resolved PyPI server, whether it installs and runs on the fallback Python (Resolved.PythonFallback), and refuses a server no runtime of the policy can install. A server the store already holds keeps the Python it was installed on: its virtual environment belongs to that line. It is idempotent.

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

func IDFor(srv manifest.MCPServer) string

IDFor is the store/catalog id a declared server resolves under — exported so callers can check the store before resolving.

func Installed

func Installed(storeDir string, srv manifest.MCPServer) bool

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

func Installing(storeDir, id string) bool

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

func LockServer(ctx context.Context, storeDir, id string) (unlock func(), err error)

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

func NormalizePyPIName(pkg string) string

NormalizePyPIName applies PEP 503 normalization: lower-case, with every run of '-', '_' or '.' collapsed to a single '-'.

func PackageOf

func PackageOf(srv manifest.MCPServer) string

PackageOf is a package server's package name, npm's or PyPI's.

func Packages

func Packages(servers []manifest.MCPServer) []manifest.MCPServer

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

func RuntimeMismatch(r Resolved, node string, pythons ...string) string

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 being the Node's version (policy.DefaultNodeVersion) and pythons the Pythons a PyPI server may run on (policy.DefaultPythonVersion, then policy.DefaultPythonFallbackVersion: the range must admit at least one), 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 StoreDir

func StoreDir(profileDir string) string

StoreDir is the signature's server store under its profile directory.

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.

func (*PinError) Error

func (e *PinError) Error() string

func (*PinError) Unwrap

func (e *PinError) Unwrap() error

type PythonChoice added in v0.6.1009

type PythonChoice struct {
	// Image is the runtime image reference.
	Image string
	// Version is the Python that image runs; "" for a policy's own image
	// whose tag names no line.
	Version string
	// Fallback is true when Image is the policy's fallback runtime, chosen
	// because the release's requires_python excludes the default's Python.
	Fallback bool
	// Why says, for the plan and the receipt, how the runtime was chosen.
	Why string
}

PythonChoice is the Python runtime a PyPI server installs and runs on.

func ChoosePython added in v0.6.1009

func ChoosePython(r Resolved, images policy.Images) (PythonChoice, error)

ChoosePython picks the Python runtime for a PyPI release from its requires_python (declared, as the registry's metadata gives it), before anything is installed:

  • a policy whose pythonRuntime is its own image gets exactly that image, whatever the range says: the operator's pin is never overridden;
  • otherwise the newest of the default runtime's Python and the fallback's that the range admits: the default when it does, the fallback when only it does, and an error when neither does;
  • a release that declares no range, or one that cannot be read, stays on the default, as pip ignores such a range ("Ignoring invalid Requires-Python").

The error carries receipt.ReasonMCPRuntimeExcluded.

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"`
	// PythonFallback (PyPI) says the server installs and runs on the policy's
	// fallback Python runtime, because its requires_python excludes the
	// default runtime's Python (ChoosePython). Recorded with the install: the
	// server's virtual environment belongs to that Python line, so a reuse of
	// the store runs on it again.
	PythonFallback bool `json:"pythonFallback,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 LoadMeta

func LoadMeta(storeDir, id string) (*Resolved, error)

LoadMeta reads a stored resolution; (nil, nil) when absent.

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, images policy.Images, 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

func (r Resolved) Command() []string

Command is the argv that launches the server inside its runtime container (stdio transport).

func (Resolved) Image

func (r Resolved) Image(images policy.Images) string

Image picks the runtime image for the server's ecosystem.

func (Resolved) Runtime added in v0.6.1009

func (r Resolved) Runtime(images policy.Images) string

Runtime names the Python a resolved PyPI server runs on under images, as the plan and the receipt say it ("Python 3.14.10"); "" for any other server. A policy's own image whose tag names no Python line gives "Python (the policy's own image)".

func (Resolved) ServerName

func (r Resolved) ServerName() string

ServerName is the gateway catalog name for a resolved server.

func (Resolved) SourceID

func (r Resolved) SourceID() string

SourceID is the declared server's ecosystem-qualified id, as the manifest's MCPServer.SourceID gives it ("npm:@scope/x").

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL