Skip to content

spec: V2 Storage Specification - Zustand Proposal#1016

Open
olaservo wants to merge 5 commits intomodelcontextprotocol:v2/mainfrom
olaservo:v2/spec/storage
Open

spec: V2 Storage Specification - Zustand Proposal#1016
olaservo wants to merge 5 commits intomodelcontextprotocol:v2/mainfrom
olaservo:v2/spec/storage

Conversation

@olaservo
Copy link
Member

@olaservo olaservo commented Jan 19, 2026 •
edited
Loading

Summary

Closes #983

This PR adds a comprehensive storage specification for Inspector V2, proposing Zustand for client-side state management.

Key Recommendations

  • Zustand for UI preferences, logs display, execution form state, testing profiles
  • useReducer + Context for connection/execution state machines (See: placeholder inspector-core PR)
  • Pino + NDJSON for server-side history persistence
  • Repository interfaces - Zustand stores wrap repository interfaces for storage-agnostic design (See: placeholder inspector-core PR)

Options Analyzed

Option Bundle Verdict
Zustand 1.2KB Recommended - minimal, persist built-in, MCPJam precedent
Redux/RTK 11KB Rejected - overkill for single-server model
Jotai 2.2KB Good alternative, smaller ecosystem
Context+useReducer 0 Keep for state machines
TanStack Query 13KB Consider as complement for API calls
Valtio 3KB Viable, but proxy semantics less familiar

Store Structure

  1. Preferences Store (persisted) - theme, log level, panel sizes
  2. Logs Display Store (ephemeral) - buffer, filters, pause/scroll
  3. Execution Form Store (ephemeral) - selected tool/resource/prompt, form values
  4. Testing Profiles Store (persisted) - custom profiles, active selection

Why Zustand?

  1. MCPJam Inspector precedent - proven patterns in comparable application
  2. Minimal bundle (1.2KB vs 11KB Redux)
  3. Built-in persist middleware for localStorage
  4. React-free core (zustand/vanilla) supports CLI/TUI reuse
  5. Selector optimization prevents unnecessary re-renders

Test plan

  • Review spec document for completeness
  • Validate alignment with existing architecture decisions (#1805, #1853)
  • Confirm integration pattern preserves interface-first design
  • Discuss open questions in spec (TanStack Query complement, devtools, store granularity)

Generated with Claude Code

@olaservo @claude
spec: Add v2 storage specification proposing Zustand
ce39e0d 
Closes modelcontextprotocol#983

Proposes a hybrid state management architecture:
- Zustand for UI preferences, logs display, playground state, testing profiles
- Keep useReducer + Context for connection/execution state machines
- Repository interfaces remain storage-agnostic for proxy API integration

Includes detailed analysis of storage options (Zustand, Redux, Jotai,
Context+useReducer, TanStack Query, Valtio) with pros/cons comparison.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@olaservo olaservo added the v2 label Jan 19, 2026
@olaservo olaservo marked this pull request as ready for review January 21, 2026 04:02
olaservo and others added 3 commits January 21, 2026 08:14
@olaservo @claude
docs(spec): update storage spec diagram to match implementation
6a132d6 
- Remove ConnectionService/ExecutionService from core interfaces
  (connection/execution state managed by React Context per spec text)
- Remove Memory implementations from core package
  (repository interfaces kept as proxy API contracts)
- Change "Handler interfaces" to "Handler functions"

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@olaservo @claude
fix(spec): correct Jotai provider claim - provider-less by default
d755666 
Jotai uses provider-less mode by default since v2. Provider is only
needed for SSR, subtree isolation, or custom initial values.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@olaservo @claude
fix(spec): simplify ExecutionFormState to use lastToolResult
adc1791 
Replace toolResponseHistory array with single lastToolResult field.
History is the source of truth for execution records - no need to
duplicate in UI state.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

v2

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@olaservo