Res mcp

.github/workflows/ruby_event_store-mcp_mutate.yml

@@ -0,0 +1,52 @@
+name: ruby_event_store-mcp_mutate
+on:
+  workflow_dispatch:
+  repository_dispatch:
+    types:
+    - script
+  push:
+    branches:
+    - master
+    paths:
+    - contrib/ruby_event_store-mcp/**
+    - ".github/workflows/ruby_event_store-mcp_mutate.yml"
+    - support/**
+    - "!support/bundler/**"
+    - "!support/ci/**"
+  pull_request:
+    paths:
+    - contrib/ruby_event_store-mcp/**
+    - ".github/workflows/ruby_event_store-mcp_mutate.yml"
+    - support/**
+    - "!support/bundler/**"
+    - "!support/ci/**"
+jobs:
+  mutate:
+    runs-on: macos-14
+    timeout-minutes: 120
+    env:
+      WORKING_DIRECTORY: contrib/ruby_event_store-mcp
+      RUBY_VERSION: "${{ matrix.ruby_version }}"
+      BUNDLE_GEMFILE: "${{ matrix.bundle_gemfile }}"
+      SINCE_SHA: "${{ github.event.pull_request.base.sha || 'HEAD~1' }}"
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - ruby_version: ruby-3.4
+          bundle_gemfile: Gemfile
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - run: test -e ${{ env.BUNDLE_GEMFILE }}.lock
+      working-directory: "${{ env.WORKING_DIRECTORY }}"
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "${{ env.RUBY_VERSION }}"
+        bundler-cache: true
+        working-directory: "${{ env.WORKING_DIRECTORY }}"
+    - run: make mutate-changes
+      working-directory: "${{ env.WORKING_DIRECTORY }}"
+      env:
+        RUBYOPT: "--enable-frozen-string-literal"

.github/workflows/ruby_event_store-mcp_test.yml

@@ -0,0 +1,55 @@
+name: ruby_event_store-mcp_test
+on:
+  workflow_dispatch:
+  repository_dispatch:
+    types:
+    - script
+  push:
+    branches:
+    - master
+    paths:
+    - contrib/ruby_event_store-mcp/**
+    - ".github/workflows/ruby_event_store-mcp_test.yml"
+    - support/**
+    - "!support/bundler/**"
+    - "!support/ci/**"
+  pull_request:
+    paths:
+    - contrib/ruby_event_store-mcp/**
+    - ".github/workflows/ruby_event_store-mcp_test.yml"
+    - support/**
+    - "!support/bundler/**"
+    - "!support/ci/**"
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    env:
+      WORKING_DIRECTORY: contrib/ruby_event_store-mcp
+      RUBY_VERSION: "${{ matrix.ruby_version }}"
+      BUNDLE_GEMFILE: "${{ matrix.bundle_gemfile }}"
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - ruby_version: ruby-3.4
+          bundle_gemfile: Gemfile
+        - ruby_version: ruby-3.3
+          bundle_gemfile: Gemfile
+        - ruby_version: ruby-3.2
+          bundle_gemfile: Gemfile
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 1
+    - run: test -e ${{ env.BUNDLE_GEMFILE }}.lock
+      working-directory: "${{ env.WORKING_DIRECTORY }}"
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: "${{ env.RUBY_VERSION }}"
+        bundler-cache: true
+        working-directory: "${{ env.WORKING_DIRECTORY }}"
+    - run: make test
+      working-directory: "${{ env.WORKING_DIRECTORY }}"
+      env:
+        RUBYOPT: "--enable-frozen-string-literal"

contrib/Makefile

@@ -9,6 +9,7 @@ GEMS = minitest-ruby_event_store \
        ruby_event_store-sequel \
        ruby_event_store-sidekiq_scheduler \
        ruby_event_store-transformations \
+       ruby_event_store-mcp \
 			 dres_rails \
 			 dres_client
 

contrib/ruby_event_store-mcp/.mutant.yml

@@ -0,0 +1,18 @@
+# https://github.com/mbj/mutant/blob/master/docs/configuration.md
+
+usage: opensource
+requires:
+  - ruby_event_store/mcp
+includes:
+  - lib
+integration:
+  name: rspec
+mutation:
+  operators: light
+coverage_criteria:
+  process_abort: true
+matcher:
+  subjects:
+    - RubyEventStore::MCP*
+  ignore:
+    - RubyEventStore::MCP::Server#start

contrib/ruby_event_store-mcp/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+gemspec
+
+eval_gemfile "../../support/bundler/Gemfile.shared"
+gem "ruby_event_store", path: "../.."

contrib/ruby_event_store-mcp/Gemfile.lock

@@ -0,0 +1,101 @@
+PATH
+  remote: ../..
+  specs:
+    ruby_event_store (2.19.2)
+      concurrent-ruby (~> 1.0, >= 1.1.6)
+
+PATH
+  remote: .
+  specs:
+    ruby_event_store-mcp (0.1.0)
+      ruby_event_store (>= 1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    concurrent-ruby (1.3.6)
+    date (3.5.1)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    erb (6.0.4)
+    io-console (0.8.2)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    minitest (6.0.5)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    mutant (0.15.1)
+      diff-lcs (>= 1.6, < 3)
+      irb (~> 1.15)
+      parser (~> 3.3.10)
+      regexp_parser (~> 2.10)
+      sorbet-runtime (~> 0.6.0)
+      unparser (~> 0.8.2)
+    mutant-minitest (0.15.1)
+      minitest (>= 5.11, < 7)
+      mutant (= 0.15.1)
+      mutex_m (~> 0.2)
+    mutant-rspec (0.15.1)
+      mutant (= 0.15.1)
+      rspec-core (>= 3.8.0, < 5.0.0)
+    mutex_m (0.3.0)
+    parser (3.3.11.1)
+      ast (~> 2.4.1)
+      racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
+    prism (1.9.0)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
+    rake (13.4.2)
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
+    regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    sorbet-runtime (0.6.13164)
+    stringio (3.2.0)
+    tsort (0.2.0)
+    unparser (0.8.2)
+      diff-lcs (>= 1.6, < 3)
+      parser (>= 3.3.0)
+      prism (>= 1.5.1)
+
+PLATFORMS
+  arm64-darwin-23
+  ruby
+
+DEPENDENCIES
+  irb
+  mutant
+  mutant-minitest
+  mutant-rspec
+  rake (>= 10.0)
+  rspec
+  ruby_event_store!
+  ruby_event_store-mcp!
+
+BUNDLED WITH
+   2.7.1

contrib/ruby_event_store-mcp/Makefile

@@ -0,0 +1,8 @@
+GEM_VERSION  = $(shell cat lib/ruby_event_store/mcp/version.rb | grep VERSION | egrep -o '[0-9]+\.[0-9]+\.[0-9]+')
+GEM_NAME     = ruby_event_store-mcp
+
+include ../../support/make/install.mk
+include ../../support/make/test.mk
+include ../../support/make/mutant.mk
+include ../../support/make/gem.mk
+include ../../support/make/help.mk

contrib/ruby_event_store-mcp/README.md

@@ -0,0 +1,82 @@
+# ruby_event_store-mcp
+
+Model Context Protocol (MCP) server for [RubyEventStore](https://railseventstore.org). Exposes your event store as AI tools so Claude (and other MCP clients) can inspect streams, events, and causal relationships directly.
+
+## Installation
+
+Add to your Rails app's `Gemfile`:
+
+```ruby
+gem "ruby_event_store-mcp"
+```
+
+## Usage
+
+Run from the root of your Rails application:
+
+```bash
+bundle exec res-mcp
+```
+
+The server communicates over stdio using the MCP protocol. Installing the gem only provides the `res-mcp` binary — you still have to register it with your MCP client. Every client takes the same server definition; only the file it lives in differs.
+
+### Claude Code
+
+Add a `.mcp.json` to your project root (or run `claude mcp add res -- bundle exec res-mcp`):
+
+```json
+{
+  "mcpServers": {
+    "res": {
+      "command": "bundle",
+      "args": ["exec", "res-mcp"]
+    }
+  }
+}
+```
+
+Launched from the project directory, Claude Code runs the server there, so no `cwd` is needed. On the next launch Claude Code asks you to trust the server — approve it, then run `/mcp` to confirm `res` is connected with its tools.
+
+### Claude Desktop
+
+Add the same block with an explicit `cwd` pointing at your app's root, in `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "res": {
+      "command": "bundle",
+      "args": ["exec", "res-mcp"],
+      "cwd": "/path/to/your/rails/app"
+    }
+  }
+}
+```
+
+Config file locations:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Other MCP clients
+
+Cursor, Windsurf, Cline and others take the same `mcpServers` block in their own config file. VS Code's built-in MCP support uses a `servers` key with `"type": "stdio"` instead. The `bundle exec res-mcp` command is the portable part.
+
+## Requirements
+
+- Ruby >= 3.0
+- A Rails application with `Rails.configuration.event_store` configured
+
+## Available tools
+
+| Tool                | Description                                                      |
+|---------------------|------------------------------------------------------------------|
+| `recent`            | Most recent events across all streams (default: 20, newest first)|
+| `stream_show`       | Event count, version, first/last event for a stream              |
+| `stream_events`     | List events in a stream (filter by type, time range, limit)      |
+| `event_show`        | Full event details: data, metadata, timestamps                   |
+| `event_streams`     | All streams an event has been published or linked to             |
+| `aggregate_history` | Full event history of an aggregate instance by type and ID       |
+| `search`            | Search events by type, time range, or stream                     |
+| `stats`             | Total event count and unique event types                         |
+| `trace`             | Causation tree for all events sharing a correlation ID           |

contrib/ruby_event_store-mcp/bin/res-mcp

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ruby_event_store/mcp"
+
+env_file = File.expand_path("config/environment.rb")
+
+abort "Could not find config/environment.rb. Run `res-mcp` from the root of your Rails application." unless File.exist?(env_file)
+
+require env_file
+
+abort <<~MSG unless defined?(Rails) && Rails.configuration.respond_to?(:event_store)
+  Could not find event store instance after loading config/environment.rb.
+
+  Expected Rails.configuration.event_store to be set (standard RES setup).
+MSG
+
+RubyEventStore::MCP.server(Rails.configuration.event_store).start

contrib/ruby_event_store-mcp/lib/ruby_event_store/mcp.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "mcp/version"
+require_relative "mcp/read_events"
+require_relative "mcp/server"
+require_relative "mcp/tools/stream_show"
+require_relative "mcp/tools/stream_events"
+require_relative "mcp/tools/event_show"
+require_relative "mcp/tools/event_streams"
+require_relative "mcp/tools/search"
+require_relative "mcp/tools/stats"
+require_relative "mcp/tools/trace"
+require_relative "mcp/tools/aggregate_history"
+require_relative "mcp/tools/recent"
+
+module RubyEventStore
+  module MCP
+    def self.server(event_store)
+      Server
+        .new(event_store: event_store)
+        .register(Tools::StreamShow.new)
+        .register(Tools::StreamEvents.new)
+        .register(Tools::EventShow.new)
+        .register(Tools::EventStreams.new)
+        .register(Tools::Search.new)
+        .register(Tools::Stats.new)
+        .register(Tools::Trace.new)
+        .register(Tools::AggregateHistory.new)
+        .register(Tools::Recent.new)
+    end
+  end
+end