mcpbundle

Documentation

Overview

Package mcpbundle builds and validates the platform-specific MCP Bundles published for gograph.

Index

• Constants
• Variables
• func BuildBundle(manifest Manifest, binary, license []byte) ([]byte, string, error)
• func MarshalManifest(manifest Manifest, version string, target Target) ([]byte, error)
• func ResolveCommand(manifest Manifest, target Target, bundleDir, projectDirectory string) (string, []string, error)
• func ValidateBinary(binary []byte, target Target, version string) error
• func ValidateManifest(manifest Manifest, version string, target Target) error
• func ValidateManifestSchema(raw []byte) error
• func ValidateServerJSON(raw []byte) error
• func ValidateVersion(version string) error
• type Artifact
  • func BuildAll(ctx context.Context, repositoryRoot, outputDir, version string) ([]Artifact, error)
  • func VerifyAll(inputDir, version string) ([]Artifact, error)
  • func VerifyAllHashes(inputDir, version string, expected map[string]string) ([]Artifact, error)
• type Author
• type Compatibility
• type MCPConfig
• type Manifest
  • func DecodeManifest(data []byte, version string, target Target) (Manifest, error)
  • func NewManifest(version string, target Target) (Manifest, error)
• type Repository
• type Server
• type SmokeResult
  • func SmokeNative(ctx context.Context, inputDir, projectDir, version string) (*SmokeResult, error)
• type Target
  • func SupportedTargets() []Target
  • func TargetFor(goos, goarch string) (Target, bool)
  • func (t Target) ArtifactName(version string) string
  • func (t Target) ExecutableName() string
  • func (t Target) InstalledCommand() string
  • func (t Target) InstalledExecutable(bundleDir string) string
  • func (t Target) ServerPath() string
  • func (t Target) Validate() error
• type UserConfig
• type Verification
  • func VerifyBundle(bundle []byte, target Target, version, expectedSHA string) (*Verification, error)

Constants

const (
	// ManifestVersion is the MCPB manifest revision used by release bundles.
	ManifestVersion = "0.4"
	// ServerName is the name reported by the bundled MCP server.
	ServerName = "gograph"
)

Variables

var Targets = []Target{
	{GOOS: "darwin", GOARCH: "amd64", Platform: "darwin"},
	{GOOS: "darwin", GOARCH: "arm64", Platform: "darwin"},
	{GOOS: "linux", GOARCH: "amd64", Platform: "linux"},
	{GOOS: "linux", GOARCH: "arm64", Platform: "linux"},
	{GOOS: "windows", GOARCH: "amd64", Platform: "win32"},
	{GOOS: "windows", GOARCH: "arm64", Platform: "win32"},
}

Targets is the complete, deterministic release target order.

Functions

func BuildBundle

func BuildBundle(manifest Manifest, binary, license []byte) ([]byte, string, error)

BuildBundle validates its inputs and returns a deterministic MCPB ZIP and the lowercase SHA-256 digest of the exact bytes returned.

func MarshalManifest

func MarshalManifest(manifest Manifest, version string, target Target) ([]byte, error)

MarshalManifest produces stable, human-readable JSON with a final newline.

func ResolveCommand

func ResolveCommand(manifest Manifest, target Target, bundleDir, projectDirectory string) (string, []string, error)

ResolveCommand resolves only the two MCPB variables emitted by NewManifest. It returns command and argv separately; it never constructs a shell string.

func ValidateBinary

func ValidateBinary(binary []byte, target Target, version string) error

ValidateBinary checks the Go executable's embedded build metadata. This is portable, so CI can validate all non-native release targets without running foreign executables.

func ValidateManifest

func ValidateManifest(manifest Manifest, version string, target Target) error

ValidateManifest enforces both the MCPB shape and gograph's release policy.

func ValidateManifestSchema

func ValidateManifestSchema(raw []byte) error

ValidateManifestSchema validates raw manifest JSON against the pinned MCPB v0.4 schema embedded in this package. It never follows a network reference.

func ValidateServerJSON

func ValidateServerJSON(raw []byte) error

ValidateServerJSON validates raw Registry metadata against the pinned 2025-12-11 official Registry schema embedded in this package. Callers should apply release-specific semantic checks after this structural validation.

func ValidateVersion

func ValidateVersion(version string) error

ValidateVersion requires a semantic version without a leading v. This also makes it safe to pass the version as one ldflag argument during builds.

Types

type Artifact

type Artifact struct {
	Target Target
	Name   string
	Path   string
	SHA256 string
	Size   int64
}

Artifact describes one on-disk MCPB release asset.

func BuildAll

func BuildAll(ctx context.Context, repositoryRoot, outputDir, version string) ([]Artifact, error)

BuildAll cross-compiles, packages, validates, and publishes to outputDir all six supported MCPB assets. It stages every artifact before changing the output directory and refuses to replace a different existing asset.

func VerifyAll

func VerifyAll(inputDir, version string) ([]Artifact, error)

