reeve 0.9.0 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 71d3d77104fed813b71681276c4a72b16a48b68860e1f8264c11ddc119144118
4
- data.tar.gz: 6fde918086722a4d08b66bd46f9d434408e0ba5110364bfc119a45dc315dc141
3
+ metadata.gz: a2494b5cc7da010efdcb652117a7bbb4e6f9e717a17e3a773ba68c95448d1564
4
+ data.tar.gz: 9b4e6c8d08ee611c2f7ac50d7b9c91a3fbd6cddead484d083cdb091d49e53012
5
5
  SHA512:
6
- metadata.gz: ab022f65ea54798281422e451977ae873c0a431c01543205662e3ac7a9f65d90c3144ddc5a3332e7bb8653149e519ad01d3ccffea49f917488ef756f3bdc8544
7
- data.tar.gz: ea8ffabe6cdeb4c6c90a9e95a4e38547b4af743e27c6f3100fafce0772073eb8d15fa2c09ca2dcc28e4c6446613cb49fdf135d8f2213ce56cf04a06542cc86ca
6
+ metadata.gz: 7154fbc3a79c52f46965a5715cd05e8d4220498adbd03d0478005e572d61e03b3052a61deb4b2dec742f039eb5d7e01a22418926e1fcbf1553e75e826fd6967f
7
+ data.tar.gz: c41b78c50fe9a6da3361c915ecbb85b08e60305285c6a117f5ecbaeef8534ccbc4bc894b4251a1970425ff72944470d8bab185d82fac676ed4ec71ee0468945e
data/CHANGELOG.md CHANGED
@@ -4,6 +4,64 @@ All notable changes are recorded here. This project follows [Semantic
4
4
  Versioning](https://semver.org), with one rule specific to what it does — see
5
5
  [Versioning policy](#versioning-policy).
6
6
 
7
+ ## [0.10.0] - 2026-11-11
8
+
9
+ Reeve now rides the official MCP SDK (`require "reeve/mcp"`) and ActionMCP
10
+ (`require "reeve/action_mcp"`). No audit-entry contract change: it stays `4`.
11
+
12
+ ### Upgrading from 0.9.0
13
+
14
+ `bundle update reeve`. Nothing changes unless you require the new adapter. If you do, read
15
+ the next paragraph first.
16
+
17
+ **Requiring `reeve/mcp` or `reeve/action_mcp` under the default `:deny` refuses every tool
18
+ of that library that has no `guard_with`, on its next call, including SDK tools registered
19
+ with `server.define_tool`.** That is deny-by-default working as documented. Set
20
+ `config.unguarded_tools = :allow_with_warning` while you add guards, then switch back.
21
+
22
+ ### Added
23
+
24
+ - **Official MCP SDK adapter**, `require "reeve/mcp"`, for `mcp` 1.x (verified on 1.0.0 and
25
+ 1.9.0), on Ruby 3.0+. Every SDK tool class, block tools included, goes through the
26
+ envelope. `guard_with`, `redact`, `scoped` and `authorize!` are class methods on every
27
+ tool. A denial reaches the client as a tool error naming the rule.
28
+ - **ActionMCP adapter**, `require "reeve/action_mcp"`, for `actionmcp` 0.200 to 0.203
29
+ (Rails 8.1, Ruby 3.2+). The envelope runs inside ActionMCP's error handling, so tool errors
30
+ and denials are recorded before ActionMCP replaces them, and what a tool renders is held
31
+ until the call is allowed. The principal is `ActionMCP::Current.user` through your
32
+ resolver; background-task calls have no user and are refused `no_principal` unless your
33
+ resolver finds one. The adapter reaches into ActionMCP's internals, so it refuses to load
34
+ on a version it was not verified against.
35
+ - **`guard_with` plus `scoped` on both.** These tools return a finished response or render
36
+ content, not records, so Reeve allows or refuses the output whole; it does not narrow it.
37
+ The output is allowed only if the tool read through `scoped(...)` during the call. That
38
+ check is one flag per call: a tool that calls `scoped(Invoice)` and also renders
39
+ `Invoice.find(id)` passes. Fetch any other record through `authorize!`.
40
+ - **`request:` on `Reeve.invoke` and `Inventory#dispatch`**, read by the principal resolver
41
+ as `context.request` and never recorded. For what identifies the human (a server context,
42
+ a verified token, a session) and must not land in the ledger. `metadata:` keeps its
43
+ meaning: recorded and redacted.
44
+ - The testing kit runs SDK and ActionMCP tool classes with no `invoke:`, one ledger row per
45
+ call. A tool class can say how it is run by defining `reeve_run(arguments)`; the adapters
46
+ do.
47
+
48
+ ### Fixed
49
+
50
+ - The fast-mcp adapter opened a second envelope when the call was already inside one (the
51
+ testing kit's default invoker, or a host that wraps `Reeve.invoke` around a fast-mcp
52
+ call). The second one had no principal, so the call was refused and recorded twice. It now
53
+ runs inside the envelope that is already open.
54
+
55
+ ### Known limitations
56
+
57
+ - fast-mcp and the official SDK cannot share a process. fast-mcp ships `lib/mcp/tool.rb`
58
+ and `lib/mcp/server.rb`, the paths the SDK loads `MCP::Tool` and `MCP::Server` from, so
59
+ loading fast-mcp first hides the SDK's classes. `reeve/mcp` refuses to load in that case
60
+ and says why.
61
+ - Every SDK block tool is a new class, and Reeve keeps every tool class it sees. A server
62
+ built per request that calls `define_tool` grows that list on every request; define block
63
+ tools once at boot with `MCP::Tool.define` and pass them in `tools:`.
64
+
7
65
  ## [0.9.0] - 2026-11-09
8
66
 
9
67
  The compliance suite can now prove the ledger anchor works, with no test of your own. No
data/README.md CHANGED
@@ -7,7 +7,7 @@ A Ruby gem that makes it safe for a Rails application to expose MCP tools to AI
7
7
  declarative per-record authorization, an append-only audit ledger, and a testing kit that
8
8
  proves both hold.
9
9
 
10
- > **Status: 0.9.0.** Read the known limitations in
10
+ > **Status: 0.10.0.** Read the known limitations in
11
11
  > [CHANGELOG.md](CHANGELOG.md) before adopting it — particularly the one about a
12
12
  > transaction wrapped around an invocation, if your application wraps requests in one.
13
13
 
@@ -639,6 +639,132 @@ FAIL CrossPrincipalLeak
639
639
  Invoice#9 (guard: InvoicePolicy, decision: allow via InvoicePolicy#index)
640
640
  ```
641
641
 
642
+ ## On the official MCP SDK
643
+
644
+ ```ruby
645
+ # config/initializers/reeve.rb
646
+ require "reeve/mcp"
647
+
648
+ Reeve.configure do |config|
649
+ # The user you passed to MCP::Server.new(server_context: { user: current_user }):
650
+ config.principal_resolver = ->(context) { context.request[:server_context]&.dig(:user) }
651
+ # Or the subject of the token the SDK's OAuth middleware verified:
652
+ # config.principal_resolver = ->(context) { User.find_by(id: context.request[:auth_info]&.subject) }
653
+ end
654
+ ```
655
+
656
+ ```ruby
657
+ class InvoiceSearchTool < MCP::Tool
658
+ input_schema(properties: { query: { type: "string" } }, required: ["query"])
659
+ guard_with InvoicePolicy
660
+
661
+ def self.call(query:)
662
+ numbers = scoped(Invoice).where("number LIKE ?", "%#{query}%").pluck(:number)
663
+ MCP::Tool::Response.new([{ type: "text", text: numbers.join("\n") }])
664
+ end
665
+ end
666
+ ```
667
+
668
+ **`guard_with` plus `scoped`.** An SDK tool returns a finished response, not records, so
669
+ Reeve cannot narrow it per record as it narrows a fast-mcp tool's return value. It allows or
670
+ refuses the whole response: allowed only if the tool read through `scoped(...)` during the
671
+ call, otherwise refused `unscoped_derived_result`. `authorize!` checks a single record before
672
+ the tool uses it.
673
+
674
+ That check is one flag per call. A tool that calls `scoped(Invoice)` and also renders
675
+ `Invoice.find(id)` passes: Reeve proves the tool asked for scoped data, not that every value
676
+ it rendered came from it. Fetch any other record through `authorize!`.
677
+
678
+ **Block tools are tools.** `server.define_tool` builds a tool class like any other, so an
679
+ unguarded block tool is refused `no_guard_declared`. Guard it on the class the server holds:
680
+
681
+ ```ruby
682
+ server.define_tool(name: "list_invoices") do |server_context:|
683
+ MCP::Tool::Response.new([{ type: "text", text: scoped(Invoice).pluck(:number).join("\n") }])
684
+ end
685
+ server.tools["list_invoices"].guard_with InvoicePolicy
686
+ ```
687
+
688
+ Each block is a new class, and Reeve keeps every tool class it sees. If you build a server
689
+ per request, define block tools once at boot with `MCP::Tool.define`, guard them there, and
690
+ pass them in `tools:`.
691
+
692
+ **What the client receives.** Allowed: the tool's own response. Denied: a tool error
693
+ (`isError: true`) whose text names the tool, the principal and the rule, never a record; a
694
+ resolver that returns nil is a denial, `no_principal`. A tool that raises: the SDK's usual
695
+ internal error. Every one of these writes exactly one ledger row.
696
+
697
+ **Request data is not recorded.** The resolver reads `context.request`: the SDK's
698
+ `server_context` and `auth_info`. They can hold a user object or a token, so neither is
699
+ written to the ledger; the row records only the client's name and version. If you dispatch
700
+ through `Reeve.invoke` yourself, pass the same kind of thing as `request:`, and only what
701
+ you would want in an audit as `metadata:`.
702
+
703
+ **Before deploying.** Requiring `reeve/mcp` under `:deny` refuses every SDK tool without
704
+ `guard_with`, block tools included, on its next call. While adopting, set
705
+ `config.unguarded_tools = :allow_with_warning`: unguarded tools run, unscoped, and each call
706
+ logs a warning to `config.logger` and is recorded with `guard: "none"`. The matchers and the
707
+ compliance suite take SDK tool classes as they are; no custom invoker is needed.
708
+
709
+ Supported: `mcp` 1.x (verified on 1.0.0 and 1.9.0), Ruby 3.0+, with or without Rails.
710
+ fast-mcp and the SDK cannot share a process: fast-mcp ships files at the paths the SDK loads
711
+ its classes from, and `reeve/mcp` raises `Reeve::ConfigurationError` if fast-mcp got there
712
+ first.
713
+
714
+ ## On ActionMCP
715
+
716
+ ```ruby
717
+ # config/initializers/reeve.rb
718
+ require "reeve/action_mcp"
719
+
720
+ Reeve.configure do |config|
721
+ # The user ActionMCP's gateway authenticated for this request:
722
+ config.principal_resolver = ->(_context) { ActionMCP::Current.user }
723
+ end
724
+ ```
725
+
726
+ ```ruby
727
+ class InvoiceSearchTool < ApplicationMCPTool
728
+ property :query, type: "string", required: true
729
+ guard_with InvoicePolicy
730
+
731
+ def perform
732
+ scoped(Invoice).where("number LIKE ?", "%#{query}%").each do |invoice|
733
+ render(text: invoice.number)
734
+ end
735
+ end
736
+ end
737
+ ```
738
+
739
+ The same rule as on the SDK: **`guard_with` plus `scoped`**. A tool renders as it goes, so
740
+ Reeve holds what it renders and releases it only if the call is allowed; a tool that read
741
+ nothing through `scoped(...)` is refused `unscoped_derived_result` and nothing it rendered
742
+ reaches the client. The check is one flag per call, with the same consequence as on the SDK:
743
+ fetch any record you did not get from `scoped` through `authorize!`.
744
+
745
+ **What the client receives.** Allowed: what the tool rendered. Denied: a tool error naming
746
+ the tool, the principal and the rule, never a record; no user is a denial, `no_principal`.
747
+ A tool that raises: ActionMCP's own error, unchanged. Each writes exactly one ledger row. A
748
+ call that `request_input!` interrupts is recorded `tool_error` and releases nothing.
749
+
750
+ **Calls that write no row.** A `before_perform` callback of yours that halts, or input
751
+ ActionMCP's schema refuses, stops the call before the tool runs, so there is nothing to
752
+ guard or record. The client gets ActionMCP's usual error for each.
753
+
754
+ **Background tasks have no user.** A task-augmented call runs in ActionMCP's
755
+ `ToolExecutionJob`, which does not set `ActionMCP::Current.user`. With the resolver above it
756
+ is refused `no_principal` and recorded. If your sessions carry the user, resolve it from
757
+ `context.request[:session]`. The session is request data: it reaches the resolver and is
758
+ never recorded; the row records only the client's name and version.
759
+
760
+ `ApplicationMCPTool` and any other class that calls `abstract!` is a base, not a tool: the
761
+ compliance suite does not ask whether it is guarded. Requiring `reeve/action_mcp` under
762
+ `:deny` refuses every unguarded ActionMCP tool, as on the SDK.
763
+
764
+ Supported: `actionmcp` 0.200 to 0.203 (verified on 0.200.0 and 0.203.0), which needs Rails
765
+ 8.1 and Ruby 3.2+. The adapter reaches into ActionMCP's internals, so it refuses to load on a
766
+ version it was not verified against; each new ActionMCP minor needs a Reeve release.
767
+
642
768
  ## Without Rails, or without fast-mcp
643
769
 
644
770
  The core needs neither. `Reeve.invoke` is the same envelope with the same guarantees:
@@ -839,7 +965,8 @@ out of scope, and the ledger's chain detects tampering rather than preventing it
839
965
  touched*. Keep your existing auth.
840
966
 
841
967
  Ruby 3.0+, Rails 7.0+. No runtime dependencies. The fast-mcp adapter needs Ruby 3.1+,
842
- because fast-mcp does.
968
+ because fast-mcp does. The official SDK adapter needs `mcp` 1.x and runs on Ruby 3.0+. The
969
+ ActionMCP adapter needs `actionmcp` 0.200 to 0.203, Rails 8.1 and Ruby 3.2+.
843
970
 
844
971
  ## Who built this
845
972
 
@@ -0,0 +1,22 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "integrations"
4
+
5
+ begin
6
+ require "action_mcp"
7
+ rescue LoadError => e
8
+ raise Reeve::ConfigurationError,
9
+ "reeve/action_mcp needs the actionmcp gem, which could not be loaded (#{e.message}). " \
10
+ "Add actionmcp to your Gemfile, or use Reeve.invoke directly: the core needs no MCP " \
11
+ "server library."
12
+ end
13
+
14
+ # The adapter reaches into ActionMCP's internals, so it loads only on the versions it was
15
+ # verified against (FR-013).
16
+ Reeve::Integrations.require_version!("reeve/action_mcp", "actionmcp", ActionMCP::VERSION,
17
+ ">= 0.200.0", "< 0.204")
18
+
19
+ require_relative "integrations/action_mcp/context_builder"
20
+ require_relative "integrations/action_mcp/tool_extension"
21
+
22
+ Reeve::Integrations::ActionMcp.install!
@@ -103,48 +103,56 @@ module Reeve
103
103
  end
104
104
  end
105
105
 
106
- # The scoped relation for the invoking principal. This is how a guarded tool returns
107
- # anything that is not a record: a count, a sum, a rendered summary. Computing from
108
- # `scoped(...)` means the tool never held unscoped data, so the derived value is safe
109
- # by construction rather than by promise (R4).
110
- def scoped(model_or_relation)
111
- state = Authorization::Current.state
112
- raise Error, "scoped(...) may only be called inside a guarded invocation" if state.nil?
113
-
114
- Authorization::Scoper.scoped_relation(state, model_or_relation)
115
- end
106
+ # `scoped` and `authorize!`, the two helpers a tool body calls. They read only the
107
+ # invocation in progress on this thread, never the receiver, so the same methods serve
108
+ # a tool whose body runs on an instance (fast-mcp, ActionMCP) and one whose body runs
109
+ # on the class (the official SDK, which extends a tool class with this module).
110
+ module Helpers
111
+ # The scoped relation for the invoking principal. This is how a guarded tool returns
112
+ # anything that is not a record: a count, a sum, a rendered summary. Computing from
113
+ # `scoped(...)` means the tool never held unscoped data, so the derived value is safe
114
+ # by construction rather than by promise (R4).
115
+ def scoped(model_or_relation)
116
+ state = Authorization::Current.state
117
+ raise Error, "scoped(...) may only be called inside a guarded invocation" if state.nil?
118
+
119
+ Authorization::Scoper.scoped_relation(state, model_or_relation)
120
+ end
121
+
122
+ # Asks the declared policy about one record, before the tool acts on it. Returns the
123
+ # record so it reads inline; raises +DeniedError+ if the policy says no.
124
+ #
125
+ # def call(id:, to:)
126
+ # invoice = authorize!(Invoice.find(id))
127
+ # InvoiceMailer.reminder(invoice, to).deliver_now
128
+ # invoice
129
+ # end
130
+ #
131
+ # The envelope authorizes before the tool runs and scopes what it returns, and between
132
+ # those two points a tool can do things neither of them can reach. A rolled-back write
133
+ # leaves no trace; a sent email does. `scoped(...)` is the answer when a tool can work
134
+ # from a relation; this is the answer when it cannot — when the tool holds one record
135
+ # and is about to do something to the world with it.
136
+ #
137
+ # The denial carries the policy's own rule, so the ledger names what refused rather
138
+ # than reporting the tool as broken. It names no record: an out-of-scope record and a
139
+ # record that does not exist have to be indistinguishable (FR-006), and a tool that
140
+ # reached this line has already fetched the record it must not talk about.
141
+ def authorize!(record)
142
+ state = Authorization::Current.state
143
+ raise Error, "authorize!(...) may only be called inside a guarded invocation" if state.nil?
144
+
145
+ decision = state.adapter.authorize(
146
+ principal: state.context.principal, policy: state.declaration.policy,
147
+ action: state.declaration.action, record: record
148
+ )
149
+ return record if decision.allowed?
116
150
 
117
- # Asks the declared policy about one record, before the tool acts on it. Returns the
118
- # record so it reads inline; raises +DeniedError+ if the policy says no.
119
- #
120
- # def call(id:, to:)
121
- # invoice = authorize!(Invoice.find(id))
122
- # InvoiceMailer.reminder(invoice, to).deliver_now
123
- # invoice
124
- # end
125
- #
126
- # The envelope authorizes before the tool runs and scopes what it returns, and between
127
- # those two points a tool can do things neither of them can reach. A rolled-back write
128
- # leaves no trace; a sent email does. `scoped(...)` is the answer when a tool can work
129
- # from a relation; this is the answer when it cannot — when the tool holds one record
130
- # and is about to do something to the world with it.
131
- #
132
- # The denial carries the policy's own rule, so the ledger names what refused rather
133
- # than reporting the tool as broken. It names no record: an out-of-scope record and a
134
- # record that does not exist have to be indistinguishable (FR-006), and a tool that
135
- # reached this line has already fetched the record it must not talk about.
136
- def authorize!(record)
137
- state = Authorization::Current.state
138
- raise Error, "authorize!(...) may only be called inside a guarded invocation" if state.nil?
139
-
140
- decision = state.adapter.authorize(
141
- principal: state.context.principal, policy: state.declaration.policy,
142
- action: state.declaration.action, record: record
143
- )
144
- return record if decision.allowed?
145
-
146
- raise DeniedError.from(decision, tool_name: state.context.tool_name,
147
- principal_id: state.context.principal_id)
151
+ raise DeniedError.from(decision, tool_name: state.context.tool_name,
152
+ principal_id: state.context.principal_id)
153
+ end
148
154
  end
155
+
156
+ include Helpers
149
157
  end
150
158
  end
@@ -25,12 +25,18 @@ module Reeve
25
25
  #
26
26
  # Reeve.invoke(tool: InvoiceSearchTool, arguments: { query: "AC" },
27
27
  # principal: current_user, agent: { id: "claude-desktop" })
28
- def invoke(tool:, arguments: {}, principal: :unset, agent: nil, metadata: {}, &body)
28
+ #
29
+ # +metadata+ is recorded. +request+ is not: it is what the principal resolver needs to
30
+ # identify the human (a server context, a verified token, a session) and it is cleared
31
+ # when the call ends.
32
+ def invoke(tool:, arguments: {}, principal: :unset, agent: nil, metadata: {}, request: {},
33
+ &body)
29
34
  context = Context.new(
30
35
  tool_name: tool_name_for(tool),
31
36
  agent: agent,
32
37
  arguments: arguments,
33
- metadata: metadata
38
+ metadata: metadata,
39
+ request: request
34
40
  )
35
41
 
36
42
  declaration = registry.guard_for(context.tool_name)
@@ -49,7 +55,11 @@ module Reeve
49
55
 
50
56
  private
51
57
 
58
+ # A tool class whose library runs it some other way (a class-level `call`, a
59
+ # `perform` behind callbacks) says how through `reeve_run`, which the adapters define.
52
60
  def run(tool, arguments)
61
+ return tool.reeve_run(arguments) if tool.respond_to?(:reeve_run)
62
+
53
63
  instance = tool.is_a?(Class) ? tool.new : tool
54
64
  arguments.empty? ? instance.call : instance.call(**arguments)
55
65
  end
data/lib/reeve/context.rb CHANGED
@@ -12,16 +12,18 @@ module Reeve
12
12
  class Context
13
13
  UNKNOWN_AGENT_ID = "unknown"
14
14
 
15
- attr_reader :invocation_id, :tool_name, :arguments, :metadata, :agent, :invoked_at
15
+ attr_reader :invocation_id, :tool_name, :arguments, :metadata, :agent, :invoked_at,
16
+ :request
16
17
  attr_accessor :principal
17
18
 
18
19
  def initialize(tool_name:, principal: nil, agent: nil, arguments: nil, metadata: nil,
19
- invoked_at: nil, invocation_id: nil)
20
+ request: nil, invoked_at: nil, invocation_id: nil)
20
21
  @tool_name = validate_tool_name(tool_name)
21
22
  @principal = principal
22
23
  @agent = build_agent(agent)
23
24
  @arguments = symbolize(:arguments, arguments)
24
25
  @metadata = symbolize(:metadata, metadata)
26
+ @request = symbolize(:request, request).freeze
25
27
  @invoked_at = invoked_at || Time.now
26
28
  @invocation_id = (invocation_id || SecureRandom.uuid).to_s
27
29
  end
@@ -36,6 +38,13 @@ module Reeve
36
38
  @principal = nil
37
39
  end
38
40
 
41
+ # Request data is for the principal resolver only: the transport's server context,
42
+ # a verified access token, a session. It can hold a user object or a credential, so
43
+ # it is never part of +to_h+ or +inspect+, and it goes when the principal goes.
44
+ def clear_request!
45
+ @request = {}.freeze
46
+ end
47
+
39
48
  def principal_type
40
49
  principal&.class&.name
41
50
  end
@@ -1,6 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
- require_relative "../reeve"
3
+ require_relative "integrations"
4
4
 
5
5
  begin
6
6
  require "fast_mcp"
@@ -14,11 +14,4 @@ end
14
14
  require_relative "integrations/fast_mcp/context_builder"
15
15
  require_relative "integrations/fast_mcp/tool_extension"
16
16
 
17
- module Reeve
18
- # Adapters for the MCP server libraries reeve rides on. Each is opt-in, conditionally
19
- # loaded, and never a dependency of the core (Constitution IV).
20
- module Integrations
21
- end
22
- end
23
-
24
17
  Reeve::Integrations::FastMcp.install!
@@ -0,0 +1,42 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Reeve
4
+ module Integrations
5
+ # The ActionMCP bridge.
6
+ module ActionMcp
7
+ # Turns what an ActionMCP tool knows about its call into what a Reeve::Context is
8
+ # built from.
9
+ #
10
+ # The session and the execution context go to the resolver as request data, which is
11
+ # never recorded. Only the client's own name and version are recorded, for
12
+ # attribution. Not the session id: on some transports it is enough to resume a
13
+ # session, and the ledger is append-only (research R6, R7).
14
+ module ContextBuilder
15
+ module_function
16
+
17
+ def attributes(tool)
18
+ client = client_for(tool.session)
19
+
20
+ {
21
+ arguments: tool.attributes,
22
+ agent: { id: client[:name] || Context::UNKNOWN_AGENT_ID,
23
+ name: client.empty? ? nil : client.values.join(" ") },
24
+ metadata: client.empty? ? {} : { client: client },
25
+ request: { session: tool.session, execution_context: tool.execution_context }
26
+ }
27
+ end
28
+
29
+ def client_for(session)
30
+ info = session.respond_to?(:client_info) ? session.client_info : nil
31
+ return {} unless info.is_a?(Hash)
32
+
33
+ name = info[:name] || info["name"]
34
+ version = info[:version] || info["version"]
35
+ return {} if name.nil? || name.to_s.strip.empty?
36
+
37
+ { name: name.to_s, version: version&.to_s }.compact
38
+ end
39
+ end
40
+ end
41
+ end
42
+ end
@@ -0,0 +1,94 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Reeve
4
+ module Integrations
5
+ # The ActionMCP bridge.
6
+ module ActionMcp
7
+ # Routes every ActionMCP tool call through the envelope.
8
+ #
9
+ # ActionMCP's `call` rescues every error a tool raises and turns it into a generic
10
+ # message, so the envelope sits inside it, around `perform`: a tool error or a denial
11
+ # reaches the ledger before ActionMCP replaces it (FR-030). Whatever the tool renders
12
+ # goes to a buffer, released to the real response only if the call is allowed
13
+ # (FR-031). This reaches into ActionMCP's internals (`@response`, the protected
14
+ # `perform`), which is why the adapter refuses versions it was not verified against.
15
+ module ToolExtension
16
+ # How the testing kit runs this tool: through ActionMCP's callbacks, with no rescue,
17
+ # so a denial or an error reaches the kit's envelope.
18
+ def reeve_perform
19
+ @response = ::ActionMCP::ToolResponse.new
20
+ run_callbacks(:perform) { perform }
21
+ @response
22
+ end
23
+
24
+ protected
25
+
26
+ def perform
27
+ return super if Integrations.inside?(self.class)
28
+
29
+ real = @response
30
+ @response = ::ActionMCP::ToolResponse.new
31
+ begin
32
+ buffer = Reeve.invoke(tool: self.class, **ContextBuilder.attributes(self)) do
33
+ super
34
+ @response
35
+ end
36
+ ActionMcp.release(buffer, into: real)
37
+ rescue DeniedError => e
38
+ real.report_tool_error(e.message)
39
+ ensure
40
+ @response = real
41
+ end
42
+ end
43
+ end
44
+
45
+ # Installs the extension into every tool defined from here on, and keeps ActionMCP's
46
+ # abstract bases out of the compliance suite.
47
+ module Inheritance
48
+ def self.wrap(klass)
49
+ klass.prepend(ToolExtension) unless Integrations.prepended?(klass, ToolExtension)
50
+ end
51
+
52
+ def inherited(subclass)
53
+ super
54
+ Inheritance.wrap(subclass)
55
+ end
56
+
57
+ # `ApplicationMCPTool` and its kind call `abstract!`: a base, not a tool (R12).
58
+ def abstract!
59
+ super
60
+ reeve_abstract!
61
+ end
62
+
63
+ def reeve_run(arguments)
64
+ tool = from_wire(arguments.deep_stringify_keys)
65
+ unless tool.valid?
66
+ raise ArgumentError,
67
+ "#{tool_name}: invalid input: #{tool.errors.full_messages.join(', ')}"
68
+ end
69
+
70
+ tool.reeve_perform
71
+ end
72
+ end
73
+
74
+ module_function
75
+
76
+ def install!(tool_base = ::ActionMCP::Tool)
77
+ Integrations.install!(tool_base, Inheritance)
78
+ Integrations.descendants(tool_base).each do |klass|
79
+ klass.reeve_abstract! if klass.abstract?
80
+ end
81
+ tool_base
82
+ end
83
+
84
+ # The allowed call's content, structured content and any error the tool reported on
85
+ # itself, moved from the buffer to the response ActionMCP returns.
86
+ def release(buffer, into:)
87
+ buffer.contents.each { |content| into.add(content) }
88
+ into.set_structured_content(buffer.structured_content) unless buffer.structured_content.nil?
89
+ into.instance_variable_set(:@tool_execution_error, true) if buffer.tool_execution_error
90
+ into
91
+ end
92
+ end
93
+ end
94
+ end
@@ -13,6 +13,10 @@ module Reeve
13
13
  # impossible to forget — there is no "remember to wrap your tool" step.
14
14
  module ToolExtension
15
15
  def call(**arguments)
16
+ # Already inside this tool's envelope (the testing kit, or a host that wrapped
17
+ # Reeve.invoke around the call): run the body there, so it is recorded once.
18
+ return super if Integrations.inside?(self.class)
19
+
16
20
  attributes = ContextBuilder.attributes(self)
17
21
 
18
22
  Reeve.invoke(
@@ -26,9 +30,13 @@ module Reeve
26
30
 
27
31
  # Installs the extension into every tool defined from here on.
28
32
  module Inheritance
33
+ def self.wrap(klass)
34
+ klass.prepend(ToolExtension) unless Integrations.prepended?(klass, ToolExtension)
35
+ end
36
+
29
37
  def inherited(subclass)
30
38
  super
31
- subclass.prepend(ToolExtension)
39
+ Inheritance.wrap(subclass)
32
40
  end
33
41
  end
34
42
 
@@ -37,22 +45,7 @@ module Reeve
37
45
  # Idempotent: requiring "reeve/fast_mcp" twice must not stack two envelopes around
38
46
  # the same call.
39
47
  def install!(tool_base = ::FastMcp::Tool)
40
- unless tool_base.include?(Reeve::Guard)
41
- tool_base.include(Reeve::Guard)
42
- # FastMcp::Tool carries the DSL for its subclasses; it is not itself a tool.
43
- tool_base.reeve_abstract!
44
- end
45
-
46
- unless tool_base.singleton_class.include?(Inheritance)
47
- tool_base.singleton_class.prepend(Inheritance)
48
- end
49
-
50
- # Tools defined before this require still get the envelope.
51
- tool_base.subclasses.each do |subclass|
52
- subclass.prepend(ToolExtension) unless subclass.include?(ToolExtension)
53
- end
54
-
55
- tool_base
48
+ Integrations.install!(tool_base, Inheritance)
56
49
  end
57
50
  end
58
51
  end
@@ -0,0 +1,46 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Reeve
4
+ module Integrations
5
+ # The official MCP SDK bridge.
6
+ module Mcp
7
+ # Turns the SDK's server context into what a Reeve::Context is built from.
8
+ #
9
+ # The server context is whatever the host passed to `MCP::Server.new`, often the user
10
+ # object, plus the verified access token. It goes to the resolver as request data,
11
+ # which is never recorded. Only the client's own name and version are recorded, for
12
+ # attribution (research R6, R7).
13
+ module ContextBuilder
14
+ module_function
15
+
16
+ def attributes(server_context)
17
+ client = client_for(server_context)
18
+
19
+ {
20
+ agent: { id: client[:name] || Context::UNKNOWN_AGENT_ID,
21
+ name: client.empty? ? nil : client.values.join(" ") },
22
+ metadata: client.empty? ? {} : { client: client },
23
+ request: { server_context: server_context, auth_info: auth_info_for(server_context) }
24
+ }
25
+ end
26
+
27
+ def client_for(server_context)
28
+ info = server_context.respond_to?(:client_info) ? server_context.client_info : nil
29
+ return {} unless info.is_a?(Hash)
30
+
31
+ name = info[:name] || info["name"]
32
+ version = info[:version] || info["version"]
33
+ return {} if name.nil? || name.to_s.strip.empty?
34
+
35
+ { name: name.to_s, version: version&.to_s }.compact
36
+ end
37
+
38
+ def auth_info_for(server_context)
39
+ return server_context.auth_info if server_context.respond_to?(:auth_info)
40
+
41
+ server_context[:auth_info] if server_context.is_a?(Hash)
42
+ end
43
+ end
44
+ end
45
+ end
46
+ end
@@ -0,0 +1,84 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Reeve
4
+ module Integrations
5
+ # The official MCP SDK bridge.
6
+ module Mcp
7
+ # Routes every SDK tool call through the envelope.
8
+ #
9
+ # The SDK calls a tool's class method, `tool.call(**arguments, server_context:)`, so
10
+ # this is prepended to each tool's singleton class. That includes tools registered
11
+ # as blocks: the SDK builds a class for each one (research R1 to R3).
12
+ module ToolExtension
13
+ def call(*args, **kwargs, &block)
14
+ forwarded = reeve_forwardable(kwargs)
15
+ return super(*args, **forwarded, &block) if Integrations.inside?(self)
16
+
17
+ reeve_guarded(kwargs) { super(*args, **forwarded, &block) }
18
+ end
19
+
20
+ # How the testing kit runs this tool: as the server would, with no server context.
21
+ # Inside the kit's envelope, so a denial raises instead of becoming a response.
22
+ def reeve_run(arguments)
23
+ return call(**arguments) unless reeve_takes_server_context?
24
+
25
+ call(**arguments, server_context: nil)
26
+ end
27
+
28
+ private
29
+
30
+ def reeve_guarded(kwargs, &body)
31
+ Reeve.invoke(
32
+ tool: self,
33
+ arguments: kwargs.except(:server_context),
34
+ **ContextBuilder.attributes(kwargs[:server_context]),
35
+ &body
36
+ )
37
+ rescue DeniedError => e
38
+ # A denial is a tool error in the SDK's own shape, carrying the rule and never a
39
+ # record (FR-007). Anything else propagates, so the SDK reports it as it would
40
+ # without reeve.
41
+ ::MCP::Tool::Response.new([{ type: "text", text: e.message }], error: true)
42
+ end
43
+
44
+ # The SDK passes `server_context:` to any `call` that takes a `**` parameter, which
45
+ # this one does. The tool still gets exactly what it got before (FR-020): the
46
+ # keyword goes on only if the tool's own `call` would have received it.
47
+ def reeve_forwardable(kwargs)
48
+ return kwargs if reeve_takes_server_context? || !kwargs.key?(:server_context)
49
+
50
+ kwargs.except(:server_context)
51
+ end
52
+
53
+ # The SDK's own rule, applied to the method this one wraps.
54
+ def reeve_takes_server_context?
55
+ method(:call).super_method.parameters.any? do |type, name|
56
+ type == :keyrest || (name == :server_context && %i[key keyreq].include?(type))
57
+ end
58
+ end
59
+ end
60
+
61
+ # Installs the extension into every tool defined from here on, and gives tools the
62
+ # class-level `scoped` and `authorize!` their body needs.
63
+ module Inheritance
64
+ def self.wrap(klass)
65
+ return if Integrations.prepended?(klass.singleton_class, ToolExtension)
66
+
67
+ klass.singleton_class.prepend(ToolExtension)
68
+ end
69
+
70
+ def inherited(subclass)
71
+ super
72
+ Inheritance.wrap(subclass)
73
+ end
74
+ end
75
+
76
+ module_function
77
+
78
+ def install!(tool_base = ::MCP::Tool)
79
+ tool_base.extend(Reeve::Guard::Helpers)
80
+ Integrations.install!(tool_base, Inheritance)
81
+ end
82
+ end
83
+ end
84
+ end
@@ -0,0 +1,67 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "../reeve"
4
+
5
+ module Reeve
6
+ # Adapters for the MCP server libraries reeve rides on. Each is opt-in, conditionally
7
+ # loaded, and never a dependency of the core (Constitution IV). What they share lives
8
+ # here: the install, the version gate, and the check that stops a call being recorded
9
+ # twice.
10
+ module Integrations
11
+ module_function
12
+
13
+ # Gives +base+ the DSL and routes every subclass through +inheritance+: the ones
14
+ # defined from here on through its `inherited` hook, the ones already defined through
15
+ # `inheritance.wrap`. Idempotent, so requiring an adapter twice cannot stack two
16
+ # envelopes around one call (FR-004).
17
+ def install!(base, inheritance)
18
+ unless base.include?(Reeve::Guard)
19
+ base.include(Reeve::Guard)
20
+ # The library's base class carries the DSL for its subclasses; it is not a tool.
21
+ base.reeve_abstract!
22
+ end
23
+
24
+ base.singleton_class.prepend(inheritance) unless base.singleton_class.include?(inheritance)
25
+ descendants(base).each { |klass| inheritance.wrap(klass) }
26
+ base
27
+ end
28
+
29
+ # True while an envelope for +tool+ is open on this thread. The testing kit and a host
30
+ # that wraps `Reeve.invoke` around a library call both open one before the library
31
+ # runs the tool; the adapter then runs the body inside it instead of opening a second,
32
+ # so a call is recorded once (FR-051).
33
+ def inside?(tool)
34
+ state = Authorization::Current.state
35
+ !state.nil? && state.context.tool_name == Reeve.__send__(:tool_name_for, tool)
36
+ end
37
+
38
+ # An adapter that reaches into a library's internals is verified against a range of
39
+ # its versions. Outside that range it refuses to load rather than guard by guesswork
40
+ # (FR-013).
41
+ def require_version!(adapter, gem_name, version, *requirements)
42
+ requirement = Gem::Requirement.new(*requirements)
43
+ return if requirement.satisfied_by?(Gem::Version.new(version))
44
+
45
+ raise ConfigurationError,
46
+ "#{adapter} supports #{gem_name} #{requirement}, but #{gem_name} #{version} is " \
47
+ "loaded. Use a supported version, or a reeve release that supports this one."
48
+ end
49
+
50
+ # Whether +mod+ is prepended to +klass+ itself. Not `include?`: that also answers true
51
+ # for a module prepended to a superclass, and a subclass that defines its own `call`
52
+ # would then run ahead of the wrapper instead of behind it.
53
+ def prepended?(klass, mod)
54
+ klass.ancestors.take_while { |ancestor| !ancestor.equal?(klass) }.include?(mod)
55
+ end
56
+
57
+ # Every subclass at any depth. `Class#subclasses` arrived in Ruby 3.1 (ActiveSupport
58
+ # adds it earlier); without it, ObjectSpace finds them.
59
+ def descendants(base)
60
+ if base.respond_to?(:subclasses)
61
+ base.subclasses.flat_map { |klass| [klass, *descendants(klass)] }
62
+ else
63
+ ObjectSpace.each_object(base.singleton_class).reject { |klass| klass.equal?(base) }
64
+ end
65
+ end
66
+ end
67
+ end
@@ -80,12 +80,13 @@ module Reeve
80
80
  #
81
81
  # +registered+ is not consulted. The host's own dispatcher already decided the name
82
82
  # exists; what this decides is whether reeve stands in front of it.
83
- def dispatch(name, arguments: {}, principal: :unset, agent: nil, metadata: {}, &handler)
83
+ def dispatch(name, arguments: {}, principal: :unset, agent: nil, metadata: {}, request: {},
84
+ &handler)
84
85
  name = name.to_s
85
86
  tool = routes[name]
86
87
  if tool
87
88
  return Reeve.invoke(tool: tool, arguments: arguments, principal: principal,
88
- agent: agent, metadata: metadata, &handler)
89
+ agent: agent, metadata: metadata, request: request, &handler)
89
90
  end
90
91
 
91
92
  if handler.nil?
@@ -96,7 +97,7 @@ module Reeve
96
97
  return handler.call if exemption_reasons.key?(name)
97
98
 
98
99
  dispatch_unbound(name, arguments: arguments, principal: principal, agent: agent,
99
- metadata: metadata, &handler)
100
+ metadata: metadata, request: request, &handler)
100
101
  end
