kailash 4.2.0-aarch64-linux → 4.3.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83264505ee8447fa0e0d675d5bacb1d45d3f2c71b68a3fb1568c8e43f2bb18e9
-  data.tar.gz: 5f7d25ec46a8ef7c0ce156c1b11ed9d4f219c1b7796a0de576556e862a9356a1
+  metadata.gz: 7b8f6e5e693eeabb267e902de1218f2748d33b22c9e8f8bf1802372b5f08526f
+  data.tar.gz: 310ecfe3c01d34e9912b25b28f2964884515d963696992b9480a5c59021eabf8
 SHA512:
-  metadata.gz: 57bad5eacd868d37784c151364010cdfb82f483c42e12128fc58355416720abed4303d9c970c75a5756d30a897c809442b847bc2a0fd6c05eee3c3402b13d598
-  data.tar.gz: cd33c2871b018ba5f18339781ef3fb86521f2876ba7ae15f830b5ddbfc4de9207aea067722af6fc874123becad86bdb55b2af62f4c0c2ec6bf94c5c3d180bf02
+  metadata.gz: c6d4682db7446fb31837bddde8738626e1dc33f65c33390d44ce73ea5a56db040f07735fcf264bb9f27637ae11e2ca27feb980d403e8db0aa7e6afce0d41e63e
+  data.tar.gz: b66927ba5a60f918174a7cdebe4c57f6d8a5e4ec6af0d70f5079445c7101f645fd6704a2132148d44ab5eda83e8f4ce8f8b00c1691c66c46d0036dd59fca2c26

