zeromcp 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2e5b203cdc7f03afff0cf6ce507e9480455b3f16e469222d5934af9351ffa9a
-  data.tar.gz: 8e968d22d810a2f25962eb5de0f242438f3ea4359c40cee4616398280695c6f8
+  metadata.gz: 4b5b1e9efe4dd7daa0f3ac769bc0989684a322df09a9b6f0886b1f8c9b11be14
+  data.tar.gz: b8b9a22497327fdf3618c01d959e01d692a83f6c4785d6e7b655bdd5eacdc8fb
 SHA512:
-  metadata.gz: b5af7807f278f6430cd65fad75104d90536fbe5c840a2dfce3b7c125415940d65f4166e420f06b085c1ff6fe60c90a525773956e4e341c3b20098258227296a5
-  data.tar.gz: 3c0c7c8350efedaf3bf7ec4342e85f817b6da45e6668d6aace1553ef98edc478143db42acc4652b119a179c7b4580ddef29c54226457d03b3ed88d4582e6bd09
+  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,31 +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 'zeromcp'
+
+config = ZeroMcp::Config.load
+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
+
+# OpenAPI
+get '/openapi.json' do
+  content_type :json
+  registry.openapi.to_json
+end
 
-  if response.nil?
-    status 204
-  else
+# 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+
@@ -66,7 +140,7 @@ end
 
 ```sh
 gem build zeromcp.gemspec
-gem install zeromcp-0.1.0.gem
+gem install zeromcp-0.2.2.gem
 ```
 
 ## Sandbox
@@ -98,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 }'
+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
+                :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
@@ -28,6 +31,10 @@ module ZeroMcp
       @namespacing = opts[:namespacing] || opts['namespacing'] || {}
       @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
@@ -43,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)
@@ -64,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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module ZeroMcp
+  module Credentials
+    module_function
+
+    # 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?
+      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
+    end
+
+    def resolve_for_ns(ns, source, config, cache)
+      return resolve_source(source) unless config.cache_credentials
+      return cache[ns] if cache && cache.key?(ns)
+      creds = resolve_source(source)
+      cache[ns] = creds if cache
+      creds
+    end
+
+    def resolve_source(source)
+      source = source.transform_keys(&:to_s) if source.is_a?(Hash)
+      if source['env']
+        val = ENV[source['env']]
+        return nil if val.nil? || val.empty?
+        begin; return JSON.parse(val); rescue; return val; end
+      end
+      if source['file']
+        path = File.expand_path(source['file'])
+        return nil unless File.exist?(path)
+        val = File.read(path).strip
+        begin; return JSON.parse(val); rescue; return val; end
+      end
+      nil
+    end
+  end
+end