101
102
 
102
103
  def inspect
@@ -179,10 +180,10 @@ module Reeve
179
180
  # own name and with nothing to look up. The registry answer below is what makes the
180
181
  # refusal name the real cause — the inventory, not a missing `guard_with` on a class
181
182
  # that may not exist.
182
- def dispatch_unbound(name, arguments:, principal:, agent:, metadata:, &handler)
183
+ def dispatch_unbound(name, arguments:, principal:, agent:, metadata:, request:, &handler)
183
184
  config = Reeve.config.with_principal(principal)
184
185
  context = Context.new(tool_name: name, agent: agent, arguments: arguments,
185
- metadata: metadata)
186
+ metadata: metadata, request: request)
186
187
 
187
188
  Invocation.call(context, registry: Unbound.new(name, config), config: config, &handler)
188
189
  end
@@ -74,6 +74,7 @@ module Reeve
74
74
  @duration_ms = ((monotonic_now - started) * 1000).round
75
75
  write_entry
76
76
  context.clear_principal!
77
+ context.clear_request!
77
78
  end
78
79
 
79
80
  private
data/lib/reeve/mcp.rb ADDED
@@ -0,0 +1,29 @@
1
+ # frozen_string_literal: true
2
+
3
+ require_relative "integrations"
4
+
5
+ begin
6
+ require "mcp"
7
+ rescue LoadError => e
8
+ raise Reeve::ConfigurationError,
9
+ "reeve/mcp needs the mcp gem, which could not be loaded (#{e.message}). Add mcp to " \
10
+ "your Gemfile, or use Reeve.invoke directly: the core needs no MCP server library."
11
+ end
12
+
13
+ Reeve::Integrations.require_version!("reeve/mcp", "mcp", MCP::VERSION, ">= 1.0", "< 2.0")
14
+
15
+ # fast-mcp ships lib/mcp/tool.rb at the path the SDK autoloads MCP::Tool from. If fast-mcp
16
+ # loaded first, Ruby considers that path loaded and MCP::Tool never appears.
17
+ begin
18
+ MCP::Tool::Response
19
+ rescue NameError
20
+ raise Reeve::ConfigurationError,
21
+ "reeve/mcp could not load MCP::Tool from the mcp gem. fast-mcp ships files at the " \
22
+ "paths the official SDK autoloads (mcp/tool.rb, mcp/server.rb), so loading fast-mcp " \
23
+ "first hides the SDK's classes. Run one MCP server library per process."
24
+ end
25
+
26
+ require_relative "integrations/mcp/context_builder"
27
+ require_relative "integrations/mcp/tool_extension"
28
+
29
+ Reeve::Integrations::Mcp.install!
@@ -86,12 +86,8 @@ module Reeve
86
86
  ledger: :unavailable)