VerifyAll requires exactly one valid canonical MCPB for every target. Other non-MCPB release files in the same directory are ignored.

func VerifyAllHashes

func VerifyAllHashes(inputDir, version string, expected map[string]string) ([]Artifact, error)

VerifyAllHashes also compares every asset with a caller-provided SHA-256 map. When expected is non-nil it must contain exactly the six asset names.

type Author

type Author struct {
	Name string `json:"name"`
	URL  string `json:"url,omitempty"`
}

type Compatibility

type Compatibility struct {
	Platforms []string          `json:"platforms"`
	Runtimes  map[string]string `json:"runtimes,omitempty"`
}

type MCPConfig

type MCPConfig struct {
	Command string            `json:"command"`
	Args    []string          `json:"args"`
	Env     map[string]string `json:"env"`
}

type Manifest

type Manifest struct {
	Schema          string                       `json:"$schema"`
	ManifestVersion string                       `json:"manifest_version"`
	Name            string                       `json:"name"`
	DisplayName     string                       `json:"display_name"`
	Version         string                       `json:"version"`
	Description     string                       `json:"description"`
	LongDescription string                       `json:"long_description,omitempty"`
	Author          Author                       `json:"author"`
	Repository      Repository                   `json:"repository"`
	Homepage        string                       `json:"homepage"`
	Documentation   string                       `json:"documentation"`
	Support         string                       `json:"support"`
	Server          Server                       `json:"server"`
	ToolsGenerated  bool                         `json:"tools_generated"`
	Keywords        []string                     `json:"keywords"`
	License         string                       `json:"license"`
	PrivacyPolicies []string                     `json:"privacy_policies"`
	Compatibility   Compatibility                `json:"compatibility"`
	UserConfig      map[string]UserConfig        `json:"user_config"`
	Meta            map[string]map[string]string `json:"_meta"`
}

Manifest is the strict subset of MCPB manifest v0.4 used by gograph binary bundles. Keeping this typed prevents release scripts from silently emitting misspelled or unsupported fields.

func DecodeManifest

func DecodeManifest(data []byte, version string, target Target) (Manifest, error)

DecodeManifest strictly decodes a manifest and rejects unknown fields or trailing JSON before applying target-aware semantic validation.

func NewManifest

func NewManifest(version string, target Target) (Manifest, error)

NewManifest returns the canonical manifest for a release target.

type Repository

type Repository struct {
	Type string `json:"type"`
	URL  string `json:"url"`
}

type Server

type Server struct {
	Type       string    `json:"type"`
	EntryPoint string    `json:"entry_point"`
	MCPConfig  MCPConfig `json:"mcp_config"`
}

type SmokeResult

type SmokeResult struct {
	ServerName    string
	ServerVersion string
	ToolNames     []string
}

SmokeResult records the MCP identity and tools returned by a native bundle.

func SmokeNative

func SmokeNative(ctx context.Context, inputDir, projectDir, version string) (*SmokeResult, error)

SmokeNative validates and executes only the host-native bundle, initializes MCP over stdio, and requests tools/list from the selected Go project.

type Target

type Target struct {
	GOOS     string
	GOARCH   string
	Platform string
}

Target identifies one supported release operating-system and architecture pair. Platform is the MCPB/Node-style platform identifier used by manifests.

func SupportedTargets

func SupportedTargets() []Target

SupportedTargets returns a copy so callers cannot change the canonical release target list accidentally.

func TargetFor

func TargetFor(goos, goarch string) (Target, bool)

TargetFor returns the supported target matching goos and goarch.

func (Target) ArtifactName

func (t Target) ArtifactName(version string) string

ArtifactName returns the canonical immutable release asset filename.

func (Target) ExecutableName

func (t Target) ExecutableName() string

ExecutableName is the executable filename stored in the bundle.

func (Target) InstalledCommand

func (t Target) InstalledCommand() string

InstalledCommand is the MCPB command template for this target.

func (Target) InstalledExecutable

func (t Target) InstalledExecutable(bundleDir string) string

InstalledExecutable resolves the executable path below an extracted bundle directory without invoking a shell.

func (Target) ServerPath

func (t Target) ServerPath() string

ServerPath is the slash-separated executable path inside a MCPB ZIP.

func (Target) Validate

func (t Target) Validate() error

Validate rejects targets outside the six release combinations and catches inconsistent MCPB platform identifiers.

type UserConfig

type UserConfig struct {
	Type        string `json:"type"`
	Title       string `json:"title"`
	Description string `json:"description"`
	Required    bool   `json:"required"`
	Multiple    bool   `json:"multiple,omitempty"`
}

type Verification

type Verification struct {
	Target       Target
	Manifest     Manifest
	SHA256       string
	BinarySHA256 string
	Size         int64
}

Verification describes one fully validated bundle.

func VerifyBundle

func VerifyBundle(bundle []byte, target Target, version, expectedSHA string) (*Verification, error)

VerifyBundle validates the digest, exact ZIP layout, manifest, license, and embedded Go executable for one target. expectedSHA may be empty when callers only need the calculated digest.