cuboid 0.3.6 → 0.5

data/spec/cuboid/mcp/auth_spec.rb

@@ -0,0 +1,179 @@
+require 'spec_helper'
+require "#{Cuboid::Options.paths.lib}/mcp/auth"
+
+describe Cuboid::MCP::Auth do
+    # Inner app: any time the middleware passes a request through, the
+    # inner app records the env it saw and replies 200 OK. Lets us
+    # check that env['cuboid.mcp.auth'] is populated AND that
+    # short-circuited (401) requests never reach it.
+    let(:inner_app) do
+        seen = []
+        app = ->(env) {
+            seen << env
+            [200, { 'content-type' => 'text/plain' }, ['ok']]
+        }
+        # Expose `seen` for assertions.
+        app.singleton_class.send(:define_method, :seen_envs) { seen }
+        app
+    end
+
+    let(:middleware) { described_class.new(inner_app) }
+
+    # Each test installs a fresh anonymous Application subclass so we
+    # don't leak validators across examples.
+    let(:fake_application) { Class.new(Cuboid::Application) }
+
+    before(:each) do
+        @prev_application = Cuboid::Application.application
+        Cuboid::Application.application = fake_application
+    end
+
+    after(:each) do
+        Cuboid::Application.application = @prev_application
+    end
+
+    def env(headers = {})
+        # Minimum env Rack expects; HTTP_AUTHORIZATION is the only
+        # header the middleware reads.
+        {
+            'REQUEST_METHOD'    => 'POST',
+            'PATH_INFO'         => '/mcp',
+            'rack.input'        => StringIO.new('{}'),
+            'rack.errors'       => StringIO.new
+        }.merge(headers)
+    end
+
+    context 'when no validator is registered' do
+        it 'passes the request through unchanged' do
+            status, _, _ = middleware.call(env)
+            status.should == 200
+            inner_app.seen_envs.size.should == 1
+        end
+
+        it 'does not populate cuboid.mcp.auth' do
+            middleware.call(env)
+            inner_app.seen_envs.first['cuboid.mcp.auth'].should be_nil
+        end
+    end
+
+    context 'when a validator is registered' do
+        before do
+            fake_application.mcp_authenticate_with do |token|
+                token == 'good-token' ? { user: 'alice' } : nil
+            end
+        end
+
+        context 'and the Authorization header is missing' do
+            it 'responds 401 with invalid_request' do
+                status, headers, body = middleware.call(env)
+
+                status.should == 401
+                headers['www-authenticate']
+                    .should == 'Bearer realm="MCP", error="invalid_request"'
+
+                JSON.parse(body.first)['error']['message'].should == 'invalid_request'
+            end
+
+            it 'never reaches the inner app' do
+                middleware.call(env)
+                inner_app.seen_envs.should be_empty
+            end
+        end
+
+        context 'and the Authorization header is not a Bearer scheme' do
+            it 'responds 401 with invalid_request' do
+                status, _, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Basic dXNlcjpwYXNz')
+                )
+                status.should == 401
+                inner_app.seen_envs.should be_empty
+            end
+        end
+
+        context 'and the Bearer token is wrong' do
+            it 'responds 401 with invalid_token' do
+                status, headers, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Bearer not-the-token')
+                )
+
+                status.should == 401
+                headers['www-authenticate']
+                    .should == 'Bearer realm="MCP", error="invalid_token"'
+
+                inner_app.seen_envs.should be_empty
+            end
+        end
+
+        context 'and the Bearer token is correct' do
+            it 'passes the request through' do
+                status, _, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Bearer good-token')
+                )
+                status.should == 200
+            end
+
+            it "stashes the validator's return value in env['cuboid.mcp.auth']" do
+                middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Bearer good-token')
+                )
+
+                inner_app.seen_envs.first['cuboid.mcp.auth']
+                    .should == { user: 'alice' }
+            end
+
+            it 'is case-insensitive on the Bearer keyword' do
+                status, _, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'bearer good-token')
+                )
+                status.should == 200
+            end
+
+            it 'tolerates extra whitespace between Bearer and the token' do
+                status, _, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => "Bearer    good-token")
+                )
+                status.should == 200
+            end
+        end
+
+        context 'and the validator raises' do
+            before do
+                fake_application.mcp_authenticate_with do |_token|
+                    raise 'database is down'
+                end
+            end
+
+            it 'responds 401 (not 500) so internals never leak' do
+                status, headers, _ = middleware.call(
+                    env('HTTP_AUTHORIZATION' => 'Bearer whatever')
+                )
+
+                status.should == 401
+                headers['www-authenticate']
+                    .should == 'Bearer realm="MCP", error="invalid_token"'
+
+                inner_app.seen_envs.should be_empty
+            end
+        end
+    end
+
+    context 'when the validator is replaced after the middleware was instantiated' do
+        # Important property: the middleware reads the validator at
+        # request time, not at construction time, so applications can
+        # swap implementations during a long-running process.
+        it 'picks up the new validator on the next request' do
+            mw = middleware
+
+            status, _, _ = mw.call(env('HTTP_AUTHORIZATION' => 'Bearer x'))
+            status.should == 200   # no validator yet → pass-through
+
+            fake_application.mcp_authenticate_with { |t| t == 'x' }
+
+            status, _, _ = mw.call(env('HTTP_AUTHORIZATION' => 'Bearer x'))
+            status.should == 200
+
+            status, _, _ = mw.call(env('HTTP_AUTHORIZATION' => 'Bearer y'))
+            status.should == 401
+        end
+    end
+end

