ask-mcp 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01bf6655c874ece6be6c44d5864e19c844f7edd1fa88c8f90b60b836092bcd90
-  data.tar.gz: 2cebafa8dd9d36901b5e78e81350c235ef837f1d4a010792f6c7d23982729969
+  metadata.gz: 90e04370e4d5b1136abb513220b68beb46a5ca2c74d8f7ca694fa59297f8f32e
+  data.tar.gz: 17f2accea77cefc0ea51fedcc3879e219fff47760999b0ba39e0e168d30dbfe1
 SHA512:
-  metadata.gz: 292a26a5c625cd6e1b06d214ce5b3cd9e38a7562f8e388b8d2817ee4fc915d6f743301c23466c03d2f5e5f3399607a02ca07c2c32bc179696cb1c71386609d5c
-  data.tar.gz: 9c6395fbae61b1013fb72013dfd3d069f76956ad25efd88c62444b3f6c33823462a01c4cb91b129f1a7001a5fef3d7580b91986391128aea41b33c253221afda
+  metadata.gz: d8a481b9467e8f4d6d4d305da61346855f4d27ac94de77f109ac528e704599c18aee5a9c5deb64f7edb71a71b4e446cc1801149df21891d15eefdcb441eb1d09
+  data.tar.gz: b78ccc9a910fbfbeaf2e273ce6169279e4195624871f89356d6564ab6cd46380dd876951544e90b2f3b3b57328ae00180c6d218e1d66afa5416090c5703e1560

data/CHANGELOG.md

@@ -1,40 +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.
-- `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.
+- `Adapters::AskToolServer` — converts tools to MCP definitions and dispatches calls.
 - `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.
+- 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.
+- 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,44 +22,49 @@ 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
 
-## 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.).
+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"
-require "ask-tools-shell"
-require "ask-web-search"
 
-tools = Ask::Tools::Shell::TOOLS.map(&:new)
-tools << Ask::Tools::WebSearch.new
+# 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: tools,
-  capabilities: { tools: {} }
+  tools: [Greeter.new]
 )
 ```
 
@@ -69,14 +75,58 @@ Configure your MCP client:
   "mcpServers": {
     "my-server": {
       "command": "ruby",
-      "args": ["path/to/your/script.rb"]
+      "args": ["/path/to/your/server.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.
+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
 
@@ -183,7 +233,6 @@ wrapped = Ask::MCP::Adapters::AskTool.wrap(client.tools)
 wrapped.each { |name, adapter| agent.register_tool(adapter.to_ask_tool) }
 ```
 
-
 ## Architecture
 
 ```
@@ -205,8 +254,9 @@ ask-mcp/
 │   └── token.rb                           # Token-based auth
 └── lib/ask/mcp/adapters/
     ├── ask_tool.rb                        # MCP::Tool → Ask::Tool adapter
-    └── ask_tool_server.rb                 # Ask::Tool → MCP server adapter (reverse)
+    └── tool_server.rb                     # Duck-typed tools → MCP server adapter
 ```
+
 ## Development
 
 ```bash

data/lib/ask/mcp/adapters/{ask_tool_server.rb → tool_server.rb}

@@ -3,19 +3,26 @@
 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.
+      # 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:
-      #   adapter = AskToolServer.new(Ask::Tools::Shell.all)
-      #   adapter.definitions  # => [{ name: "bash", description: "...", inputSchema: {...} }]
-      #   adapter.call("bash", { command: "echo hi" })  # => { content: [...], isError: ... }
-      class AskToolServer
+      #   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.
-        #   Each tool must respond to name, description, params_schema, and call(args).
+        # @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 }
@@ -44,12 +51,10 @@ module Ask
             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

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

@@ -26,7 +26,7 @@ module Ask
           @prompts = prompts
           @debug = debug
 
-          @adapter = Adapters::AskToolServer.new(tools || [])
+          @adapter = Adapters::ToolServer.new(tools || [])
           @initialized = false
           @running = false
         end

data/lib/ask/mcp/version.rb

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

data/lib/ask/mcp.rb

@@ -28,7 +28,7 @@ module Ask
 
     module Adapters
       autoload :AskTool, "ask/mcp/adapters/ask_tool"
-      autoload :AskToolServer, "ask/mcp/adapters/ask_tool_server"
+      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.2.0
+  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.
-  Run as an MCP server to expose Ask::Tool instances. Discover tools, resources, and
-  prompts. OAuth 2.1 authentication.
+  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,7 +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/adapters/tool_server.rb
 - lib/ask/mcp/auth/oauth.rb
 - lib/ask/mcp/auth/token.rb
 - lib/ask/mcp/client.rb