Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,24 @@ jobs:
bundler-cache: true
- run: bundle exec rspec

# The adapters claim a range of each library's versions, and the matrix above installs
# only the newest. This proves the oldest: the SDK adapter uses the SDK's public tool
# interface from 1.0, and the ActionMCP adapter reaches into internals verified from
# 0.200.0. The Gemfile reads both pins.
adapter-floors:
name: "specs (adapter floors: mcp 1.0.0, actionmcp 0.200.0)"
runs-on: ubuntu-latest
env:
MCP_VERSION: "1.0.0"
ACTIONMCP_VERSION: "0.200.0"
steps:
- uses: actions/checkout@v4
- uses: ruby/setup-ruby@v1
with:
ruby-version: "3.4"
bundler-cache: true
- run: bundle exec rspec spec/reeve/integrations spec/reeve/testing/adapter_parity_spec.rb

# The gem claims to work on every database ActiveRecord supports — the ledger stores
# `invocation_id` as a string rather than a native uuid precisely so that holds. Until
# this job existed the claim had only ever been run against SQLite, while the three
Expand Down
58 changes: 58 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,64 @@ All notable changes are recorded here. This project follows [Semantic
Versioning](https://semver.org), with one rule specific to what it does — see
[Versioning policy](#versioning-policy).

## [Unreleased]

Reeve now rides the official MCP SDK (`require "reeve/mcp"`) and ActionMCP
(`require "reeve/action_mcp"`). No audit-entry contract change: it stays `4`.

### Upgrading from 0.9.0

`bundle update reeve`. Nothing changes unless you require the new adapter. If you do, read
the next paragraph first.

**Requiring `reeve/mcp` or `reeve/action_mcp` under the default `:deny` refuses every tool
of that library that has no `guard_with`, on its next call, including SDK tools registered
with `server.define_tool`.** That is deny-by-default working as documented. Set
`config.unguarded_tools = :allow_with_warning` while you add guards, then switch back.

### Added

- **Official MCP SDK adapter**, `require "reeve/mcp"`, for `mcp` 1.x (verified on 1.0.0 and
1.9.0), on Ruby 3.0+. Every SDK tool class, block tools included, goes through the
envelope. `guard_with`, `redact`, `scoped` and `authorize!` are class methods on every
tool. A denial reaches the client as a tool error naming the rule.
- **ActionMCP adapter**, `require "reeve/action_mcp"`, for `actionmcp` 0.200 to 0.203
(Rails 8.1, Ruby 3.2+). The envelope runs inside ActionMCP's error handling, so tool errors
and denials are recorded before ActionMCP replaces them, and what a tool renders is held
until the call is allowed. The principal is `ActionMCP::Current.user` through your
resolver; background-task calls have no user and are refused `no_principal` unless your
resolver finds one. The adapter reaches into ActionMCP's internals, so it refuses to load
on a version it was not verified against.
- **`guard_with` plus `scoped` on both.** These tools return a finished response or render
content, not records, so Reeve allows or refuses the output whole; it does not narrow it.
The output is allowed only if the tool read through `scoped(...)` during the call. That
check is one flag per call: a tool that calls `scoped(Invoice)` and also renders
`Invoice.find(id)` passes. Fetch any other record through `authorize!`.
- **`request:` on `Reeve.invoke` and `Inventory#dispatch`**, read by the principal resolver
as `context.request` and never recorded. For what identifies the human (a server context,
a verified token, a session) and must not land in the ledger. `metadata:` keeps its
meaning: recorded and redacted.
- The testing kit runs SDK and ActionMCP tool classes with no `invoke:`, one ledger row per
call. A tool class can say how it is run by defining `reeve_run(arguments)`; the adapters
do.

### Fixed

- The fast-mcp adapter opened a second envelope when the call was already inside one (the
testing kit's default invoker, or a host that wraps `Reeve.invoke` around a fast-mcp
call). The second one had no principal, so the call was refused and recorded twice. It now
runs inside the envelope that is already open.

### Known limitations

- fast-mcp and the official SDK cannot share a process. fast-mcp ships `lib/mcp/tool.rb`
and `lib/mcp/server.rb`, the paths the SDK loads `MCP::Tool` and `MCP::Server` from, so
loading fast-mcp first hides the SDK's classes. `reeve/mcp` refuses to load in that case
and says why.
- Every SDK block tool is a new class, and Reeve keeps every tool class it sees. A server
built per request that calls `define_tool` grows that list on every request; define block
tools once at boot with `MCP::Tool.define` and pass them in `tools:`.

## [0.9.0] - 2026-11-09

The compliance suite can now prove the ledger anchor works, with no test of your own. No
Expand Down
8 changes: 8 additions & 0 deletions Gemfile
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,14 @@ else
gem "sqlite3"
end

# The official MCP SDK runs on Ruby 2.7+, so it is installed on every Ruby in the matrix.
# MCP_VERSION pins it to the floor of the range reeve/mcp supports (the CI floor job).
gem "mcp", ENV.fetch("MCP_VERSION", ">= 1.0")

# ActionMCP needs Rails 8.1, which needs Ruby 3.2+, so it is absent below that, and its
# specs skip there. ACTIONMCP_VERSION pins it to the floor of reeve/action_mcp's range.
gem "actionmcp", ENV.fetch("ACTIONMCP_VERSION", ">= 0.200.0") if RUBY_VERSION >= "3.2"

# The other two engines the gem claims to support (spec/support/optional/database.rb).
# Installed only when asked for, because building either driver needs native client
# libraries and the default `bundle install` should not require them:
Expand Down
129 changes: 128 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -639,6 +639,132 @@ FAIL CrossPrincipalLeak
Invoice#9 (guard: InvoicePolicy, decision: allow via InvoicePolicy#index)
```

## On the official MCP SDK

```ruby
# config/initializers/reeve.rb
require "reeve/mcp"

Reeve.configure do |config|
# The user you passed to MCP::Server.new(server_context: { user: current_user }):
config.principal_resolver = ->(context) { context.request[:server_context]&.dig(:user) }
# Or the subject of the token the SDK's OAuth middleware verified:
# config.principal_resolver = ->(context) { User.find_by(id: context.request[:auth_info]&.subject) }
end
```

```ruby
class InvoiceSearchTool < MCP::Tool
input_schema(properties: { query: { type: "string" } }, required: ["query"])
guard_with InvoicePolicy

def self.call(query:)
numbers = scoped(Invoice).where("number LIKE ?", "%#{query}%").pluck(:number)
MCP::Tool::Response.new([{ type: "text", text: numbers.join("\n") }])
end
end
```

**`guard_with` plus `scoped`.** An SDK tool returns a finished response, not records, so
Reeve cannot narrow it per record as it narrows a fast-mcp tool's return value. It allows or
refuses the whole response: allowed only if the tool read through `scoped(...)` during the
call, otherwise refused `unscoped_derived_result`. `authorize!` checks a single record before
the tool uses it.

That check is one flag per call. A tool that calls `scoped(Invoice)` and also renders
`Invoice.find(id)` passes: Reeve proves the tool asked for scoped data, not that every value
it rendered came from it. Fetch any other record through `authorize!`.

**Block tools are tools.** `server.define_tool` builds a tool class like any other, so an
unguarded block tool is refused `no_guard_declared`. Guard it on the class the server holds:

```ruby
server.define_tool(name: "list_invoices") do |server_context:|
MCP::Tool::Response.new([{ type: "text", text: scoped(Invoice).pluck(:number).join("\n") }])
end
server.tools["list_invoices"].guard_with InvoicePolicy
```

Each block is a new class, and Reeve keeps every tool class it sees. If you build a server
per request, define block tools once at boot with `MCP::Tool.define`, guard them there, and
pass them in `tools:`.

**What the client receives.** Allowed: the tool's own response. Denied: a tool error
(`isError: true`) whose text names the tool, the principal and the rule, never a record; a
resolver that returns nil is a denial, `no_principal`. A tool that raises: the SDK's usual
internal error. Every one of these writes exactly one ledger row.

**Request data is not recorded.** The resolver reads `context.request`: the SDK's
`server_context` and `auth_info`. They can hold a user object or a token, so neither is
written to the ledger; the row records only the client's name and version. If you dispatch
through `Reeve.invoke` yourself, pass the same kind of thing as `request:`, and only what
you would want in an audit as `metadata:`.

**Before deploying.** Requiring `reeve/mcp` under `:deny` refuses every SDK tool without
`guard_with`, block tools included, on its next call. While adopting, set
`config.unguarded_tools = :allow_with_warning`: unguarded tools run, unscoped, and each call
logs a warning to `config.logger` and is recorded with `guard: "none"`. The matchers and the
compliance suite take SDK tool classes as they are; no custom invoker is needed.

Supported: `mcp` 1.x (verified on 1.0.0 and 1.9.0), Ruby 3.0+, with or without Rails.
fast-mcp and the SDK cannot share a process: fast-mcp ships files at the paths the SDK loads
its classes from, and `reeve/mcp` raises `Reeve::ConfigurationError` if fast-mcp got there
first.

## On ActionMCP

```ruby
# config/initializers/reeve.rb
require "reeve/action_mcp"

Reeve.configure do |config|
# The user ActionMCP's gateway authenticated for this request:
config.principal_resolver = ->(_context) { ActionMCP::Current.user }
end
```

```ruby
class InvoiceSearchTool < ApplicationMCPTool
property :query, type: "string", required: true
guard_with InvoicePolicy

def perform
scoped(Invoice).where("number LIKE ?", "%#{query}%").each do |invoice|
render(text: invoice.number)
end
end
end
```

The same rule as on the SDK: **`guard_with` plus `scoped`**. A tool renders as it goes, so
Reeve holds what it renders and releases it only if the call is allowed; a tool that read
nothing through `scoped(...)` is refused `unscoped_derived_result` and nothing it rendered
reaches the client. The check is one flag per call, with the same consequence as on the SDK:
fetch any record you did not get from `scoped` through `authorize!`.

**What the client receives.** Allowed: what the tool rendered. Denied: a tool error naming
the tool, the principal and the rule, never a record; no user is a denial, `no_principal`.
A tool that raises: ActionMCP's own error, unchanged. Each writes exactly one ledger row. A
call that `request_input!` interrupts is recorded `tool_error` and releases nothing.

**Calls that write no row.** A `before_perform` callback of yours that halts, or input
ActionMCP's schema refuses, stops the call before the tool runs, so there is nothing to
guard or record. The client gets ActionMCP's usual error for each.

**Background tasks have no user.** A task-augmented call runs in ActionMCP's
`ToolExecutionJob`, which does not set `ActionMCP::Current.user`. With the resolver above it
is refused `no_principal` and recorded. If your sessions carry the user, resolve it from
`context.request[:session]`. The session is request data: it reaches the resolver and is
never recorded; the row records only the client's name and version.

`ApplicationMCPTool` and any other class that calls `abstract!` is a base, not a tool: the
compliance suite does not ask whether it is guarded. Requiring `reeve/action_mcp` under
`:deny` refuses every unguarded ActionMCP tool, as on the SDK.

Supported: `actionmcp` 0.200 to 0.203 (verified on 0.200.0 and 0.203.0), which needs Rails
8.1 and Ruby 3.2+. The adapter reaches into ActionMCP's internals, so it refuses to load on a
version it was not verified against; each new ActionMCP minor needs a Reeve release.

## Without Rails, or without fast-mcp

The core needs neither. `Reeve.invoke` is the same envelope with the same guarantees:
Expand Down Expand Up @@ -839,7 +965,8 @@ out of scope, and the ledger's chain detects tampering rather than preventing it
touched*. Keep your existing auth.

Ruby 3.0+, Rails 7.0+. No runtime dependencies. The fast-mcp adapter needs Ruby 3.1+,
because fast-mcp does.
because fast-mcp does. The official SDK adapter needs `mcp` 1.x and runs on Ruby 3.0+. The
ActionMCP adapter needs `actionmcp` 0.200 to 0.203, Rails 8.1 and Ruby 3.2+.

## Who built this

Expand Down
22 changes: 22 additions & 0 deletions lib/reeve/action_mcp.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# frozen_string_literal: true

require_relative "integrations"

begin
require "action_mcp"
rescue LoadError => e
raise Reeve::ConfigurationError,
"reeve/action_mcp needs the actionmcp gem, which could not be loaded (#{e.message}). " \
"Add actionmcp to your Gemfile, or use Reeve.invoke directly: the core needs no MCP " \
"server library."
end

# The adapter reaches into ActionMCP's internals, so it loads only on the versions it was
# verified against (FR-013).
Reeve::Integrations.require_version!("reeve/action_mcp", "actionmcp", ActionMCP::VERSION,
">= 0.200.0", "< 0.204")

require_relative "integrations/action_mcp/context_builder"
require_relative "integrations/action_mcp/tool_extension"

Reeve::Integrations::ActionMcp.install!
14 changes: 12 additions & 2 deletions lib/reeve/authorization.rb
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,18 @@ class << self
#
# Reeve.invoke(tool: InvoiceSearchTool, arguments: { query: "AC" },
# principal: current_user, agent: { id: "claude-desktop" })
def invoke(tool:, arguments: {}, principal: :unset, agent: nil, metadata: {}, &body)
#
# +metadata+ is recorded. +request+ is not: it is what the principal resolver needs to
# identify the human (a server context, a verified token, a session) and it is cleared
# when the call ends.
def invoke(tool:, arguments: {}, principal: :unset, agent: nil, metadata: {}, request: {},
&body)
context = Context.new(
tool_name: tool_name_for(tool),
agent: agent,
arguments: arguments,
metadata: metadata
metadata: metadata,
request: request
)

declaration = registry.guard_for(context.tool_name)
Expand All @@ -49,7 +55,11 @@ def invoke(tool:, arguments: {}, principal: :unset, agent: nil, metadata: {}, &b

private

# A tool class whose library runs it some other way (a class-level `call`, a
# `perform` behind callbacks) says how through `reeve_run`, which the adapters define.
def run(tool, arguments)
return tool.reeve_run(arguments) if tool.respond_to?(:reeve_run)

instance = tool.is_a?(Class) ? tool.new : tool
arguments.empty? ? instance.call : instance.call(**arguments)
end
Expand Down
Loading
Loading