data/spec/cuboid/mcp/server_spec.rb

@@ -0,0 +1,346 @@
+require 'spec_helper'
+require "#{Cuboid::Options.paths.lib}/mcp/server"
+
+describe Cuboid::MCP::Server do
+    include Rack::Test::Methods
+
+    # Each test gets a fresh anonymous Application subclass so service /
+    # validator registrations don't leak between examples.
+    let(:fake_application) { Class.new(Cuboid::Application) }
+
+    before(:each) do
+        @prev_application = Cuboid::Application.application
+        Cuboid::Application.application = fake_application
+    end
+
+    after(:each) do
+        Cuboid::Application.application = @prev_application
+        # Reset the shared instances map so per-example fixtures don't
+        # bleed into the next example.
+        Cuboid::Server::InstanceHelpers.instances.clear
+    end
+
+    # Rack::Test's `app` hook — built per-test from current options/state.
+    # Default to `stateless: true` so tests can hit individual JSON-RPC
+    # methods without an explicit `initialize` handshake first.
+    def app
+        described_class.rack_app({ stateless: true }.merge(@app_options || {}))
+    end
+
+    def jsonrpc(method, params = {}, id: 1)
+        {
+            jsonrpc: '2.0',
+            id:      id,
+            method:  method,
+            params:  params
+        }.to_json
+    end
+
+    def post_jsonrpc(path, method, params = {}, headers: {})
+        post path,
+             jsonrpc(method, params),
+             {
+                'CONTENT_TYPE' => 'application/json',
+                'HTTP_ACCEPT'  => 'application/json, text/event-stream'
+             }.merge(headers)
+    end
+
+    INITIALIZE_PARAMS = {
+        protocolVersion: '2025-06-18',
+        capabilities:    {},
+        clientInfo:      { name: 'spec', version: '0' }
+    }.freeze
+
+    # Stub for an MCP-tool handler module/class — what an application
+    # gem supplies via `mcp_service_for`.
+    def build_handler_with_tools(*tools)
+        h = Module.new
+        h.define_singleton_method(:tools) { tools }
+        h
+    end
+
+    # Plant an entry in the shared instance map so the dispatcher can
+    # resolve `:instance` to something. The value is whatever an RPC
+    # client would normally be — for tests we just use a plain
+    # double / OpenStruct that the tools may interact with.
+    def stub_instance(id, instance_obj = Object.new)
+        Cuboid::Server::InstanceHelpers.instances[id] = instance_obj
+        instance_obj
+    end
+
+    context 'when the path is unrecognised' do
+        before do
+            fake_application.mcp_service_for(:my_service, build_handler_with_tools)
+            stub_instance('inst-1')
+        end
+
+        it '404s an unrelated path' do
+            post_jsonrpc '/random/path', 'initialize', INITIALIZE_PARAMS
+            last_response.status.should == 404
+        end
+    end
+
+    context 'core tools at /mcp (framework-level)' do
+        # Stub double for kill_instance: needs `.shutdown` and `.close`.
+        let(:killable) do
+            obj = Object.new
+            obj.define_singleton_method(:shutdown) { nil }
+            obj.define_singleton_method(:close)    { nil }
+            obj
+        end
+
+        it 'serves an initialize handshake' do
+            post_jsonrpc '/mcp', 'initialize', INITIALIZE_PARAMS
+
+            last_response.status.should == 200
+            JSON.parse(last_response.body)['result']['protocolVersion']
+                .should == '2025-06-18'
+        end
+
+        it 'lists the framework tools (list/spawn/kill instance)' do
+            post_jsonrpc '/mcp', 'tools/list'
+
+            names = JSON.parse(last_response.body)['result']['tools'].map { |t| t['name'] }
+            names.sort.should == %w[kill_instance list_instances spawn_instance]
+        end
+
+        it 'list_instances returns currently-registered ids' do
+            stub_instance('inst-a')
+            stub_instance('inst-b')
+
+            post_jsonrpc '/mcp', 'tools/call', { name: 'list_instances', arguments: {} }
+
+            structured = JSON.parse(last_response.body)['result']['structuredContent']
+            structured['instances'].keys.sort.should == %w[inst-a inst-b]
+        end
+
+        it 'kill_instance removes the instance from the shared map' do
+            stub_instance('inst-x', killable)
+
+            post_jsonrpc '/mcp', 'tools/call',
+                         { name: 'kill_instance', arguments: { instance_id: 'inst-x' } }
+
+            structured = JSON.parse(last_response.body)['result']['structuredContent']
+            structured['killed'].should == 'inst-x'
+            Cuboid::Server::InstanceHelpers.instances.key?('inst-x').should == false
+        end
+
+        it 'kill_instance returns an error response when the id is unknown' do
+            post_jsonrpc '/mcp', 'tools/call',
+                         { name: 'kill_instance', arguments: { instance_id: 'nope' } }
+
+            body    = JSON.parse(last_response.body)
+            content = body['result']['content'].first
+            body['result']['isError'].should == true
+            content['text'].should include('unknown instance')
+        end
+    end
+
+    context 'with a service registered' do
+        let(:tool_class) do
+            klass = Class.new(MCP::Tool)
+            klass.instance_eval do
+                tool_name 'echo'
+                description 'Returns "<instance_id>: <message>".'
+                input_schema(
+                    properties: { message: { type: 'string' } },
+                    required:   ['message']
+                )
+
+                def self.call(message:, server_context:)
+                    text = "#{server_context[:instance_id]}: #{message}"
+                    MCP::Tool::Response.new([{ type: 'text', text: text }])
+                end
+            end
+            klass
+        end
+
+        let(:handler) { build_handler_with_tools(tool_class) }
+
+        before do
+            fake_application.mcp_service_for(:my_service, handler)
+            stub_instance('inst-1')
+        end
+
+        it 'lists the wrapped tool under its <service>_<tool> name with instance_id required' do
+            post_jsonrpc '/mcp', 'tools/list'
+
+            tools = JSON.parse(last_response.body)['result']['tools']
+            wrapped = tools.find { |t| t['name'] == 'my_service_echo' }
+            wrapped.should_not be_nil
+            wrapped['inputSchema']['required'].should include('instance_id')
+            wrapped['inputSchema']['properties'].keys.map(&:to_s)
+                .should include('instance_id', 'message')
+        end
+
+        it 'resolves the instance_id arg into server_context for the wrapped tool' do
+            post_jsonrpc '/mcp', 'tools/call',
+                         { name: 'my_service_echo',
+                           arguments: { instance_id: 'inst-1', message: 'hi' } }
+
+            content = JSON.parse(last_response.body)['result']['content']
+            content.first['text'].should == 'inst-1: hi'
+        end
+
+        it 'returns an MCP tool error (not a routing 404) when instance_id is unknown' do
+            post_jsonrpc '/mcp', 'tools/call',
+                         { name: 'my_service_echo',
+                           arguments: { instance_id: 'missing', message: 'hi' } }
+
+            body = JSON.parse(last_response.body)
+            body['result']['isError'].should == true
+            body['result']['content'].first['text'].should include('unknown instance')
+        end
+
+        it 'isolates state across instance_ids passed as arguments' do
+            stub_instance('inst-2')
+
+            post_jsonrpc '/mcp', 'tools/call',
+                         { name: 'my_service_echo',
+                           arguments: { instance_id: 'inst-1', message: 'hi' } }
+            JSON.parse(last_response.body)['result']['content']
+                .first['text'].should == 'inst-1: hi'
+
+            post_jsonrpc '/mcp', 'tools/call',
+                         { name: 'my_service_echo',
+                           arguments: { instance_id: 'inst-2', message: 'hi' } }
+            JSON.parse(last_response.body)['result']['content']
+                .first['text'].should == 'inst-2: hi'
+        end
+    end
+
+    context 'when an auth validator is registered' do
+        before do
+            fake_application.mcp_service_for(:my_service, build_handler_with_tools)
+            stub_instance('inst-1')
+            fake_application.mcp_authenticate_with do |token|
+                token == 'good' ? :ok : nil
+            end
+        end
+
+        it '401s a request with no Authorization header' do
+            post_jsonrpc '/mcp', 'initialize', INITIALIZE_PARAMS
+            last_response.status.should == 401
+        end
+
+        it 'allows requests with a valid bearer token' do
+            post_jsonrpc '/mcp', 'initialize', INITIALIZE_PARAMS,
+                         headers: { 'HTTP_AUTHORIZATION' => 'Bearer good' }
+            last_response.status.should == 200
+        end
+    end
+
+    context 'with custom name / version' do
+        before do
+            fake_application.mcp_service_for(:my_service, build_handler_with_tools)
+            stub_instance('inst-1')
+            @app_options = { name: 'custom-mcp', version: '7.7.7' }
+        end
+
+        it 'advertises them in serverInfo' do
+            post_jsonrpc '/mcp', 'initialize', INITIALIZE_PARAMS
+
+            info = JSON.parse(last_response.body)['result']['serverInfo']
+            info['name'].should    == 'custom-mcp'
+            info['version'].should == '7.7.7'
+        end
+    end
+
+    context 'when the application class lives under a branded top-level namespace' do
+        # Synthesize a real-looking namespace: a `shortname` method
+        # (the brand the user wants advertised) and a `version`
+        # method (preferred over the VERSION constant when both are
+        # present). The dispatcher should pick the branded methods
+        # over the raw module name.
+        before do
+            stub_const('BrandFake', Module.new)
+            BrandFake.define_singleton_method(:shortname) { :foo   }
+            BrandFake.define_singleton_method(:version)   { '9.9.9' }
+            BrandFake.const_set(
+                :Application,
+                Class.new(Cuboid::Application) { def self.name; 'BrandFake::Application'; end }
+            )
+
+            Cuboid::Application.application = BrandFake::Application
+            BrandFake::Application.mcp_service_for(:my_service, build_handler_with_tools)
+            stub_instance('inst-1')
+        end
+
+        it 'advertises the brand shortname + version at /mcp' do
+            post_jsonrpc '/mcp', 'initialize', INITIALIZE_PARAMS
+
+            info = JSON.parse(last_response.body)['result']['serverInfo']
+            info['name'].should    == 'foo'
+            info['version'].should == '9.9.9'
+        end
+
+    end
+
+    context 'live route (`/mcp/live/<token>`)' do
+        # The route is loopback-only; Rack::Test sets REMOTE_ADDR to
+        # '127.0.0.1' by default which lets the loopback gate pass.
+
+        before(:each) do
+            # Reset Live registry between examples so tokens don't bleed.
+            Cuboid::MCP::Live.instance_variable_set(:@by_token, {})
+            Cuboid::MCP::Live.instance_variable_set(:@by_instance_id, {})
+            Cuboid::MCP::Live.transport = nil
+        end
+
+        it '410s when the token isn\'t registered' do
+            post '/mcp/live/no-such-token', '{}',
+                 { 'CONTENT_TYPE' => 'application/json' }
+
+            last_response.status.should == 410
+            JSON.parse(last_response.body)['error']
+                .should include('live token unknown')
+        end
+
+        it 'rejects pushes from non-loopback with 404' do
+            post '/mcp/live/whatever', '{}',
+                 { 'CONTENT_TYPE' => 'application/json',
+                   'REMOTE_ADDR'  => '203.0.113.5' }
+
+            last_response.status.should == 404
+            JSON.parse(last_response.body)['error']['message']
+                .should include('loopback')
+        end
+
+        it '400s on an undecodable body for the declared content type' do
+            # Register a token so we get past the 410 path.
+            Cuboid::MCP::Live.instance_variable_get(:@by_token)['tok'] = {
+                session_id: 'sess-1', instance_id: 'inst-x'
+            }
+
+            post '/mcp/live/tok', "\xff\xff\xff not json".b,
+                 { 'CONTENT_TYPE' => 'application/json' }
+
+            last_response.status.should == 400
+            JSON.parse(last_response.body)['error']
+                .should include('could not decode')
+        end
+    end
+
+    context 'when the namespace exposes only a VERSION constant (no branded methods)' do
+        before do
+            stub_const('PlainFake', Module.new)
+            PlainFake.const_set(:VERSION, '2.0.0')
+            PlainFake.const_set(
+                :Application,
+                Class.new(Cuboid::Application) { def self.name; 'PlainFake::Application'; end }
+            )
+
+            Cuboid::Application.application = PlainFake::Application
+            PlainFake::Application.mcp_service_for(:my_service, build_handler_with_tools)
+            stub_instance('inst-1')
+        end
+
+        it 'falls back to the namespace name + VERSION' do
+            post_jsonrpc '/mcp', 'initialize', INITIALIZE_PARAMS
+
+            info = JSON.parse(last_response.body)['result']['serverInfo']
+            info['name'].should    == 'PlainFake'
+            info['version'].should == '2.0.0'
+        end
+    end
+end

