mcp

Documentation

Overview

Package mcp exposes a Readproof deployment as a Model Context Protocol server: registered resources become readable `readproof://` MCP resources, and the operations behind the CLI (resolve, tags, runs, manifests, diff, replay, evidence) become MCP tools.

The server is written entirely against client.Client, exactly like every CLI command, so `readproof mcp` behaves identically whether it runs embedded over a local data directory or against a remote readproofd — the transport is chosen once, by the caller constructing the client, and nothing in here knows which one it got.

Index

• Constants
• func NewServer(c client.Client, opts Options) *mcpsdk.Server
• type ContentPayload
• type DiffEntryOut
• type DiffOut
• type HistoryOut
• type ManifestEntryOut
• type ManifestOut
• type MountOut
• type Options
• type PolicyInfo
• type ReplayEntryOut
• type ReplayOut
• type ResolveOut
• type ResourceInfo
• type ResourceListOut
• type RunStartOut
• type SnapshotInfo
• type SourceInfo
• type TagDeleteOut
• type TagInfo
• type TagListOut

Constants

const DefaultMaxInlineBytes = 1 << 20 // 1 MiB

DefaultMaxInlineBytes caps how many bytes of resolved content any single resource read or tool result carries inline. A context resource can be a multi-megabyte spec; pushing all of it through a model's context window unasked is worse than handing back a truncation marker plus the content hash the caller can replay against.

Functions

func NewServer

func NewServer(c client.Client, opts Options) *mcpsdk.Server

NewServer builds an MCP server over c. The caller owns c's lifetime (and must Close it) and owns the transport: run the result with (*mcpsdk.Server).Run over a StdioTransport, or connect it to an in-memory transport in tests.

Types

type ContentPayload

type ContentPayload struct {
	Encoding   string `json:"encoding"`
	Text       string `json:"text,omitempty"`
	Base64     string `json:"base64,omitempty"`
	Truncated  bool   `json:"truncated"`
	TotalBytes int    `json:"total_bytes"`
}

ContentPayload carries resolved bytes. Exactly one of Text/Base64 is set, per Encoding; Truncated says whether it is a prefix, and TotalBytes is always the full length so a caller can tell how much it is missing.

type DiffEntryOut

type DiffEntryOut struct {
	URI             string `json:"uri"`
	Status          string `json:"status"`
	SnapshotIDA     string `json:"snapshot_id_a,omitempty"`
	SnapshotIDB     string `json:"snapshot_id_b,omitempty"`
	SourceRevisionA string `json:"source_revision_a,omitempty"`
	SourceRevisionB string `json:"source_revision_b,omitempty"`
	ObservedAtA     string `json:"observed_at_a,omitempty"`
	ObservedAtB     string `json:"observed_at_b,omitempty"`
	RefA            string `json:"ref_a,omitempty"`
	RefB            string `json:"ref_b,omitempty"`
	UnifiedDiff     string `json:"unified_diff,omitempty"`
}

DiffEntryOut is one URI's status between two manifests. The per-side source_revision/observed_at/ref fields are the "why did this change?" provenance; unified_diff is set only for a changed entry.

type DiffOut

type DiffOut struct {
	ManifestA string `json:"manifest_a"`
	ManifestB string `json:"manifest_b"`
	Changed   int    `json:"changed"`
	Added     int    `json:"added"`
	Removed   int    `json:"removed"`
	Unchanged int    `json:"unchanged"`
	// Entries omits unchanged URIs' diff text but still lists them, so a
	// caller can see the full comparison, not just what moved.
	Entries []DiffEntryOut `json:"entries"`
}

DiffOut compares two manifests entry by entry.

type HistoryOut

type HistoryOut struct {
	URI       string         `json:"uri"`
	Snapshots []SnapshotInfo `json:"snapshots"`
}

type ManifestEntryOut

type ManifestEntryOut struct {
	Position          int    `json:"position"`
	URI               string `json:"uri"`
	Ref               string `json:"ref,omitempty"`
	SnapshotID        string `json:"snapshot_id"`
	MaterializationID string `json:"materialization_id"`
	ContentHash       string `json:"content_hash"`
}

ManifestEntryOut is one position in a committed manifest.

type ManifestOut

type ManifestOut struct {
	ManifestID string             `json:"manifest_id"`
	RunID      string             `json:"run_id"`
	CreatedAt  string             `json:"created_at"`
	Entries    []ManifestEntryOut `json:"entries"`
}

ManifestOut is a committed manifest: the immutable record of everything one run resolved, in mount order.

type MountOut

type MountOut struct {
	RunID    string     `json:"run_id"`
	Position int        `json:"position"`
	Resolved ResolveOut `json:"resolved"`
}

type Options

type Options struct {
	// Name and Version identify this server to MCP clients; they default
	// to "readproof" and the current Readproof version.
	Name    string
	Version string
	// MaxInlineBytes caps the content any one resource read or tool result
	// carries inline (default DefaultMaxInlineBytes). Content past the cap
	// is replaced by a truncation marker naming the content hash.
	MaxInlineBytes int
	// Logger receives SDK server activity. It must never write to stdout
	// on a stdio transport — stdout is the JSON-RPC channel.
	Logger *slog.Logger
}