data/lib/kailash/mcp.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Kailash
+  # MCP (Model Context Protocol) module — Ruby bindings for the canonical
+  # MCP types exposed by the underlying `kailash_mcp` Rust crate.
+  #
+  # Four layers ship under this namespace:
+  #
+  # 1. **Info types** (defined in the native extension, mirror Python / Node):
+  #    - `Kailash::Mcp::McpToolInfo`         — `tools/list` entry
+  #    - `Kailash::Mcp::McpResourceInfo`     — `resources/list` entry
+  #    - `Kailash::Mcp::ServerCapabilities`  — `initialize` capability flags
+  #    - `Kailash::Mcp::ServerInfo`          — full `initialize` payload
+  #
+  # 2. **Elicitation** (gated on the `_gvl_release` build feature, default ON):
+  #    - `Kailash::Mcp::ElicitationSystem`   — MCP 2025-06-18 server→client
+  #                                             `elicitation/create` round-trips
+  #
+  # 3. **Server / client / auth surface** (Wave-3c W3.5b + F15):
+  #    - `Kailash::Mcp::McpServer`           — catalog-backed MCP server
+  #    - `Kailash::Mcp::McpClient`           — in-memory client (pairs with McpServer)
+  #    - `Kailash::Mcp::OAuth2Client`        — OAuth 2.1 + PKCE client (sync flow-setup
+  #                                             + async token redemption; see below)
+  #    - `Kailash::Mcp::PermissionManager`   — fine-grained scope→tool RBAC
+  #
+  # **Current W3.5b limitation (visible deferral, NOT a silent stub):**
+  #
+  # - **Tool-callback dispatch** — `McpServer.register_tool` accepts a Ruby
+  #   block, but the tool invocation path through `_ruby_catalog_stub` echoes
+  #   the request and does NOT yet route the Ruby block as the response body.
+  #   Real Ruby-callback dispatch lands after the cross-binding W0-CALLBACK
+  #   shard wires async dispatch through the capi callback ABI.
+  #
+  # **OAuth2Client surface (sync + async, F15 complete):**
+  #
+  # Sync surfaces (PKCE flow setup + state verification; see registration at
+  # `bindings/kailash-ruby/ext/kailash/src/mcp_server.rs:1714-1721`):
+  #   `new`, `client_id`, `token_endpoint`, `build_authorization_request`,
+  #   `verify_state`, plus lifecycle (`close`, `closed?`, `inspect`, `to_s`
+  #   at `bindings/kailash-ruby/ext/kailash/src/mcp_server.rs:1735-1738`).
+  #
+  # Async surfaces (token redemption + revocation, F15; see registration at
+  # `bindings/kailash-ruby/ext/kailash/src/mcp_server.rs:1722-1734`):
+  #   `redeem_authorization_code(code, verifier)` — RFC 6749 § 4.1.3
+  #   `refresh_token(refresh_token)`              — RFC 6749 § 6
+  #   `cache_token(key, token_hash)`              — persist for later retrieval
+  #   `get_valid_token(key)`                      — auto-refresh on expiry
+  #   `revoke_token(endpoint, token, hint)`       — RFC 7009
+  #
+  # Each async method blocks on a per-call tokio runtime (mirrors the
+  # capi `build_runtime` pattern) and releases the GVL so other Ruby
+  # threads run concurrently. Token-response Hashes carry the canonical
+  # OAuth2 shape (`access_token`, `token_type`, `expires_in`,
+  # `refresh_token`, `scope`, `id_token`, `expires_at`).
+  #
+  # 4. **Exception hierarchy** (also defined by `elicitation_system`):
+  #    - `Kailash::Mcp::RequestCancelled`
+  #    - `Kailash::Mcp::SchemaValidation`
+  #    - `Kailash::Mcp::ElicitationTimeout`
+  #    - `Kailash::Mcp::TransportRebound`
+  #
+  # ## Examples
+  #
+  # Build a tool descriptor for a tools/list response:
+  #
+  #   tool = Kailash::Mcp::McpToolInfo.new("search", "Search the web")
+  #   tool.to_json
+  #   # => '{"name":"search","description":"Search the web","inputSchema":{}}'
+  #
+  # Build a resource descriptor with keyword args:
+  #
+  #   res = Kailash::Mcp::McpResourceInfo.new(
+  #     "cfg://settings",
+  #     "Settings",
+  #     description: "Application settings",
+  #     mime_type: "application/json",
+  #   )
+  #
+  # Block-based server lifecycle:
+  #
+  #   Kailash::Mcp::McpServer.open(name: "my-server", version: "1.0.0") do |srv|
+  #     srv.register_tool(name: "search", description: "Search the web")
+  #     srv.register_resource(uri: "doc://1", name: "Doc 1")
+  #     # ... use srv ...
+  #   end   # srv automatically closed at block exit
+  #
+  module Mcp
+    # Keyword-arg convenience constructor for `McpResourceInfo`. The native
+    # `McpResourceInfo.new` now accepts keyword args directly; this helper
+    # is preserved for back-compat with code written against the previous
+    # API and as a documented entry point for the keyword form.
+    #
+    # @param uri [String] resource URI (required)
+    # @param name [String] human-readable name (required)
+    # @param description [String, nil] optional description
+    # @param mime_type [String, nil] optional MIME type
+    # @return [Kailash::Mcp::McpResourceInfo]
+    def self.resource(uri:, name:, description: nil, mime_type: nil)
+      McpResourceInfo.new(uri, name, description: description, mime_type: mime_type)
+    end
+
+    # Convenience: predicate-only summary of a `ServerCapabilities`. Returns
+    # a Hash with boolean values, useful for logging the server handshake.
+    #
+    #   caps = Kailash::Mcp::ServerCapabilities.from_json('{"tools":{}}')
+    #   Kailash::Mcp.capability_summary(caps)
+    #   # => { tools: true, resources: false, prompts: false, elicitation: false }
+    #
+    # @param caps [Kailash::Mcp::ServerCapabilities]
+    # @return [Hash{Symbol => Boolean}]
+    def self.capability_summary(caps)
+      {
+        tools: caps.has_tools?,
+        resources: caps.has_resources?,
+        prompts: caps.has_prompts?,
+        elicitation: caps.has_elicitation?,
+      }
+    end
+
+    # `McpServer` block-based lifecycle (Ruby idiom matching File.open /
+    # Registry.open). Yields a fresh `McpServer` to the block and calls
+    # `close` automatically when the block returns. Returns the block's
+    # value.
+    #
+    #   Kailash::Mcp::McpServer.open(name: "srv", version: "1.0") do |srv|
+    #     srv.register_tool(name: "search", description: "...")
+    #     srv
+    #   end
+    #
+    # When called WITHOUT a block, returns the constructed `McpServer`
+    # (equivalent to `McpServer.new` — caller MUST `close` explicitly).
+    class McpServer
+      def self.open(*args, **kwargs)
+        srv = if kwargs.empty?
+                new(*args)
+              elsif args.empty?
+                new(kwargs)
+              else
+                new(*args, kwargs)
+              end
+        return srv unless block_given?
+
+        begin
+          yield srv
+        ensure
+          srv.close
+        end
+      end
+    end
+
+    # `McpClient` block-based lifecycle. Same shape as `McpServer.open`.
+    #
+    #   Kailash::Mcp::McpClient.open(server: srv) do |client|
+    #     # ... use client ...
+    #   end
+    class McpClient
+      def self.open(*args, **kwargs)
+        client = if kwargs.empty?
+                   new(*args)
+                 elsif args.empty?
+                   new(kwargs)
+                 else
+                   new(*args, kwargs)
+                 end
+        return client unless block_given?
+
+        begin
+          yield client
+        ensure
+          client.close
+        end
+      end
+    end
+
+    # `OAuth2Client` block-based lifecycle.
+    #
+    #   Kailash::Mcp::OAuth2Client.open(client_id: "...", token_endpoint: "...") do |oauth|
+    #     # ... use oauth ...
+    #   end
+    class OAuth2Client
+      def self.open(**kwargs, &_block)
+        oauth = new(kwargs)
+        return oauth unless block_given?
+
+        begin
+          yield oauth
+        ensure
+          oauth.close
+        end
+      end
+    end
+
+    # `PermissionManager` block-based lifecycle.
+    class PermissionManager
+      def self.open(&_block)
+        pm = new
+        return pm unless block_given?
+
+        begin
+          yield pm
+        ensure
+          pm.close
+        end
+      end
+    end
+  end
+end

data/lib/kailash.rb

@@ -9,6 +9,13 @@ rescue LoadError
   require "kailash/kailash"
 end
 
+# Pure-Ruby convenience layer on top of the native MCP type wrappers
+# (Kailash::Mcp::McpToolInfo / McpResourceInfo / ServerCapabilities /
+# ServerInfo are defined by the native extension; this file adds the
+# keyword-arg helper `Kailash::Mcp.resource(...)` and a capability-
+# summary helper for logging).
+require_relative "kailash/mcp"
+
 module Kailash
   module Nexus
     # Typed exception a `handler_extract` callable raises to emit a

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kailash
 version: !ruby/object:Gem::Version
-  version: 4.2.0
+  version: 4.3.0
 platform: aarch64-linux
 authors:
 - Kailash Authors
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-16 00:00:00.000000000 Z
+date: 2026-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -48,6 +48,7 @@ files:
 - README.md
 - lib/kailash.rb
 - lib/kailash/kailash.so
+- lib/kailash/mcp.rb
 - lib/kailash/trust_plane.rb
 - lib/kailash/version.rb
 homepage: https://github.com/kailash/kailash