data/spec/cuboid/rest/server_spec.rb

@@ -479,7 +479,7 @@ describe Cuboid::Rest::Server do
             end
         end
 
-        context 'when the instance is from the Scheduler' do
+        context 'when the instance is from the Scheduler'do
             before do
                 put '/scheduler/url', scheduler.url
             end
@@ -581,7 +581,6 @@ describe Cuboid::Rest::Server do
             delete url
 
             get "/instances/#{id}"
-            ap response
             expect(response_code).to eq 404
         end
 
@@ -606,9 +605,9 @@ describe Cuboid::Rest::Server do
                 delete url
                 expect(response_code).to eq 200
 
-                sleep 0.1 while scheduler.failed.empty?
+                sleep 1 while !scheduler.running.empty?
 
-                expect(scheduler.failed).to include @id
+                expect(scheduler.completed).to include @id
             end
 
             context 'when the instance completes' do

data/spec/support/shared/option_group.rb

@@ -7,9 +7,19 @@ shared_examples_for 'option_group' do
         it 'converts self to a serializable hash' do
             expect(data).to be_kind_of Hash
 
+            # MessagePack — the on-wire serializer behind
+            # `Cuboid::RPC::Serializer` — has no Symbol type, so any
+            # Symbol value in `data` round-trips as a String. Compare
+            # against the stringified-Symbol form rather than `data`
+            # itself; the round-trip equality the spec is asserting
+            # holds modulo that one well-known coercion.
+            expected = data.each_with_object({}) do |(k, v), h|
+                h[k] = v.is_a?(Symbol) ? v.to_s : v
+            end
+
             expect(Cuboid::RPC::Serializer.load(
                 Cuboid::RPC::Serializer.dump( data )
-            )).to eq(data)
+            )).to eq(expected)
         end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuboid
 version: !ruby/object:Gem::Version
