ask-mcp 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f8dc795c9584e225ffb354888e3c2694ec2a5f2378498fa6f1046023aa8b8a6
-  data.tar.gz: aa580507f8d318f224a09a57e1d8cbca372ff95a05a1fb8c54463be8dd21c483
+  metadata.gz: 90e04370e4d5b1136abb513220b68beb46a5ca2c74d8f7ca694fa59297f8f32e
+  data.tar.gz: 17f2accea77cefc0ea51fedcc3879e219fff47760999b0ba39e0e168d30dbfe1
 SHA512:
-  metadata.gz: ed50f3c8de7c5902afd35c29073480b6a34c7f97af24ff5942a2ad38cdd2e0adf9db53698a35ec0c22b985f9957aa9fd5bc3b92cba37afbb4f30b802077aaeb7
-  data.tar.gz: 367d7ff2f4523bfa42af5a261dcdbb2e6157753da05b430652439b4f4f9468a94cf517872563d1509100ebdfa51eb2b41b47c0fa21bde502dbc9372af4cd9a15
+  metadata.gz: d8a481b9467e8f4d6d4d305da61346855f4d27ac94de77f109ac528e704599c18aee5a9c5deb64f7edb71a71b4e446cc1801149df21891d15eefdcb441eb1d09
+  data.tar.gz: b78ccc9a910fbfbeaf2e273ce6169279e4195624871f89356d6564ab6cd46380dd876951544e90b2f3b3b57328ae00180c6d218e1d66afa5416090c5703e1560

data/CHANGELOG.md

@@ -1,24 +1,37 @@
+## [0.3.0] - 2026-06-26
+
+### Changed
+- Renamed `Adapters::AskToolServer` → `Adapters::ToolServer` — the adapter is
+  now duck-typed and works with any Ruby object, not just Ask::Tool instances.
+- README fully rewritten: leads with a general-purpose duck-typed server example
+  instead of ask-tools-specific code. ask-rb integration is now a sub-section.
+- Gemspec description updated to reflect general-purpose positioning.
+
+## [0.2.0] - 2026-06-26
+
+### Added
+- Server Runtime: `Ask::MCP::Server::Stdio` — run as an MCP server over stdio
+  with full initialize handshake, tool discovery, and tool call dispatch.
+- `Adapters::AskToolServer` — converts tools to MCP definitions and dispatches calls.
+- `Ask::MCP::Server.start_stdio` entry point for easy one-line server setup.
+
+### Changed
+- 56 new tests across adapter, server stdio, integration, and start_stdio (170 total).
+
 ## [0.1.1] - 2026-06-25
 
 ### Changed
-- Major test expansion: Transport tests (SSE/Stdio/StreamableHTTP), MessagesParser, OAuth, Client(17t with cache invalidation), Server(7t), Tool(8t), Messages(17t with serialization), integration tests(7t with mock server). Infrastructure: rubocop, overcommit, CI matrix, gemspec, SimpleCov.
-# Changelog
+- Major test expansion: Transport tests, MessagesParser, OAuth, Client, Server, Tool, Messages, integration. Rubocop, overcommit, CI matrix, SimpleCov.
 
 ## [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
+- stdio, SSE, and Streamable HTTP transports
+- Tool, Resource, and Prompt data models
+- Client lifecycle, tool calling, resource reading, prompt retrieval
+- Token-based and OAuth 2.1 authentication
+- Ask::Tool adapter for ask-agent integration
 - Thread-safe request/response matching with configurable timeouts
-- Server-side notifications handling (tools/resources/prompts list changed)
-- Comprehensive test suite with mock MCP server
+- Server-side notifications handling
 - Factory methods: `from_stdio`, `from_sse`, `from_http`, `connect`
-- Ability to cache or bypass caching for tools/resources/prompts

data/README.md

