ollama-client 0.2.6 → 0.2.7

data/docs/FEATURES_ADDED.md

@@ -43,7 +43,18 @@ client = Ollama::Client.new(config: config)
 **Usage**:
 ```ruby
 options = Ollama::Options.new(temperature: 0.7, top_p: 0.95)
-client.generate(prompt: "...", schema: {...}, options: options.to_h)
+# Use with chat() - chat() accepts options parameter
+client.chat(
+  messages: [{ role: "user", content: "..." }],
+  format: {...},
+  options: options.to_h,
+  allow_chat: true
+)
+
+# Note: generate() doesn't accept options - use config instead
+# config = Ollama::Config.new
+# config.temperature = 0.7
+# client = Ollama::Client.new(config: config)
 ```
 
 **Files Added**:

data/examples/README.md

@@ -25,6 +25,14 @@ This directory contains **minimal examples** demonstrating `ollama-client` usage
   - Demonstrates Tool class serialization/deserialization
   - Shows DTO functionality
 
+- **[mcp_executor.rb](mcp_executor.rb)** - MCP tools with Executor (local stdio)
+  - Connects to a local MCP server (stdio)
+  - Requires Node.js/npx for the filesystem server example
+
+- **[mcp_http_executor.rb](mcp_http_executor.rb)** - MCP tools with Executor (remote URL)
+  - Connects to a remote MCP server via HTTP (e.g. [gitmcp.io](https://gitmcp.io)/owner/repo)
+  - Use the same URL you would add to Cursor’s `mcp.json`
+
 ## Running Examples
 
 All examples are standalone and can be run directly:
@@ -41,6 +49,12 @@ ruby examples/tool_calling_parsing.rb
 
 # Tool DTO
 ruby examples/tool_dto_example.rb
+
+# MCP Executor (local stdio; requires Node.js/npx)
+ruby examples/mcp_executor.rb
+
+# MCP Executor (remote URL, e.g. GitMCP)
+ruby examples/mcp_http_executor.rb
 ```
 
 ### Requirements

data/examples/mcp_executor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Example: Use a local MCP server's tools with Ollama::Agent::Executor.
+#
+# Prerequisites:
+#   - Ollama running (localhost:11434)
+#   - Node.js/npx (for @modelcontextprotocol/server-filesystem)
+#
+# Run:
+#   ruby examples/mcp_executor.rb
+#
+# This connects to the MCP filesystem server, fetches its tools, and runs
+# the Executor so the LLM can call those tools (e.g. list directory, read file).
+
+require_relative "../lib/ollama_client"
+
+ollama = Ollama::Client.new
+
+# Local MCP server via stdio; allow /tmp and the project directory
+project_root = File.expand_path("..", __dir__)
+mcp_client = Ollama::MCP::StdioClient.new(
+  command: "npx",
+  args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp", project_root],
+  timeout_seconds: 60
+)
+
+bridge = Ollama::MCP::ToolsBridge.new(stdio_client: mcp_client)
+tools = bridge.tools_for_executor
+
+executor = Ollama::Agent::Executor.new(ollama, tools: tools)
+
+answer = executor.run(
+  system: "You have access to filesystem tools. Use them when the user asks about files or directories.",
+  user: "What files are in  ~/project/ollama-client? List a few."
+)
+
+puts answer
+
+mcp_client.close

data/examples/mcp_http_executor.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Example: Use a remote MCP server (HTTP URL) with Ollama::Agent::Executor.
+#
+# Works with GitMCP and any MCP-over-HTTP endpoint:
+#   https://gitmcp.io/owner/repo  → MCP server for that GitHub repo
+#
+# Prerequisites:
+#   - Ollama running (localhost:11434)
+#   - Network access to the MCP URL
+#
+# Run:
+#   ruby examples/mcp_http_executor.rb
+#
+# To add this MCP to Cursor, use ~/.cursor/mcp.json:
+#   {
+#     "mcpServers": {
+#       "agent-runtime Docs": {
+#         "url": "https://gitmcp.io/shubhamtaywade82/agent-runtime"
+#       }
+#     }
+#   }
+
+require "ollama_client"
+
+client = Ollama::Client.new
+
+mcp_client = Ollama::MCP::HttpClient.new(
+  url: "https://gitmcp.io/shubhamtaywade82/agent-runtime",
+  timeout_seconds: 60
+)
+
+bridge = Ollama::MCP::ToolsBridge.new(client: mcp_client)
+tools = bridge.tools_for_executor
+
+executor = Ollama::Agent::Executor.new(client, tools: tools)
+
+answer = executor.run(
+  system: "You have access to the agent-runtime repository docs. Use tools when the user asks about the repo.",
+  user: "What does this repository do? Summarize briefly."
+)
+
+puts answer
+
+mcp_client.close

data/lib/ollama/config.rb

@@ -6,14 +6,16 @@ module Ollama
   # Configuration class with safe defaults for agent-grade usage
   #
   # ⚠️ THREAD SAFETY WARNING:
-  # Global configuration via OllamaClient.configure is NOT thread-safe.
-  # For concurrent agents or multi-threaded applications, use per-client
-  # configuration instead:
+  # Global configuration access is mutex-protected, but modifying global config
+  # while clients are active can cause race conditions. For concurrent agents
+  # or multi-threaded applications, use per-client configuration (recommended):
   #
   #   config = Ollama::Config.new
   #   config.model = "llama3.1"
   #   client = Ollama::Client.new(config: config)
   #
+  # Each client instance with its own config is thread-safe.
+  #
   class Config
     attr_accessor :base_url, :model, :timeout, :retries, :temperature, :top_p, :num_ctx, :on_response, :allow_chat,
                   :streaming_enabled

data/lib/ollama/embeddings.rb

@@ -21,7 +21,8 @@ module Ollama
     # @param input [String, Array<String>] Single text or array of texts
     # @return [Array<Float>, Array<Array<Float>>] Embedding vector(s)
     def embed(model:, input:)
-      uri = URI("#{@config.base_url}/api/embeddings")
+      # Use /api/embed (not /api/embeddings) - the working endpoint
+      uri = URI("#{@config.base_url}/api/embed")
       req = Net::HTTP::Post.new(uri)
       req["Content-Type"] = "application/json"
 
@@ -42,11 +43,12 @@ module Ollama
       handle_http_error(res, requested_model: model) unless res.is_a?(Net::HTTPSuccess)
 
       response_body = JSON.parse(res.body)
-      embedding = response_body["embedding"]
+      # /api/embed returns "embeddings" (plural) as array of arrays
+      embeddings = response_body["embeddings"] || response_body["embedding"]
 
-      validate_embedding_response!(embedding, response_body, model)
+      validate_embedding_response!(embeddings, response_body, model)
 
-      format_embedding_result(embedding, input)
+      format_embedding_result(embeddings, input)
     rescue JSON::ParserError => e
       raise InvalidJSONError, "Failed to parse embeddings response: #{e.message}"
     rescue Net::ReadTimeout, Net::OpenTimeout
@@ -57,42 +59,58 @@ module Ollama
 
     private
 
-    def validate_embedding_response!(embedding, response_body, model)
-      if embedding.nil?
+    def validate_embedding_response!(embeddings, response_body, model)
+      if embeddings.nil?
         keys = response_body.keys.join(", ")
         response_preview = response_body.inspect[0..200]
-        raise Error, "Embedding not found in response. Response keys: #{keys}. " \
+        raise Error, "Embeddings not found in response. Response keys: #{keys}. " \
                      "Full response: #{response_preview}"
       end
 
-      return unless embedding.is_a?(Array) && embedding.empty?
+      # Handle both formats: array of arrays [[...]] or single array [...]
+      # Check if it's empty or contains empty arrays
+      if embeddings.is_a?(Array) && (embeddings.empty? || (embeddings.first.is_a?(Array) && embeddings.first.empty?))
+        error_msg = build_empty_embedding_error_message(model, response_body)
+        raise Error, error_msg
+      end
 
-      error_msg = build_empty_embedding_error_message(model, response_body)
-      raise Error, error_msg
+      nil
     end
 
     def build_empty_embedding_error_message(model, response_body)
-      curl_command = "curl http://localhost:11434/api/embeddings " \
+      curl_command = "curl -X POST http://localhost:11434/api/embed " \
                      "-d '{\"model\":\"#{model}\",\"input\":\"test\"}'"
       response_preview = response_body.inspect[0..300]
 
+      # Check for error messages in response
+      error_hint = ""
+      if response_body.is_a?(Hash)
+        if response_body.key?("error")
+          error_hint = "\n  Error from Ollama: #{response_body["error"]}"
+        elsif response_body.key?("message")
+          error_hint = "\n  Message from Ollama: #{response_body["message"]}"
+        end
+      end
+
       "Empty embedding returned. This usually means:\n  " \
         "1. The model may not be properly loaded - try: ollama pull #{model}\n  " \
-        "2. The model may not support embeddings - verify it's an embedding model\n  " \
-        "3. Check if the model is working: #{curl_command}\n" \
+        "2. The model file may be corrupted - try: ollama rm #{model} && ollama pull #{model}\n  " \
+        "3. The model may not support embeddings - verify it's an embedding model\n  " \
+        "4. Check if the model is working: #{curl_command}#{error_hint}\n" \
         "Response: #{response_preview}"
     end
 
-    def format_embedding_result(embedding, input)
-      return embedding unless input.is_a?(Array)
-
-      # Ollama returns single embedding array even for multiple inputs
-      # We need to check the response structure
-      if embedding.is_a?(Array) && embedding.first.is_a?(Array)
-        embedding
+    def format_embedding_result(embeddings, input)
+      # /api/embed returns "embeddings" as array of arrays [[...]]
+      # For single input, it's [[...]], for multiple inputs it's [[...], [...], ...]
+      if embeddings.is_a?(Array) && embeddings.first.is_a?(Array)
+        # Already in correct format (array of arrays)
+        # For single input, return first embedding array
+        # For multiple inputs, return all embedding arrays
+        input.is_a?(Array) ? embeddings : embeddings.first
       else
-        # Single embedding returned, wrap it
-        [embedding]
+        # Fallback: single array format (shouldn't happen with /api/embed)
+        input.is_a?(Array) ? [embeddings] : embeddings
       end
     end
 

data/lib/ollama/mcp/http_client.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Ollama
+  module MCP
+    # Connects to a remote MCP server via HTTP(S).
+    # Sends JSON-RPC via POST; supports session ID from initialize response.
+    # Use for URLs like https://gitmcp.io/owner/repo.
+    class HttpClient
+      PROTOCOL_VERSION = "2025-11-25"
+
+      def initialize(url:, timeout_seconds: 30, headers: {})
+        @uri = URI(url)
+        @uri.path = "/" if @uri.path.nil? || @uri.path.empty?
+        @timeout = timeout_seconds
+        @extra_headers = headers.transform_keys(&:to_s)
+        @request_id = 0
+        @session_id = nil
+        @initialized = false
+      end
+
+      def start
+        return if @initialized
+
+        run_initialize
+        @initialized = true
+      end
+
+      def tools
+        start
+        response = request("tools/list", {})
+        list = response.dig("result", "tools")
+        return [] unless list.is_a?(Array)
+
+        list.map do |t|
+          {
+            name: (t["name"] || t[:name]).to_s,
+            description: (t["description"] || t[:description]).to_s,
+            input_schema: t["inputSchema"] || t[:input_schema] || { "type" => "object" }
+          }
+        end
+      end
+
+      def call_tool(name:, arguments: {})
+        start
+        response = request("tools/call", "name" => name.to_s, "arguments" => stringify_keys(arguments))
+        result = response["result"]
+        raise Ollama::Error, "tools/call failed: #{response["error"]}" if response["error"]
+        raise Ollama::Error, "tools/call returned no result" unless result
+
+        content_to_string(result["content"])
+      end
+
+      def close
+        @session_id = nil
+        @initialized = false
+      end
+
+      private
+
+      def run_initialize
+        init_params = {
+          "protocolVersion" => PROTOCOL_VERSION,
+          "capabilities" => {},
+          "clientInfo" => {
+            "name" => "ollama-client",
+            "version" => Ollama::VERSION
+          }
+        }
+        response = request("initialize", init_params)
+        raise Ollama::Error, "initialize failed: #{response["error"]}" if response["error"]
+
+        send_notification("notifications/initialized", {})
+      end
+
+      def next_id
+        @request_id += 1
+      end
+
+      def request(method, params)
+        id = next_id
+        msg = { "jsonrpc" => "2.0", "id" => id, "method" => method, "params" => params }
+        post_request(msg, method: method)
+      end
+
+      def send_notification(method, params)
+        body = { "jsonrpc" => "2.0", "method" => method, "params" => params }
+        post_request(body, method: method)
+      end
+
+      def post_request(body, method: nil)
+        req = Net::HTTP::Post.new(@uri)
+        req["Content-Type"] = "application/json"
+        req["Accept"] = "application/json, text/event-stream"
+        req["MCP-Protocol-Version"] = PROTOCOL_VERSION
+        req["MCP-Session-Id"] = @session_id if @session_id
+        @extra_headers.each { |k, v| req[k] = v }
+        req.body = body.is_a?(Hash) ? JSON.generate(body) : body.to_s
+
+        res = http_request(req)
+
+        if method == "initialize" && res["MCP-Session-Id"]
+          @session_id = res["MCP-Session-Id"].to_s.strip
+          @session_id = nil if @session_id.empty?
+        end
+
+        return {} if res.code == "202"
+
+        raise Ollama::Error, "MCP HTTP error: #{res.code} #{res.message}" unless res.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(res.body)
+      end
+
+      def http_request(req)
+        Net::HTTP.start(
+          @uri.hostname,
+          @uri.port,
+          use_ssl: @uri.scheme == "https",
+          read_timeout: @timeout,
+          open_timeout: @timeout
+        ) { |http| http.request(req) }
+      rescue Net::ReadTimeout, Net::OpenTimeout
+        raise Ollama::TimeoutError, "MCP server did not respond within #{@timeout}s"
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+        raise Ollama::Error, "MCP connection failed: #{e.message}"
+      end
+
+      def stringify_keys(hash)
+        return {} if hash.nil?
+
+        hash.transform_keys(&:to_s)
+      end
+
+      def content_to_string(content)
+        return "" unless content.is_a?(Array)
+
+        content.filter_map do |item|
+          next unless item.is_a?(Hash)
+
+          text = item["text"] || item[:text]
+          text&.to_s
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/ollama/mcp/stdio_client.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module Ollama
+  module MCP
+    # Connects to a local MCP server via stdio (spawns subprocess).
+    # Handles JSON-RPC lifecycle: initialize, tools/list, tools/call.
+    class StdioClient
+      PROTOCOL_VERSION = "2025-11-25"
+
+      def initialize(command:, args: [], env: {}, timeout_seconds: 30)
+        @command = command
+        @args = Array(args)
+        @env = env
+        @timeout = timeout_seconds
+        @request_id = 0
+        @reader = nil
+        @writer = nil
+        @initialized = false
+      end
+
+      def start
+        return if @initialized
+
+        env_merged = ENV.to_h.merge(@env.transform_keys(&:to_s))
+        stdin, stdout = Open3.popen2(env_merged, @command, *@args)
+        @writer = stdin
+        @reader = stdout
+        run_initialize
+        @initialized = true
+      end
+
+      def tools
+        start
+        response = request("tools/list", {})
+        list = response.dig("result", "tools")
+        return [] unless list.is_a?(Array)
+
+        list.map do |t|
+          {
+            name: (t["name"] || t[:name]).to_s,
+            description: (t["description"] || t[:description]).to_s,
+            input_schema: t["inputSchema"] || t[:input_schema] || { "type" => "object" }
+          }
+        end
+      end
+
+      def call_tool(name:, arguments: {})
+        start
+        response = request("tools/call", "name" => name.to_s, "arguments" => stringify_keys(arguments))
+        result = response["result"]
+        raise Ollama::Error, "tools/call failed: #{response["error"]}" if response["error"]
+        raise Ollama::Error, "tools/call returned no result" unless result
+
+        content_to_string(result["content"])
+      end
+
+      def close
+        return unless @writer
+
+        @writer.close
+        @writer = nil
+        @reader = nil
+        @initialized = false
+      end
+
+      private
+
+      def run_initialize
+        init_params = {
+          "protocolVersion" => PROTOCOL_VERSION,
+          "capabilities" => {},
+          "clientInfo" => {
+            "name" => "ollama-client",
+            "version" => Ollama::VERSION
+          }
+        }
+        response = request("initialize", init_params)
+        raise Ollama::Error, "initialize failed: #{response["error"]}" if response["error"]
+
+        send_notification("notifications/initialized", {})
+      end
+
+      def next_id
+        @request_id += 1
+      end
+
+      def request(method, params)
+        id = next_id
+        msg = { "jsonrpc" => "2.0", "id" => id, "method" => method, "params" => params }
+        send_message(msg)
+        wait_for_response(id)
+      end
+
+      def send_notification(method, params)
+        send_message("jsonrpc" => "2.0", "method" => method, "params" => params)
+      end
+
+      def send_message(msg)
+        line = "#{JSON.generate(msg)}\n"
+        @writer.write(line)
+        @writer.flush
+      end
+
+      def wait_for_response(expected_id)
+        loop do
+          line = read_line_with_timeout
+          next if line.nil? || line.strip.empty?
+          next unless line.strip.start_with?("{")
+
+          parsed = JSON.parse(line)
+          next if parsed["method"] # notification from server
+
+          return parsed if parsed["id"] == expected_id
+        end
+      end
+
+      def read_line_with_timeout
+        unless @reader.wait_readable(@timeout)
+          raise Ollama::TimeoutError, "MCP server did not respond within #{@timeout}s"
+        end
+
+        @reader.gets
+      end
+
+      def stringify_keys(hash)
+        return {} if hash.nil?
+
+        hash.transform_keys(&:to_s)
+      end
+
+      def content_to_string(content)
+        return "" unless content.is_a?(Array)
+
+        content.filter_map do |item|
+          next unless item.is_a?(Hash)
+
+          text = item["text"] || item[:text]
+          text&.to_s
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/ollama/mcp/tools_bridge.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "../tool"
+
+module Ollama
+  module MCP
+    # Bridges an MCP server's tools to Ollama::Agent::Executor.
+    # Fetches tools via tools/list, converts them to Ollama tool format,
+    # and provides a callable per tool that invokes tools/call.
+    # Accepts either client: (StdioClient or HttpClient) or stdio_client: for backward compatibility.
+    class ToolsBridge
+      def initialize(stdio_client: nil, client: nil)
+        @client = client || stdio_client
+        raise ArgumentError, "Provide client: or stdio_client:" unless @client
+
+        @tools_cache = nil
+      end
+
+      # Returns a hash suitable for Executor: name => { tool: Ollama::Tool, callable: proc }.
+      # Callable receives keyword args and returns a string (tool result for the LLM).
+      def tools_for_executor
+        fetch_tools unless @tools_cache
+
+        @tools_cache.transform_values do |entry|
+          {
+            tool: entry[:tool],
+            callable: build_callable(entry[:name])
+          }
+        end
+      end
+
+      # Returns raw MCP tool list (name, description, input_schema).
+      def list_tools
+        @client.tools
+      end
+
+      private
+
+      def fetch_tools
+        list = @client.tools
+        @tools_cache = list.each_with_object({}) do |mcp_tool, hash|
+          name = mcp_tool[:name]
+          next if name.nil? || name.to_s.empty?
+
+          hash[name.to_s] = {
+            name: name.to_s,
+            tool: mcp_tool_to_ollama(mcp_tool)
+          }
+        end
+      end
+
+      def mcp_tool_to_ollama(mcp_tool)
+        schema = mcp_tool[:input_schema] || { "type" => "object" }
+        function_hash = {
+          "name" => mcp_tool[:name].to_s,
+          "description" => (mcp_tool[:description] || "MCP tool: #{mcp_tool[:name]}").to_s,
+          "parameters" => schema
+        }
+        Ollama::Tool.from_hash("type" => "function", "function" => function_hash)
+      end
+
+      def build_callable(name)
+        client = @client
+        ->(**kwargs) { client.call_tool(name: name, arguments: stringify_keys(kwargs)) }
+      end
+
+      def stringify_keys(hash)
+        hash.transform_keys(&:to_s)
+      end
+    end
+  end
+end

data/lib/ollama/mcp.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# MCP (Model Context Protocol) support for local servers.
+#
+# Connect to MCP servers running via stdio (e.g. npx @modelcontextprotocol/server-filesystem)
+# and use their tools with Ollama::Agent::Executor.
+#
+# Example (remote URL, e.g. GitMCP):
+#   mcp_client = Ollama::MCP::HttpClient.new(url: "https://gitmcp.io/owner/repo")
+#   bridge = Ollama::MCP::ToolsBridge.new(client: mcp_client)
+#   tools = bridge.tools_for_executor
+#   executor = Ollama::Agent::Executor.new(ollama_client, tools: tools)
+#   executor.run(system: "...", user: "What does this repo do?")
+#
+# Example (local stdio):
+#   mcp_client = Ollama::MCP::StdioClient.new(
+#     command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+#   )
+#   bridge = Ollama::MCP::ToolsBridge.new(stdio_client: mcp_client)
+#   tools = bridge.tools_for_executor
+#   executor.run(system: "...", user: "List files in /tmp")
+#
+module Ollama
+  # Model Context Protocol client and tools bridge for Executor.
+  module MCP
+  end
+end
+
+require_relative "mcp/stdio_client"
+require_relative "mcp/http_client"
+require_relative "mcp/tools_bridge"

data/lib/ollama/options.rb

@@ -8,7 +8,9 @@ module Ollama
   #
   # Example:
   #   options = Ollama::Options.new(temperature: 0.7, top_p: 0.95)
-  #   client.generate(prompt: "...", schema: {...}, options: options.to_h)
+  #   client.chat(messages: [...], format: {...}, options: options.to_h, allow_chat: true)
+  #
+  # Note: generate() doesn't accept options parameter - set options in config instead
   class Options
     VALID_KEYS = %i[temperature top_p top_k num_ctx repeat_penalty seed].freeze