data/lib/zeromcp/openapi.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require_relative 'schema'
+
+module ZeroMcp
+  module OpenApi
+    module_function
+
+    def build(tools, config)
+      paths = {}
+
+      tools.each do |_name, tool|
+        next unless tool.route.is_a?(Hash)
+
+        route_method = tool.route_method
+        route_path = tool.route_path
+
+        # Extract :param names from path, convert to {param} for OpenAPI
+        path_param_names = route_path.scan(/:([A-Za-z_][A-Za-z0-9_]*)/).flatten
+        openapi_path = route_path.gsub(/:([A-Za-z_][A-Za-z0-9_]*)/, '{\1}')
+
+        input = tool.input || {}
+        operation = {
+          'operationId' => tool.name,
+          'description' => tool.description || '',
+          'responses'   => {
+            '200' => { 'description' => 'Success' },
+            '500' => { 'description' => 'Error' }
+          }
+        }
+
+        if route_method == 'GET'
+          operation['parameters'] = build_parameters(input, path_param_names)
+        else
+          operation['requestBody'] = build_request_body(input, path_param_names)
+          unless path_param_names.empty?
+            operation['parameters'] = path_param_names.map do |name|
+              {
+                'name'     => name,
+                'in'       => 'path',
+                'required' => true,
+                'schema'   => { 'type' => 'string' }
+              }
+            end
+          end
+        end
+
+        paths[openapi_path] ||= {}
+        paths[openapi_path][route_method.downcase] = operation
+      end
+
+      {
+        'openapi' => '3.0.0',
+        'info'    => { 'title' => config.title, 'version' => '0.5.0' },
+        'paths'   => paths
+      }
+    end
+
+    def build_parameters(input, path_param_names)
+      params = []
+
+      # Path params first (preserve order from path)
+      path_param_names.each do |name|
+        spec = field_to_openapi_schema(input[name] || input[name.to_sym])
+        params << {
+          'name'     => name,
+          'in'       => 'path',
+          'required' => true,
+          'schema'   => spec
+        }
+      end
+
+      # Remaining fields as query params
+      input.each do |key, value|
+        key_s = key.to_s
+        next if path_param_names.include?(key_s)
+
+        spec     = field_to_openapi_schema(value)
+        optional = value.is_a?(Hash) && (value[:optional] || value['optional'])
+        params << {
+          'name'     => key_s,
+          'in'       => 'query',
+          'required' => !optional,
+          'schema'   => spec
+        }
+      end
+
+      params
+    end
+
+    def build_request_body(input, path_param_names)
+      body_input = input.reject { |key, _| path_param_names.include?(key.to_s) }
+      schema = Schema.to_json_schema(body_input)
+      {
+        'required' => true,
+        'content'  => {
+          'application/json' => { 'schema' => schema }
+        }
+      }
+    end
+
+    def field_to_openapi_schema(value)
+      return { 'type' => 'string' } if value.nil?
+
+      if value.is_a?(String)
+        Schema::TYPE_MAP[value] || { 'type' => 'string' }
+      elsif value.is_a?(Hash)
+        type = value[:type] || value['type']
+        mapped = Schema::TYPE_MAP[type.to_s] || { 'type' => 'string' }
+        spec = mapped.dup
+        desc = value[:description] || value['description']
+        spec['description'] = desc if desc
+        spec
+      else
+        { 'type' => 'string' }
+      end
+    end
+  end
+end

data/lib/zeromcp/registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+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, :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. 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, ns: tool.credentials_ns),
+          runtime: get_runtime&.call
+        )
+      end
+    end
+
+    module_function
+
+    # tools:           Hash[String, ZeroMcp::Tool] — already-constructed Tool
+    #                   instances, the same object Scanner#load_tool produces.
+    #                   Not raw hashes, and not file paths.
+    # config:           optional ZeroMcp::Config. Defaults to ZeroMcp::Config.new
+    #                   (in-memory defaults, no zeromcp.config.json file read).
+    #                   When supplied, title:/execute_timeout: are ignored (the
+    #                   config already fully specifies them).
+    # title:            OpenAPI info.title override. Ignored if config: is given.
+    # execute_timeout:  default per-tool execute timeout in seconds. Ignored if
+    #                   config: is given.
+    # 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|
+        next unless tool.route.is_a?(Hash)
+        acc << RouteDefinition.new(name: name, method: tool.route_method, path: tool.route_path, tool: tool)
+      end
+
+      ToolRegistry.new(
+        routes: routes,
+        openapi: OpenApi.build(merged, cfg),
+        mcp: ->(request) { server.handle_request(request) },
+        config: cfg,
+        credential_cache: credential_cache,
+        get_runtime: get_runtime
+      )
+    end
+  end
+
+  # 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.
@@ -57,7 +62,9 @@ module ZeroMcp
         name: name,
         description: tool_def[:description] || '',
         input: tool_def[:input] || {},
-        permissions: tool_def[:permissions] || {}
+        permissions: tool_def[:permissions] || {},
+        route: tool_def[:route],
+        credentials_ns: credentials_ns
       ) { |args, ctx| tool_def[:execute].call(args, ctx) }
 
       $stderr.puts "[zeromcp] Loaded: #{name}"
@@ -72,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)
@@ -103,10 +131,11 @@ module ZeroMcp
       @definition = {}
     end
 
-    def tool(description: '', permissions: {}, input: {})
+    def tool(description: '', permissions: {}, input: {}, route: nil)
       @definition[:description] = description
       @definition[:permissions] = permissions
       @definition[:input] = input