@@ -2,9 +2,10 @@
 
 [![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.
+**Model Context Protocol (MCP) client and server for Ruby.** Connect to MCP
+servers via stdio, SSE, or Streamable HTTP transports. Run as an MCP server
+to expose your own tools to any MCP client. No framework lock-in — just
+implement a couple of duck-typed methods and you're done.
 
 MCP is the industry standard for LLM tool discovery — the same protocol used by
 Claude Code, Codex, Cursor, and GitHub Copilot.
@@ -21,26 +22,112 @@ Or add to your Gemfile:
 gem "ask-mcp", "~> 0.1.0"
 ```
 
-## Quick Start
+## Quick Start — Client
+
+Connect to any MCP server and call its tools:
 
 ```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
 ```
 
+## Quick Start — Server
+
+Run as a standalone MCP server exposing your own tools to any MCP client
+(Codex, Claude Code, Cursor, etc.). Any object that responds to `name`,
+`description`, `params_schema`, and `call(args)` will work:
+
+```ruby
+require "ask/mcp"
+
+# Define your tools — no base class needed, just duck typing
+class Greeter
+  def name; "greet" end
+  def description; "Greets someone by name" end
+  def params_schema
+    { type: "object", properties: { "name" => { "type" => "string" } }, required: ["name"] }
+  end
+  def call(args = {})
+    "Hello, #{args['name']}!"
+  end
+end
+
+# Start the server (blocking — runs until stdin closes)
+Ask::MCP::Server.start_stdio(
+  name: "my-server",
+  tools: [Greeter.new]
+)
+```
+
+Configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "ruby",
+      "args": ["/path/to/your/server.rb"]
+    }
+  }
+}
+```
+
+Tools can return any value the client can use. The server automatically wraps
+the result into MCP's `content` array format.
+
+### What about complex tools?
+
+The result object from `call(args)` should respond to `ok?` (or `ok`) and
+`output` / `error_message`. Use `OpenStruct` for simple cases:
+
+```ruby
+require "ostruct"
+
+class BashTool
+  def name; "bash" end
+  def description; "Run a shell command" end
+  def params_schema
+    { type: "object", properties: { "command" => { "type" => "string" } }, required: ["command"] }
+  end
+  def call(args = {})
+    output = `#{args['command']} 2>&1`
+    OpenStruct.new(ok?: true, output: output)
+  rescue => e
+    OpenStruct.new(ok?: false, error_message: e.message)
+  end
+end
+```
+
+For a production example with shell tools, file ops, and web search,
+see [llm-proxy](https://github.com/ask-rb/llm-proxy).
+
+### Using with ask-tools
+
+If you use the ask-rb ecosystem, you can expose Ask::Tool subclasses directly:
+
+```ruby
+require "ask/mcp"
+require "ask-tools-shell"
+require "ask-web-search"
+
+tools = Ask::Tools::Shell::TOOLS.map(&:new) + [Ask::Tools::WebSearch.new]
+
+Ask::MCP::Server.start_stdio(
+  name: "my-server",
+  tools: tools,
+  capabilities: { tools: {} }
+)
+```
+
 ## Transports
 
 ```ruby
@@ -152,20 +239,22 @@ wrapped.each { |name, adapter| agent.register_tool(adapter.to_ask_tool) }
 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/server.rb                  # MCP server representation + Server.start_stdio entry point
+├── lib/ask/mcp/server/stdio.rb            # MCP server stdio runtime (run as server)
 ├── 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
+│   ├── stdio.rb                           # stdio transport (client direction)
 │   ├── 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
+    ├── ask_tool.rb                        # MCP::Tool → Ask::Tool adapter
+    └── tool_server.rb                     # Duck-typed tools → MCP server adapter
 ```
 
 ## Development

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Ask
+  module MCP
+    module Adapters
+      # Converts duck-typed tool objects into MCP tool definitions and dispatches
+      # calls. This is the server-direction adapter — it takes any objects that
+      # respond to +name+, +description+, +params_schema+, and +call(args)+ and
+      # exposes them over MCP.
+      #
+      # Usage:
+      #   class MyTool
+      #     def name; "hello" end
+      #     def description; "Says hello" end
+      #     def params_schema; nil end
+      #     def call(args = {}); OpenStruct.new(ok?: true, output: "Hello!") end
+      #   end
+      #
+      #   adapter = ToolServer.new([MyTool.new])
+      #   adapter.definitions  # => [{ name: "hello", ... }]
+      #   adapter.call("hello", {})  # => { content: [...], isError: false }
+      class ToolServer
+        attr_reader :tools
+
+        # @param tools [Array<#call, #name, #description, #params_schema>] tool instances to expose
+        def initialize(tools = [])
+          @tools = tools
+          @tool_map = tools.each_with_object({}) { |t, h| h[t.name] = t }
+        end
+
+        # MCP tool definitions for tools/list
+        # @return [Array<Hash>]
+        def definitions
+          @tools.map do |tool|
+            schema = tool.params_schema || { type: "object", properties: {}, required: [] }
+            {
+              name: tool.name,
+              description: tool.description || "",
+              inputSchema: schema
+            }
+          end
+        end
+
+        # Call a tool and wrap the result in MCP format
+        # @param name [String] tool name
+        # @param arguments [Hash] arguments (may have symbol or string keys)
+        # @return [Hash] { content: [...], isError: true/false }
+        def call(name, arguments = {})
+          tool = @tool_map[name]
+          unless tool
+            return error_result("Tool not found: #{name}")
+          end
+
+          normalized = deep_stringify_keys(arguments)
+          result = tool.call(normalized)
+          wrap_result(result)
+        rescue StandardError => e
+          if defined?(Ask::Tool::Halt) && e.is_a?(Ask::Tool::Halt)
+            return { content: [{ type: "text", text: e.content.to_s }], isError: false }
+          end
+          error_result("#{e.class}: #{e.message}")
+        end
+
+        private
+
+        def wrap_result(result)
+          if result.respond_to?(:ok?) ? result.ok? : result.ok
+            output = result.respond_to?(:output) ? result.output : result.to_s
+            text = output.is_a?(Hash) ? (output[:summary] || output.to_s) : output.to_s
+            { content: [{ type: "text", text: text }], isError: false }
+          else
+            msg = result.respond_to?(:error_message) ? result.error_message : result.to_s
+            { content: [{ type: "text", text: "Error: #{msg}" }], isError: true }
+          end
+        end
+
+        def error_result(message)
+          { content: [{ type: "text", text: message }], isError: true }
+        end
+
+        def deep_stringify_keys(obj)
+          case obj
+          when Hash then obj.each_with_object({}) { |(k, v), h| h[k.to_s] = deep_stringify_keys(v) }
+          when Array then obj.map { |v| deep_stringify_keys(v) }
+          else obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/mcp/server/stdio.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ask
+  module MCP
+    class Server
+      # MCP server over stdio transport.
+      #
+      # Reads JSON-RPC 2.0 messages from stdin and writes responses to stdout.
+      # Designed to be spawned as a child process by MCP clients (Codex Desktop,
+      # Claude Code, etc.) with command/args config.
+      #
+      # Usage:
+      #   Server::Stdio.new(name: "my-server", tools: my_tools).start
+      #
+      class Stdio
+        PROTOCOL_VERSION = "0.1.0"
+
+        attr_reader :name, :tools, :capabilities, :resources, :prompts
+
+        def initialize(name:, tools: [], capabilities: {}, resources: {}, prompts: {}, debug: false)
+          @name = name
+          @capabilities = capabilities
+          @resources = resources
+          @prompts = prompts
+          @debug = debug
+
+          @adapter = Adapters::ToolServer.new(tools || [])
+          @initialized = false
+          @running = false
+        end
+
+        # Start the server (blocking). Processes stdin until EOF.
+        def start
+          @running = true
+          $stdout.sync = true
+
+          debug_log "Server starting: #{@name} (PID #{Process.pid})"
+          debug_log "Tools: #{@adapter.definitions.map { |d| d[:name] }.join(', ')}"
+
+          while @running && (line = $stdin.gets)
+            line = line.strip
+            next if line.empty?
+
+            process_line(line)
+          end
+
+          debug_log "stdin closed — exiting"
+        rescue Errno::EBADF, IOError
+          # stdin closed externally
+        ensure
+          @running = false
+        end
+
+        # Stop the server (non-blocking, closes stdin to unblock the read loop).
+        def stop
+          @running = false
+        end
+
+        # Is the server still running?
+        def running?
+          @running
+        end
+
+        private
+
+        def process_line(line)
+          msg = JSON.parse(line, symbolize_names: true)
+          handle_message(msg)
+        rescue JSON::ParserError => e
+          send_error(nil, -32700, "Parse error: #{e.message}")
+        end
+
+        def handle_message(msg)
+          method = msg[:method]
+          id = msg[:id]
+          params = msg[:params] || {}
+          has_id = msg.key?(:id)
+
+          case method
+          when "initialize"
+            handle_initialize(id, params)
+          when "notifications/initialized"
+            @initialized = true
+            debug_log "Client initialized"
+          when "tools/list"
+            return send_error(id, -32000, "Server not initialized") unless @initialized
+            handle_tools_list(id)
+          when "tools/call"
+            return send_error(id, -32000, "Server not initialized") unless @initialized
+            handle_tool_call(id, params)
+          else
+            debug_log "Unknown method: #{method}"
+            send_error(id, -32601, "Method not found: #{method}") if has_id
+          end
+        end
+
+        def handle_initialize(id, _params)
+          @initialized = true
+          debug_log "Handling initialize (id=#{id.inspect})"
+          send_result(id, {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: @capabilities,
+            serverInfo: {
+              name: @name,
+              version: Ask::MCP::VERSION
+            }
+          })
+          debug_log "Initialize complete"
+        end
+
+        def handle_tools_list(id)
+          debug_log "Handling tools/list (id=#{id.inspect})"
+          defs = @adapter.definitions
+          debug_log "tools/list returning #{defs.length} tool definitions"
+          send_result(id, { tools: defs })
+        end
+
+        def handle_tool_call(id, params)
+          tool_name = params[:name].to_s
+          arguments = params[:arguments] || {}
+
+          debug_log "Handling tools/call: #{tool_name} (id=#{id.inspect})"
+
+          result = @adapter.call(tool_name, arguments)
+          send_result(id, result)
+        end
+
+        def send_result(id, result)
+          $stdout.puts({ jsonrpc: "2.0", id: id, result: result }.to_json)
+        end
+
+        def send_error(id, code, message)
+          $stdout.puts({ jsonrpc: "2.0", id: id, error: { code: code, message: message } }.to_json)
+        end
+
+        def debug_log(msg)
+          return unless @debug
+          ts = Time.now.strftime("%H:%M:%S.%L")
+          $stderr.puts "[#{ts}] [ask-mcp] #{msg}"
+        end
+      end
+    end
+  end
+end

data/lib/ask/mcp/server.rb

@@ -36,6 +36,20 @@ module Ask
           prompts: @prompts.values.map(&:to_h)
         }
       end
+
+      # Start an MCP server over stdio.
+      # Blocking — designed to be the last line of an entry-point script.
+      #
+      # @param name [String] server name
+      # @param tools [Array<#call, #name, #description, #params_schema>] tool instances to expose
+      # @param capabilities [Hash] MCP capabilities (default: { tools: {} })
+      # @param debug [Boolean] enable stderr debug logging
+      def self.start_stdio(name:, tools: [], capabilities: { tools: {} }, debug: false)
+        Stdio.new(name: name, tools: tools, capabilities: capabilities, debug: debug).start
+      end
     end
   end
 end
+
+# Load Server subclasses after the Server class is defined
+require_relative "server/stdio"

data/lib/ask/mcp/version.rb

@@ -1,5 +1,5 @@
 module Ask
   module MCP
-    VERSION = "0.1.1"
+    VERSION = "0.3.0"
   end
 end

data/lib/ask/mcp.rb

@@ -28,6 +28,7 @@ module Ask
 
     module Adapters
       autoload :AskTool, "ask/mcp/adapters/ask_tool"
+      autoload :ToolServer, "ask/mcp/adapters/tool_server"
     end
 
     class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -80,8 +80,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 description: Connect to MCP servers via stdio, SSE, and Streamable HTTP transports.
-  Discover tools, resources, and prompts. OAuth 2.1 authentication. Convert MCP tools
-  to Ask::Tool instances. Supports the full MCP spec.
+  Run as an MCP server exposing any Ruby object as a tool. Discover tools, resources,
+  and prompts. OAuth 2.1 authentication.
 email:
 - kaka@myrrlabs.com
 executables: []
@@ -95,6 +95,7 @@ files:
 - lib/ask-mcp.rb
 - lib/ask/mcp.rb
 - lib/ask/mcp/adapters/ask_tool.rb
+- lib/ask/mcp/adapters/tool_server.rb
 - lib/ask/mcp/auth/oauth.rb
 - lib/ask/mcp/auth/token.rb
 - lib/ask/mcp/client.rb
@@ -102,6 +103,7 @@ files:
 - lib/ask/mcp/prompt.rb
 - lib/ask/mcp/resource.rb
 - lib/ask/mcp/server.rb
+- lib/ask/mcp/server/stdio.rb
 - lib/ask/mcp/tool.rb
 - lib/ask/mcp/transport/sse.rb
 - lib/ask/mcp/transport/stdio.rb
@@ -131,5 +133,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-summary: Model Context Protocol (MCP) client for Ruby
+summary: Model Context Protocol (MCP) client and server for Ruby
 test_files: []