mcp

package
v0.14.4-dev.14 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 32 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CredentialOAuth  = "oauth"
	CredentialHeader = "header"
	CredentialEnv    = "env"
)

Credential kinds stored by the gateway.

View Source
const (
	LauncherNPM     = "npm"
	LauncherPyPI    = "pypi"
	LauncherDocker  = "docker"
	LauncherRemote  = "remote"
	LauncherCommand = "command"
)
View Source
const TreeDigestPrefix = "sha256-npm-tree-v1:"

TreeDigestPrefix names the digest of a locked npm tree.

Variables

View Source
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.

View Source
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

func CanonicalURL(raw string) (string, error)

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

func DecodeServers(raw map[string]json.RawMessage) (map[string]Server, []string)

DecodeServers decodes a name-to-server map one server at a time.

func Describe

func Describe(name string, entry Entry) lockfile.MCPServer

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

func LoginURL(server Server) string

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

func NPMRegistry(server Server) string

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 NPMSpec

func NPMSpec(record lockfile.MCPServer) string

NPMSpec returns the version or dist-tag part of a record's requested spec.

func NotCarried

func NotCarried(agent, name string, settings ...string) string

NotCarried names, for a warning, the settings of a server that an agent's MCP format has no place for.

func ParseServers

func ParseServers(data []byte) (map[string]Server, []string, error)

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

func RunsWithNode(path string) bool

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

func StartsWithNPX(server Server) bool

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.

func Unrecorded

func Unrecorded(entries Entries, records []lockfile.MCPServer) []string

Unrecorded names the servers that have no lock record for their current definition.

Types

type Config

type Config struct {
	Servers map[string]Server `json:"mcpServers"`
}

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

type Entries map[string]Entry

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

func ApplyPins(entries Entries, records []lockfile.MCPServer) Entries

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.

func (Entries) Bare

func (entries Entries) Bare() map[string]Server

func (Entries) Names

func (entries Entries) Names() []string

type Entry

type Entry struct {
	Server Server
	Source Source
	// Module and CacheKey name the package a plugin's server came from.
	Module   string
	CacheKey string
}

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 PlannedTreeFile struct {
	Path     string
	Contents []byte
}

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

func (server Server) Definition() string

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) IsRemote

func (server Server) IsRemote() bool

func (Server) JSONObject

func (server Server) JSONObject() map[string]any

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 Source

type Source string
const (
	Plugin    Source = "plugin"
	Manifest  Source = "manifest"
	DotAgents Source = ".agents"
)

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"`
	Incremental bool                    `json:"-"`
}

TreeSpec is what `agentpack mcp-exec` needs to start a locked server.

func SpecFor added in v0.7.0

func SpecFor(record lockfile.MCPServer) (TreeSpec, bool)

SpecFor returns the spec of a pinned record whose tree is locked.

Jump to

Keyboard shortcuts

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