+      @definition[:route] = route
     end
 
     def execute(&block)

data/lib/zeromcp/server.rb

@@ -8,58 +8,67 @@ require_relative 'config'
 require_relative 'tool'
 require_relative 'scanner'
 require_relative 'sandbox'
+require_relative 'credentials'
+require_relative 'remote'
 
 module ZeroMcp
   class Server
-    def initialize(config = 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 = tools || {}
+      @remote_names = {}
+      @get_runtime = get_runtime
       @resources = {}
       @templates = {}
       @prompts = {}
       @subscriptions = {}
       @log_level = 'info'
-      @icon = nil
+      @icon = tools ? Config.resolve_icon(@config.icon) : nil
       @credential_cache = {}
+      @out_mutex = Mutex.new
+      @notify = nil
+      @autoload_thread = nil
     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
@@ -77,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.
@@ -423,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]) ||
@@ -440,38 +450,124 @@ module ZeroMcp
       end
     end
 
-    def _resolve_credentials(tool_name)
-      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_credentials_for_ns(ns.to_s, source)
+    def _resolve_credentials(tool, tool_name)
+      Credentials.resolve(tool_name, @config, cache: @credential_cache, ns: tool.credentials_ns)
+    end
+
+    # --- Loading ---
+
+    # 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
+
+    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
+
+    # 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
-      nil
+      @tools = build_tool_map(local)
+      load_resources_and_prompts
     end
 
-    def _resolve_credentials_for_ns(ns, source)
-      return _resolve_credential_source(source) unless @config.cache_credentials
-      return @credential_cache[ns] if @credential_cache.key?(ns)
-      creds = _resolve_credential_source(source)
-      @credential_cache[ns] = creds
-      creds
+    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)
+
+      resource_count = @resources.size + @templates.size
+      $stderr.puts "[zeromcp] #{@tools.size} tool(s), #{resource_count} resource(s), #{@prompts.size} prompt(s)"
     end
 
-    def _resolve_credential_source(source)
-      source = source.transform_keys(&:to_s) if source.is_a?(Hash)
-      if source['env']
-        val = ENV[source['env']]
-        return nil if val.nil? || val.empty?
-        begin; return JSON.parse(val); rescue; return val; end
+    # --- 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
-      if source['file']
-        path = File.expand_path(source['file'])
-        return nil unless File.exist?(path)
-        val = File.read(path).strip
-        begin; return JSON.parse(val); rescue; return val; end
+    end
+
+    # --- 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
+
+    def stop_autoload
+      @autoload_thread&.kill
+      @autoload_thread = nil
+    end
+
+    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
+
+    # { <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
-      nil
+      snap
     end
   end
 end

data/lib/zeromcp/tool.rb

@@ -4,13 +4,20 @@ require_relative 'schema'
 
 module ZeroMcp
   class Tool
-    attr_reader :name, :description, :input, :permissions, :execute_block, :cached_schema
+    attr_reader :name, :description, :input, :permissions, :execute_block, :cached_schema, :route,
+                :credentials_ns
 
-    def initialize(name:, description: '', input: {}, permissions: {}, &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
@@ -18,16 +25,27 @@ module ZeroMcp
     def call(args, ctx = {})
       @execute_block.call(args, ctx)
     end
+
+    def route_method
+      return nil unless @route.is_a?(Hash)
+      (@route[:method] || @route['method'] || 'POST').upcase
+    end
+
+    def route_path
+      return nil unless @route.is_a?(Hash)
+      @route[:path] || @route['path'] || '/'
+    end
   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,8 @@
 # frozen_string_literal: true
 
 require_relative 'zeromcp/server'
+require_relative 'zeromcp/remote'
+require_relative 'zeromcp/registry'
 
 module ZeroMcp
   def self.serve(config_path = nil)

data/zeromcp.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |s|
   s.name        = 'zeromcp'
-  s.version     = '0.2.2'
+  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.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Antidrift
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-25 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
@@ -22,6 +22,10 @@ files:
 - bin/zeromcp
 - lib/zeromcp.rb
 - lib/zeromcp/config.rb
+- 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