zeromcp 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa95cc5fe08e2a54b9034a2248b978e1a01919bd3cb0249f444031e070f0dcd1
-  data.tar.gz: ae4cd9f4405f8b9786f0bf5e238898b8260d5d37b5a8aac9bdd96ac3ae02876a
+  metadata.gz: 4b5b1e9efe4dd7daa0f3ac769bc0989684a322df09a9b6f0886b1f8c9b11be14
+  data.tar.gz: b8b9a22497327fdf3618c01d959e01d692a83f6c4785d6e7b655bdd5eacdc8fb
 SHA512:
-  metadata.gz: 38b41336ef5617f74cf599c79cb0fd52f872eba7c912825c74020a3026cf8c8e360a1b79ac2f12a612e73cb657e2a2d240a4fed709012796c430990100ddd26f
-  data.tar.gz: b502b28ab22e0666937aeb772818d6bf8739671c4b274b03acec2307652d64830aa37ee7611094405be58de2c9d134ed67a3ed507241cb8615ea6fe3c90d7def
+  metadata.gz: e49425f27d7726ca510f08014d5e5bb9418a5da74ce91f8a7ea746fed9e7c6d7ea9f1a05fe72197bf70c043952143e972707699c41fe3a7308fc490ad669230d
+  data.tar.gz: 91328849237941d7ce8aa4a4dd86fb63a8d20c375e40000df390c302ef24e36cd166ca311cc04987fdc7416af51e7a73371ff9b0dfffd08edbcb9919ed20f539

data/Gemfile

@@ -6,4 +6,5 @@ gemspec
 
 group :test do
   gem 'minitest', '~> 5.0'
+  gem 'webrick' # fake upstream servers in tests only; the gem has no HTTP dependency
 end

data/README.md

@@ -32,36 +32,105 @@ Ruby passes all 10 conformance suites.
 
 ## HTTP / Streamable HTTP
 
-ZeroMCP doesn't own the HTTP layer. You bring your own framework; ZeroMCP gives you a `handle_request` method that takes a Hash and returns a Hash (or `nil` for notifications).
+ZeroMCP doesn't own the HTTP layer and ships no HTTP server. You mount it in the framework you already run. `ZeroMcp.create_registry` gives you everything as plain data:
 
-```ruby
-# response = server.handle_request(request)
-```
+- `registry.routes`: one entry per tool with a `route:` (`name`, `method`, `path`, `tool`)
+- `registry.openapi`: an OpenAPI 3.0 document (a Hash) for the routed tools
+- `registry.mcp`: a callable that takes a JSON-RPC Hash and returns a response Hash (or `nil` for notifications)
+- `registry.context_for(tool)`: a ready-made `ctx` (credentials, permissions, runtime) for calling a routed tool yourself
+
+A config with an `http` transport now fails at startup and points you here.
 
 **Sinatra**
 
 ```ruby
 require 'sinatra'
 require 'json'
-require_relative 'lib/zeromcp'
+require 'zeromcp'
 
 config = ZeroMcp::Config.load
-server = ZeroMcp::Server.new(config)
-server.load_tools
+tools = ZeroMcp::Scanner.new(config).scan
+registry = ZeroMcp.create_registry(tools, config: config)
 
+# MCP over HTTP
 post '/mcp' do
-  request_body = JSON.parse(request.body.read)
-  response = server.handle_request(request_body)
+  response = registry.mcp.call(JSON.parse(request.body.read))
+  halt 204 if response.nil?
+  content_type :json
+  response.to_json
+end
 
-  if response.nil?
-    status 204
-  else
+# OpenAPI
+get '/openapi.json' do
+  content_type :json
+  registry.openapi.to_json
+end
+
+# One HTTP route per routed tool. Sinatra uses the same :param syntax.
+registry.routes.each do |route|
+  send(route.method.downcase, route.path) do
+    body = request.body.read
+    args = request.GET.merge(body.empty? ? {} : JSON.parse(body))
+    args = args.merge(params.slice(*route.path.scan(/:(\w+)/).flatten))
+    result = route.tool.call(args, registry.context_for(route.tool))
     content_type :json
-    response.to_json
+    { ok: true, result: result }.to_json
   end
 end
 ```
 
