manifest

Documentation

Overview

Package manifest builds a canonical, hashable snapshot of an MCP server's advertised tools, prompts, and resources.

Index

• func Canonicalize(m *Manifest) ([]byte, error)
• func CanonicalizeValue(raw json.RawMessage) (string, error)
• func Hash(canonicalJSON []byte) string
• type Manifest
  • func Build(tools []mcp.Tool, prompts []mcp.Prompt, resources []mcp.Resource) (*Manifest, error)
  • func FromCanonicalJSON(b []byte) (*Manifest, error)
  • func (m *Manifest) ToolByName(name string) *mcp.Tool

Functions

func Canonicalize

func Canonicalize(m *Manifest) ([]byte, error)

Canonicalize renders a Manifest as deterministic, whitespace-free JSON: object keys are sorted recursively, and arrays whose elements are all JSON primitives (string/number/bool/null) are sorted too. Arrays that contain any object or nested array are canonicalized element-wise but keep their original order, since reordering something like a JSON Schema `anyOf`/`oneOf` array has no well-defined canonical order and can even change validation semantics.

The same canonical bytes are always produced for the same capability set regardless of the order the upstream server returned tools/prompts/ resources in, or the key order of nested schema objects — this is what makes Hash(Canonicalize(m)) a stable identity for a manifest.

func CanonicalizeValue

func CanonicalizeValue(raw json.RawMessage) (string, error)

CanonicalizeValue normalizes an arbitrary JSON blob (e.g. a tool's input_schema) using the same key/array canonicalization rules as Canonicalize, returning a compact deterministic string. This is exported so callers that need to compare two JSON values for semantic equality (the diff engine comparing a stored, already-canonical baseline schema against a freshly fetched live one) normalize both sides identically — otherwise a schema whose primitive arrays got sorted once at storage time would spuriously appear "changed" against an unsorted live fetch of the exact same schema.

func Hash

func Hash(canonicalJSON []byte) string

Hash returns the hex-encoded SHA256 digest of canonical manifest bytes. This becomes the version identity of an upstream MCP server's capability set — see Canonicalize for the determinism guarantees this relies on.

Types

type Manifest

type Manifest struct {
	Tools     []mcp.Tool
	Prompts   []mcp.Prompt
	Resources []mcp.Resource
}

Manifest is the canonical capability snapshot of one upstream MCP server. It intentionally holds only capability content (tools/prompts/resources), not storage identifiers like a database server ID — the manifest hash must depend solely on what the upstream server advertises, not on how mcp-shield happens to track it internally.

Every constructor in this package guarantees the same invariant: within a Manifest, no two tools share a name, no two prompts share a name, and no two resources share a URI. See validateUniqueIdentities for why that is enforced rather than tolerated.

func Build

func Build(tools []mcp.Tool, prompts []mcp.Prompt, resources []mcp.Resource) (*Manifest, error)

Build assembles a Manifest from live upstream lists, sorting each collection by identity so equivalent capability sets always canonicalize identically regardless of the order the upstream server returned them in.

It fails closed on a capability set that advertises the same identity twice; see validateUniqueIdentities.

func FromCanonicalJSON

func FromCanonicalJSON(b []byte) (*Manifest, error)

FromCanonicalJSON reconstructs a Manifest from bytes previously produced by Canonicalize (as stored in manifests.canonical_json). Used to rebuild the approved baseline manifest for diffing against a newly observed one.

It enforces the same unique-identity invariant as Build. Build cannot write duplicates to the database, so a stored manifest that has them was corrupted or tampered with after the fact — a baseline that no longer means what was approved must not be diffed against.

func (*Manifest) ToolByName

func (m *Manifest) ToolByName(name string) *mcp.Tool

ToolByName returns the tool with the given name, or nil.