ask-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f1427ce9d98f71ef7654b7f8ac59cfd2c58940dbecf5d32525005e1af1e1a440
+  data.tar.gz: e4efdc1538eb707317ceb9f1fb2d06ba5b2e0f4903ee9a8eff7c094915d28d36
+SHA512:
+  metadata.gz: e18c000c2f9069f8648e1090c0283d33359ae451172b0c831fa60b7d3ccc980285ea963bda1e86cae26ffa35ac5cfea6b89a48da6ad84b34ac1fc492ce9de3bf
+  data.tar.gz: 1456d670425a9b6cfb1f0609f6af58b4b81ea1d10755b3f6c0c9d0f2e93b7cf146a6aecbcca1426fcb9e3387ab4a94b3320a3f4c21d5486935bacd6e7d27f6d8

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.1.0] - 2026-06-10
+
+### Added
+- Core MCP client with full JSON-RPC 2.0 message layer
+- stdio transport for local process MCP servers
+- SSE transport for remote Server-Sent Events MCP servers
+- Streamable HTTP transport for remote HTTP MCP servers
+- Tool, Resource, and Prompt data models with `from_h`/`to_h` serialization
+- Client lifecycle: initialize, capabilities discovery, session management
+- Tool calling, resource reading, and prompt retrieval
+- Token-based authentication (Bearer/Basic)
+- OAuth 2.1 authentication (client credentials + authorization code flows)
+- Ask::Tool adapter for integration with ask-agent
+- Thread-safe request/response matching with configurable timeouts
+- Server-side notifications handling (tools/resources/prompts list changed)
+- Comprehensive test suite with mock MCP server
+- Factory methods: `from_stdio`, `from_sse`, `from_http`, `connect`
+- Ability to cache or bypass caching for tools/resources/prompts

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kaka Ruto
+
+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,189 @@
+# ask-mcp
+
+[![Gem Version](https://badge.fury.io/rb/ask-mcp.svg)](https://badge.fury.io/rb/ask-mcp)
+
+**Model Context Protocol (MCP) client for Ruby.** Connect to MCP servers via
+stdio, SSE, or Streamable HTTP transports. Discover tools, resources, and
+prompts. Supports the full MCP protocol with OAuth 2.1 authentication.
+
+MCP is the industry standard for LLM tool discovery — the same protocol used by
+Claude Code, Codex, Cursor, and GitHub Copilot.
+
+## Installation
+
+```ruby
+gem "ask-mcp"
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "ask-mcp", "~> 0.1.0"
+```
+
+## Quick Start
+
+```ruby
+require "ask/mcp"
+
+# Connect to a local MCP server via stdio
+client = Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
+client.start
+
+# List available tools
+client.tools.each { |name, tool| puts "#{name}: #{tool.description}" }
+
+# Call a tool
+result = client.call_tool("read_file", path: "/tmp/test.txt")
+puts result
+
+# Clean up
+client.stop
+```
+
+## Transports
+
+```ruby
+# stdio — local processes
+Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-github"])
+
+# SSE — remote servers with Server-Sent Events
+Ask::MCP.from_sse("https://mcp.example.com/sse")
+
+# Streamable HTTP — remote servers
+Ask::MCP.from_http("https://mcp.example.com/mcp")
+```
+
+## API
+
+### Client Lifecycle
+
+```ruby
+# Create a client with any transport
+transport = Ask::MCP::Transport::Stdio.new("ruby", ["server.rb"])
+client = Ask::MCP::Client.new(transport, timeout: 30)
+
+# Start the session (sends initialize + receives capabilities)
+client.start
+
+# Use the client
+client.tools       # => { "tool_name" => #<Ask::MCP::Tool> }
+client.resources   # => { "resource_uri" => #<Ask::MCP::Resource> }
+client.prompts     # => { "prompt_name" => #<Ask::MCP::Prompt> }
+client.call_tool("tool_name", arg1: "value")
+client.read_resource("file:///path")
+client.get_prompt("prompt_name", arg1: "value")
+
+# Stop the session
+client.stop
+```
+
+### Tool, Resource, Prompt Objects
+
+```ruby
+# Tool
+tool = Ask::MCP::Tool.new(
+  name: "read_file",
+  description: "Read a file from disk",
+  input_schema: {
+    type: "object",
+    properties: { path: { type: "string" } },
+    required: ["path"]
+  }
+)
+tool.name         # => "read_file"
+tool.description  # => "Read a file from disk"
+tool.input_schema # => { type: "object", ... }
+
+# Resource
+resource = Ask::MCP::Resource.new(
+  uri: "file:///tmp/test.txt",
+  name: "Test File",
+  mime_type: "text/plain"
+)
+
+# Prompt
+prompt = Ask::MCP::Prompt.new(
+  name: "greet",
+  description: "Generate a greeting",
+  arguments: [{ name: "name", description: "Name to greet", required: true }]
+)
+```
+
+### Authentication
+
+```ruby
+# Token-based auth
+token = Ask::MCP::Auth::Token.new("my-api-token")
+headers = token.apply({})  # => { "Authorization" => "Bearer my-api-token" }
+
+# OAuth 2.1
+oauth = Ask::MCP::Auth::OAuth.new(
+  client_id: "my-client",
+  client_secret: "my-secret",
+  token_url: "https://auth.example.com/token",
+  scopes: ["mcp"]
+)
+oauth.authenticate!
+headers = oauth.apply({})
+```
+
+### With ask-agent
+
+```ruby
+require "ask/mcp"
+
+client = Ask::MCP.from_stdio("npx", ["-y", "@modelcontextprotocol/server-github"])
+client.start
+
+# Convert MCP tools to Ask::Tool instances for use with Ask::Agent
+client.tools.each do |name, mcp_tool|
+  agent.register_tool(mcp_tool.to_ask_tool)
+end
+
+# Or use the adapter directly
+wrapped = Ask::MCP::Adapters::AskTool.wrap(client.tools)
+wrapped.each { |name, adapter| agent.register_tool(adapter.to_ask_tool) }
+```
+
+## Architecture
+
+```
+ask-mcp/
+├── lib/ask/mcp.rb                         # Entry point, factory methods
+├── lib/ask/mcp/client.rb                  # MCP client (connect, call_tool, etc.)
+├── lib/ask/mcp/server.rb                  # MCP server representation
+├── lib/ask/mcp/tool.rb                    # MCP tool representation
+├── lib/ask/mcp/resource.rb                # MCP resource representation
+├── lib/ask/mcp/prompt.rb                  # MCP prompt representation
+├── lib/ask/mcp/native/messages.rb         # JSON-RPC message layer
+├── lib/ask/mcp/transport/
+│   ├── stdio.rb                           # stdio transport
+│   ├── sse.rb                             # Server-Sent Events transport
+│   └── streamable_http.rb                 # Streamable HTTP transport
+├── lib/ask/mcp/auth/
+│   ├── oauth.rb                           # OAuth 2.1 for MCP
+│   └── token.rb                           # Token-based auth
+└── lib/ask/mcp/adapters/
+    └── ask_tool.rb                        # MCP::Tool → Ask::Tool adapter
+```
+
+## Development
+
+```bash
+# Run tests
+bundle exec rake test
+
+# Run specific tests
+bundle exec ruby -Itest test/messages_test.rb
+bundle exec ruby -Itest test/stdio_integration_test.rb
+```
+
+## License
+
+MIT
+
+## Authentication
+
+See the [Auth Setup Guide](docs/auth-setup.md) for detailed documentation on
+token-based and OAuth 2.1 authentication, including ask-auth integration.

data/docs/auth-setup.md

@@ -0,0 +1,141 @@
+# Authentication Setup
+
+ask-mcp supports two authentication methods for connecting to MCP servers that
+require authorization: **Token-based auth** and **OAuth 2.1**.
+
+## Token Authentication
+
+Use for servers with simple API tokens or bearer tokens.
+
+```ruby
+require "ask/mcp"
+
+token = Ask::MCP::Auth::Token.new("my-api-token")
+headers = token.apply({})
+# => { "Authorization" => "Bearer my-api-token" }
+
+# Custom scheme
+basic = Ask::MCP::Auth::Token.new("base64encoded", scheme: "Basic")
+headers = basic.apply({})
+# => { "Authorization" => "Basic base64encoded" }
+```
+
+### Applying to Transports
+
+```ruby
+# With SSE transport
+token = Ask::MCP::Auth::Token.new("my-token")
+client = Ask::MCP.from_sse("https://mcp.example.com/sse",
+  headers: token.apply({})
+)
+
+# With Streamable HTTP transport
+client = Ask::MCP.from_http("https://mcp.example.com/mcp",
+  headers: token.apply({})
+)
+```
+
+## OAuth 2.1
+
+Use for servers that implement the OAuth 2.1 authorization framework.
+
+### Client Credentials Flow
+
+For server-to-server communication where you have a client secret:
+
+```ruby
+oauth = Ask::MCP::Auth::OAuth.new(
+  client_id: "your-client-id",
+  client_secret: "your-client-secret",
+  token_url: "https://auth.example.com/token",
+  scopes: ["mcp"]
+)
+
+oauth.authenticate!
+headers = oauth.apply({})
+# => { "Authorization" => "Bearer eyJhbGciOi..." }
+```
+
+### Authorization Code Flow
+
+For user-facing applications that need delegated access:
+
+```ruby
+oauth = Ask::MCP::Auth::OAuth.new(
+  client_id: "your-client-id",
+  token_url: "https://auth.example.com/token",
+  auth_url: "https://auth.example.com/authorize",
+  redirect_uri: "http://localhost:3000/callback",
+  scopes: ["mcp"]
+)
+
+# This opens the authorization URL for the user to approve
+oauth.authenticate!
+```
+
+### Token Refresh
+
+OAuth tokens are automatically refreshed when expired:
+
+```ruby
+oauth.authenticate!
+# ... use the token ...
+
+# When the token expires, refresh it:
+oauth.refresh!
+```
+
+## With ask-auth
+
+If you're using `ask-auth` for credential resolution:
+
+```ruby
+require "ask-auth"
+require "ask/mcp"
+
+# Resolve credentials from ask-auth chain (env → file → rails)
+token = Ask::Auth.resolve(:mcp_token)
+if token
+  auth = Ask::MCP::Auth::Token.new(token)
+  client = Ask::MCP.from_sse("https://mcp.example.com/sse",
+    headers: auth.apply({})
+  )
+end
+```
+
+For OAuth credentials:
+
+```ruby
+client_id = Ask::Auth.resolve(:mcp_client_id)
+client_secret = Ask::Auth.resolve(:mcp_client_secret)
+token_url = Ask::Auth.resolve(:mcp_token_url)
+
+oauth = Ask::MCP::Auth::OAuth.new(
+  client_id: client_id,
+  client_secret: client_secret,
+  token_url: token_url
+)
+oauth.authenticate!
+```
+
+## Configuration File
+
+You can store credentials in `~/.ask/credentials.yml` for use with ask-auth:
+
+```yaml
+mcp_token: "my-mcp-server-token"
+mcp_client_id: "my-client-id"
+mcp_client_secret: "my-client-secret"
+mcp_token_url: "https://auth.example.com/token"
+```
+
+## Environment Variables
+
+ask-auth detects these environment variables automatically:
+
+```
+MCP_TOKEN=my-token
+MCP_CLIENT_ID=my-client-id
+MCP_CLIENT_SECRET=my-client-secret
+MCP_TOKEN_URL=https://auth.example.com/token
+```

data/lib/ask/mcp/adapters/ask_tool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ask
+  module MCP
+    module Adapters
+      class AskTool
+        def initialize(mcp_tool)
+          @mcp_tool = mcp_tool
+        end
+
+        def name
+          @mcp_tool.name
+        end
+
+        def description
+          @mcp_tool.description
+        end
+
+        def parameters
+          @mcp_tool.input_schema
+        end
+
+        def to_ask_tool
+          require "ask/tools/tool"
+
+          Ask::Tools::Tool.new(
+            name: @mcp_tool.name,
+            description: @mcp_tool.description,
+            parameters: @mcp_tool.input_schema
+          )
+        end
+
+        def self.from(mcp_tool)
+          new(mcp_tool)
+        end
+
+        def self.wrap(tools_hash)
+          tools_hash.transform_values { |tool| new(tool) }
+        end
+      end
+    end
+  end
+end

data/lib/ask/mcp/auth/oauth.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Ask
+  module MCP
+    module Auth
+      class OAuth
+        attr_reader :client_id, :client_secret, :token_url, :auth_url
+
+        def initialize(client_id:, client_secret: nil, token_url:, auth_url: nil,
+                       redirect_uri: nil, scopes: [])
+          @client_id = client_id
+          @client_secret = client_secret
+          @token_url = token_url
+          @auth_url = auth_url
+          @redirect_uri = redirect_uri
+          @scopes = scopes
+          @access_token = nil
+          @refresh_token = nil
+          @expires_at = nil
+        end
+
+        def authenticated?
+          !@access_token.nil? && !expired?
+        end
+
+        def apply(headers = {})
+          headers.merge("Authorization" => "Bearer #{@access_token}")
+        end
+
+        def authenticate!
+          if @client_secret
+            authenticate_client_credentials
+          elsif @auth_url
+            authenticate_authorization_code
+          else
+            raise AuthError, "No authentication method available"
+          end
+          self
+        end
+
+        def refresh!
+          raise AuthError, "No refresh token available" unless @refresh_token
+          perform_token_refresh
+          self
+        end
+
+        private
+
+        def expired?
+          @expires_at && Time.now >= @expires_at
+        end
+
+        def authenticate_client_credentials
+          require "httpx"
+
+          response = HTTPX.post(@token_url, json: {
+            grant_type: "client_credentials",
+            client_id: @client_id,
+            client_secret: @client_secret,
+            scope: @scopes.join(" ") || "mcp"
+          })
+
+          handle_token_response(response)
+        end
+
+        def authenticate_authorization_code
+          raise AuthError, "Authorization code flow requires a redirect URI" unless @redirect_uri
+          raise AuthError, "Authorization code flow must be completed interactively"
+
+          # The authorization code flow requires user interaction.
+          # This is a placeholder for the interactive flow that would:
+          # 1. Open the auth URL in a browser
+          # 2. Listen for the redirect with the auth code
+          # 3. Exchange the code for tokens
+        end
+
+        def perform_token_refresh
+          require "httpx"
+
+          response = HTTPX.post(@token_url, json: {
+            grant_type: "refresh_token",
+            refresh_token: @refresh_token,
+            client_id: @client_id,
+            client_secret: @client_secret
+          })
+
+          handle_token_response(response)
+        end
+
+        def handle_token_response(response)
+          unless response.status == 200
+            raise AuthError, "Token request failed: #{response.status} #{response.body.to_s[0..200]}"
+          end
+
+          data = JSON.parse(response.body.to_s, symbolize_names: true)
+          @access_token = data[:access_token]
+          @refresh_token = data[:refresh_token]
+          @expires_at = data[:expires_in] ? Time.now + data[:expires_in].to_i : nil
+        rescue JSON::ParserError => e
+          raise AuthError, "Invalid token response: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/ask/mcp/auth/token.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ask
+  module MCP
+    module Auth
+      class Token
+        attr_reader :token, :scheme
+
+        def initialize(token, scheme: "Bearer")
+          @token = token
+          @scheme = scheme
+        end
+
+        def apply(headers = {})
+          headers.merge("Authorization" => "#{@scheme} #{@token}")
+        end
+
+        def to_s
+          "#{@scheme} #{@token[0..7]}..."
+        end
+      end
+    end
+  end
+end