ask-mcp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1427ce9d98f71ef7654b7f8ac59cfd2c58940dbecf5d32525005e1af1e1a440
-  data.tar.gz: e4efdc1538eb707317ceb9f1fb2d06ba5b2e0f4903ee9a8eff7c094915d28d36
+  metadata.gz: 01bf6655c874ece6be6c44d5864e19c844f7edd1fa88c8f90b60b836092bcd90
+  data.tar.gz: 2cebafa8dd9d36901b5e78e81350c235ef837f1d4a010792f6c7d23982729969
 SHA512:
-  metadata.gz: e18c000c2f9069f8648e1090c0283d33359ae451172b0c831fa60b7d3ccc980285ea963bda1e86cae26ffa35ac5cfea6b89a48da6ad84b34ac1fc492ce9de3bf
-  data.tar.gz: 1456d670425a9b6cfb1f0609f6af58b4b81ea1d10755b3f6c0c9d0f2e93b7cf146a6aecbcca1426fcb9e3387ab4a94b3320a3f4c21d5486935bacd6e7d27f6d8
+  metadata.gz: 292a26a5c625cd6e1b06d214ce5b3cd9e38a7562f8e388b8d2817ee4fc915d6f743301c23466c03d2f5e5f3399607a02ca07c2c32bc179696cb1c71386609d5c
+  data.tar.gz: 9c6395fbae61b1013fb72013dfd3d069f76956ad25efd88c62444b3f6c33823462a01c4cb91b129f1a7001a5fef3d7580b91986391128aea41b33c253221afda

data/CHANGELOG.md

@@ -1,4 +1,24 @@
-# Changelog
+## [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.
+- `Ask::MCP::Adapters::AskToolServer` — converts `Ask::Tool` instances to MCP
+  tool definitions and dispatches calls, enabling any Ask::Tool to be exposed
+  via MCP without modification.
+- `Ask::MCP::Server.start_stdio` entry point for easy one-line server setup.
+- `examples/` — reference usage in README "Running as an MCP Server" section.
+
+### Changed
+- Server Runtime adds 56 new tests across adapter, server stdio, integration,
+  and start_stdio entry point (170 total, up from 114).
+- `ask-mcp` gem description updated to reflect client + server capabilities.
+- Architecture section updated to include server/ and adapters/ask_tool_server.rb.
+
+## [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.
 
 ## [0.1.0] - 2026-06-10
 

data/README.md

@@ -41,6 +41,43 @@ puts result
 client.stop
 ```
 
+
+## Running as an MCP Server
+
+`ask-mcp` can run as a standalone MCP server over stdio, exposing any
+`Ask::Tool` instances to MCP-compatible clients (Codex Desktop, Claude Code, etc.).
+
+```ruby
+require "ask/mcp"
+require "ask-tools-shell"
+require "ask-web-search"
+
+tools = Ask::Tools::Shell::TOOLS.map(&:new)
+tools << Ask::Tools::WebSearch.new
+
+Ask::MCP::Server.start_stdio(
+  name: "my-server",
+  tools: tools,
+  capabilities: { tools: {} }
+)
+```
+
+Configure your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "ruby",
+      "args": ["path/to/your/script.rb"]
+    }
+  }
+}
+```
+
+For a production example, see [llm-proxy](https://github.com/ask-rb/llm-proxy)
+which embeds the same server and adds rate limiting, auth, and monitoring.
+
 ## Transports
 
 ```ruby
@@ -146,28 +183,30 @@ 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/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
+    └── ask_tool_server.rb                 # Ask::Tool → MCP server adapter (reverse)
 ```
-
 ## Development
 
 ```bash

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

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Ask
+  module MCP
+    module Adapters
+      # Converts Ask::Tool instances into MCP tool definitions and dispatches
+      # calls. This is the server-direction adapter — it takes Ask::Tool objects
+      # (from tool packs like ask-tools-shell) and makes them available over MCP.
+      #
+      # Usage:
+      #   adapter = AskToolServer.new(Ask::Tools::Shell.all)
+      #   adapter.definitions  # => [{ name: "bash", description: "...", inputSchema: {...} }]
+      #   adapter.call("bash", { command: "echo hi" })  # => { content: [...], isError: ... }
+      class AskToolServer
+        attr_reader :tools
+
+        # @param tools [Array<#call, #name, #description, #params_schema>] tool instances to expose.
+        #   Each tool must respond to name, description, params_schema, and call(args).
+        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
+
+          # Stringify keys — Ask::Tool subclasses expect string keys
+          normalized = deep_stringify_keys(arguments)
+          result = tool.call(normalized)
+          wrap_result(result)
+        rescue StandardError => e
+          # If the tool raised Ask::Tool::Halt, treat it as a success
+          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::AskToolServer.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.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/ask/mcp.rb

@@ -28,6 +28,7 @@ module Ask
 
     module Adapters
       autoload :AskTool, "ask/mcp/adapters/ask_tool"
+      autoload :AskToolServer, "ask/mcp/adapters/ask_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.0
+  version: 0.2.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 to expose Ask::Tool instances. 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/ask_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: []