Options configures a server. The zero value is usable.

type PolicyInfo

type PolicyInfo struct {
	Strategy         string `json:"strategy"`
	MaxAgeSeconds    int64  `json:"max_age_seconds,omitempty"`
	PinnedSnapshotID string `json:"pinned_snapshot_id,omitempty"`
}

PolicyInfo is a resource's freshness policy.

type ReplayEntryOut

type ReplayEntryOut struct {
	Position          int             `json:"position"`
	URI               string          `json:"uri"`
	MaterializationID string          `json:"materialization_id"`
	RecordedHash      string          `json:"recorded_hash"`
	ReplayedHash      string          `json:"replayed_hash"`
	Match             bool            `json:"match"`
	Content           *ContentPayload `json:"content,omitempty"`
}

ReplayEntryOut verifies one manifest entry: recorded_hash is what the manifest committed to, replayed_hash is what re-hashing the bytes read back out of the blob store produced.

type ReplayOut

type ReplayOut struct {
	ManifestID string           `json:"manifest_id"`
	RunID      string           `json:"run_id"`
	AllMatch   bool             `json:"all_match"`
	Entries    []ReplayEntryOut `json:"entries"`
}

ReplayOut is a whole manifest reconstructed from storage alone.

type ResolveOut

type ResolveOut struct {
	URI               string            `json:"uri"`
	Ref               string            `json:"ref,omitempty"`
	Decision          string            `json:"decision"`
	SnapshotID        string            `json:"snapshot_id"`
	ContentHash       string            `json:"content_hash"`
	SourceRevision    string            `json:"source_revision"`
	ObservedAt        string            `json:"observed_at"`
	ContentType       string            `json:"content_type"`
	Bytes             int64             `json:"bytes"`
	MaterializationID string            `json:"materialization_id"`
	Provenance        map[string]string `json:"provenance,omitempty"`
	Content           *ContentPayload   `json:"content,omitempty"`
}

ResolveOut is the result of resolving one reference: the snapshot that was selected, why it was selected (Decision), and optionally the bytes.

type ResourceInfo

type ResourceInfo struct {
	URI               string     `json:"uri"`
	Namespace         string     `json:"namespace"`
	Path              string     `json:"path"`
	Description       string     `json:"description"`
	Source            SourceInfo `json:"source"`
	Policy            PolicyInfo `json:"policy"`
	CurrentSnapshotID string     `json:"current_snapshot_id,omitempty"`
}

ResourceInfo is one registered resource as readproof_resources_list reports it.

type ResourceListOut

type ResourceListOut struct {
	Resources []ResourceInfo `json:"resources"`
}

type RunStartOut

type RunStartOut struct {
	RunID string `json:"run_id"`
	// NextStep spells out the lifecycle so a model that called start in
	// isolation knows a manifest only exists after commit.
	NextStep string `json:"next_step"`
}

type SnapshotInfo

type SnapshotInfo struct {
	SnapshotID     string            `json:"snapshot_id"`
	ResourceURI    string            `json:"resource_uri"`
	SourceRevision string            `json:"source_revision"`
	ContentHash    string            `json:"content_hash"`
	ObservedAt     string            `json:"observed_at"`
	CreatedAt      string            `json:"created_at"`
	ContentType    string            `json:"content_type"`
	Bytes          int64             `json:"bytes"`
	Provenance     map[string]string `json:"provenance,omitempty"`
	// Tags are the tag names currently pointing at this snapshot — the
	// answer to "which of these can I pin?" without a second call.
	Tags []string `json:"tags,omitempty"`
}

SnapshotInfo is one immutable observation of a resource.

type SourceInfo

type SourceInfo struct {
	Kind    string            `json:"kind"`
	Path    string            `json:"path,omitempty"`
	Owner   string            `json:"owner,omitempty"`
	Repo    string            `json:"repo,omitempty"`
	Ref     string            `json:"ref,omitempty"`
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
}

SourceInfo is a resource's origin with credential-bearing fields redacted (see internal/redact). HTTP header values are the field that carries secrets, and they are masked even in embedded mode: this projection is the one that leaves the process.

type TagDeleteOut

type TagDeleteOut struct {
	URI     string `json:"uri"`
	Tag     string `json:"tag"`
	Deleted bool   `json:"deleted"`
}

type TagInfo

type TagInfo struct {
	URI        string `json:"uri"`
	Tag        string `json:"tag"`
	SnapshotID string `json:"snapshot_id"`
	UpdatedAt  string `json:"updated_at"`
	// Reference is the string to read this tag by, uri@tag — spelling it
	// out saves a model from assembling it and getting the syntax wrong.
	Reference string `json:"reference"`
}

TagInfo is a named, movable pointer from a resource to one of its snapshots.

type TagListOut

type TagListOut struct {
	URI  string    `json:"uri"`
	Tags []TagInfo `json:"tags"`
}