ask-web-search-mcp 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f160f5a8fb458d0709056a11c582668c7635a5eaaaf85d9be6874177eba701ac
-  data.tar.gz: 846c889c1942698894bb3d5af8b385ee54c775d6b1d355ebe62227cb39a46539
+  metadata.gz: ac5646c79697323c0e3468f1ae9f23c75c961d0a39e844abac53c47cf3f1cd15
+  data.tar.gz: 8786a020e9ebc20cc94dcf2b7e7c29246351e7ae7aed2ecad369f04108aabab9
 SHA512:
-  metadata.gz: badf1176d59f3b255a7fd66b89c5a772c6bcb8fea3b4bb94bf1ce1a1d49f6d031fe8c2cfaf9f135a1f965dcaed758e7fa2222de7168d6d80cf42d5f5731364ea
-  data.tar.gz: 821fc274ee6ea451359afedacca24bc319a532bf10a6b67b1a458345194a89227d457d255432020eb1feb86e03908d774cc2da3785db84d7ef0eccbc71f2728c
+  metadata.gz: 4b0ece49a60e7203c45f9c3c240bcb94e1449ca12f77b94097766ad64b403f1f263e907af7260db7e3fcb293f58a91dae787875a84efa3f573fdef32922d3be5
+  data.tar.gz: bc67755832d14e152efcafc2e0a4f8334e4693197c92608acc1770d2c8a845fedf1343a9a133a3c1a5da628c1d06536c6ba7e9fa7f32ad5dd922343477a94abe

data/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [0.4.0] - 2026-08-12
+
+### Changed
+
+- **The server owns its tool shell.** `ask_web_search` is now a
+  duck-typed tool (`Ask::WebSearch::MCP::Tool` — `name` /
+  `description` / `params_schema` / `call`) wrapping the library entry
+  `Ask::WebSearch.search`, instead of a renamed `Ask::Tools::WebSearch`.
+  The MCP adapter's contract is duck-typed by design, so the ask-tools /
+  ask-core / ask-schema dependency chain is gone from the server
+  process entirely. `ask-web-search` floor raised to `>= 0.3.0` (the
+  module-level API). The native agent tool remains available in
+  ask-web-search as an optional integration for non-MCP consumers.
+
+## [0.3.1] - 2026-08-04
+
+### Fixed
+
+- Corrected publish of the 0.3.0 changeset (0.3.0 was yanked — it shipped a
+  stale build missing the `tool` extraction and serverInfo version
+  passthrough). 0.3.1 is the same changeset built correctly.
+
+## [0.3.0] - 2026-08-04
+
+### Changed
+
+- **Stateless protocol support (2026-07-28)** — the server now negotiates the
+  stateless MCP revision via `server/discover` (no `initialize` handshake,
+  per-request `_meta`, `resultType`) when the client supports it, while
+  remaining backward compatible with legacy `initialize`-handshake clients.
+  Requires `ask-mcp >= 0.4` — the 0.4 line also brings server-side
+  resources/prompts and the Streamable HTTP rework.
+- Development resolves `ask-mcp` from rubygems via the `>= 0.4` floor — no
+  local path overrides; the server always exercises the published protocol
+  support.
+
+### Added
+
+- Functional test suite (`test/server_test.rb`) driving the server end-to-end
+  with `Ask::MCP::Client` over a real stdio subprocess: stateless
+  negotiation, tool listing, tool calls against a stubbed SearXNG (in-process
+  `FakeSearxng`), no-results handling, unknown-tool errors, and a
+  SearXNG-unreachable error path.
+- `Ask::WebSearch::MCP.tool` — extracted, testable accessor for the
+  `ask_web_search` tool instance, with unit tests covering the MCP tool
+  contract (name, description, params schema).
+- The server now reports its own gem version in the MCP `serverInfo`
+  handshake (via `ask-mcp >= 0.4.3`), instead of ask-mcp's version.
+
 ## [0.2.0] - 2026-07-18
 
 ### Changed

data/README.md

