manceps 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f524ef8b916adcac4f46f0f382f973b59ab047091b841feeadf5e1691cdb8634
+  data.tar.gz: 7708c36c00d55478545f953f762584f99f8d660705e167a5046bbed0818bdee3
+SHA512:
+  metadata.gz: 9965075ca2b50283f9a5a1b08b922f32be4b74519828103d5c174b163e15b5acf328a54d9b03e3bacd02a54d6766316dfec285ff78290140f33e03e3cffc8311
+  data.tar.gz: 82a066ba382c508fca8b80772f4d78acaaf7009b21f1f210a2c1e1305ebc2f1c662c898cee7e2fb2112767e111534a1e91c3f96b552472db031fe349a0991503

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to Manceps are documented here.
+
+## [1.0.0] - 2026-04-06
+
+First public release. A production-grade Ruby client for the Model Context Protocol (MCP).
+
+### Features
+
+- **Streamable HTTP transport** with persistent connections via httpx
+- **stdio transport** for local MCP servers (subprocess communication over stdin/stdout)
+- **Auto-detect transport** from URL vs command
+- **Authentication**: Bearer token, API key header, OAuth token support with auto-refresh
+- **Tools**: list, call, streaming calls, structured output support
+- **Resources**: list, read, templates
+- **Prompts**: list, get with arguments
+- **Notifications**: register handlers, subscribe to resource updates, cancel requests
+- **Elicitation**: handle server requests for additional user input
+- **Tasks** (experimental): list, get, cancel, await with polling
+- **Resilience**: automatic retry with exponential backoff, session recovery on 404
+- **Pagination**: automatic cursor-based pagination for list operations
+- **Protocol negotiation**: targets MCP 2025-11-25, falls back to 2025-06-18 and 2025-03-26
+- **Configuration**: client name, version, timeouts, supported protocol versions
+- **Full error hierarchy**: ConnectionError, TimeoutError, ProtocolError, AuthenticationError, SessionExpiredError, ToolError
+
+### Requirements
+
+- Ruby >= 3.4.0
+- httpx >= 1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Obie Fernandez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,325 @@
+# Manceps
+
+A Ruby client for the [Model Context Protocol](https://modelcontextprotocol.io) (MCP).
+
+From Latin *manceps* -- one who takes in hand (contractor, acquirer). From *manus* (hand) + *capere* (to take).
+
+## Installation
+
+```ruby
+# Gemfile
+gem "manceps"
+```
+
+Or install directly:
+
+```
+gem install manceps
+```
+
+Requires Ruby >= 3.4.0.
+
+## Quick Start
+
+```ruby
+require "manceps"
+
+# HTTP server with bearer auth
+Manceps::Client.open("https://mcp.example.com/mcp", auth: Manceps::Auth::Bearer.new(ENV["MCP_TOKEN"])) do |client|
+  client.tools.each { |t| puts "#{t.name}: #{t.description}" }
+
+  result = client.call_tool("search_documents", query: "quarterly report")
+  puts result.text
+end
+
+# stdio server (local process)
+Manceps::Client.open("npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]) do |client|
+  contents = client.read_resource("file:///tmp/hello.txt")
+  puts contents.text
+end
+```
+
+The block form connects, yields the client, and disconnects on exit -- even if an exception is raised.
+
+## Transports
+
+### Streamable HTTP
+
+The primary MCP transport. Uses [httpx](https://honeyryderchuck.gitlab.io/httpx/) for persistent connections -- MCP servers bind sessions to TCP connections, so connection reuse is required.
+
+```ruby
+client = Manceps::Client.new("https://mcp.example.com/mcp", auth: auth)
+```
+
+### stdio
+
+Spawns a local subprocess and communicates via newline-delimited JSON over stdin/stdout.
+
+```ruby
+client = Manceps::Client.new("npx", args: ["-y", "@modelcontextprotocol/server-memory"])
+
+# With environment variables
+client = Manceps::Client.new("mm-mcp", env: { "MM_TOKEN" => "...", "MM_URL" => "..." })
+```
+
+The transport auto-detects: HTTP(S) URLs use Streamable HTTP, everything else uses stdio.
+
+## Authentication
+
+### Bearer Token
+
+```ruby
+auth = Manceps::Auth::Bearer.new("your-token")
+```
+
+### API Key Header
+
+```ruby
+auth = Manceps::Auth::ApiKeyHeader.new("x-api-key", "your-key")
+```
+
+### OAuth 2.1 (Experimental)
+
+RFC 8414 discovery, RFC 7591 dynamic registration, PKCE, and automatic token refresh. Works but not yet tested against a wide range of authorization servers.
+
+```ruby
+# If you already have tokens
+auth = Manceps::Auth::OAuth.new(
+  access_token: "...",
+  refresh_token: "...",
+  token_url: "https://auth.example.com/token",
+  client_id: "...",
+  expires_at: Time.now + 3600,
+  on_token_refresh: ->(tokens) { save_tokens(tokens) }
+)
+
+# Full discovery + authorization flow
+discovery = Manceps::Auth::OAuth.discover("https://mcp.example.com", redirect_uri: "http://localhost:3000/callback")
+pkce = Manceps::Auth::OAuth.generate_pkce
+
+url = Manceps::Auth::OAuth.authorize_url(
+  authorization_url: discovery.authorization_url,
+  client_id: discovery.client_id,
+  redirect_uri: "http://localhost:3000/callback",
+  state: SecureRandom.hex(16),
+  scopes: discovery.scopes,
+  code_challenge: pkce[:challenge]
+)
+# Redirect user to `url`, then exchange the code:
+
+tokens = Manceps::Auth::OAuth.exchange_code(
+  token_url: discovery.token_url,
+  client_id: discovery.client_id,
+  client_secret: discovery.client_secret,
+  code: params[:code],
+  redirect_uri: "http://localhost:3000/callback",
+  code_verifier: pkce[:verifier]
+)
+```
+
+Token refresh happens automatically when a token is within 5 minutes of expiry. The `on_token_refresh` callback fires after each refresh so you can persist the new tokens.
+
+### No Auth
+
+The default. Useful for local servers:
+
+```ruby
+client = Manceps::Client.new("http://localhost:3000/mcp")
+```
+
+## Tools
+
+```ruby
+# List available tools
+tools = client.tools
+tools.each do |tool|
+  puts "#{tool.title || tool.name}: #{tool.description}"
+  puts "  Input:  #{tool.input_schema}"
+  puts "  Output: #{tool.output_schema}" if tool.output_schema  # structured output (2025-06-18+)
+end
+
+# Call a tool
+result = client.call_tool("get_weather", location: "New York")
+result.text                # joined text content
+result.content             # Array<Content>
+result.error?              # true if server flagged an error
+result.structured_content  # parsed structured output (when tool declares outputSchema)
+result.structured?         # true if structured content present
+
+# Stream a long-running tool call
+client.call_tool_streaming("analyze_data", dataset: "large.csv") do |event|
+  puts "Progress: #{event}"
+end
+```
+
+## Resources
+
+```ruby
+# List resources
+resources = client.resources
+resources.each { |r| puts "#{r.uri}: #{r.title || r.name}" }
+
+# List resource templates
+templates = client.resource_templates
+templates.each { |t| puts "#{t.uri_template}: #{t.title || t.name}" }
+
+# Read a resource
+contents = client.read_resource("file:///project/src/main.rs")
+puts contents.text
+```
+
+## Prompts
+
+```ruby
+# List prompts
+prompts = client.prompts
+prompts.each do |p|
+  puts "#{p.name}: #{p.description}"
+  p.arguments.each { |a| puts "  #{a.name} (required: #{a.required?})" }
+end
+
+# Get a prompt
+result = client.get_prompt("code_review", code: "def hello; end")
+result.messages.each { |m| puts "#{m.role}: #{m.text}" }
+```
+
+## Configuration
+
+```ruby
+Manceps.configure do |c|
+  c.client_name      = "MyApp"           # default: "Manceps"
+  c.client_version   = "1.0.0"           # default: Manceps::VERSION
+  c.protocol_version = "2025-11-25"      # default: "2025-11-25"
+  c.request_timeout  = 60                # default: 30 (seconds)
+  c.connect_timeout  = 15                # default: 10 (seconds)
+  c.client_description = "My app"        # optional, sent in clientInfo
+  c.supported_versions = ["2025-11-25", "2025-06-18", "2025-03-26"]  # for negotiation
+end
+```
+
+## Error Handling
+
+All errors inherit from `Manceps::Error`:
+
+```
+Manceps::Error
+  Manceps::ConnectionError         # transport-level failures
+  Manceps::TimeoutError            # request or connect timeout
+  Manceps::ProtocolError           # JSON-RPC error (has #code, #data)
+  Manceps::AuthenticationError     # 401, failed OAuth flows
+  Manceps::SessionExpiredError     # server invalidated the session (404)
+  Manceps::ToolError               # tool invocation failed (has #result)
+```
+
+```ruby
+begin
+  result = client.call_tool("risky_operation", id: 42)
+rescue Manceps::SessionExpiredError
+  client.connect  # re-establish session
+  retry
+rescue Manceps::ProtocolError => e
+  puts "RPC error #{e.code}: #{e.message}"
+end
+```
+
+## Why Manceps?
+
+**Persistent connections.** MCP servers bind sessions to TCP connections. Manceps uses httpx to keep connections alive across requests, which most HTTP libraries don't do by default.
+
+**Auth-first.** Bearer, API key, and OAuth 2.1 (experimental) are built in, not bolted on.
+
+**No LLM coupling.** Pure protocol client. No `to_openai_tools()` or framework integrations -- use it with anything.
+
+**Extracted from production.** Built and tested under real MCP load, not just spec examples.
+
+**Full 2025-11-25 spec.** Protocol version negotiation, elicitation, tasks, structured tool output, `MCP-Protocol-Version` header -- not just the basics.
+
+## Notifications
+
+Register handlers for server-initiated messages:
+
+```ruby
+client.on("notifications/tools/list_changed") { puts "Tools changed!" }
+client.on("notifications/resources/updated") { |params| puts "Updated: #{params['uri']}" }
+
+# Subscribe to resource updates
+client.subscribe_resource("file:///project/config.yml")
+
+# Cancel a long-running request
+client.cancel_request(request_id, reason: "User cancelled")
+
+# Listen for notifications (blocking)
+client.listen  # dispatches to registered handlers
+```
+
+## Elicitation
+
+Handle server requests for additional user input during tool calls:
+
+```ruby
+client.on_elicitation do |elicitation|
+  puts "Server asks: #{elicitation.message}"
+  puts "Schema: #{elicitation.requested_schema}"
+
+  # Respond with user input
+  Manceps::Elicitation.accept({ "name" => "Alice", "confirm" => true })
+  # Or decline/cancel:
+  # Manceps::Elicitation.decline
+  # Manceps::Elicitation.cancel
+end
+```
+
+Elicitation capability is automatically declared during initialization when a handler is registered.
+
+## Tasks (Experimental)
+
+Track long-running operations:
+
+```ruby
+# List tasks
+client.tasks.each { |t| puts "#{t.id}: #{t.status}" }
+
+# Get a specific task
+task = client.get_task("task-123")
+task.completed?  # => false
+task.running?    # => true
+
+# Poll until done
+task = client.await_task("task-123", interval: 2, timeout: 60)
+puts task.result
+
+# Cancel a task
+client.cancel_task("task-123")
+```
+
+## Resilience
+
+Automatic retry with exponential backoff on connection failures:
+
+```ruby
+# Connect retries up to max_retries (default: 3)
+client = Manceps::Client.new("https://mcp.example.com/mcp", auth: auth, max_retries: 5)
+
+# Requests auto-retry once on session expiry (re-initializes session)
+client.call_tool("search", query: "test")  # retries transparently on 404
+
+# Check connection health
+client.ping  # => true/false
+
+# Manual reconnect
+client.reconnect!
+```
+
+## Protocol Version
+
+Manceps targets MCP protocol **2025-11-25** by default. It negotiates with the server during initialization and supports fallback to `2025-06-18` and `2025-03-26`.
+
+After initialization, the `MCP-Protocol-Version` header is included on all HTTP requests per the spec.
+
+## License
+
+MIT. See [LICENSE](LICENSE) for details.
+
+---
+
+Author: [Obie Fernandez](https://github.com/obie)

data/lib/manceps/auth/api_key_header.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Manceps
+  module Auth
+    # Authenticates requests with a custom API key header.
+    class ApiKeyHeader
+      def initialize(header_name, key)
+        @header_name = header_name.downcase
+        @key = key
+      end
+
+      def apply(headers)
+        headers[@header_name] = @key
+      end
+    end
+  end
+end

data/lib/manceps/auth/bearer.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Manceps
+  module Auth
+    # Authenticates requests with a Bearer token.
+    class Bearer
+      def initialize(token)
+        @token = token
+      end
+
+      def apply(headers)
+        headers['authorization'] = "Bearer #{@token}"
+      end
+    end
+  end
+end

data/lib/manceps/auth/none.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Manceps
+  module Auth
+    # No-op auth strategy for unauthenticated connections.
+    class None
+      def apply(headers)
+        # no-op
+      end
+    end
+  end
+end

data/lib/manceps/auth/oauth.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'openssl'
+require 'base64'
+require 'securerandom'
+require 'uri'
+require 'json'
+
+module Manceps
+  module Auth
+    # OAuth 2.1 authentication with discovery, PKCE, and token refresh.
+    class OAuth
+      Discovery = Struct.new(
+        :authorization_url,
+        :token_url,
+        :registration_endpoint,
+        :client_id,
+        :client_secret,
+        :scopes,
+        keyword_init: true
+      )
+
+      attr_reader :access_token, :refresh_token, :expires_at
+
+      def initialize(
+        access_token:,
+        refresh_token: nil,
+        token_url: nil,
+        client_id: nil,
+        client_secret: nil,
+        expires_at: nil,
+        on_token_refresh: nil
+      )
+        @access_token = access_token
+        @refresh_token = refresh_token
+        @token_url = token_url
+        @client_id = client_id
+        @client_secret = client_secret
+        @expires_at = expires_at
+        @on_token_refresh = on_token_refresh
+        @mutex = Mutex.new
+      end
+
+      def apply(headers)
+        refresh_if_needed!
+        headers['authorization'] = "Bearer #{@access_token}"
+      end
+
+      # Fetch OAuth Authorization Server Metadata (RFC 8414) and optionally
+      # perform Dynamic Client Registration (RFC 7591).
+      def self.discover(server_url, redirect_uri:, client_name: 'Manceps')
+        server_uri = URI.parse(server_url)
+        port_suffix = [80, 443].include?(server_uri.port) ? '' : ":#{server_uri.port}"
+        well_known = "#{server_uri.scheme}://#{server_uri.host}#{port_suffix}/.well-known/oauth-authorization-server"
+
+        http = HTTPX.with(timeout: { connect_timeout: 10, request_timeout: 30 })
+        metadata = fetch_json(http.get(well_known), 'OAuth discovery')
+
+        discovery = Discovery.new(
+          authorization_url: metadata['authorization_endpoint'],
+          token_url: metadata['token_endpoint'],
+          registration_endpoint: metadata['registration_endpoint'],
+          scopes: metadata['scopes_supported']
+        )
+
+        register_client(http, discovery, redirect_uri, client_name)
+        discovery
+      end
+
+      def self.register_client(http, discovery, redirect_uri, client_name)
+        reg_endpoint = discovery.registration_endpoint
+        return if reg_endpoint.nil? || reg_endpoint.empty?
+
+        reg_response = http.post(
+          reg_endpoint,
+          headers: { 'content-type' => 'application/json' },
+          body: JSON.generate({
+                                client_name: client_name,
+                                redirect_uris: [redirect_uri],
+                                grant_types: %w[authorization_code refresh_token],
+                                response_types: ['code'],
+                                token_endpoint_auth_method: 'client_secret_post'
+                              })
+        )
+
+        reg_data = fetch_json(reg_response, 'Client registration')
+        unless reg_data['client_id']
+          raise Manceps::AuthenticationError,
+                "Client registration failed: #{reg_data['error']}"
+        end
+
+        discovery.client_id = reg_data['client_id']
+        discovery.client_secret = reg_data['client_secret']
+      end
+
+      def self.fetch_json(response, context)
+        if response.status >= 400
+          raise Manceps::AuthenticationError,
+                "#{context} failed (HTTP #{response.status})"
+        end
+
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        raise Manceps::AuthenticationError,
+              "#{context}: invalid response (not JSON): #{response.body.to_s[0..200]}"
+      end
+
+      # Build authorization URL for user redirect
+      def self.authorize_url(authorization_url:, client_id:, redirect_uri:, state:, scopes: nil, code_challenge: nil)
+        params = {
+          'response_type' => 'code',
+          'client_id' => client_id,
+          'redirect_uri' => redirect_uri,
+          'state' => state
+        }
+        params['scope'] = Array(scopes).join(' ') if !scopes.nil? && !Array(scopes).empty?
+        if code_challenge
+          params['code_challenge'] = code_challenge
+          params['code_challenge_method'] = 'S256'
+        end
+
+        "#{authorization_url}?#{URI.encode_www_form(params)}"
+      end
+
+      # Exchange authorization code for tokens
+      def self.exchange_code(token_url:, client_id:, code:, redirect_uri:, client_secret: nil, code_verifier: nil)
+        body = {
+          'grant_type' => 'authorization_code',
+          'code' => code,
+          'redirect_uri' => redirect_uri,
+          'client_id' => client_id
+        }
+        body['client_secret'] = client_secret if !client_secret.nil? && !client_secret.empty?
+        body['code_verifier'] = code_verifier if !code_verifier.nil? && !code_verifier.empty?
+
+        http = HTTPX.with(timeout: { connect_timeout: 10, request_timeout: 30 })
+        response = http.post(
+          token_url,
+          headers: { 'content-type' => 'application/x-www-form-urlencoded' },
+          body: URI.encode_www_form(body)
+        )
+
+        data = fetch_json(response, 'Token exchange')
+        unless data['access_token']
+          raise Manceps::AuthenticationError,
+                "Token exchange failed: #{data['error_description'] || data['error'] || 'no access_token'}"
+        end
+
+        data
+      end
+
+      # PKCE helpers (RFC 7636)
+      def self.generate_pkce
+        verifier = SecureRandom.urlsafe_base64(32)
+        challenge = Base64.urlsafe_encode64(
+          OpenSSL::Digest::SHA256.digest(verifier), padding: false
+        )
+        { verifier: verifier, challenge: challenge }
+      end
+
+      private
+
+      def refresh_if_needed!
+        return unless token_expiring_soon? && @refresh_token && @token_url
+
+        @mutex.synchronize do
+          return unless token_expiring_soon?
+
+          perform_token_refresh
+        end
+      end
+
+      def perform_token_refresh
+        body = { 'grant_type' => 'refresh_token', 'refresh_token' => @refresh_token, 'client_id' => @client_id }
+        body['client_secret'] = @client_secret if !@client_secret.nil? && !@client_secret.empty?
+
+        http = HTTPX.with(timeout: { connect_timeout: 10, request_timeout: 30 })
+        response = http.post(
+          @token_url,
+          headers: { 'content-type' => 'application/x-www-form-urlencoded' },
+          body: URI.encode_www_form(body)
+        )
+
+        data = self.class.fetch_json(response, 'Token refresh')
+        unless data['access_token']
+          raise Manceps::AuthenticationError,
+                "Token refresh failed: #{data['error'] || 'no access_token in response'}"
+        end
+
+        @access_token = data['access_token']
+        @refresh_token = data['refresh_token'] if data['refresh_token']
+        @expires_at = data['expires_in'] ? Time.now + data['expires_in'].to_i : nil
+
+        @on_token_refresh&.call(access_token: @access_token, refresh_token: @refresh_token, expires_at: @expires_at)
+      end
+
+      def token_expiring_soon?
+        @expires_at && @expires_at < Time.now + 300
+      end
+    end
+  end
+end

data/lib/manceps/backoff.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Manceps
+  # Exponential backoff calculator for retry logic.
+  class Backoff
+    def initialize(base: 1, max: 30, multiplier: 2, jitter: true)
+      @base = base
+      @max = max
+      @multiplier = multiplier
+      @jitter = jitter
+      @attempts = 0
+    end
+
+    def next_delay
+      delay = [@base * (@multiplier**@attempts), @max].min
+      delay *= rand(0.5..1.0) if @jitter
+      @attempts += 1
+      delay
+    end
+
+    def reset
+      @attempts = 0
+    end
+  end
+end