ruby_event_store-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff5bf2fc507301e40e1e307280b1e3dcbb7ea00a8babf6dc9bf5684a72a0c0b2
+  data.tar.gz: 823bd757d780fb861a7423ca4e80e767662f472dcda92640a95811983f3b0570
+SHA512:
+  metadata.gz: 975772a2e847f88f07b84b3d2bca336e6a4e4267e09028e6980d7d0f61c48c691207a6fbbcaa27b593b03e3df9c268eefe51adcffaf53acc8d5a72f9c6121272
+  data.tar.gz: 93ec27cded4a7f5e9b45a40bf31cd25a51866d74258117984738a6e03b6f17021d4350030d8f8145449ff61b24e4d4b1666b9aff0e12f4985daf0c013f87a492

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

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

data/lib/ruby_event_store/mcp/read_events.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module MCP
+    class ReadEvents
+      def self.of(specification, type: nil, after: nil, before: nil, from: nil, limit: nil)
+        specification = specification.of_type(resolve_type(type))    if type
+        specification = specification.newer_than(Time.parse(after))  if after
+        specification = specification.older_than(Time.parse(before)) if before
+        specification = specification.from(from)                     if from
+        limit ? specification.limit(limit.to_i).to_a : specification.to_a
+      end
+
+      def self.resolve_type(name)
+        Object.const_get(name)
+      rescue NameError
+        raise "Unknown event type: #{name}"
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/server.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyEventStore
+  module MCP
+    class Server
+      PROTOCOL_VERSION = "2024-11-05"
+
+      attr_reader :event_store, :name, :version, :tools
+
+      def initialize(event_store:, name: "ruby-event-store", version: VERSION)
+        @event_store = event_store
+        @name = name
+        @version = version
+        @tools = []
+      end
+
+      def register(tool)
+        tools << tool
+        self
+      end
+
+      def start(input: $stdin, output: $stdout)
+        output.sync = true
+        input.each_line do |line|
+          request = JSON.parse(line.strip)
+          response = handle(request)
+          output.puts(JSON.generate(response)) if response
+        end
+      end
+
+      private
+
+      def handle(request)
+        id = request["id"]
+        method = request["method"]
+
+        case method
+        when "initialize"
+          result = {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: { name: name, version: version }
+          }
+          jsonrpc_result(id, result)
+        when "notifications/initialized"
+          nil
+        when "tools/list"
+          jsonrpc_result(id, { tools: tools.map(&:schema) })
+        when "tools/call"
+          call_tool(id, request["params"])
+        when "ping"
+          jsonrpc_result(id, {})
+        else
+          jsonrpc_error(id, -32601, "Method not found: #{method}")
+        end
+      rescue => e
+        jsonrpc_error(request["id"], -32603, e.message)
+      end
+
+      def call_tool(id, params)
+        tool_name = params["name"]
+        arguments = params["arguments"] || {}
+        tool = tools.find { |t| t.name == tool_name }
+        return jsonrpc_result(id, { content: [{ type: "text", text: "Unknown tool: #{tool_name}" }], isError: true }) unless tool
+
+        result = tool.call(event_store, arguments)
+        jsonrpc_result(id, { content: [{ type: "text", text: result }] })
+      rescue => e
+        jsonrpc_result(id, { content: [{ type: "text", text: "Error: #{e.message}" }], isError: true })
+      end
+
+      def jsonrpc_result(id, result)
+        { jsonrpc: "2.0", id: id, result: result }
+      end
+
+      def jsonrpc_error(id, code, message)
+        { jsonrpc: "2.0", id: id, error: { code: code, message: message } }
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/aggregate_history.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class AggregateHistory
+        def name
+          "aggregate_history"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "Show the full event history of an aggregate instance",
+            inputSchema: {
+              type: "object",
+              properties: {
+                aggregate_type: { type: "string", description: "Aggregate class name (e.g. Order, Payment::Invoice)" },
+                aggregate_id: { type: "string", description: "Aggregate ID (UUID or other identifier)" }
+              },
+              required: %w[aggregate_type aggregate_id]
+            }
+          }
+        end
+
+        def call(event_store, args)
+          aggregate_type = args.fetch("aggregate_type")
+          aggregate_id = args.fetch("aggregate_id")
+          stream_name = "#{aggregate_type}$#{aggregate_id}"
+          events = events(event_store, stream_name)
+          render(stream_name, events)
+        end
+
+        private
+
+        def events(event_store, stream_name)
+          event_store.read.stream(stream_name).to_a
+        end
+
+        def render(stream_name, events)
+          header = "Aggregate: #{stream_name}\nEvents:    #{events.size}"
+          return header if events.empty?
+          "#{header}\n\n#{events.map { |e| "#{e.timestamp.iso8601(3)}  #{e.event_type}  [#{e.event_id}]" }.join("\n")}"
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/event_show.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class EventShow
+        def name
+          "event_show"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "Show full event details including data, metadata, and timestamps",
+            inputSchema: {
+              type: "object",
+              properties: {
+                event_id: { type: "string", description: "Event ID (UUID)" }
+              },
+              required: ["event_id"]
+            }
+          }
+        end
+
+        def call(event_store, args)
+          event = event_store.read.event!(args.fetch("event_id"))
+          format_event(event)
+        end
+
+        private
+
+        def format_event(event)
+          [
+            "Event ID:   #{event.event_id}",
+            "Type:       #{event.event_type}",
+            "Timestamp:  #{event.timestamp.iso8601(3)}",
+            "Valid at:   #{event.valid_at.iso8601(3)}",
+            "Data:       #{JSON.pretty_generate(event.data)}",
+            "Metadata:   #{JSON.pretty_generate(event.metadata.to_h)}"
+          ].join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/event_streams.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class EventStreams
+        def name
+          "event_streams"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "List all streams the event has been published or linked to",
+            inputSchema: {
+              type: "object",
+              properties: {
+                event_id: { type: "string", description: "Event ID (UUID)" }
+              },
+              required: ["event_id"]
+            }
+          }
+        end
+
+        def call(event_store, args)
+          streams = event_store.streams_of(args.fetch("event_id"))
+          return "(no streams — event not found or not linked to any stream)" if streams.empty?
+          format_streams(streams)
+        end
+
+        private
+
+        def format_streams(streams)
+          streams.map(&:name).join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/recent.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class Recent
+        DEFAULT_LIMIT = 20
+
+        def name
+          "recent"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "Show the most recent events across all streams",
+            inputSchema: {
+              type: "object",
+              properties: {
+                limit: { type: "integer", description: "Number of events to return (default: #{DEFAULT_LIMIT})" }
+              },
+              required: []
+            }
+          }
+        end
+
+        def call(event_store, args)
+          limit = args.fetch("limit", DEFAULT_LIMIT).to_i
+          events = event_store.read.limit(limit).backward.to_a
+          return "(no events)" if events.empty?
+          render(events)
+        end
+
+        private
+
+        def render(events)
+          events.map { |e| "#{e.timestamp.iso8601(3)}  #{e.event_type}  [#{e.event_id}]" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/search.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../read_events"
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class Search
+        def name
+          "search"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "Search events across all streams by type, time range, or stream name",
+            inputSchema: {
+              type: "object",
+              properties: {
+                type: { type: "string", description: "Filter by event type class name" },
+                after: { type: "string", description: "Filter events newer than timestamp (ISO8601)" },
+                before: { type: "string", description: "Filter events older than timestamp (ISO8601)" },
+                stream: { type: "string", description: "Limit search to a specific stream" },
+                limit: { type: "integer", description: "Max number of events (default: 50)" }
+              }
+            }
+          }
+        end
+
+        def call(event_store, args)
+          specification = args.key?("stream") ? event_store.read.stream(args.fetch("stream")) : event_store.read
+          events = ReadEvents.of(
+            specification,
+            type: args["type"],
+            after: args["after"],
+            before: args["before"],
+            limit: args.fetch("limit", 50)
+          )
+          return "(no events found)" if events.empty?
+          format_events(events)
+        end
+
+        private
+
+        def format_events(events)
+          events.map { |e| "#{e.timestamp.iso8601(3)}  #{e.event_type}  [#{e.event_id}]" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/stats.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class Stats
+        def name
+          "stats"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "Show event count and unique event types. Use stream to get per-stream stats.",
+            inputSchema: {
+              type: "object",
+              properties: {
+                stream: { type: "string", description: "Show stats for a specific stream" }
+              }
+            }
+          }
+        end
+
+        def call(event_store, args)
+          specification = args.key?("stream") ? event_store.read.stream(args.fetch("stream")) : event_store.read
+          format_stats(specification, stream: args["stream"])
+        end
+
+        private
+
+        def format_stats(specification, stream:)
+          lines = []
+          lines << "Stream:  #{stream}" if stream
+          lines << "Events:  #{specification.count}"
+          lines.concat(format_event_types(specification))
+          lines.join("\n")
+        end
+
+        def format_event_types(specification)
+          types = specification.map(&:event_type).uniq.sort
+          return [] if types.empty?
+          ["\nEvent types:"] + types.map { |t| "  #{t}" }
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/stream_events.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "../read_events"
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class StreamEvents
+        def name
+          "stream_events"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "List events in a stream with optional filters",
+            inputSchema: {
+              type: "object",
+              properties: {
+                stream_name: { type: "string", description: "Stream name" },
+                limit: { type: "integer", description: "Max number of events (default: 20)" },
+                type: { type: "string", description: "Filter by event type class name" },
+                after: { type: "string", description: "Filter events newer than timestamp (ISO8601)" },
+                before: { type: "string", description: "Filter events older than timestamp (ISO8601)" },
+                from: { type: "string", description: "Start reading from event ID (exclusive)" }
+              },
+              required: ["stream_name"]
+            }
+          }
+        end
+
+        def call(event_store, args)
+          events = ReadEvents.of(
+            event_store.read.stream(args.fetch("stream_name")),
+            type: args["type"],
+            after: args["after"],
+            before: args["before"],
+            from: args["from"],
+            limit: args.fetch("limit", 20)
+          )
+          return "(no events)" if events.empty?
+          format_events(events)
+        end
+
+        private
+
+        def format_events(events)
+          events.map { |e| "#{e.timestamp.iso8601(3)}  #{e.event_type}  [#{e.event_id}]" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/stream_show.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class StreamShow
+        def name
+          "stream_show"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "Show event count, version, and first/last event for a stream",
+            inputSchema: {
+              type: "object",
+              properties: {
+                stream_name: { type: "string", description: "Stream name" }
+              },
+              required: ["stream_name"]
+            }
+          }
+        end
+
+        def call(event_store, args)
+          stream_name = args.fetch("stream_name")
+          specification = event_store.read.stream(stream_name)
+          format_stream(stream_name, specification)
+        end
+
+        private
+
+        def format_stream(stream_name, specification)
+          count = specification.count
+          lines = ["Stream:  #{stream_name}", "Events:  #{count}"]
+          lines.concat(format_bounds(specification, count)) if count > 0
+          lines.join("\n")
+        end
+
+        def format_bounds(specification, count)
+          first = specification.first
+          last = specification.last
+          [
+            "Version: #{count - 1}",
+            "First:   #{first.timestamp.iso8601(3)} (#{first.event_type})",
+            "Last:    #{last.timestamp.iso8601(3)} (#{last.event_type})"
+          ]
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/tools/trace.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module MCP
+    module Tools
+      class Trace
+        def name
+          "trace"
+        end
+
+        def schema
+          {
+            name: name,
+            description: "Show the causation tree for all events sharing a correlation ID",
+            inputSchema: {
+              type: "object",
+              properties: {
+                correlation_id: { type: "string", description: "Correlation ID (UUID)" }
+              },
+              required: ["correlation_id"]
+            }
+          }
+        end
+
+        def call(event_store, args)
+          events = events_for(event_store, args.fetch("correlation_id"))
+          return "(no events found for correlation ID #{args.fetch("correlation_id")})" if events.empty?
+          build_tree(events)
+        end
+
+        private
+
+        def events_for(event_store, correlation_id)
+          event_store.read.stream("$by_correlation_id_#{correlation_id}").to_a
+        end
+
+        def build_tree(events)
+          by_causation = events.group_by { |e| e.metadata[:causation_id] }
+          roots = root_events(events)
+          lines = []
+          roots.each do |e|
+            lines << "#{e.event_type} [#{e.event_id}]"
+            render_children(e, by_causation, "", lines)
+          end
+          lines.join("\n")
+        end
+
+        def root_events(events)
+          event_ids = events.map(&:event_id)
+          events.reject { |e| event_ids.include?(e.metadata[:causation_id]) }
+        end
+
+        def render_node(event, by_causation, prefix, lines)
+          lines << event_line(event, prefix, "├── ")
+          child_prefix = prefix + "│   "
+          render_children(event, by_causation, child_prefix, lines)
+        end
+
+        def render_last_node(event, by_causation, prefix, lines)
+          lines << event_line(event, prefix, "└── ")
+          child_prefix = prefix + "    "
+          render_children(event, by_causation, child_prefix, lines)
+        end
+
+        def event_line(event, prefix, connector)
+          "#{prefix}#{connector}#{event.event_type} [#{event.event_id}]"
+        end
+
+        def render_children(event, by_causation, prefix, lines)
+          *non_last, last = by_causation[event.event_id]
+          return if last.nil?
+          non_last.each { |child| render_node(child, by_causation, prefix, lines) }
+          render_last_node(last, by_causation, prefix, lines)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_event_store/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RubyEventStore
+  module MCP
+    VERSION = "0.1.0"
+  end
+end

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

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: ruby_event_store-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Arkency
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_event_store
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+email: dev@arkency.com
+executables:
+- res-mcp
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- bin/res-mcp
+- lib/ruby_event_store/mcp.rb
+- lib/ruby_event_store/mcp/read_events.rb
+- lib/ruby_event_store/mcp/server.rb
+- lib/ruby_event_store/mcp/tools/aggregate_history.rb
+- lib/ruby_event_store/mcp/tools/event_show.rb
+- lib/ruby_event_store/mcp/tools/event_streams.rb
+- lib/ruby_event_store/mcp/tools/recent.rb
+- lib/ruby_event_store/mcp/tools/search.rb
+- lib/ruby_event_store/mcp/tools/stats.rb
+- lib/ruby_event_store/mcp/tools/stream_events.rb
+- lib/ruby_event_store/mcp/tools/stream_show.rb
+- lib/ruby_event_store/mcp/tools/trace.rb
+- lib/ruby_event_store/mcp/version.rb
+homepage: https://railseventstore.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://railseventstore.org
+  source_code_uri: https://github.com/RailsEventStore/rails_event_store
+  bug_tracker_uri: https://github.com/RailsEventStore/rails_event_store/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.1
+specification_version: 4
+summary: Model Context Protocol server for Ruby Event Store
+test_files: []