-  version: 0.3.6
+  version: '0.5'
 platform: ruby
 authors:
 - Tasos Laskos
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-05 00:00:00.000000000 Z
+date: 2026-05-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -178,6 +178,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.15'
 - !ruby/object:Gem::Dependency
   name: toq
   requirement: !ruby/object:Gem::Requirement
@@ -248,6 +262,10 @@ files:
 - lib/cuboid/data.rb
 - lib/cuboid/data/application.rb
 - lib/cuboid/error.rb
+- lib/cuboid/mcp/auth.rb
+- lib/cuboid/mcp/core_tools.rb
+- lib/cuboid/mcp/live.rb
+- lib/cuboid/mcp/server.rb
 - lib/cuboid/option_group.rb
 - lib/cuboid/option_groups.rb
 - lib/cuboid/option_groups/agent.rb
@@ -265,6 +283,7 @@ files:
 - lib/cuboid/processes/executables/agent.rb
 - lib/cuboid/processes/executables/base.rb
 - lib/cuboid/processes/executables/instance.rb
+- lib/cuboid/processes/executables/mcp.rb
 - lib/cuboid/processes/executables/rest_service.rb
 - lib/cuboid/processes/executables/scheduler.rb
 - lib/cuboid/processes/helpers.rb
@@ -304,6 +323,7 @@ files:
 - lib/cuboid/ruby/array.rb
 - lib/cuboid/ruby/hash.rb
 - lib/cuboid/ruby/object.rb
+- lib/cuboid/server/instance_helpers.rb
 - lib/cuboid/snapshot.rb
 - lib/cuboid/state.rb
 - lib/cuboid/state/application.rb
@@ -362,6 +382,8 @@ files:
 - spec/cuboid/data/application_spec.rb
 - spec/cuboid/data_spec.rb
 - spec/cuboid/error_spec.rb
+- spec/cuboid/mcp/auth_spec.rb
+- spec/cuboid/mcp/server_spec.rb
 - spec/cuboid/option_groups/agent_spec.rb
 - spec/cuboid/option_groups/datastore_spec.rb
 - spec/cuboid/option_groups/output_spec.rb
@@ -486,6 +508,8 @@ test_files:
 - spec/cuboid/data/application_spec.rb
 - spec/cuboid/data_spec.rb
 - spec/cuboid/error_spec.rb
+- spec/cuboid/mcp/auth_spec.rb
+- spec/cuboid/mcp/server_spec.rb
 - spec/cuboid/option_groups/agent_spec.rb
 - spec/cuboid/option_groups/datastore_spec.rb
 - spec/cuboid/option_groups/output_spec.rb