bundleup-sdk 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e385086d7a4207cb36ec82ac134eab03155093407c098488ea40478d62f79d3
-  data.tar.gz: ca70fa9281ad486160c66a731e81c0ad56f200ad4e8fccf15e818340e43ea5d6
+  metadata.gz: 3ece90ca061e8b5bbac827ca07dcc35b1c029e235d27ec319cef3117cd0652d0
+  data.tar.gz: 034fdb9a5ccf8c36aa38a3d8a7870f8c32a7997ff617cfed395fd4e0ff03aaae
 SHA512:
-  metadata.gz: 9245dcc515bff7307c4073bbc223ce3b2e5bdd8e3ff91dbb83cfdf95437c89bc7e03a7c3b8c9c0db0ca2bb0962df0c9597d127c0a3209d2bcb909e934c787f65
-  data.tar.gz: e472e19410d920eb5fbbe6abab03c2af1d1ea05945d7249d1be90c7d47ab7375d67dc503ba2698e57ce7b40ed9fed423400847b3dffefde47b51931c5ee74117
+  metadata.gz: eb30ce08198acee62b5ec10469a4a116a8186eab6669fbc1bcaece16899911ca50f5b37a1bc15d6dcc096a87b6c160faa3ea2319c8ce552159aa4347be869b85
+  data.tar.gz: 38855ea19f0662f62acbddc68e0b439f4171dadf5bba56f29b4dde40c4cfc14f72cf6da871af0faa9039b6a37c5b3188a968bacd3abcb859468053913bd2efe6

data/lib/bundleup/client.rb

@@ -38,5 +38,13 @@ module BundleUp
 
       BundleUp::Unify::Client.new(@api_key, connection_id)
     end
+
+    def mcp(connection_id)
+      if connection_id.nil? || connection_id.empty?
+        raise ArgumentError, 'Connection ID is required to create an MCP instance.'
+      end
+
+      BundleUp::MCP.new(@api_key, connection_id)
+    end
   end
 end

