reader

Documentation

Overview

Package reader provides streaming and path-based access to large JSON response files stored in the workspace. It is used by the response_* MCP tools to build outlines, compress arrays, and extract fragments without loading entire files into memory.

Index

• Variables
• type CompressMode
• type CompressOptions
• type CompressResult
• type Outline
• type OutlineOptions
• type Reader
  • func New(responsesDir string) Reader
• type Slice
• type SliceOptions

Variables

var (
	// ErrFileNotFound indicates the requested response file does not exist.
	ErrFileNotFound = errors.New("response file not found")
	// ErrPathNotAllowed indicates the path is outside the responses directory.
	ErrPathNotAllowed = errors.New("path is not inside the responses directory")
	// ErrInvalidJSONPath indicates the provided jsonPath syntax is not supported.
	ErrInvalidJSONPath = errors.New("invalid jsonPath")
	// ErrPathNotFound indicates the jsonPath did not resolve to any value in the file.
	ErrPathNotFound = errors.New("jsonPath did not match any value")
	// ErrInvalidLineRange indicates the requested line range is malformed or out of bounds.
	ErrInvalidLineRange = errors.New("invalid line range")
	// ErrNotJSON indicates the file is not valid JSON.
	ErrNotJSON = errors.New("file is not valid JSON")
	// ErrInvalidCompressMode indicates the compression mode is not supported.
	ErrInvalidCompressMode = errors.New("invalid compress mode")
	// ErrSelectKeysRequired indicates select_keys mode requires at least one key.
	ErrSelectKeysRequired = errors.New("select_keys requires at least one selectKey")
)

Types

type CompressMode

type CompressMode string

CompressMode selects how a large JSON value is reduced.

const (
	// CompressFirstOfArray keeps only the first element of a homogeneous array.
	CompressFirstOfArray CompressMode = "first_of_array"
	// CompressSampleArray keeps a head and tail sample of an array.
	CompressSampleArray CompressMode = "sample_array"
	// CompressTruncateStrings shortens every string value.
	CompressTruncateStrings CompressMode = "truncate_strings"
	// CompressKeysOnly replaces object values with their type names.
	CompressKeysOnly CompressMode = "keys_only"
	// CompressSelectKeys keeps only the selected keys for every object in an array.
	CompressSelectKeys CompressMode = "select_keys"
)

type CompressOptions

type CompressOptions struct {
	JSONPath   string       `json:"jsonPath,omitempty"`
	Mode       CompressMode `json:"mode"`
	ArrayHead  int          `json:"arrayHead,omitempty"`
	ArrayTail  int          `json:"arrayTail,omitempty"`
	StringLen  int          `json:"stringLen,omitempty"`
	SelectKeys []string     `json:"selectKeys,omitempty"`
	Limit      int          `json:"limit,omitempty"`
}

CompressOptions controls how compression is performed.

type CompressResult

type CompressResult struct {
	Body     any    `json:"body,omitempty"`
	TooLarge bool   `json:"tooLarge"`
	Hint     string `json:"hint,omitempty"`
}

CompressResult is the outcome of compression.

type Outline

type Outline struct {
	Type             string      `json:"type"`
	Size             int64       `json:"size"`
	LineCount        int         `json:"lineCount"`
	Depth            int         `json:"depth"`
	Structure        outlineNode `json:"structure"`
	SchemaHint       string      `json:"schemaHint"`
	Keys             []string    `json:"keys,omitempty"`
	ItemCount        int         `json:"itemCount,omitempty"`
	ItemType         string      `json:"itemType,omitempty"`
	CompressionHints []string    `json:"compressionHints"`
	NavigationHints  navigation  `json:"navigationHints"`
}

Outline describes the high-level structure of a JSON response file.

type OutlineOptions

type OutlineOptions struct {
	MaxDepth      int `json:"maxDepth,omitempty"`
	MaxArrayItems int `json:"maxArrayItems,omitempty"`
}

OutlineOptions controls how the outline is built.

type Reader

type Reader interface {
	// Outline returns a high-level structural summary of the file at path.
	Outline(path string, opts OutlineOptions) (Outline, error)
	// Compress reduces a JSON value selected by jsonPath according to mode.
	Compress(path string, opts CompressOptions) (CompressResult, error)
	// Slice returns a fragment of JSON by jsonPath or line range.
	Slice(path string, opts SliceOptions) (Slice, error)
}

Reader reads and navigates large JSON response files in a workspace.

func New

func New(responsesDir string) Reader

New creates a Reader rooted at responsesDir.

type Slice

type Slice struct {
	Lines      [2]int `json:"lines"`
	Fragment   string `json:"fragment,omitempty"`
	Value      any    `json:"value"`
	JSONPath   string `json:"jsonPath,omitempty"`
	Context    string `json:"context"`
	IsComplete bool   `json:"isComplete"`
	NextLine   int    `json:"nextLine"`
	PrevLine   int    `json:"prevLine"`
	NextPath   string `json:"nextPath,omitempty"`
	PrevPath   string `json:"prevPath,omitempty"`
}

Slice describes a fragment extracted from a JSON file.

type SliceOptions

type SliceOptions struct {
	JSONPath string `json:"jsonPath,omitempty"`
	Line     int    `json:"line,omitempty"`
	Range    string `json:"range,omitempty"`
	Around   int    `json:"around,omitempty"`
	Limit    int    `json:"limit,omitempty"`
}

SliceOptions controls fragment extraction.