Documentation
¶
Index ¶
- Constants
- Variables
- func CanonicalURL(raw string) (string, error)
- 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 LoginURL(server Server) string
- 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 PlanTrees(entries Entries, records []lockfile.MCPServer, executable, specDir string) (Entries, []PlannedTreeFile, 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 RunsWithNode(path string) bool
- func StartsWithNPX(server Server) bool
- func TreeDigest(tree []lockfile.NPMTreeEntry) string
- func Unrecorded(entries Entries, records []lockfile.MCPServer) []string
- type Config
- type CredentialIndex
- type CredentialRef
- type Entries
- type Entry
- type OAuth
- type PlannedTreeFile
- type Server
- type Source
- type TreeSpec
Constants ¶
const ( CredentialOAuth = "oauth" CredentialHeader = "header" CredentialEnv = "env" )
Credential kinds stored by the gateway.
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 CanonicalURL ¶ added in v0.14.1
CanonicalURL is the form credentials match on: lowercase scheme and host, no default port, no fragment and no trailing slash, so "…/mcp/" and "…/mcp" match.
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 LoginURL ¶ added in v0.14.1
LoginURL is the canonical URL a shared login for server would match, or "" when the server cannot use one: it is local, names its own credential or Authorization header, or its URL has a query, which may hold a secret and so never leaves the machine.
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 PlanTrees ¶ added in v0.9.0
func PlanTrees(entries Entries, records []lockfile.MCPServer, executable, specDir string) (Entries, []PlannedTreeFile, error)
PlanTrees computes exact pinned-tree spec files without writing them.
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 RunsWithNode ¶ added in v0.13.0
RunsWithNode reports whether a package executable is a script for node, as npm's bin shims decide it: a JavaScript extension or a node shebang.
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 CredentialIndex ¶ added in v0.14.1
type CredentialIndex struct {
Credentials []CredentialRef `json:"credentials"`
}
func ReadCredentialIndex ¶ added in v0.14.1
func ReadCredentialIndex(path string) (CredentialIndex, error)
ReadCredentialIndex reads the gateway-written index; a missing file is an empty index.
type CredentialRef ¶ added in v0.14.1
type CredentialRef struct {
ID string `json:"id"`
Match string `json:"match,omitempty"` // canonical URL; empty for env credentials
Label string `json:"label"`
Kind string `json:"kind"`
// Plugins are the plugin modules approved to receive this credential.
Plugins []string `json:"plugins,omitempty"`
}
CredentialRef is one stored credential as staging sees it: never a secret value. The gateway writes them to the credential index for the account bound to this machine.
type Entries ¶
func ApplyCredentials ¶ added in v0.14.1
func ApplyCredentials(entries Entries, index CredentialIndex, executable string) (Entries, []string)
ApplyCredentials replaces each server a stored credential applies to with `agentpack mcp-bridge`, which adds the credential at run time, so no secret reaches staging. A remote server matches by canonical URL unless it already sends its own Authorization header; a server naming `credential` uses that one. A plugin's server matches only after its module was approved for the credential. The returned lines explain servers left unchanged.
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 PlannedTreeFile ¶ added in v0.9.0
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:"-"`
// Credential names a stored MCP credential (label or ID) to use for this
// server instead of matching one by URL. It is never a secret.
Credential string `toml:"credential,omitempty" json:"credential,omitempty"`
}
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.