data/lib/bundleup/mcp.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module BundleUp
+  # Transport for a connection's MCP server.
+  #
+  # +post+ and +delete+ return the raw Faraday response, the way Proxy does.
+  # Use +connect+ for a managed session that handles the handshake and
+  # response decoding.
+  class MCP
+    BASE_URL = 'https://mcp.bundleup.io'
+
+    # Separates the API key from an appended connection ID. Safe to split on:
+    # API keys are alphanumeric and connection IDs are cuids.
+    CREDENTIAL_SEPARATOR = '.'
+
+    attr_reader :api_key, :connection_id
+
+    def initialize(api_key, connection_id)
+      @api_key = api_key
+      @connection_id = connection_id
+    end
+
+    # The URL and headers for an MCP client running in your own process.
+    def transport
+      { url: BASE_URL, headers: default_headers }
+    end
+
+    # The URL and a single bearer token carrying both the API key and the
+    # connection, for model-hosted MCP clients that cannot set custom headers.
+    # Note this hands your API key to the model provider.
+    def hosted
+      { url: BASE_URL, token: "#{@api_key}#{CREDENTIAL_SEPARATOR}#{@connection_id}" }
+    end
+
+    # Send a JSON-RPC message and return the raw response. Pass
+    # +Mcp-Session-Id+ in +headers+ to stay on an existing session.
+    def post(body, headers: {})
+      payload = body.is_a?(String) ? body : body.to_json
+
+      connection.post(BASE_URL, payload, default_headers.merge(headers))
+    end
+
+    # End an MCP session. Pass the session's +Mcp-Session-Id+ in +headers+.
+    def delete(headers: {})
+      connection.delete(BASE_URL, nil, default_headers.merge(headers))
+    end
+
+    # Open a managed MCP session for this connection.
+    def connect
+      MCPClient.new(BASE_URL, @api_key, @connection_id)
+    end
+
+    private
+
+    def default_headers
+      {
+        'Authorization' => "Bearer #{@api_key}",
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json, text/event-stream',
+        'BU-Connection-Id' => @connection_id
+      }
+    end
+
+    def connection
+      @connection ||= Faraday.new { |faraday| faraday.adapter Faraday.default_adapter }
+    end
+  end
+
+  # A connected MCP session.
+  #
+  # Tools, resources and prompts are defined by the provider — BundleUp does
+  # not rename or normalize them.
+  class MCPClient
+    PROTOCOL_VERSION = '2025-06-18'
+    CLIENT_NAME = 'bundleup-sdk'
+
+    def initialize(base_url, api_key, connection_id)
+      @base_url = base_url
+      @api_key = api_key
+      @connection_id = connection_id
+      @session_id = nil
+      @connected = false
+      @last_id = 0
+    end
+
+    # List the provider's tools, following pagination to the end.
+    def tools
+      paginate('tools/list', 'tools')
+    end
+
+    # Call a tool by name, with arguments matching its own input schema.
+    def tool(name, args = {})
+      raise ArgumentError, 'Tool name is required to call a tool.' if blank?(name)
+
+      connect
+      send_message('tools/call', { name: name, arguments: args })
+    end
+
+    # List the provider's resources, following pagination to the end.
+    def resources
+      paginate('resources/list', 'resources')
+    end
+
+    # Read a resource by URI.
+    def resource(uri)
+      raise ArgumentError, 'Resource URI is required to read a resource.' if blank?(uri)
+
+      connect
+      send_message('resources/read', { uri: uri })
+    end
+
+    # List the provider's prompts, following pagination to the end.
+    def prompts
+      paginate('prompts/list', 'prompts')
+    end
+
+    # Get a prompt by name.
+    def prompt(name, args = {})
+      raise ArgumentError, 'Prompt name is required to get a prompt.' if blank?(name)
+
+      connect
+      send_message('prompts/get', { name: name, arguments: args })
+    end
+
+    # Send any other JSON-RPC method on this session.
+    def request(method, params = nil)
+      raise ArgumentError, 'Method is required to send a request.' if blank?(method)
+
+      connect
+      send_message(method, params)
+    end
+
+    # End the session and reset local state.
+    def close
+      delete_session if @session_id
+
+      @session_id = nil
+      @connected = false
+      nil
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || value.to_s.empty?
+    end
+
+    def default_headers
+      headers = {
+        'Authorization' => "Bearer #{@api_key}",
+        'Content-Type' => 'application/json',
+        'Accept' => 'application/json, text/event-stream',
+        'BU-Connection-Id' => @connection_id
+      }
+      headers['Mcp-Session-Id'] = @session_id if @session_id
+      headers
+    end
+
+    def connection
+      @connection ||= Faraday.new { |faraday| faraday.adapter Faraday.default_adapter }
+    end
+
+    def post_payload(payload)
+      response = connection.post(@base_url, payload.to_json, default_headers)
+      session_id = response.headers['mcp-session-id']
+      @session_id = session_id if session_id
+
+      raise error_for(response) unless response.success?
+
+      response
+    end
+
+    def error_for(response)
+      fallback = "MCP request failed with status #{response.status}."
+      parsed = JSON.parse(response.body.to_s)
+      return RuntimeError.new(fallback) unless parsed.is_a?(Hash) && parsed['message']
+
+      code = parsed['code']
+      RuntimeError.new(code ? "#{parsed['message']} (#{code})" : parsed['message'])
+    rescue JSON::ParserError
+      RuntimeError.new(fallback)
+    end
+
+    # Run the MCP handshake, once. Deferred until the first call.
+    def connect
+      return if @connected
+
+      send_message('initialize', handshake_params)
+      post_payload({ jsonrpc: '2.0', method: 'notifications/initialized' })
+      @connected = true
+    end
+
+    def handshake_params
+      {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: CLIENT_NAME, version: BundleUp::VERSION }
+      }
+    end
+
+    def send_message(method, params = nil)
+      @last_id += 1
+      payload = { jsonrpc: '2.0', id: @last_id, method: method }
+      payload[:params] = params unless params.nil?
+
+      message = parse(post_payload(payload), @last_id)
+      raise "No response received for #{method}." if message.nil?
+      raise message['error']['message'].to_s if message['error']
+
+      message['result'] || {}
+    end
+
+    # Providers may answer a plain request/response over text/event-stream.
+    def parse(response, message_id)
+      body = response.body.to_s
+      return nil if body.empty?
+
+      content_type = response.headers['content-type'].to_s
+      return JSON.parse(body) unless content_type.include?('text/event-stream')
+
+      parse_stream(body, message_id)
+    end
+
+    def parse_stream(body, message_id)
+      body.gsub("\r\n", "\n").split("\n\n").each do |event|
+        data = event_data(event)
+        next if data.empty?
+
+        message = JSON.parse(data)
+        # Skip server notifications interleaved on the stream.
+        return message if message.is_a?(Hash) && message['id'] == message_id
+      end
+
+      nil
+    end
+
+    def event_data(event)
+      event.split("\n")
+           .select { |line| line.start_with?('data:') }
+           .map { |line| line.sub('data:', '').strip }
+           .join("\n")
+    end
+
+    def paginate(method, key)
+      connect
+      items = []
+      cursor = nil
+
+      loop do
+        result = send_message(method, cursor ? { cursor: cursor } : nil)
+        items.concat(result[key] || [])
+        cursor = result['nextCursor']
+        break unless cursor
+      end
+
+      items
+    end
+
+    def delete_session
+      connection.delete(@base_url, nil, default_headers)
+    rescue Faraday::Error
+      nil
+    end
+  end
+end

data/lib/bundleup/unify/git.rb

@@ -17,6 +17,8 @@ module BundleUp
 
       # Fetches pull requests for a specific repository from the connected Git provider.
       def pulls(repo_name, params = {})
+        raise ArgumentError, 'repo_name is required to fetch pulls.' if blank?(repo_name)
+
         encoded_repo_name = URI.encode_www_form_component(repo_name)
 
         response = connection.get("git/repos/#{encoded_repo_name}/pulls") do |req|
@@ -30,6 +32,8 @@ module BundleUp
 
       # Fetches tags for a specific repository from the connected Git provider.
       def tags(repo_name, params = {})
