Documentation
¶
Index ¶
- Constants
- Variables
- func DecodeServers(raw map[string]json.RawMessage) (map[string]Server, []string)
- func Describe(name string, entry Entry) lockfile.MCPServer
- func InstallTree(ctx context.Context, client *http.Client, cacheRoot string, spec TreeSpec) (string, error)
- func NPMRegistry(server Server) string
- func NPMSpec(record lockfile.MCPServer) string
- func NotCarried(agent, name string, settings ...string) string
- func ParseServers(data []byte) (map[string]Server, []string, error)
- func ResolveNPM(ctx context.Context, client *http.Client, registry, name, spec string) (version, integrity string, err error)
- func ResolveNPMTree(ctx context.Context, registry, name, version, integrity string) ([]lockfile.NPMTreeEntry, string, error)
- func StartsWithNPX(server Server) bool
- func TreeDigest(tree []lockfile.NPMTreeEntry) string
- func Unrecorded(entries Entries, records []lockfile.MCPServer) []string
- type Config
- type Entries
- type Entry
- type OAuth
- type Server
- type Source
- type TreeSpec
Constants ¶
const ( LauncherNPM = "npm" LauncherPyPI = "pypi" LauncherDocker = "docker" LauncherRemote = "remote" LauncherCommand = "command" )
const TreeDigestPrefix = "sha256-npm-tree-v1:"
TreeDigestPrefix names the digest of a locked npm tree.
Variables ¶
var ErrNoNPM = errors.New("npm is not on PATH")
ErrNoNPM reports that the npm CLI, which resolves a tree at lock time, is not on PATH. The server then stays pinned at its top-level version only.
var ResolveTree = ResolveNPMTree
ResolveTree resolves a server's npm tree at lock time. Tests replace it so that they never start npm against their stand-in registries.
Functions ¶
func DecodeServers ¶
DecodeServers decodes a name-to-server map one server at a time.
func Describe ¶
Describe classifies a server by what launches it and returns the lock record that can be written without network access. An npm registry package comes back with an empty Status: it still needs ResolveNPM.
func InstallTree ¶ added in v0.7.0
func InstallTree(ctx context.Context, client *http.Client, cacheRoot string, spec TreeSpec) (string, error)
InstallTree makes sure the locked tree is unpacked under cacheRoot and returns the path of the server's executable. Every tarball is checked against its locked integrity before anything is written; no package script runs. A finished tree is marked and reused by later launches.
func NPMRegistry ¶
NPMRegistry returns the registry a server's launcher will use as far as agentpack can see it: the server's own environment, then the process environment, then the public registry. Per-user .npmrc files are not read.
func NotCarried ¶
NotCarried names, for a warning, the settings of a server that an agent's MCP format has no place for.
func ParseServers ¶
ParseServers reads the MCP servers of a JSON (or JSONC) document in either published form: wrapped in "mcpServers", or the bare name-to-server map that Claude Code also accepts in a plugin's .mcp.json. A server that cannot be read is left out and named in the returned warnings; the others are kept.
func ResolveNPM ¶
func ResolveNPM(ctx context.Context, client *http.Client, registry, name, spec string) (version, integrity string, err error)
ResolveNPM asks the registry which exact version a version or dist-tag names and returns that version with the registry's tarball integrity.
func ResolveNPMTree ¶ added in v0.7.0
func ResolveNPMTree(ctx context.Context, registry, name, version, integrity string) ([]lockfile.NPMTreeEntry, string, error)
ResolveNPMTree asks npm which packages it would install for name@version, without running any package script, and returns them with the executable that npx would start. The root package must have the integrity the lock already records.
func StartsWithNPX ¶ added in v0.7.0
StartsWithNPX reports whether a server is started by npx, the only npm runner whose packages run on node; bunx, pnpm dlx and yarn dlx keep their own runtime and stay pinned at the top level.
func TreeDigest ¶ added in v0.7.0
func TreeDigest(tree []lockfile.NPMTreeEntry) string
TreeDigest is a digest of every package a tree installs: path, version and integrity, in path order. Resolved URLs and platform constraints describe where and when a package is fetched, not what it is, so they are not part of it.
Types ¶
type Entries ¶
func ApplyPins ¶
ApplyPins rewrites each npm server that the lock pins so it launches the exact locked version. A record made for a different definition is ignored: the server then runs as written until `agentpack lock` records it again.
func ApplyTrees ¶ added in v0.7.0
func ApplyTrees(entries Entries, records []lockfile.MCPServer, executable, specDir string) (Entries, error)
ApplyTrees rewrites each npm server whose lock record holds a locked tree so that it starts through `executable mcp-exec`, which installs exactly that tree and runs the package's executable with the server's own arguments. The spec of each server is written under specDir. Servers without a tree are left to ApplyPins.
type OAuth ¶
type OAuth struct {
ClientID string `toml:"client_id,omitempty"`
ClientSecret string `toml:"client_secret,omitempty"`
CallbackPort int `toml:"callback_port,omitempty"`
Scopes []string `toml:"scopes,omitempty"`
MetadataURL string `toml:"metadata_url,omitempty"`
}
OAuth is the OAuth client a remote MCP server is used with.
type Server ¶
type Server struct {
Type *string `toml:"type,omitempty" json:"type,omitempty"`
Command *string `toml:"command,omitempty" json:"command,omitempty"`
Args []string `toml:"args,omitempty" json:"args,omitempty"`
Env map[string]string `toml:"env,omitempty" json:"env,omitempty"`
URL *string `toml:"url,omitempty" json:"url,omitempty"`
Disabled *bool `toml:"disabled,omitempty" json:"disabled,omitempty"`
// Headers are sent with every request to a remote server. Like Env, they
// may hold credentials and never reach pack.lock.
Headers map[string]string `toml:"headers,omitempty" json:"headers,omitempty"`
// Cwd is the directory a local server is started in.
Cwd *string `toml:"cwd,omitempty" json:"cwd,omitempty"`
// OAuth holds the client settings of a remote server. Each agent spells
// them its own way, so the harness writers render them.
OAuth *OAuth `toml:"oauth,omitempty" json:"-"`
}
Server is the canonical MCP server definition shared by manifest loading, source merging, and harness-specific renderers.
func (Server) Definition ¶
Definition digests what a server definition runs: its type, command, arguments, and URL. Environment values are excluded so secrets never influence, or leak through, the lockfile.
func (Server) JSONObject ¶
JSONObject is the server in the JSON shape Claude Code, Cursor and Antigravity share: type, command, args, env, url, headers, disabled. Each writer adds or renames what its agent spells differently.
type TreeSpec ¶ added in v0.7.0
type TreeSpec struct {
Server string `json:"server"`
Package string `json:"package"`
Version string `json:"version"`
Registry string `json:"registry"`
Bin string `json:"bin"`
TreeDigest string `json:"tree_digest"`
Tree []lockfile.NPMTreeEntry `json:"tree"`
}
TreeSpec is what `agentpack mcp-exec` needs to start a locked server.