+`Server#handle_request` is still there if you only need `/mcp`: `server = ZeroMcp::Server.new(config); server.load_tools; server.handle_request(hash)`.
+
+## Runtime context
+
+Pass `get_runtime:` to hand your tools something from your app (a DB handle, the current request's user). It is called on every local tool execution, and its return value is `ctx.runtime`:
+
+```ruby
+registry = ZeroMcp.create_registry(tools, get_runtime: -> { { db: DB } })
+# or: ZeroMcp::Server.new(config, get_runtime: -> { { db: DB } })
+
+# tools/report.rb
+execute do |args, ctx|
+  ctx.runtime[:db].query(args['sql'])
+end
+```
+
+Without `get_runtime:`, `ctx.runtime` is `nil`. Remote tools never call it.
+
+## Remote servers
+
+ZeroMCP can federate other MCP servers over HTTP. Their tools appear as `<name>.<tool>`; a local tool with the same name wins.
+
+```json
+{
+  "tools": "./tools",
+  "remote": [
+    { "name": "probeo", "url": "https://mcp.example.com/mcp", "auth": "env:PROBEO_TOKEN", "tools": ["list_pages"] }
+  ]
+}
+```
+
+`auth` is sent as `Authorization: Bearer <token>`; `env:VAR` reads it from the environment. `tools` is an optional allowlist of upstream tool names. A server that fails to connect is logged and skipped. The registry takes the same list: `ZeroMcp.create_registry(tools, remote: [...])` (it connects before returning). Remote tools have no route, so they are served from `mcp` only.
+
+## Hot reload
+
+Set `"autoload_tools": true` and `zeromcp serve` polls the tool directories once a second. When a `.rb` file is added or changed it rescans, loads the new tools, and sends `notifications/tools/list_changed` over stdio. Removed files keep their tools until restart.
+
+## Tool sources and namespacing
+
+`tools` takes a path, or an array of paths and `{ "path": ..., "prefix": ... }` entries. A prefix is prepended to every tool from that source:
+
+```json
+{
+  "tools": ["./tools", { "path": "./vendor/github-tools", "prefix": "gh" }],
+  "namespacing": { "math": { "prefix": "m" } }
+}
+```
+
+`namespacing` renames a subdirectory's prefix (`math/add.rb` becomes `m_add`; `""` drops it). Credentials stay keyed by the directory name. `resources` and `prompts` accept the same entry shapes.
+
+`icon` accepts a data URI, a file path, or an `http(s)` URL.
+
 ## Requirements
 
 - Ruby 3.0+
@@ -103,6 +172,8 @@ tools/
 
 ## Testing
 
+The tests use WEBrick for fake upstream servers (`gem 'webrick'`, in the Gemfile's test group). The gem itself doesn't need it.
+
 ```sh
 ruby -I lib -I test -e 'Dir["test/**/test_*.rb"].each { |f| require_relative f }'
 ```

data/lib/zeromcp/config.rb

@@ -2,22 +2,25 @@
 
 require 'json'
 require 'base64'
+require 'net/http'
+require 'uri'
 
 module ZeroMcp
   class Config
-    attr_reader :tools_dir, :resources_dir, :prompts_dir,
+    attr_reader :tools_dir, :tool_sources, :resources_dir, :prompts_dir,
                 :separator, :logging, :bypass_permissions, :execute_timeout,
-                :page_size, :icon, :title
+                :page_size, :icon, :title, :remote, :autoload_tools, :transport
 
     def initialize(opts = {})
       tools = opts[:tools_dir] || opts['tools'] || './tools'
-      @tools_dir = tools.is_a?(Array) ? tools : [tools]
+      @tool_sources = Config.resolve_sources(tools)
+      @tools_dir = @tool_sources.map { |s| s['path'] }
 
       resources = opts[:resources_dir] || opts['resources']
-      @resources_dir = resources ? (resources.is_a?(Array) ? resources : [resources]) : []
+      @resources_dir = resources ? Config.resolve_sources(resources).map { |s| s['path'] } : []
 
       prompts = opts[:prompts_dir] || opts['prompts']
-      @prompts_dir = prompts ? (prompts.is_a?(Array) ? prompts : [prompts]) : []
+      @prompts_dir = prompts ? Config.resolve_sources(prompts).map { |s| s['path'] } : []
 
       @separator = opts[:separator] || opts['separator'] || '_'
       @logging = opts[:logging] || opts['logging'] || false
@@ -29,6 +32,9 @@ module ZeroMcp
       @page_size = opts[:page_size] || opts['page_size'] || 0
       @icon = opts[:icon] || opts['icon']
       @title = opts[:title] || opts['title'] || 'ZeroMCP'
+      @remote = opts[:remote] || opts['remote'] || []
+      @autoload_tools = opts[:autoload_tools] || opts['autoload_tools'] || false
+      @transport = opts[:transport] || opts['transport']
     end
 
     attr_reader :credentials, :cache_credentials, :namespacing
@@ -44,13 +50,53 @@ module ZeroMcp
       new
     end
 
+    # Normalize a `tools` / `resources` / `prompts` value (a string, or an
+    # array of strings and { 'path' => ..., 'prefix' => ... } hashes) to an
+    # array of { 'path' => String, 'prefix' => String|nil }.
+    def self.resolve_sources(value)
+      list = value.is_a?(Array) ? value : [value]
+      list.map do |entry|
+        if entry.is_a?(Hash)
+          { 'path' => entry['path'] || entry[:path], 'prefix' => entry['prefix'] || entry[:prefix] }
+        else
+          { 'path' => entry, 'prefix' => nil }
+        end
+      end
+    end
+
+    # True when `transport` asks for the removed built-in HTTP server: the
+    # string "http", a { 'type' => 'http' } hash, or an array containing either.
+    def http_transport?
+      list = @transport.is_a?(Array) ? @transport : [@transport]
+      list.any? do |t|
+        type = t.is_a?(Hash) ? (t['type'] || t[:type]) : t
+        type.to_s == 'http'
+      end
+    end
+
+    # Resolve an auth value: "env:VAR" reads ENV[VAR] (warning when unset),
+    # anything else is returned as-is. nil passes through.
+    def self.resolve_auth(auth)
+      return nil if auth.nil?
+
+      if auth.start_with?('env:')
+        var = auth[4..]
+        val = ENV[var]
+        $stderr.puts "[zeromcp] Warning: environment variable #{var} not set" if val.nil?
+        return val
+      end
+      auth
+    end
+
     # Resolve an icon config value to a data URI. Supports:
     # - data: URIs (returned as-is)
+    # - http(s) URLs (fetched and base64 encoded)
     # - Local file paths (read and base64 encode)
     # Returns nil on failure or if icon is not set.
     def self.resolve_icon(icon)
       return nil if icon.nil? || icon.empty?
       return icon if icon.start_with?('data:')
+      return fetch_icon(icon) if icon.start_with?('http://', 'https://')
 
       # File path
       path = File.expand_path(icon)
@@ -65,6 +111,19 @@ module ZeroMcp
       nil
     end
 
+    def self.fetch_icon(url)
+      res = Net::HTTP.get_response(URI(url))
+      unless res.is_a?(Net::HTTPSuccess)
+        $stderr.puts "[zeromcp] Warning: failed to fetch icon #{url}: #{res.code}"
+        return nil
+      end
+      content_type = res['content-type'] || 'image/png'
+      "data:#{content_type};base64,#{Base64.strict_encode64(res.body || '')}"
+    rescue => e
+      $stderr.puts "[zeromcp] Warning: failed to fetch icon #{url}: #{e.message}"
+      nil
+    end
+
     ICON_MIME = {
       '.png'  => 'image/png',
       '.jpg'  => 'image/jpeg',

data/lib/zeromcp/credentials.rb

@@ -6,11 +6,18 @@ module ZeroMcp
   module Credentials
     module_function
 
-    def resolve(tool_name, config, cache: nil)
+    # ns: the credentials key to use (a scanned tool's top-level directory).
+    # When nil, the key is found by matching the tool name's prefix.
+    def resolve(tool_name, config, cache: nil, ns: nil)
       return nil if config.credentials.empty?
-      config.credentials.each do |ns, source|
-        if tool_name.start_with?("#{ns}_") || tool_name.start_with?("#{ns}#{config.separator}")
-          return resolve_for_ns(ns.to_s, source, config, cache)
+      if ns
+        key = config.credentials.key?(ns) ? ns : (config.credentials.key?(ns.to_sym) ? ns.to_sym : nil)
+        return nil unless key
+        return resolve_for_ns(ns.to_s, config.credentials[key], config, cache)
+      end
+      config.credentials.each do |key, source|
+        if tool_name.start_with?("#{key}_") || tool_name.start_with?("#{key}#{config.separator}")
+          return resolve_for_ns(key.to_s, source, config, cache)
         end
       end
       nil

data/lib/zeromcp/registry.rb

@@ -3,22 +3,25 @@
 require_relative 'server'
 require_relative 'openapi'
 require_relative 'credentials'
+require_relative 'remote'
 
 module ZeroMcp
   module Registry
     RouteDefinition = Struct.new(:name, :method, :path, :tool, keyword_init: true)
 
-    ToolRegistry = Struct.new(:routes, :openapi, :mcp, :config, :credential_cache, keyword_init: true) do
+    ToolRegistry = Struct.new(:routes, :openapi, :mcp, :config, :credential_cache, :get_runtime, keyword_init: true) do
       # Build a ready-to-use Context for `tool`, using the same config-driven
       # credential/permission rules Server#call_tool already applies — so a
       # caller invoking a routed tool directly (route.tool.call(args, ctx))
-      # doesn't have to hand-roll credential lookup.
+      # doesn't have to hand-roll credential lookup. ctx.runtime comes from
+      # the registry's get_runtime hook, when one was given.
       def context_for(tool)
         ZeroMcp::Context.new(
           tool_name: tool.name,
           permissions: tool.permissions,
           bypass: config.bypass_permissions,
-          credentials: ZeroMcp::Credentials.resolve(tool.name, config, cache: credential_cache)
+          credentials: ZeroMcp::Credentials.resolve(tool.name, config, cache: credential_cache, ns: tool.credentials_ns),
+          runtime: get_runtime&.call
         )
       end
     end
@@ -35,9 +38,19 @@ module ZeroMcp
     # title:            OpenAPI info.title override. Ignored if config: is given.
     # execute_timeout:  default per-tool execute timeout in seconds. Ignored if
     #                   config: is given.
-    def create(tools, config: nil, title: nil, execute_timeout: nil)
-      cfg = config || Config.new(title: title, execute_timeout: execute_timeout)
-      server = Server.new(cfg, tools: tools)
+    # remote:           Array of remote MCP servers ({ 'name', 'url', 'auth',
+    #                   'tools' }) to federate. Ignored if config: is given
+    #                   (config.remote is used). Connects synchronously:
+    #                   create blocks until every remote has answered or failed.
+    #                   Remote tools are served from `mcp` only; they have no
+    #                   route, so they never appear in `routes` or `openapi`.
+    # get_runtime:      optional callable, arity 0. Its return value becomes
+    #                   ctx.runtime for local tools, on `mcp` tools/call and in
+    #                   context_for.
+    def create(tools, config: nil, title: nil, execute_timeout: nil, remote: nil, get_runtime: nil)
+      cfg = config || Config.new(title: title, execute_timeout: execute_timeout, remote: remote)
+      server = Server.new(cfg, tools: tools, get_runtime: get_runtime)
+      merged = cfg.remote.empty? ? tools : server.attach_remote(Remote.connect(cfg.remote))
       credential_cache = {}
 
       routes = tools.each_with_object([]) do |(name, tool), acc|
@@ -47,16 +60,18 @@ module ZeroMcp
 
       ToolRegistry.new(
         routes: routes,
-        openapi: OpenApi.build(tools, cfg),
+        openapi: OpenApi.build(merged, cfg),
         mcp: ->(request) { server.handle_request(request) },
         config: cfg,
-        credential_cache: credential_cache
+        credential_cache: credential_cache,
+        get_runtime: get_runtime
       )
     end
   end
 
-  # Top-level convenience, mirroring ZeroMcp.serve / ZeroMcp.serve_http.
-  def self.create_registry(tools, config: nil, title: nil, execute_timeout: nil)
-    Registry.create(tools, config: config, title: title, execute_timeout: execute_timeout)
+  # Top-level convenience, mirroring ZeroMcp.serve.
+  def self.create_registry(tools, config: nil, title: nil, execute_timeout: nil, remote: nil, get_runtime: nil)
+    Registry.create(tools, config: config, title: title, execute_timeout: execute_timeout,
+                           remote: remote, get_runtime: get_runtime)
   end
 end

data/lib/zeromcp/remote.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+require_relative 'config'
+require_relative 'tool'
+
+module ZeroMcp
+  # Federates remote MCP servers over HTTP. Each remote tool is exposed
+  # locally as "<server name>.<tool name>" and forwards tools/call upstream.
+  module Remote
+    module_function
+
+    # servers: Array<Hash> ('name', 'url', 'auth', 'tools'; string or symbol keys)
+    # => Hash[String, ZeroMcp::Tool], keyed "<server name>.<tool name>"
+    def connect(servers)
+      all = {}
+      (servers || []).each do |server|
+        name = fetch(server, 'name')
+        begin
+          tools = connect_one(server)
+          tools.each do |tool_name, tool|
+            ns_name = "#{name}.#{tool_name}"
+            all[ns_name] = tool
+            $stderr.puts "[mcp] Remote tool: #{ns_name}"
+          end
+        rescue => e
+          $stderr.puts "[mcp] Failed to connect to #{name}: #{e.message}"
+        end
+      end
+      all
+    end
+
+    # JSON Schema properties/required -> ZeroMcp input hash
+    def schema_to_input(schema)
+      input = {}
+      return input unless schema.is_a?(Hash) && schema['properties'].is_a?(Hash)
+
+      required = schema['required'].is_a?(Array) ? schema['required'] : []
+      schema['properties'].each do |key, prop|
+        prop = {} unless prop.is_a?(Hash)
+        type = prop['type'] || 'string'
+        is_required = required.include?(key)
+
+        if prop['description'] || !is_required
+          entry = { type: type }
+          entry[:description] = prop['description'] if prop['description']
+          entry[:optional] = true unless is_required
+          input[key] = entry
+        else
+          input[key] = type
+        end
+      end
+      input
+    end
+
+    def connect_one(server)
+      name = fetch(server, 'name')
+      url = fetch(server, 'url').to_s
+      unless url.start_with?('http://', 'https://')
+        raise "Remote server \"#{name}\" must have an HTTP/HTTPS URL, got: #{url}"
+      end
+
+      auth = Config.resolve_auth(fetch(server, 'auth'))
+      allow = fetch(server, 'tools')
+
+      rpc(url, { jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }, auth)
+      list = rpc(url, { jsonrpc: '2.0', id: 2, method: 'tools/list', params: {} }, auth)
+
+      remote_tools = (list.is_a?(Hash) && list['result'].is_a?(Hash) && list['result']['tools']) || []
+      remote_tools = remote_tools.select { |rt| allow.include?(rt['name']) } if allow
+
+      tools = {}
+      remote_tools.each do |rt|
+        upstream = rt['name']
+        tools[upstream] = Tool.new(
+          name: "#{name}.#{upstream}",
+          description: rt['description'],
+          input: schema_to_input(rt['inputSchema']),
+          permissions: {},
+          route: nil
+        ) do |args, _ctx|
+          res = rpc(url, {
+            jsonrpc: '2.0', id: (Time.now.to_f * 1000).to_i,
+            method: 'tools/call', params: { name: upstream, arguments: args }
+          }, auth)
+          result = res.is_a?(Hash) ? res['result'] : nil
+          content = result.is_a?(Hash) ? result['content'] : nil
+          text = content.is_a?(Array) && content[0].is_a?(Hash) ? content[0]['text'] : nil
+          text.nil? || text == '' ? result : text
+        end
+      end
+
+      $stderr.puts "[mcp] Connected to #{name} (HTTP): #{tools.size} tool(s)"
+      tools
+    end
+
+    def rpc(url, body, auth)
+      uri = URI(url)
+      req = Net::HTTP::Post.new(uri)
+      req['Content-Type'] = 'application/json'
+      req['Authorization'] = "Bearer #{auth}" if auth
+      req.body = JSON.generate(body)
+
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') { |http| http.request(req) }
+      raise "HTTP #{res.code}" unless res.is_a?(Net::HTTPSuccess)
+
+      JSON.parse(res.body)
+    end
+
+    def fetch(hash, key)
+      return nil unless hash.is_a?(Hash)
+      hash.key?(key) ? hash[key] : hash[key.to_sym]
+    end
+  end
+end

data/lib/zeromcp/scanner.rb

@@ -13,38 +13,43 @@ module ZeroMcp
 
     def scan
       @tools.clear
-      dirs = @config.tools_dir
-      dirs = [dirs] unless dirs.is_a?(Array)
 
-      dirs.each do |d|
-        dir = File.expand_path(d)
+      @config.tool_sources.each do |source|
+        dir = File.expand_path(source['path'])
         unless Dir.exist?(dir)
           $stderr.puts "[zeromcp] Cannot read tools directory: #{dir}"
           next
         end
-        scan_dir(dir, dir)
+        scan_dir(dir, dir, source['prefix'])
       end
       @tools
     end
 
+    # The tool source directories, expanded. Used by the autoload watcher.
+    def source_dirs
+      @config.tool_sources.map { |s| File.expand_path(s['path']) }
+    end
+
     private
 
-    def scan_dir(dir, root_dir)
+    def scan_dir(dir, root_dir, source_prefix = nil)
       Dir.entries(dir).sort.each do |entry|
         next if entry.start_with?('.')
 
         full_path = File.join(dir, entry)
 
         if File.directory?(full_path)
-          scan_dir(full_path, root_dir)
+          scan_dir(full_path, root_dir, source_prefix)
         elsif entry.end_with?('.rb')
-          load_tool(full_path, root_dir)
+          load_tool(full_path, root_dir, source_prefix)
         end
       end
     end
 
-    def load_tool(file_path, root_dir)
-      name = build_name(file_path, root_dir)
+    def load_tool(file_path, root_dir, source_prefix = nil)
+      name = build_name(file_path, root_dir, source_prefix)
+      rel_parts = Pathname.new(file_path).relative_path_from(Pathname.new(root_dir)).to_s.split('/')
+      credentials_ns = rel_parts.length > 1 ? rel_parts[0] : nil
 
       # Each tool file should return a hash via a special structure.
       # We use a sandboxed binding to evaluate the file.
@@ -58,7 +63,8 @@ module ZeroMcp
         description: tool_def[:description] || '',
         input: tool_def[:input] || {},
         permissions: tool_def[:permissions] || {},
-        route: tool_def[:route]
+        route: tool_def[:route],
+        credentials_ns: credentials_ns
       ) { |args, ctx| tool_def[:execute].call(args, ctx) }
 
       $stderr.puts "[zeromcp] Loaded: #{name}"
@@ -73,17 +79,38 @@ module ZeroMcp
       loader._tool_definition
     end
 
-    def build_name(file_path, root_dir)
+    # inner = filename, or "<dir_prefix><sep><filename>" for a file under a
+    # subdir, where dir_prefix is namespacing[<top dir>]['prefix'] when that
+    # key is set (an empty string means no prefix) and the dir name otherwise.
+    # A source prefix is then prepended: "<source_prefix><sep><inner>".
+    def build_name(file_path, root_dir, source_prefix = nil)
       rel = Pathname.new(file_path).relative_path_from(Pathname.new(root_dir)).to_s
       parts = rel.split('/')
       filename = File.basename(parts.pop, '.rb')
+      sep = @config.separator
 
+      inner = filename
       if parts.length > 0
-        dir_prefix = parts[0]
-        "#{dir_prefix}#{@config.separator}#{filename}"
-      else
-        filename
+        dir = parts[0]
+        dir_prefix = namespace_prefix(dir)
+        dir_prefix = dir if dir_prefix.nil?
+        inner = "#{dir_prefix}#{sep}#{filename}" unless dir_prefix.empty?
       end
+
+      source_prefix && !source_prefix.empty? ? "#{source_prefix}#{sep}#{inner}" : inner
+    end
+
+    # namespacing[dir]['prefix'] (string or symbol keys), or nil when unset.
+    def namespace_prefix(dir)
+      ns = @config.namespacing
+      return nil unless ns.is_a?(Hash)
+
+      entry = ns.key?(dir) ? ns[dir] : ns[dir.to_sym]
+      return nil unless entry.is_a?(Hash)
+      return entry['prefix'].to_s if entry.key?('prefix') && !entry['prefix'].nil?
+      return entry[:prefix].to_s if entry.key?(:prefix) && !entry[:prefix].nil?
+
+      nil
     end
 
     def log_permissions(name, permissions)

data/lib/zeromcp/server.rb

@@ -3,23 +3,29 @@
 require 'json'
 require 'base64'
 require 'timeout'
-require 'webrick'
 require_relative 'schema'
 require_relative 'config'
 require_relative 'tool'
 require_relative 'scanner'
 require_relative 'sandbox'
-require_relative 'openapi'
 require_relative 'credentials'
+require_relative 'remote'
 
 module ZeroMcp
   class Server
-    def initialize(config = nil, tools: nil)
+    HTTP_REMOVED_MESSAGE = '[zeromcp] The built-in HTTP transport was removed. Mount ZeroMcp.create_registry ' \
+                           '(routes, openapi, mcp) or ZeroMcp::Server#handle_request in your own HTTP server.'
+
+    # get_runtime: optional callable (lambda/proc/method), arity 0. Called on
+    # every local tool execution; its return value becomes ctx.runtime.
+    def initialize(config = nil, tools: nil, get_runtime: nil)
       @config = config || Config.load
       @scanner = Scanner.new(@config)
       @resource_scanner = ResourceScanner.new(@config)
       @prompt_scanner = PromptScanner.new(@config)
       @tools = tools || {}
+      @remote_names = {}
+      @get_runtime = get_runtime
       @resources = {}
       @templates = {}
       @prompts = {}
@@ -27,97 +33,42 @@ module ZeroMcp
       @log_level = 'info'
       @icon = tools ? Config.resolve_icon(@config.icon) : nil
       @credential_cache = {}
+      @out_mutex = Mutex.new
+      @notify = nil
+      @autoload_thread = nil
     end
 
-    # Start an HTTP server that exposes:
-    #   POST /mcp  — JSON-RPC over HTTP
-    #   <method> <path> — per-tool route handlers (tools with a `route:` field)
-    #
-    # Usage: ZeroMcp::Server.new.serve_http(port: 3000)
-    def serve_http(port: 3000)
-      load_tools
-
-      http = WEBrick::HTTPServer.new(Port: port, Logger: WEBrick::Log.new($stderr), AccessLog: [])
-      $stderr.puts "[zeromcp] HTTP server listening on port #{port}"
-
-      # /mcp — JSON-RPC endpoint
-      http.mount_proc('/mcp') do |req, res|
-        begin
-          request = JSON.parse(req.body || '{}')
-        rescue JSON::ParserError
-          res.status = 400
-          res.content_type = 'application/json'
-          res.body = JSON.generate({ 'error' => 'Invalid JSON' })
-          next
-        end
-        response = handle_request(request)
-        res.content_type = 'application/json'
-        res.body = JSON.generate(response || {})
-      end
-
-      # /openapi.json — auto-generated OpenAPI 3.0 spec from routed tools
-      http.mount_proc('/openapi.json') do |_req, res|
-        res.content_type = 'application/json'
-        res.body = JSON.generate(build_openapi_spec)
-      end
-
-      # /docs — Swagger UI
-      http.mount_proc('/docs') do |_req, res|
-        res.content_type = 'text/html'
-        res.body = SWAGGER_UI_HTML
-      end
-
-      # /health — liveness check
-      http.mount_proc('/health') do |_req, res|
-        res.content_type = 'application/json'
-        res.body = JSON.generate({ 'ok' => true })
-      end
-
-      # Register per-tool HTTP routes
-      @tools.each do |_name, tool|
-        next unless tool.route.is_a?(Hash)
-        register_tool_route(http, tool, tool.route_method, tool.route_path)
-      end
-
-      trap('INT')  { http.shutdown }
-      trap('TERM') { http.shutdown }
-      http.start
-    end
-
-    # Load tools (and resources/prompts) from the configured directories.
+    # Load tools (remote + local), resources and prompts from the config.
     # Call this before using handle_request directly (serve calls this
-    # automatically).
+    # automatically). A local scan error propagates.
     def load_tools
-      @tools = @scanner.scan
-      @resource_scanner.scan
-      @resources = @resource_scanner.resources
-      @templates = @resource_scanner.templates
-      @prompt_scanner.scan
-      @prompts = @prompt_scanner.prompts
-      @icon = Config.resolve_icon(@config.icon)
+      @tools = build_tool_map(@scanner.scan)
+      load_resources_and_prompts
+    end
 
-      resource_count = @resources.size + @templates.size
-      $stderr.puts "[zeromcp] #{@tools.size} tool(s), #{resource_count} resource(s), #{@prompts.size} prompt(s)"
+    # Merge remote tools under the current tool map: local tools win, logging
+    # each override. Returns the merged map. Used by Registry.
+    def attach_remote(remote_tools)
+      @tools = merge_remote(remote_tools, @tools)
     end
 
     def serve
+      if @config.http_transport?
+        $stderr.puts HTTP_REMOVED_MESSAGE
+        exit 1
+      end
+
       $stdout.sync = true
       $stderr.sync = true
       $stdin.set_encoding('UTF-8')
       $stdout.set_encoding('UTF-8')
 
-      @tools = @scanner.scan
-      @resource_scanner.scan
-      @resources = @resource_scanner.resources
-      @templates = @resource_scanner.templates
-      @prompt_scanner.scan
-      @prompts = @prompt_scanner.prompts
-      @icon = Config.resolve_icon(@config.icon)
-
-      resource_count = @resources.size + @templates.size
-      $stderr.puts "[zeromcp] #{@tools.size} tool(s), #{resource_count} resource(s), #{@prompts.size} prompt(s)"
+      load_for_serve
       $stderr.puts "[zeromcp] stdio transport ready"
 
+      @notify = ->(method, params) { write_message({ 'jsonrpc' => '2.0', 'method' => method, 'params' => params }) }
+      start_autoload if @config.autoload_tools
+
       $stdin.each_line do |line|
         begin
           line = line.encode('UTF-8', invalid: :replace, undef: :replace, replace: '').strip
@@ -135,11 +86,10 @@ module ZeroMcp
         next unless request.is_a?(Hash)
 
         response = handle_request(request)
-        if response
-          $stdout.puts JSON.generate(response)
-          $stdout.flush
-        end
+        write_message(response) if response
       end
+    ensure
+      stop_autoload
     end
 
     # Process a single JSON-RPC request hash and return a response hash.
@@ -481,7 +431,9 @@ module ZeroMcp
       end
 
       begin
-        ctx = Context.new(tool_name: name, permissions: tool.permissions, bypass: @config.bypass_permissions, credentials: _resolve_credentials(name))
+        ctx = Context.new(tool_name: name, permissions: tool.permissions, bypass: @config.bypass_permissions,
+                          credentials: _resolve_credentials(tool, name),
+                          runtime: @remote_names.key?(name) ? nil : @get_runtime&.call)
 
         # Tool-level timeout overrides config default
         timeout_secs = (tool.permissions.is_a?(Hash) && tool.permissions[:execute_timeout]) ||
@@ -498,96 +450,124 @@ module ZeroMcp
       end
     end
 
-    def _resolve_credentials(tool_name)
-      Credentials.resolve(tool_name, @config, cache: @credential_cache)
+    def _resolve_credentials(tool, tool_name)
+      Credentials.resolve(tool_name, @config, cache: @credential_cache, ns: tool.credentials_ns)
     end
 
-    # --- HTTP route helpers ---
+    # --- Loading ---
 
-    def register_tool_route(http, tool, route_method, route_path)
-      # Convert :param segments to a regex for matching
-      param_names = []
-      regex_str = route_path.gsub(/:([A-Za-z_][A-Za-z0-9_]*)/) do
-        param_names << $1
-        '([^/]+)'
-      end
-      route_regex = /\A#{regex_str}\z/
+    # Remote tools first, then local tools over them (Node: server.ts / handler.ts).
+    def build_tool_map(local_tools)
+      @remote_names = {}
+      remote = @config.remote.empty? ? {} : Remote.connect(@config.remote)
+      merge_remote(remote, local_tools)
+    end
 
-      http.mount_proc(route_path_prefix(route_path)) do |req, res|
-        next unless req.request_method == route_method
+    def merge_remote(remote_tools, local_tools)
+      merged = {}
+      remote_tools.each { |name, tool| merged[name] = tool }
+      local_tools.each do |name, tool|
+        $stderr.puts "[zeromcp] Local tool \"#{name}\" overrides remote" if remote_tools.key?(name)
+        merged[name] = tool
+      end
+      remote_tools.each_key { |name| @remote_names[name] = true unless local_tools.key?(name) }
+      merged
+    end
 
-        path_params = extract_path_params(req.path, route_regex, param_names)
-        unless path_params
-          res.status = 404
-          res.content_type = 'application/json'
-          res.body = JSON.generate({ 'ok' => false, 'error' => 'Not found' })
-          next
+    # serve's loading path: like load_tools, but a failing local scan only
+    # exits when there is nothing else to serve (Node: server.ts).
+    def load_for_serve
+      local = begin
+        @scanner.scan
+      rescue StandardError
+        if @config.remote.empty? && @config.resources_dir.empty? && @config.prompts_dir.empty?
+          $stderr.puts '[zeromcp] No tools directory and no remote servers configured'
+          exit 1
         end
+        {}
+      end
+      @tools = build_tool_map(local)
+      load_resources_and_prompts
+    end
 
-        args = if route_method == 'GET'
-          query_args = WEBrick::HTTPUtils.parse_query(req.query_string || '')
-          query_args.merge(path_params)
-        else
-          body_args = begin
-            req.body && !req.body.empty? ? JSON.parse(req.body) : {}
-          rescue JSON::ParserError
-            {}
-          end
-          body_args.merge(path_params)
-        end
+    def load_resources_and_prompts
+      @resource_scanner.scan
+      @resources = @resource_scanner.resources
+      @templates = @resource_scanner.templates
+      @prompt_scanner.scan
+      @prompts = @prompt_scanner.prompts
+      @icon = Config.resolve_icon(@config.icon)
 
-        begin
-          ctx = Context.new(tool_name: tool.name, permissions: tool.permissions,
-                            bypass: @config.bypass_permissions,
-                            credentials: _resolve_credentials(tool.name))
-          timeout_secs = (tool.permissions.is_a?(Hash) && tool.permissions[:execute_timeout]) ||
-                         (tool.permissions.is_a?(Hash) && tool.permissions['execute_timeout']) ||
-                         @config.execute_timeout
-          result = Timeout.timeout(timeout_secs) { tool.call(args, ctx) }
-          res.content_type = 'application/json'
-          res.body = JSON.generate({ 'ok' => true, 'result' => result })
-        rescue => e
-          res.status = 500
-          res.content_type = 'application/json'
-          res.body = JSON.generate({ 'ok' => false, 'error' => e.message })
-        end
-      end
+      resource_count = @resources.size + @templates.size
+      $stderr.puts "[zeromcp] #{@tools.size} tool(s), #{resource_count} resource(s), #{@prompts.size} prompt(s)"
     end
 
-    def route_path_prefix(route_path)
-      # WEBrick mounts on a fixed prefix; use the static prefix before first :param
-      route_path.split('/:').first || '/'
+    # --- Output ---
+
+    # Stdout is shared by the stdin loop and the autoload watcher thread.
+    def write_message(message)
+      @out_mutex.synchronize do
+        $stdout.puts JSON.generate(message)
+        $stdout.flush
+      end
     end
 
-    def extract_path_params(path, route_regex, param_names)
-      m = path.match(route_regex)
-      return nil unless m
-      result = {}
-      param_names.each_with_index { |name, i| result[name] = m[i + 1] }
-      result
+    # --- Hot reload (autoload_tools) ---
+
+    # Ruby's stdlib has no recursive file watcher, so poll mtimes of every
+    # .rb file under each tool source. On a change: rescan, set every
+    # rescanned tool into the live map (never removing entries, as Node does),
+    # and send notifications/tools/list_changed when stdio is running.
+    def start_autoload(interval: 1.0)
+      snapshot = tool_file_snapshot
+      @autoload_thread = Thread.new do
+        loop do
+          sleep interval
+          current = tool_file_snapshot
+          changed = (current.keys | snapshot.keys).reject { |k| current[k] == snapshot[k] }
+          snapshot_was = snapshot
+          snapshot = current
+          next if changed.empty?
+
+          changed.sort.each { |path| $stderr.puts "[zeromcp] Change detected: #{(current[path] || snapshot_was[path])[0]}" }
+          reload_tools
+        rescue StandardError => e
+          $stderr.puts "[zeromcp] autoload error: #{e.message}"
+        end
+      end
+      $stderr.puts '[zeromcp] autoload_tools enabled — watching for changes'
+      @autoload_thread
     end
 
-    # --- OpenAPI spec builder ---
+    def stop_autoload
+      @autoload_thread&.kill
+      @autoload_thread = nil
+    end
 
-    def build_openapi_spec
-      OpenApi.build(@tools, @config)
+    def reload_tools
+      rescanned = @scanner.scan.dup
+      tools = @tools.dup
+      rescanned.each do |name, tool|
+        tools[name] = tool
+        @remote_names.delete(name)
+      end
+      @tools = tools
+      @notify&.call('notifications/tools/list_changed', {})
     end
 
-    SWAGGER_UI_HTML = <<~HTML.freeze
-      <!DOCTYPE html>
-      <html>
-      <head>
-        <title>ZeroMCP API</title>
-        <meta charset="utf-8"/>
-        <meta name="viewport" content="width=device-width, initial-scale=1">
-        <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css">
-      </head>
-      <body>
-      <div id="swagger-ui"></div>
-      <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
-      <script>SwaggerUIBundle({ url: '/openapi.json', dom_id: '#swagger-ui' })</script>
-      </body>
-      </html>
-    HTML
+    # { <absolute path> => [<path relative to its source>, mtime] } for every tool file.
+    def tool_file_snapshot
+      snap = {}
+      @scanner.source_dirs.each do |dir|
+        next unless Dir.exist?(dir)
+        Dir.glob('**/*.rb', base: dir).each do |rel|
+          full = File.join(dir, rel)
+          snap[full] = [rel, File.mtime(full)]
+        rescue StandardError
+          next
+        end
+      end
+      snap
+    end
   end
 end

data/lib/zeromcp/tool.rb

@@ -4,14 +4,20 @@ require_relative 'schema'
 
 module ZeroMcp
   class Tool
-    attr_reader :name, :description, :input, :permissions, :execute_block, :cached_schema, :route
+    attr_reader :name, :description, :input, :permissions, :execute_block, :cached_schema, :route,
+                :credentials_ns
 
-    def initialize(name:, description: '', input: {}, permissions: {}, route: nil, &block)
+    # credentials_ns: the `credentials` config key this tool's credentials come
+    # from. Scanner sets it to the tool's top-level directory, so a
+    # `namespacing` prefix doesn't change which credentials it gets. nil means
+    # match by tool-name prefix.
+    def initialize(name:, description: '', input: {}, permissions: {}, route: nil, credentials_ns: nil, &block)
       @name = name
       @description = description
       @input = input
       @permissions = permissions
       @route = route
+      @credentials_ns = credentials_ns
       @execute_block = block
       @cached_schema = Schema.to_json_schema(@input)
     end
@@ -32,13 +38,14 @@ module ZeroMcp
   end
 
   class Context
-    attr_reader :credentials, :tool_name, :permissions, :bypass
+    attr_reader :credentials, :tool_name, :permissions, :bypass, :runtime
 
-    def initialize(tool_name:, credentials: nil, permissions: {}, bypass: false)
+    def initialize(tool_name:, credentials: nil, permissions: {}, bypass: false, runtime: nil)
       @tool_name = tool_name
       @credentials = credentials
       @permissions = permissions
       @bypass = bypass
+      @runtime = runtime
     end
   end
 

data/lib/zeromcp.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'zeromcp/server'
+require_relative 'zeromcp/remote'
 require_relative 'zeromcp/registry'
 
 module ZeroMcp
@@ -9,10 +10,4 @@ module ZeroMcp
     server = Server.new(config)
     server.serve
   end
-
-  def self.serve_http(port: 3000, config_path: nil)
-    config = config_path ? Config.load(config_path) : Config.load
-    server = Server.new(config)
-    server.serve_http(port: port)
-  end
 end

data/zeromcp.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name        = 'zeromcp'
-  s.version     = '0.3.0'
+  s.version     = '0.4.0'
   s.summary     = 'Zero-config MCP runtime'
   s.description = 'Drop tool files in a directory, get a working MCP server. Zero boilerplate.'
   s.authors     = ['Antidrift']

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeromcp
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Antidrift
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-06 00:00:00.000000000 Z
+date: 2026-10-14 00:00:00.000000000 Z
 dependencies: []
 description: Drop tool files in a directory, get a working MCP server. Zero boilerplate.
 email: hello@probeo.io
@@ -25,6 +25,7 @@ files:
 - lib/zeromcp/credentials.rb
 - lib/zeromcp/openapi.rb
 - lib/zeromcp/registry.rb
+- lib/zeromcp/remote.rb
 - lib/zeromcp/sandbox.rb
 - lib/zeromcp/scanner.rb
 - lib/zeromcp/schema.rb