+        raise ArgumentError, 'repo_name is required to fetch tags.' if blank?(repo_name)
+
         encoded_repo_name = URI.encode_www_form_component(repo_name)
 
         response = connection.get("git/repos/#{encoded_repo_name}/tags") do |req|
@@ -43,6 +47,8 @@ module BundleUp
 
       # Fetches releases for a specific repository from the connected Git provider.
       def releases(repo_name, params = {})
+        raise ArgumentError, 'repo_name is required to fetch releases.' if blank?(repo_name)
+
         encoded_repo_name = URI.encode_www_form_component(repo_name)
 
         response = connection.get("git/repos/#{encoded_repo_name}/releases") do |req|
@@ -56,6 +62,8 @@ module BundleUp
 
       # Fetches branches for a specific repository from the connected Git provider.
       def branches(repo_name, params = {})
+        raise ArgumentError, 'repo_name is required to fetch branches.' if blank?(repo_name)
+
         encoded_repo_name = URI.encode_www_form_component(repo_name)
 
         response = connection.get("git/repos/#{encoded_repo_name}/branches") do |req|
@@ -66,6 +74,27 @@ module BundleUp
 
         response.body
       end
+
+      # Fetches commits for a specific repository from the connected Git provider.
+      def commits(repo_name, params = {})
+        raise ArgumentError, 'repo_name is required to fetch commits.' if blank?(repo_name)
+
+        encoded_repo_name = URI.encode_www_form_component(repo_name)
+
+        response = connection.get("git/repos/#{encoded_repo_name}/commits") do |req|
+          req.params = params
+        end
+
+        raise "Failed to fetch git/repos/#{encoded_repo_name}/commits: #{response.status}" unless response.success?
+
+        response.body
+      end
+
+      private
+
+      def blank?(value)
+        value.nil? || value.to_s.empty?
+      end
     end
   end
 end

data/lib/bundleup/unify/mcp.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module BundleUp
+  module Unify
+    # The Unified MCP server.
+    #
+    # Same protocol and headers as Proxy MCP, but the tools are BundleUp's
+    # normalized ones rather than the provider's. Tools only — Unified MCP
+    # exposes no resources or prompts.
+    #
+    # The server is stateless and POST-only, so there is no session to close.
+    class MCP
+      BASE_URL = 'https://unify.bundleup.io/v1/mcp'
+
+      attr_reader :api_key, :connection_id
+
+      def initialize(api_key, connection_id)
+        @api_key = api_key
+        @connection_id = connection_id
+        @client = ::BundleUp::MCPClient.new(BASE_URL, api_key, connection_id)
+      end
+
+      # The URL and a single bearer token carrying both the API key and the
+      # connection, for model-hosted MCP clients that cannot set headers.
+      def hosted
+        separator = ::BundleUp::MCP::CREDENTIAL_SEPARATOR
+
+        { url: BASE_URL, token: "#{@api_key}#{separator}#{@connection_id}" }
+      end
+
+      # List the available unified tools.
+      def tools
+        @client.tools
+      end
+
+      # Call a unified tool with optional arguments.
+      def tool(name, args = {})
+        raise ArgumentError, 'Tool name is required to call a tool.' if name.nil? || name.to_s.empty?
+
+        @client.tool(name, args)
+      end
+    end
+  end
+end

data/lib/bundleup/unify.rb

@@ -40,6 +40,11 @@ module BundleUp
       def drive
         @drive ||= BundleUp::Unify::Drive.new(api_key, connection_id)
       end
+
+      # Access the Unified MCP server for the connection.
+      def mcp
+        @mcp ||= BundleUp::Unify::MCP.new(api_key, connection_id)
+      end
     end
   end
 end

data/lib/bundleup/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BundleUp
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/bundleup.rb

@@ -6,6 +6,7 @@ require_relative 'bundleup/version'
 require_relative 'bundleup/client'
 require_relative 'bundleup/proxy'
 require_relative 'bundleup/unify'
+require_relative 'bundleup/mcp'
 
 # Resources
 require_relative 'bundleup/resources/base'
@@ -20,6 +21,7 @@ require_relative 'bundleup/unify/git'
 require_relative 'bundleup/unify/ticketing'
 require_relative 'bundleup/unify/crm'
 require_relative 'bundleup/unify/drive'
+require_relative 'bundleup/unify/mcp'
 
 # Main module for the BundleUp SDK.
 module BundleUp

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bundleup-sdk
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - BundleUp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -168,6 +168,7 @@ files:
 - README.md
 - lib/bundleup.rb
 - lib/bundleup/client.rb
+- lib/bundleup/mcp.rb
 - lib/bundleup/proxy.rb
 - lib/bundleup/resources/base.rb
 - lib/bundleup/resources/connection.rb
@@ -179,6 +180,7 @@ files:
 - lib/bundleup/unify/crm.rb
 - lib/bundleup/unify/drive.rb
 - lib/bundleup/unify/git.rb
+- lib/bundleup/unify/mcp.rb
 - lib/bundleup/unify/ticketing.rb
 - lib/bundleup/version.rb
 - sig/bundleup/unify.rbs