@@ -2,9 +2,18 @@
 
 [![Gem Version](https://badge.fury.io/rb/ask-web-search-mcp.svg)](https://rubygems.org/gems/ask-web-search-mcp)
 
-A minimal [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server
-that exposes an `ask_web_search` tool backed by SearXNG. Designed for use with
-MCP-compatible clients like **ZCode**, **Claude Code**, **Codex**, and others.
+A minimal [MCP](https://modelcontextprotocol.io/) (Model Context Protocol)
+server that exposes an `ask_web_search` tool backed by SearXNG. Designed for
+use with MCP-compatible clients like ZCode, Claude Code, Codex, and others.
+
+The server speaks MCP **dual-mode** (requires `ask-mcp >= 0.4`): it negotiates
+the stateless `2026-07-28` revision via `server/discover` (no `initialize`
+handshake, per-request `_meta`, `resultType`) when the client supports it, and
+falls back to the legacy `initialize` handshake for older clients.
+
+The tool was renamed from `web_search` to `ask_web_search` in version 0.2.0 to
+avoid collisions with client-side tools. Use `ask_web_search` in your
+configuration and prompts.
 
 ## Prerequisites
 
@@ -15,15 +24,14 @@ is `http://localhost:8888`.
 docker run -d --name searxng -p 8888:8080 searxng/searxng
 ```
 
-Or use the provided `docker-compose.yml` in the [`searxng`](../searxng) directory:
+Or use the provided `docker-compose.yml` in the `searxng` directory of this
+repository:
 
 ```sh
 cd searxng
 docker compose up -d
 ```
 
-You can customise the SearXNG URL via the `SEARXNG_URL` environment variable.
-
 ## Installation
 
 ```sh
@@ -49,8 +57,8 @@ The server reads JSON-RPC messages on stdin and writes responses to stdout
 
 ### With ZCode
 
-Add the server to your ZCode user configuration
-(`~/.zcode/v2/config.json`):
+Add to your ZCode user configuration (`~/.zcode/v2/config.json` or
+`~/.zcode/cli/config.json`):
 
 ```json
 {
@@ -66,7 +74,8 @@ Add the server to your ZCode user configuration
 }
 ```
 
-After restarting ZCode, the `ask_web_search` tool will be available to the model.
+After restarting ZCode, the `ask_web_search` tool will be available to the
+model automatically.
 
 ### With Claude Code
 
@@ -74,15 +83,30 @@ After restarting ZCode, the `ask_web_search` tool will be available to the model
 claude mcp add ask-web-search-mcp -- npx -y @anthropic-ai/mcp-serve ask-web-search-mcp
 ```
 
+## Configuration
+
+- `SEARXNG_URL` - the SearXNG endpoint (default: `http://localhost:8888`).
+- `DEBUG=1` - enable verbose logs on stderr.
+
+## Full documentation
+
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+[Core: Web Search](https://ask-rb.github.io/ask-docs/core/web-search) covers
+ask-web-search-mcp in depth, including the tool library and troubleshooting.
+API reference: https://ask-rb.github.io/ask-docs/reference/api.
+
 ## Development
 
-```sh
-git clone https://github.com/ask-rb/ask-web-search-mcp
-cd ask-web-search-mcp
-bin/setup
+```
+bundle install
 bundle exec rake test
 ```
 
+`ask-mcp` resolves from rubygems (`>= 0.4` — the 0.4 line carries the
+stateless 2026-07-28 protocol support). The suite drives the server
+end-to-end with `Ask::MCP::Client` over a real stdio subprocess, stubbing
+SearXNG in-process (no network required).
+
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT

data/lib/ask/web_search/mcp/tool.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "ask/web_search"
+
+module Ask
+  module WebSearch
+    module MCP
+      # The ask_web_search tool, duck-typed for Ask::MCP's ToolServer
+      # adapter (name / description / params_schema / call). The tool
+      # framing lives with its consumer — this server — not in the
+      # library: the capability is Ask::WebSearch.search, this is the
+      # agent-facing shell around it.
+      class Tool
+        def name
+          "ask_web_search"
+        end
+
+        def description
+          "Search the web for current information. Use this to get up-to-date results, recent events, or facts that may have changed."
+        end
+
+        def params_schema
+          {
+            "type" => "object",
+            "properties" => {
+              "query" => { "type" => "string", "description" => "The search query" }
+            },
+            "required" => ["query"]
+          }
+        end
+
+        # Returns the formatted results (a String is a success for the
+        # adapter) or raises on connection/HTTP failures — the adapter
+        # surfaces them as classed errors.
+        def call(args)
+          query = args["query"].to_s
+          raise ArgumentError, "missing required parameter: query" if query.empty?
+
+          Ask::WebSearch.search(query)
+        end
+      end
+    end
+  end
+end

data/lib/ask/web_search/mcp/version.rb

@@ -3,7 +3,7 @@
 module Ask
   module WebSearch
     module MCP
-      VERSION = "0.2.0"
+      VERSION = "0.4.0"
     end
   end
 end

data/lib/ask/web_search/mcp.rb

@@ -2,11 +2,20 @@
 
 require "ask/mcp"
 require "ask/web_search"
+require_relative "mcp/tool"
 require_relative "mcp/version"
 
 module Ask
   module WebSearch
     module MCP
+      # Builds the tool exposed over MCP. The tool framing lives here —
+      # ask-web-search is a library (Ask::WebSearch.search); this server
+      # owns the agent-facing shell, named "ask_web_search" to avoid
+      # collisions with client-side tools of the same name.
+      def self.tool
+        Tool.new
+      end
+
       # Start the MCP server over stdio, exposing the ask_web_search tool.
       #
       #   $ ask-web-search-mcp
@@ -25,11 +34,9 @@ module Ask
       #     }
       #   }
       def self.start
-        tool = Ask::Tools::WebSearch.new
-        tool.define_singleton_method(:name) { "ask_web_search" }
-
         Ask::MCP::Server.start_stdio(
           name: "ask-web-search-mcp",
+          version: VERSION,
           tools: [tool],
           capabilities: { tools: {} },
           debug: ENV["DEBUG"] == "1"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-web-search-mcp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kaka Ruto
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.4.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.1'
+        version: 0.4.3
 - !ruby/object:Gem::Dependency
   name: ask-web-search
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 0.3.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 0.3.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -66,10 +66,11 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '13.0'
 description: |
-  A minimal MCP (Model Context Protocol) server that exposes Ask::Tools::WebSearch
+  A minimal MCP (Model Context Protocol) server that exposes ask_web_search
   as a callable tool over stdio. Designed for use with clients that support MCP
   (ZCode, Claude Code, etc.), it queries a local SearXNG instance and returns
-  formatted search results suitable for LLM consumption.
+  formatted search results suitable for LLM consumption. The tool shell (name,
+  schema, call) lives here, wrapping the Ask::WebSearch library.
 email:
 - kaka@myrrlabs.com
 executables:
@@ -83,6 +84,7 @@ files:
 - bin/ask-web-search-mcp
 - lib/ask-web-search-mcp.rb
 - lib/ask/web_search/mcp.rb
+- lib/ask/web_search/mcp/tool.rb
 - lib/ask/web_search/mcp/version.rb
 homepage: https://github.com/ask-rb/ask-web-search-mcp
 licenses: