Skip to content

spec: V2 Storage Specification - Zustand Proposal #1016

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
olaservo wants to merge 2 commits into
base: v2/main
Choose a base branch
from
Open

spec: V2 Storage Specification - Zustand Proposal #1016

olaservo wants to merge 2 commits into from
+485 −0

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
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