87
87
  end
88
88
 
89
- # The name a developer will recognise in a failure: the constant, not the
90
- # snake_cased protocol name the ledger stores.
91
89
  def tool_label
92
- return "the ledger" if tool.nil?
93
-
94
- tool.respond_to?(:name) && tool.name ? tool.name : tool.to_s
90
+ tool.nil? ? "the ledger" : Testing.label_for(tool)
95
91
  end
96
92
 
97
93
  def declaration
data/lib/reeve/testing.rb CHANGED
@@ -21,6 +21,16 @@ module Reeve
21
21
  # abort report.to_s if report.failed? || report.nothing_checked?
22
22
  module Testing
23
23
  class << self
24
+ # The name a developer will recognise in a failure: the constant, not the
25
+ # snake_cased protocol name the ledger stores. A tool registered as a block has no
26
+ # constant, so its published name is the next best.
27
+ def label_for(tool)
28
+ return tool.name if tool.respond_to?(:name) && tool.name
29
+ return tool.tool_name.to_s if tool.respond_to?(:tool_name) && tool.tool_name
30
+
31
+ tool.to_s
32
+ end
33
+
24
34
  # The two fixture principals the compliance suite runs every tool against. Set once,
25
35
  # in the host's test helper, and both front-ends' compliance suites pick it up:
26
36
  #
data/lib/reeve/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Reeve
4
- VERSION = "0.9.0"
4
+ VERSION = "0.10.0"
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: reeve
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.9.0
4
+ version: 0.10.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Victor Velazquez
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-11-09 00:00:00.000000000 Z
11
+ date: 2026-11-11 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: |
14
14
  Reeve makes it safe for a Rails application to expose MCP (Model Context Protocol)
@@ -37,6 +37,7 @@ files:
37
37
  - lib/generators/reeve/upgrade/upgrade_generator.rb
38
38
  - lib/generators/reeve/upgrade/upgrade_notes.rb
39
39
  - lib/reeve.rb
40
+ - lib/reeve/action_mcp.rb
40
41
  - lib/reeve/audit.rb
41
42
  - lib/reeve/audit/chain.rb
42
43
  - lib/reeve/audit/chain/anchoring.rb
@@ -89,12 +90,18 @@ files:
89
90
  - lib/reeve/decision.rb
90
91
  - lib/reeve/errors.rb
91
92
  - lib/reeve/fast_mcp.rb
93
+ - lib/reeve/integrations.rb
94
+ - lib/reeve/integrations/action_mcp/context_builder.rb
95
+ - lib/reeve/integrations/action_mcp/tool_extension.rb
92
96
  - lib/reeve/integrations/fast_mcp/context_builder.rb
93
97
  - lib/reeve/integrations/fast_mcp/tool_extension.rb
98
+ - lib/reeve/integrations/mcp/context_builder.rb
99
+ - lib/reeve/integrations/mcp/tool_extension.rb
94
100
  - lib/reeve/inventory.rb
95
101
  - lib/reeve/inventory/report.rb
96
102
  - lib/reeve/invocation.rb
97
103
  - lib/reeve/ledger_key.rb
104
+ - lib/reeve/mcp.rb
98
105
  - lib/reeve/minitest.rb
99
106
  - lib/reeve/railtie.rb
100
107
  - lib/reeve/rspec.rb