nano_mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '049ec03429cd7d181a0b123542e7717dafacfa3ab0ba7bebcfe91240c0d47f80'
+  data.tar.gz: 1800e1e3f538bf4821cf870bfc6db2989024bc41aa28dcaf24252f1cbc9e4f53
+SHA512:
+  metadata.gz: 187c7b64250f6589e5552b51ed36a9cb9e084c322fe0601ec455a79cafcff0d708c86f980943a5fcb425163d69f094b16076642b6d66018f2e3d4decee4a406a
+  data.tar.gz: bd907532fe5710d2de079f6a2b144dd3fa360bcce79cb307d15920983cc8e404be4650dd56d0f4073d75a25bd9ded00f87aa6c900437c76c37bbdbfec7bacbb5

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+Initial release, extracted from the MCP servers in geneva_drive_admin and Comptoir.
+
+- `NanoMCP::Server`, a Rack app serving tools over stateless Streamable HTTP per MCP revision 2026-07-28,
+  which also answers clients of 2025-11-25 and earlier
+- `NanoMCP::Tool` and `NanoMCP::Result` for writing tools, with argument checking against the input schema
+- `NanoMCP.bearer_token` and `NanoMCP.token_matches?` for token authentication
+- Servers and tools work from non-main Ractors, and a server can be made shareable between them

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Julik Tarkhanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,237 @@
+# nano_mcp
+
+A (slightly unhinged) library for building small MCPs.
+
+> [!IMPORTANT]
+> **This gem is for my own private use.** It is public so that my other gems can depend on it,
+> not because I am looking to support it for anyone else. It sits underneath several of my
+> gems and apps at once - a diamond dependency - and that comes with **strict
+> backwards-compatibility constraints**:
+>
+> - The public API is the short list under [Public API](#public-api), and nothing else.
+> - Within a major version that list only ever grows. Nothing on it gets renamed, removed or
+>   changes meaning.
+> - Anything not on the list - private constants, the log line format, error message wording -
+>   can change in any release.
+> - Feature requests that grow the surface will most likely be declined. Bug reports are welcome.
+>
+> If you need something bigger, use [the official Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk).
+
+## What it is
+
+A Rack app that serves [MCP](https://modelcontextprotocol.io) tools over Streamable HTTP, written
+against the **stateless** revision of the spec, [2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28).
+It has:
+
+- no sessions, no SSE, no GET stream - every request is one POST, and any process can serve it
+- no runtime dependencies - not even Rack, only `json` and `openssl` from the standard library
+- tools only - no resources, prompts, sampling or elicitation
+
+Clients of revision 2025-11-25 and earlier open with `initialize` instead of putting the protocol
+version in every request. They get answered the way they expect, from the same endpoint, but still
+without a session.
+
+## Installation
+
+```ruby
+gem "nano_mcp"
+```
+
+## Usage
+
+A tool is a class with a name, a description, an input schema and a `#call`:
+
+```ruby
+class GetWorkflow < NanoMCP::Tool
+  tool_name "get_workflow"
+  title "Get workflow"
+  description "One workflow by id, with its state and hero"
+  input_schema properties: {id: {type: "integer", minimum: 1}}, required: ["id"]
+  annotations readOnlyHint: true, openWorldHint: false
+
+  def call(id:)
+    workflow = context.store.find(id) or raise NanoMCP::ToolError, "No workflow with id #{id}"
+    NanoMCP::Result.json(workflow.to_h)
+  end
+end
+```
+
+A server is a Rack app with a list of tools and a block that authenticates. The block gets the Rack
+env and the request's `_meta`, and returns whatever your tools should see as `context`, or `nil` to
+refuse with a 401:
+
+```ruby
+MCP_SERVER = NanoMCP::Server.new(
+  name: "workflows",
+  title: "Workflows on #{Rails.application.class.module_parent_name} (#{Rails.env})",
+  version: MyGem::VERSION,
+  instructions: "Read this before drawing conclusions: `paused` is not a crash...",
+  tools: [GetWorkflow, SearchWorkflows],
+  logger: Rails.logger
+) do |env, meta|
+  key = ApiToken.find_by(token: NanoMCP.bearer_token(env))
+  next if key.nil? || key.expired?
+  MyContext.new(user: key.user, client: meta.dig("io.modelcontextprotocol/clientInfo", "name"))
+end
+```
+
+The context is how tools know who is calling: whatever the block returns is `context` in every tool
+for that request, and nano_mcp never looks inside it. Copy into it anything from the request that
+tools need. They don't see the Rack env themselves.
+
+`_meta` is the hash as the client sent it, with string keys. A current client sends its name and
+capabilities in it on every request. An older client sends them only once, in `initialize`, so for
+its tool calls `_meta` is usually empty. A lambda taking only `env` works too.
+
+Mount it:
+
+```ruby
+# config/routes.rb
+mount MCP_SERVER => "/mcp"
+```
+
+or run it from a `config.ru`. See [examples/](examples) for a complete server, which the tests drive.
+
+### Results
+
+`#call` returns a `NanoMCP::Result`:
+
+- `Result.text(string)` - prose
+- `Result.json(value, summary: nil)` - structured data. A current client gets it as
+  `structuredContent`, next to a text block holding `summary` (or the JSON itself if you gave no
+  summary). An older client gets the JSON in the text block.
+- `Result.error(message)` - a refusal the agent should read. Raising `NanoMCP::ToolError` does the same.
+
+Bad arguments come back as error results too, worded so an agent can fix its call. Any other
+exception becomes a JSON-RPC internal error that names the exception class. The message stays in
+your logs, since it may carry your data.
+
+### Arguments
+
+Arguments are checked against `input_schema` before `#call` sees them, and passed as keywords.
+The checker handles the top level of the schema: `type`, `required`, `enum`, `minimum`, `maximum`,
+`minLength`, `maxLength`, `minItems`, `maxItems`, `items` and `default`. Unknown arguments are
+refused, and the schema sent to clients says `additionalProperties: false` to match. Integers sent
+as strings are accepted, because agents do that. A number over `maximum` is clamped down to it rather than refused.
+
+### Wrapping every tool
+
+There are two hooks for house rules, both meant to be overridden in your own base class:
+
+```ruby
+class MyTool < NanoMCP::Tool
+  def self.mutating
+    @mutating = true
+    annotations readOnlyHint: false, destructiveHint: false
+  end
+
+  def self.mutating? = !!@mutating
+
+  # Around every call: permission gates, log tags, timeouts
+  def invoke(arguments)
+    if self.class.mutating? && !context.mutations_permitted?
+      return NanoMCP::Result.error("Refused: mutations are disabled on this server")
+    end
+    Rails.logger.tagged("mcp_tool=#{self.class.tool_name}") { super }
+  end
+
+  # The tools/list entry, per caller
+  def self.descriptor(context)
+    entry = super
+    entry[:description] += "\n\nDISABLED for you" if mutating? && !context.mutations_permitted?
+    entry
+  end
+end
+
+class PauseWorkflows < MyTool
+  tool_name "pause_workflows"
+  mutating
+  # ...
+end
+```
+
+### Ractors
+
+A server works from non-main Ractors in two ways, and the test suite checks both.
+
+**One server per Ractor.** Build it inside the Ractor, and anything goes: any block, any logger.
+
+**One server shared by every Ractor**, which is what a Ractor-based Rack server loading a
+`config.ru` would want. The server's own state is all frozen, so `Ractor.make_shareable` works on it
+as long as the two things you hand it are shareable too:
+
+- The block has to be a shareable proc. A block written in `config.ru` has the Rack builder as its
+  `self`, which is not shareable, so create it with a `nil` self instead. It may only refer to
+  shareable things, such as frozen constants.
+- The logger has to be shareable or left out. A standard `Logger` is not, and freezing it breaks it.
+
+```ruby
+# Ruby 4.0
+authenticate = Ractor.shareable_proc { |env, meta| ... }
+# Ruby 3.2 and up
+authenticate = nil.instance_eval { proc { |env, meta| ... } }
+
+run Ractor.make_shareable(NanoMCP::Server.new(name: "workflows", version: "1", tools: TOOLS, &authenticate))
+```
+
+Tool classes store whatever you set on them as frozen copies, so they can be read from any Ractor.
+
+### Things the server does not do for you
+
+The server stays small by leaving these to the host:
+
+- **Turning it off.** Wrap it: `->(env) { enabled? ? MCP_SERVER.call(env) : [404, {}, []] }`.
+- **Pretending to be absent.** To answer 404 rather than 401 to a caller without a token, check the
+  token in a wrapper like the one above.
+- **Building the server from runtime settings.** Constructing one is cheap, so build it per request
+  if its instructions or tools depend on configuration.
+- **Logging arguments.** The log line per call has the tool, era, error flag, size and duration.
+  Arguments are left out because they may carry secrets. Log them in `#invoke` if you need them.
+
+## Public API
+
+This is all of it. Everything else is private, whatever Ruby visibility it happens to have.
+
+- `NanoMCP::VERSION`, `NanoMCP::PROTOCOL_VERSION`, `NanoMCP::MINIMUM_TOKEN_LENGTH`
+- `NanoMCP.bearer_token(env)`, `NanoMCP.token_matches?(presented, configured)`
+- `NanoMCP::Error`, `NanoMCP::ToolError`
+- `NanoMCP::Tool`: class methods `tool_name`, `title`, `description`, `input_schema`, `annotations`,
+  `descriptor(context)`. Instance methods `#initialize(context)`, `#context`, `#invoke(arguments)`, `#call(**)`
+- `NanoMCP::Result`: `.text`, `.json`, `.error`, `#text`, `#structured`, `#error?`
+- `NanoMCP::Server`: `.new(name:, version:, tools:, title:, instructions:, allowed_origins:, logger:, &authenticate)` and `#call(env)`.
+  The block is called with `(env, meta)`
+
+## Protocol behaviour
+
+| | 2026-07-28 (`_meta` in every request) | 2025-11-25 and earlier (`initialize`) |
+|-|-|-|
+| Handshake | `server/discover`, optional | `initialize`, answered and forgotten |
+| Version | checked on every request, 400 + `-32022` if unsupported | negotiated in `initialize` |
+| `MCP-Protocol-Version`, `Mcp-Method`, `Mcp-Name` | required, must match the body (400 + `-32020`) | ignored |
+| Unknown method | 404 + `-32601` | 200 + `-32601` |
+| `ping` | gone | `{}` |
+| Results | `resultType: "complete"`, `ttlMs`/`cacheScope` on lists | plain |
+| Structured results | `structuredContent` plus a text block | JSON in a text block |
+
+In both eras:
+
+- GET, DELETE and other verbs get a 405.
+- No session id is ever issued.
+- A notification gets an empty 202.
+- Batches are refused.
+- A request with an `Origin` header is refused with a 403 unless that origin is in
+  `allowed_origins`. MCP clients don't send `Origin`, browsers do. Comparing it against the
+  server's own host would not help: after a DNS rebind, the attacker's page sends its own name in both.
+- Bodies over 1MB get a 413. Responses over 1MB are truncated, with a note saying so.
+
+## Development
+
+```
+bundle install
+bundle exec rake          # tests and standard
+WORKFLOWS_MCP_TOKEN=$(ruby -rsecurerandom -e 'puts SecureRandom.hex(32)') rackup examples/config.ru
+```
+
+## License
+
+MIT

data/lib/nano_mcp/arguments.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module NanoMCP
+  # The slice of JSON Schema tool arguments get checked against, by hand. Deliberately
+  # not a general implementation - a tool that needs more than this is asking for too much.
+  #
+  # Checked: `type`, `required`, `enum`, `minimum`, `maximum`, `minLength`, `maxLength`,
+  # `minItems`, `maxItems` and `items`, plus `default`. Nested object properties are
+  # not descended into. Unknown arguments are refused rather than ignored, so a misspelled
+  # filter is heard about instead of silently returning everything.
+  module Arguments
+    module_function
+
+    # @param arguments [Hash, nil] as they came off the wire
+    # @param schema [Hash] the input schema with string keys
+    # @return [Hash] symbol-keyed, coerced, with defaults filled in
+    def validate!(arguments, schema)
+      arguments = {} if arguments.nil?
+      raise ToolError, "Arguments must be an object, got #{json_type(arguments)}" unless arguments.is_a?(Hash)
+
+      properties = schema.fetch("properties", {})
+      unknown = arguments.keys.map(&:to_s) - properties.keys
+      if unknown.any?
+        accepted = properties.empty? ? "no arguments" : properties.keys.join(", ")
+        raise ToolError, "Unknown argument(s): #{unknown.join(", ")}. This tool accepts: #{accepted}"
+      end
+
+      missing = Array(schema["required"]) - arguments.keys.map(&:to_s)
+      raise ToolError, "Missing required argument(s): #{missing.join(", ")}" if missing.any?
+
+      properties.each_with_object({}) do |(name, property), validated|
+        value = arguments.fetch(name) { arguments[name.to_sym] }
+        if !value.nil?
+          validated[name.to_sym] = coerce(value, property, name)
+        elsif property.key?("default")
+          validated[name.to_sym] = property["default"]
+        end
+      end
+    end
+
+    def coerce(value, property, name)
+      value = coerce_type(value, property["type"], name)
+
+      if (enum = property["enum"]) && !enum.include?(value)
+        raise ToolError, "#{name} must be one of: #{enum.join(", ")} (got #{value.inspect})"
+      end
+
+      case value
+      when Numeric
+        if property["minimum"] && value < property["minimum"]
+          raise ToolError, "#{name} must be at least #{property["minimum"]}"
+        end
+        # Clamped rather than refused: an agent asking for more rows than we serve
+        # wants as many as it can get, and an error just costs it a round trip
+        value = property["maximum"] if property["maximum"] && value > property["maximum"]
+      when String
+        if property["minLength"] && value.length < property["minLength"]
+          raise ToolError, "#{name} must be at least #{property["minLength"]} characters"
+        end
+        if property["maxLength"] && value.length > property["maxLength"]
+          raise ToolError, "#{name} must be at most #{property["maxLength"]} characters"
+        end
+      when Array
+        if property["minItems"] && value.length < property["minItems"]
+          raise ToolError, "#{name} needs at least #{property["minItems"]} items, got #{value.length}"
+        end
+        if property["maxItems"] && value.length > property["maxItems"]
+          raise ToolError, "#{name} accepts at most #{property["maxItems"]} items, got #{value.length}"
+        end
+        if (items = property["items"]).is_a?(Hash)
+          value = value.each_with_index.map { |item, index| coerce(item, items, "#{name}[#{index}]") }
+        end
+      end
+
+      value
+    end
+
+    def coerce_type(value, type, name)
+      case type
+      when "string"
+        raise ToolError, "#{name} must be a string, got #{json_type(value)}" unless value.is_a?(String)
+        value
+      when "integer"
+        # Agents routinely send ids as strings, and refusing those just buys a retry
+        return value if value.is_a?(Integer)
+        return value.to_i if value.is_a?(Float) && value == value.floor
+        return value.to_i if value.is_a?(String) && /\A-?\d+\z/.match?(value)
+        raise ToolError, "#{name} must be an integer, got #{value.inspect}"
+      when "number"
+        return value if value.is_a?(Numeric)
+        return Float(value) if value.is_a?(String) && /\A-?\d+(\.\d+)?\z/.match?(value)
+        raise ToolError, "#{name} must be a number, got #{value.inspect}"
+      when "boolean"
+        return value if value == true || value == false
+        return value == "true" if value == "true" || value == "false"
+        raise ToolError, "#{name} must be a boolean, got #{json_type(value)}"
+      when "array"
+        raise ToolError, "#{name} must be an array, got #{json_type(value)}" unless value.is_a?(Array)
+        value
+      when "object"
+        raise ToolError, "#{name} must be an object, got #{json_type(value)}" unless value.is_a?(Hash)
+        value
+      else
+        value
+      end
+    end
+
+    def json_type(value)
+      case value
+      when nil then "null"
+      when true, false then "boolean"
+      when Integer then "integer"
+      when Numeric then "number"
+      when String then "string"
+      when Array then "array"
+      when Hash then "object"
+      else value.class.name
+      end
+    end
+  end
+  private_constant :Arguments
+end

data/lib/nano_mcp/result.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module NanoMCP
+  # What a tool returns from #call. Build one with {.text}, {.json} or {.error};
+  # the server shapes it for whichever protocol revision the caller speaks.
+  class Result
+    # Prose for the agent to read.
+    #
+    # @param string [String]
+    # @return [Result]
+    def self.text(string)
+      new(string.to_s, nil, false)
+    end
+
+    # Structured data. A current client gets it as `structuredContent`, an older one
+    # gets it serialized into a text block. The text block a current client gets next
+    # to the data is `summary` when given, and the data as JSON when not - pass a summary
+    # to avoid sending a large answer twice.
+    #
+    # @param value [Hash, Array, String, Numeric, true, false] anything JSON can represent
+    # @param summary [String, nil] a line saying what came back
+    # @return [Result]
+    def self.json(value, summary: nil)
+      raise ArgumentError, "Result.json needs a value, use Result.text for an empty answer" if value.nil?
+      new(summary&.to_s, value, false)
+    end
+
+    # A refusal or failure the agent should read and act on. Same as raising ToolError.
+    #
+    # @param message [String]
+    # @return [Result]
+    def self.error(message)
+      new(message.to_s, nil, true)
+    end
+
+    private_class_method :new
+
+    # @return [String, nil] the text, or the summary of a structured result
+    attr_reader :text
+
+    # @return [Object, nil] the structured value, nil for text and error results
+    attr_reader :structured
+
+    def initialize(text, structured, error)
+      @text = text
+      @structured = structured
+      @error = error
+      freeze
+    end
+
+    # @return [Boolean]
+    def error?
+      @error
+    end
+  end
+end

data/lib/nano_mcp/server.rb

@@ -0,0 +1,351 @@
+# frozen_string_literal: true
+
+module NanoMCP
+  # The MCP endpoint, as a Rack app. Mount it wherever you like:
+  #
+  #   SERVER = NanoMCP::Server.new(name: "comptoir", version: "1", tools: [ListSnapshots]) do |env|
+  #     Context.new(...) if NanoMCP.token_matches?(NanoMCP.bearer_token(env), ENV["MCP_TOKEN"])
+  #   end
+  #   mount SERVER => "/mcp"
+  #
+  # Stateless all the way down: no sessions, no streams, nothing remembered between
+  # requests, so any process can answer any request. It speaks revision 2026-07-28,
+  # where every request carries its own protocol version in `_meta`. A client of
+  # 2025-11-25 or earlier opens with `initialize` instead, and gets answered the way
+  # those revisions expect - minus the session, which they never strictly needed.
+  #
+  # The block authenticates. It receives the Rack env and the request's `_meta`, and
+  # returns the context every tool in this request gets, or nil/false to refuse the
+  # request with a 401. A block that raises refuses too.
+  #
+  # `_meta` is the hash as the client sent it, string keys and all. A current client
+  # puts its identity there on every request, under "io.modelcontextprotocol/clientInfo".
+  # An older one sends it only once, in `initialize`, so for its tool calls `_meta`
+  # is usually empty.
+  class Server
+    MODERN_VERSIONS = [PROTOCOL_VERSION].freeze
+    LEGACY_VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"].freeze
+
+    META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion"
+    META_SERVER_INFO = "io.modelcontextprotocol/serverInfo"
+
+    PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    UNAUTHORIZED = -32001
+    HEADER_MISMATCH = -32020
+    UNSUPPORTED_PROTOCOL_VERSION = -32022
+
+    # How long a client may cache the tool list. It only changes on a deploy, and
+    # "private" because it may vary with the caller
+    TOOL_LIST_TTL_MS = 300_000
+    CACHE_SCOPE = "private"
+
+    MAX_REQUEST_BYTES = 1_000_000
+    MAX_RESPONSE_BYTES = 1_000_000
+
+    BASE64_SENTINEL = /\A=\?base64\?(.*)\?=\z/m
+
+    # Methods whose `Mcp-Name` header mirrors a body param
+    NAMED_METHODS = {"tools/call" => "name", "prompts/get" => "name", "resources/read" => "uri"}.freeze
+
+    private_constant(*constants)
+
+    class ProtocolError < StandardError
+      attr_reader :code, :status, :data
+
+      def initialize(message, code:, status: 200, data: nil)
+        super(message)
+        @code = code
+        @status = status
+        @data = data
+      end
+    end
+    private_constant :ProtocolError
+
+    # @param name [String] `serverInfo.name`, which clients key on - keep it fixed
+    # @param version [String] `serverInfo.version`
+    # @param tools [Array<Class>] NanoMCP::Tool subclasses, listed in this order
+    # @param title [String, nil] `serverInfo.title` - say which app and environment this is
+    # @param instructions [String, nil] handed to the client up front, usually ends up in the system prompt
+    # @param allowed_origins [Array<String>] browser origins allowed to call, none by default
+    # @param logger [Logger, nil] gets a line per tool call and every internal error
+    # @yieldparam env [Hash] the Rack env
+    # @yieldparam meta [Hash] the request's `params._meta`, empty when there is none
+    # @yieldreturn [Object, nil] the tool context, or nil/false to refuse with a 401
+    def initialize(name:, version:, tools:, title: nil, instructions: nil, allowed_origins: [], logger: nil, &authenticate)
+      raise ArgumentError, "Pass a block which authenticates the request and returns the tool context, or nil to refuse" unless authenticate
+
+      @name = name.to_s
+      @version = version.to_s
+      @title = title&.to_s
+      @instructions = instructions&.to_s
+      @allowed_origins = Array(allowed_origins).map(&:to_s)
+      @logger = logger
+      @authenticate = authenticate
+      @tools = tools.each_with_object({}) do |tool, by_name|
+        raise ArgumentError, "#{tool.inspect} is not a NanoMCP::Tool subclass" unless tool.is_a?(Class) && tool < Tool
+        tool_name = tool.tool_name.to_s
+        raise ArgumentError, "#{tool} has no tool_name" if tool_name.empty?
+        raise ArgumentError, "Two tools are named #{tool_name}" if by_name.key?(tool_name)
+        by_name[tool_name] = tool
+      end.freeze
+    end
+
+    # @param env [Hash] the Rack env
+    # @return [Array] a Rack response
+    def call(env)
+      # GET opened a stream and DELETE ended a session in older revisions. The current
+      # one tells a server with neither to answer exactly this
+      unless env["REQUEST_METHOD"] == "POST"
+        return respond(405, error_body(nil, METHOD_NOT_FOUND, "This MCP server is stateless and POST-only. POST JSON-RPC requests to this same URL."), "allow" => "POST")
+      end
+
+      # Required by the transport to defeat DNS rebinding. MCP clients send no Origin
+      unless origin_permitted?(env["HTTP_ORIGIN"])
+        return respond(403, error_body(nil, INVALID_REQUEST, "Origin not allowed"))
+      end
+
+      # Read before authenticating, since the block gets the request's _meta - but
+      # answered after, so a caller without a token learns nothing from its body
+      body = read_body(env)
+      request = begin
+        body && JSON.parse(body)
+      rescue JSON::ParserError
+        :unparseable
+      end
+
+      context = authenticate(env, request_meta(request))
+      unless context
+        return respond(401, error_body(nil, UNAUTHORIZED, "Unauthorized: send a valid bearer token in the Authorization header"),
+          "www-authenticate" => %(Bearer realm="#{@name}"))
+      end
+
+      return respond(413, error_body(nil, INVALID_REQUEST, "Request body over #{MAX_REQUEST_BYTES} bytes")) unless body
+      return respond(400, error_body(nil, PARSE_ERROR, "Parse error: body is not valid JSON")) if request == :unparseable
+
+      status, payload = handle(request, env, context)
+      payload ? respond(status, payload) : [status, {}, []]
+    end
+
+    private
+
+    def handle(request, env, context)
+      return [400, error_body(nil, INVALID_REQUEST, "Batches are not supported, send one JSON-RPC request per POST")] if request.is_a?(Array)
+      return [400, error_body(nil, INVALID_REQUEST, "Request must be a JSON object")] unless request.is_a?(Hash)
+
+      id = request["id"]
+      method = request["method"]
+      params = request.fetch("params", nil) || {}
+      return [400, error_body(id, INVALID_REQUEST, "Request has no method")] unless method.is_a?(String)
+      return [400, error_body(id, INVALID_REQUEST, "params must be an object")] unless params.is_a?(Hash)
+
+      # A notification. None of them need anything from us
+      return [202, nil] unless request.key?("id")
+
+      modern = modern?(method, params, env)
+      validate_modern_request!(method, params, env) if modern
+      result = dispatch(method, params, context, modern)
+      result[:resultType] = "complete" if modern
+      [200, {jsonrpc: "2.0", id: id, result: result}]
+    rescue ProtocolError => e
+      [e.status, error_body(id, e.code, e.message, e.data)]
+    rescue => e
+      log(:error) { "#{method} raised #{e.class}: #{e.message}\n#{Array(e.backtrace).first(10).join("\n")}" }
+      # The message may carry the host's data, so it stays in the host's logs
+      [200, error_body(id, INTERNAL_ERROR, "Internal error (#{e.class}). See the server logs.")]
+    end
+
+    # The spec's rule for serving both eras: `initialize` always selects the old one,
+    # and per-request `_meta` the new one. A modern header with no `_meta` is a broken
+    # modern request rather than an old one, and gets told so
+    def modern?(method, params, env)
+      return false if method == "initialize"
+      !meta_version(params).nil? || MODERN_VERSIONS.include?(env["HTTP_MCP_PROTOCOL_VERSION"])
+    end
+
+    def request_meta(request)
+      params = request.is_a?(Hash) ? request["params"] : nil
+      meta = params.is_a?(Hash) ? params["_meta"] : nil
+      meta.is_a?(Hash) ? meta.freeze : {}.freeze
+    end
+
+    def meta_version(params)
+      meta = params["_meta"]
+      meta.is_a?(Hash) ? meta[META_PROTOCOL_VERSION] : nil
+    end
+
+    # The headers mirror the body so a load balancer can route without parsing it.
+    # That only holds if both say the same, so anything that disagrees is refused
+    def validate_modern_request!(method, params, env)
+      version = meta_version(params)
+      if version.nil?
+        raise ProtocolError.new("Header mismatch: request has no _meta[#{META_PROTOCOL_VERSION}]", code: HEADER_MISMATCH, status: 400)
+      end
+      unless MODERN_VERSIONS.include?(version)
+        raise ProtocolError.new("Unsupported protocol version: #{version}",
+          code: UNSUPPORTED_PROTOCOL_VERSION, status: 400,
+          data: {supported: MODERN_VERSIONS + LEGACY_VERSIONS, requested: version})
+      end
+
+      header_matches!("MCP-Protocol-Version", env["HTTP_MCP_PROTOCOL_VERSION"], version)
+      header_matches!("Mcp-Method", env["HTTP_MCP_METHOD"], method)
+      if (param = NAMED_METHODS[method]) && params.key?(param)
+        header_matches!("Mcp-Name", decode_header(env["HTTP_MCP_NAME"]), params[param].to_s)
+      end
+    end
+
+    def header_matches!(header_name, header_value, body_value)
+      if header_value.nil?
+        raise ProtocolError.new("Header mismatch: #{header_name} header is required", code: HEADER_MISMATCH, status: 400)
+      end
+      return if header_value == body_value
+      raise ProtocolError.new("Header mismatch: #{header_name} header value #{header_value.inspect} does not match body value #{body_value.inspect}",
+        code: HEADER_MISMATCH, status: 400)
+    end
+
+    def decode_header(value)
+      match = BASE64_SENTINEL.match(value.to_s)
+      return value unless match
+      match[1].unpack1("m0").force_encoding(Encoding::UTF_8)
+    rescue ArgumentError
+      raise ProtocolError.new("Header mismatch: malformed base64 in Mcp-Name", code: HEADER_MISMATCH, status: 400)
+    end
+
+    def dispatch(method, params, context, modern)
+      case [method, modern]
+      in ["server/discover", true] then discover_result
+      in ["initialize", false] then initialize_result(params)
+      in ["ping", false] then {}
+      in ["tools/list", _] then tools_list_result(context, modern)
+      in ["tools/call", _] then call_tool(params, context, modern)
+      else
+        # In the current revision the 404 is how a client tells "no such method"
+        # apart from "not an MCP endpoint at all"
+        raise ProtocolError.new("Method not found: #{method}", code: METHOD_NOT_FOUND, status: modern ? 404 : 200)
+      end
+    end
+
+    def discover_result
+      {
+        supportedVersions: MODERN_VERSIONS,
+        capabilities: {tools: {listChanged: false}},
+        instructions: @instructions,
+        ttlMs: TOOL_LIST_TTL_MS,
+        cacheScope: CACHE_SCOPE,
+        _meta: {META_SERVER_INFO => server_info}
+      }.compact
+    end
+
+    def initialize_result(params)
+      requested = params["protocolVersion"]
+      {
+        protocolVersion: LEGACY_VERSIONS.include?(requested) ? requested : LEGACY_VERSIONS.first,
+        capabilities: {tools: {listChanged: false}},
+        serverInfo: server_info,
+        instructions: @instructions
+      }.compact
+    end
+
+    def server_info
+      {name: @name, title: @title, version: @version}.compact
+    end
+
+    def tools_list_result(context, modern)
+      result = {tools: @tools.values.map { |tool| tool.descriptor(context) }}
+      modern ? result.merge(ttlMs: TOOL_LIST_TTL_MS, cacheScope: CACHE_SCOPE) : result
+    end
+
+    def call_tool(params, context, modern)
+      name = params["name"]
+      raise ProtocolError.new("tools/call needs a tool name", code: INVALID_PARAMS) unless name.is_a?(String)
+      tool = @tools.fetch(name) { raise ProtocolError.new("Unknown tool: #{name}. Call tools/list to see what this server offers.", code: INVALID_PARAMS) }
+
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = begin
+        tool.new(context).invoke(params["arguments"])
+      rescue ToolError => e
+        Result.error(e.message)
+      end
+      raise TypeError, "#{tool}#call returned #{result.class}, not a NanoMCP::Result" unless result.is_a?(Result)
+
+      shaped = shape(result, modern)
+      log(:info) do
+        elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(1)
+        "tool=#{name} era=#{modern ? "modern" : "legacy"} error=#{result.error?} bytes=#{JSON.generate(shaped).bytesize} duration_ms=#{elapsed_ms}"
+      end
+      shaped
+    end
+
+    # A client of an older revision may not read `structuredContent`, so it gets the
+    # data as JSON in prose. A current one gets the data once, plus the summary if
+    # there is one. An answer over the size cap goes out as truncated text: a clipped
+    # structure would be a lie about its own shape
+    def shape(result, modern)
+      return {content: [text_block(result.text)], isError: result.error?} if result.structured.nil?
+
+      unless modern
+        return {content: [text_block(JSON.pretty_generate(result.structured))], isError: false}
+      end
+
+      json = JSON.generate(result.structured)
+      if json.bytesize > MAX_RESPONSE_BYTES
+        return {content: [text_block(JSON.pretty_generate(result.structured))], isError: false}
+      end
+      {content: [text_block(result.text || json)], structuredContent: result.structured, isError: false}
+    end
+
+    def text_block(string)
+      string = string.to_s
+      if string.bytesize > MAX_RESPONSE_BYTES
+        string = string.byteslice(0, MAX_RESPONSE_BYTES).scrub("") + "\n\n[truncated: response exceeded #{MAX_RESPONSE_BYTES} bytes]"
+      end
+      {type: "text", text: string}
+    end
+
+    def authenticate(env, meta)
+      # A lambda taking just the env would raise on a second argument, a block would not
+      if @authenticate.lambda? && @authenticate.arity == 1
+        @authenticate.call(env)
+      else
+        @authenticate.call(env, meta)
+      end
+    rescue => e
+      log(:error) { "authentication raised #{e.class}: #{e.message} - refusing" }
+      nil
+    end
+
+    # Absent is fine, since MCP clients are not browsers. A present one has to be listed:
+    # comparing it to our own Host proves nothing after a rebind, because the browser
+    # then sends the attacker's name in both
+    def origin_permitted?(origin)
+      return true if origin.nil? || origin.empty?
+      @allowed_origins.any? { |allowed| origin.casecmp?(allowed) }
+    end
+
+    def read_body(env)
+      input = env["rack.input"]
+      return "" unless input
+      input.rewind if input.respond_to?(:rewind)
+      body = input.read(MAX_REQUEST_BYTES + 1).to_s
+      input.rewind if input.respond_to?(:rewind)
+      (body.bytesize > MAX_REQUEST_BYTES) ? nil : body
+    end
+
+    def respond(status, payload, headers = {})
+      [status, {"content-type" => "application/json"}.merge(headers), [JSON.generate(payload)]]
+    end
+
+    def error_body(id, code, message, data = nil)
+      error = {code: code, message: message}
+      error[:data] = data if data
+      {jsonrpc: "2.0", id: id, error: error}
+    end
+
+    def log(level, &message)
+      @logger&.public_send(level) { "[nano_mcp] server=#{@name} #{message.call}" }
+    end
+  end
+end

data/lib/nano_mcp/tool.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module NanoMCP
+  # Base class for tools. A tool is a name, a description an agent picks it by,
+  # an input schema, and a #call returning a Result.
+  #
+  #   class GetWorkflow < NanoMCP::Tool
+  #     tool_name "get_workflow"
+  #     description "One workflow by id"
+  #     input_schema properties: {id: {type: "integer"}}, required: ["id"]
+  #     annotations readOnlyHint: true
+  #
+  #     def call(id:)
+  #       NanoMCP::Result.json(context.store.find(id))
+  #     end
+  #   end
+  #
+  # A tool is instantiated once per call, with whatever the server's authentication
+  # block returned as its context.
+  class Tool
+    EMPTY_JSON_SCHEMA = Ractor.make_shareable({"type" => "object", "properties" => {}, "additionalProperties" => false})
+    private_constant :EMPTY_JSON_SCHEMA
+
+    # Everything set on the class is stored as a deep-frozen copy and nothing is computed
+    # lazily, because other Ractors can only read a class's instance variables if they are shareable
+    class << self
+      # @param value [String] the name agents call the tool by, `[A-Za-z0-9_.-]{1,128}`
+      def tool_name(value = nil)
+        @tool_name = -value.to_s if value
+        @tool_name
+      end
+
+      # @param value [String] a human-readable name for client UIs
+      def title(value = nil)
+        @title = -value.to_s if value
+        @title
+      end
+
+      # @param value [String] what the tool does, written for the agent choosing it
+      def description(value = nil)
+        @description = -value.to_s.strip if value
+        @description
+      end
+
+      # JSON Schema for the arguments, keys as symbols or strings. Only the top-level
+      # `properties` and `required` are given meaning by the validator, and arguments
+      # not in `properties` are always refused - `additionalProperties` is forced to
+      # false to say so.
+      #
+      # @param value [Hash]
+      def input_schema(value = nil)
+        if value
+          @input_schema = Ractor.make_shareable(value, copy: true)
+          schema = JSON.parse(JSON.generate(value))
+          schema["type"] = "object"
+          schema["properties"] ||= {}
+          schema["additionalProperties"] = false
+          @json_schema = Ractor.make_shareable(schema)
+        end
+        @input_schema || EMPTY_JSON_SCHEMA
+      end
+
+      # Behaviour hints for the client, passed through verbatim. Use the spec's names:
+      # `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`.
+      #
+      # @param value [Hash]
+      def annotations(value = nil)
+        @annotations = Ractor.make_shareable(value, copy: true) if value
+        @annotations
+      end
+
+      # The `tools/list` entry for this tool. Override it (calling super) to vary the
+      # entry with the caller, for example to say a tool is disabled for them.
+      #
+      # @param context [Object] what the server's authentication block returned
+      # @return [Hash]
+      def descriptor(context)
+        {
+          name: tool_name,
+          title: title,
+          description: description.to_s,
+          inputSchema: json_schema,
+          annotations: annotations
+        }.compact
+      end
+
+      private
+
+      def json_schema
+        @json_schema || EMPTY_JSON_SCHEMA
+      end
+    end
+
+    # @return [Object] what the server's authentication block returned
+    attr_reader :context
+
+    def initialize(context)
+      @context = context
+    end
+
+    # Validates the arguments and calls #call with them as keywords. This is the
+    # seam for wrapping every tool of yours at once - a permission check, log tags,
+    # a timeout: override it in your own base class and call super.
+    #
+    # @param arguments [Hash, nil] as they came off the wire
+    # @return [Result]
+    def invoke(arguments)
+      call(**Arguments.validate!(arguments, self.class.send(:json_schema)))
+    end
+
+    # Implement this. Receives the validated arguments as keywords; ones the caller
+    # left out and that have no `default` are not passed at all.
+    #
+    # @return [Result]
+    def call(**)
+      raise NotImplementedError, "#{self.class} must implement #call"
+    end
+  end
+end

data/lib/nano_mcp/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module NanoMCP
+  VERSION = "0.1.0"
+end

data/lib/nano_mcp.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+# A Rack app serving MCP tools over stateless Streamable HTTP.
+#
+# The public API is what this file, NanoMCP::Tool, NanoMCP::Result and NanoMCP::Server
+# document. Anything else - including any constant marked private - can change in any release.
+module NanoMCP
+  # The MCP revision this library is written against
+  PROTOCOL_VERSION = "2026-07-28"
+
+  # A configured token shorter than this never matches - see {.token_matches?}
+  MINIMUM_TOKEN_LENGTH = 32
+
+  class Error < StandardError
+  end
+
+  # Raise from a tool to refuse or fail in a way the agent can act on. It goes back
+  # as a tool result with `isError` set and the message as its text, not as a JSON-RPC error.
+  class ToolError < Error
+  end
+
+  # The bearer token from a Rack env, or nil when there is none.
+  #
+  # @param env [Hash] the Rack env
+  # @return [String, nil]
+  def self.bearer_token(env)
+    token = env["HTTP_AUTHORIZATION"].to_s[/\ABearer +(.+)\z/i, 1].to_s.strip
+    token.empty? ? nil : token
+  end
+
+  # Whether a presented token is the configured one. Both are hashed before comparing,
+  # so the comparison takes the same time whatever they are. A configured token shorter
+  # than MINIMUM_TOKEN_LENGTH matches nothing.
+  #
+  # @param presented [String, nil] what the caller sent
+  # @param configured [String, nil] what you expect
+  # @return [Boolean]
+  def self.token_matches?(presented, configured)
+    return false if presented.nil? || configured.nil?
+    return false if configured.to_s.length < MINIMUM_TOKEN_LENGTH
+    # Not OpenSSL::Digest::SHA256: its methods come from define_method, and those
+    # cannot be called from a Ractor other than the one that loaded them
+    OpenSSL.fixed_length_secure_compare(
+      OpenSSL::Digest.digest("SHA256", presented.to_s),
+      OpenSSL::Digest.digest("SHA256", configured.to_s)
+    )
+  end
+end
+
+require_relative "nano_mcp/version"
+require_relative "nano_mcp/arguments"
+require_relative "nano_mcp/result"
+require_relative "nano_mcp/tool"
+require_relative "nano_mcp/server"

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: nano_mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Julik Tarkhanov
+bindir: bin
+cert_chain: []
+date: 2026-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: A Rack app serving MCP tools over stateless Streamable HTTP, per MCP
+  revision 2026-07-28. No sessions, no streams, no dependencies.
+email:
+- me@julik.nl
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/nano_mcp.rb
+- lib/nano_mcp/arguments.rb
+- lib/nano_mcp/result.rb
+- lib/nano_mcp/server.rb
+- lib/nano_mcp/tool.rb
+- lib/nano_mcp/version.rb
+homepage: https://github.com/julik/nano_mcp
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/julik/nano_mcp
+  changelog_uri: https://github.com/julik/nano_mcp/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A (slightly unhinged) library for building small MCPs
+test_files: []