Res mcp

[tomaszpatrzek]

New contrib gem exposing RubyEventStore as an MCP (Model Context Protocol) server. Allows AI assistants
(Claude, etc.) to inspect the event store directly — without a terminal, without writing SQL, without leaving
the conversation.

How it works

The server runs as a stdio process started by the MCP client (Claude Desktop, Claude Code). It reads JSON-RPC
requests from stdin and writes responses to stdout. The MCP client decides which tool to call based on the
user's question.

Claude ←→ MCP protocol (stdio JSON-RPC) ←→ res-mcp ←→ Rails.configuration.event_store

Usage

Add to your Gemfile:

gem "ruby_event_store-mcp"

Configure in your MCP client. Add the snippet to the appropriate config file:

Claude Code

• Project-local: .claude/settings.json
• Global: ~/.claude/settings.json

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
   "mcpServers": {
     "res": {
       "command": "bundle",
       "args": ["exec", "res-mcp"],
       "cwd": "/path/to/rails/app"
     }
   }
 }

After that Claude can answer questions like:

• "What happened to order 123? Show me the causation tree."
• "How many events do we have and what types?"
• "Find all OrderShipped events from last week."
• "Show me the full lifecycle of Order abc-123."
• "What are the 20 most recent events across all streams?"

Available tools

• recent — most recent events across all streams (default: 20, newest first)
• stream_show — event count, version, first/last event for a stream
• stream_events — events in a stream with filters (type, time range, limit)
• event_show — full event details: data, metadata, timestamps
• event_streams — all streams an event was published or linked to
• aggregate_history — full event history of an aggregate instance by type and ID
• search — search across all streams by type, time range, stream
• stats — total event count and unique event types
• trace — causation tree for all events sharing a correlation ID

Architecture

• No external dependencies — MCP protocol implemented from scratch (~80 lines of JSON-RPC over stdio)
• Tools use only public event_store.* API — adapter-agnostic (InMemory, AR, Sequel, ROM)
• Each tool is an independent class: name, schema, call(event_store, args) → String
• MCP.server(event_store) builds a fully configured server with all tools registered
• Full mutation test coverage with Mutant (all surviving mutations are documented equivalent mutations)