installpkg

Documentation

Overview

Package installpkg implements the `dockyard install` verb — registering a built Dockyard server with an MCP host (RFC §14).

`dockyard install claude|cursor` writes the host's MCP config file so the host launches this Dockyard server as a local stdio subprocess ({"command": "<binary path>"}), then verifies the server boots by spawning it and driving one real MCP `initialize` handshake.

Two security-relevant properties hold:

• The write is NON-DESTRUCTIVE. installpkg loads the host's existing config, merges this server's entry into the mcpServers map, and writes the result back — every unrelated host entry is preserved. The prior file is backed up first.
• The boot check is NOT a production MCP client (P4). It is a throwaway, localhost, dev-only spawn of the built server with a bounded timeout: it proves the host config launches a working server and then tears the process down. Harbor owns the production MCP client.

The per-host config-file locations are kept behind a small hostProfile struct (claude, cursor) — a filesystem-path derivation, not a hardcoded capability matrix (CLAUDE.md §6).

installpkg is internal — the reusable, testable seam the `dockyard install` cobra verb and the Phase 20 integration test consume.

Index

• Variables
• type Host
  • func ParseHost(s string) (Host, error)
• type Options
• type Result
  • func Install(ctx context.Context, opts Options) (Result, error)

Variables

var ErrBootCheck = errors.New("dockyard/internal/installpkg: server boot check failed")

ErrBootCheck is the sentinel wrapping a boot-check failure: the host config was written, but the spawned server did not complete the MCP initialize handshake. It is distinct from ErrInstall so a caller can tell "config not written" from "config written but server unhealthy".

var ErrInstall = errors.New("dockyard/internal/installpkg: install failed")

ErrInstall is the sentinel wrapping a `dockyard install` failure that is not a boot-check failure — a missing project, an unwritable or malformed config, an unknown host. Callers branch with errors.Is(err, ErrInstall).

Types

type Host

type Host string

Host identifies an MCP host `dockyard install` can register a server with.

const (
	// HostClaude is Claude Desktop — its config is claude_desktop_config.json
	// under the per-OS Claude application-support directory.
	HostClaude Host = "claude"
	// HostCursor is the Cursor editor — its MCP config is ~/.cursor/mcp.json.
	HostCursor Host = "cursor"
)

func ParseHost

func ParseHost(s string) (Host, error)

ParseHost validates a host argument and returns the typed Host. An unknown value is a clear, typed error naming the supported hosts.

type Options

type Options struct {
	// ProjectDir is the root of the Dockyard project — the directory holding
	// dockyard.app.yaml. Required: the manifest supplies the server name the
	// host config entry is keyed under.
	ProjectDir string
	// Host is the MCP host to register the server with. Required.
	Host Host
	// ConfigPath overrides the per-OS host config-file path. Empty uses the
	// host default. Tests set it to a temp path so the developer's real
	// ~/.claude / Cursor config is never touched.
	ConfigPath string
	// BinaryPath is the absolute path of the built server binary the host
	// config will launch. Required.
	BinaryPath string
	// SkipBootCheck disables the post-write boot check. It is a test seam —
	// production installs always verify the server boots. Normal use leaves
	// it false.
	SkipBootCheck bool
	// Logger receives the install's structured output. A nil Logger falls
	// back to a discarding logger.
	Logger *slog.Logger
}

Options configures one `dockyard install` invocation.

type Result

type Result struct {
	// Host is the host the server was registered with.
	Host Host
	// ConfigPath is the absolute path of the host config file written.
	ConfigPath string
	// BackupPath is the absolute path of the backup of the prior config, or
	// "" when there was no prior config to back up.
	BackupPath string
	// ServerName is the key the server entry was written under.
	ServerName string
	// BootOK reports whether the post-write boot check passed. It is false
	// when SkipBootCheck was set.
	BootOK bool
}

Result reports what an Install produced.

func Install

func Install(ctx context.Context, opts Options) (Result, error)

Install registers the project's built server with an MCP host (RFC §14): it writes the host's MCP config non-destructively — backing up the prior file, merging this server's entry into the existing mcpServers map without touching any unrelated entry — then verifies the server boots with a real MCP initialize handshake.

A failure to write the config wraps ErrInstall; a config that was written but whose server failed to boot wraps ErrBootCheck. On the latter the Result is still returned (the config IS written) so the caller can report both facts.