nano_mcp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '049ec03429cd7d181a0b123542e7717dafacfa3ab0ba7bebcfe91240c0d47f80'
-  data.tar.gz: 1800e1e3f538bf4821cf870bfc6db2989024bc41aa28dcaf24252f1cbc9e4f53
+  metadata.gz: ffcb1e248eedd6b3c90e7bb904e866a70290d25ba3c184407aa4848199398324
+  data.tar.gz: cd91b4d772601f9d613d9aa4034f610fe88fd90320f0306f02a14c2e528726ef
 SHA512:
-  metadata.gz: 187c7b64250f6589e5552b51ed36a9cb9e084c322fe0601ec455a79cafcff0d708c86f980943a5fcb425163d69f094b16076642b6d66018f2e3d4decee4a406a
-  data.tar.gz: bd907532fe5710d2de079f6a2b144dd3fa360bcce79cb307d15920983cc8e404be4650dd56d0f4073d75a25bd9ded00f87aa6c900437c76c37bbdbfec7bacbb5
+  metadata.gz: 5faa4fd9cedf6fe30faf267960a5d8342bbb2d55d4510da1f3cfc6d325e48e5080f56e00409c24f064d58ba7c5bbc359167fa124e87dc07c63cc3eac9f4dab1d
+  data.tar.gz: 305575f794a6ef8ea7845dc5b6b9196d580a2f09c639b711ce8054036139d3bd2d5927b3f73dbc70a7807104dbd9aa749c838c70f5d16b0ed6ea53be43bbf3bc

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0
+
+- `Result.json` without a `summary:` now puts a line like "12 workflows in structuredContent."
+  in the text block for current clients, rather than the data again as JSON. This changes what
+  an existing call sends, which the compatibility rules in the README say we don't do - but both
+  apps using nano_mcp were working around the old behaviour, so it changes now rather than never.
+- `Server.new` takes `on_call:`, which hears about every tool call, for audit logging.
+- `Tool.annotations` set on a base class apply to its subclasses.
+
 ## 0.1.0
 
 Initial release, extracted from the MCP servers in geneva_drive_admin and Comptoir.

data/README.md

@@ -98,8 +98,12 @@ or run it from a `config.ru`. See [examples/](examples) for a complete server, w
 
 - `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.
+  `structuredContent`, next to a text block holding `summary`, or a line like "12 workflows in
+  structuredContent." if you gave none. An older client gets the JSON in the text block.
+
+  The spec suggests repeating the data as JSON in the text block. We don't: a client on the
+  current revision reads `structuredContent`, and a second copy of a large answer just fills the
+  agent's context window.
 - `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
@@ -120,9 +124,12 @@ There are two hooks for house rules, both meant to be overridden in your own bas
 
 ```ruby
 class MyTool < NanoMCP::Tool
+  # Every tool of ours unless it says otherwise - annotations are inherited
+  annotations readOnlyHint: true, openWorldHint: false
+
   def self.mutating
     @mutating = true
-    annotations readOnlyHint: false, destructiveHint: false
+    annotations readOnlyHint: false, destructiveHint: false, openWorldHint: false
   end
 
   def self.mutating? = !!@mutating
@@ -186,7 +193,23 @@ The server stays small by leaving these to the host:
 - **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.
+  Arguments are left out because they may carry secrets. For an audit trail, see `on_call` below.
+
+### Auditing calls
+
+Pass `on_call:` and it gets a frozen Hash after every tool call, including ones that raised:
+
+```ruby
+on_call: ->(event) do
+  Rails.logger.info "mcp tool=#{event[:tool]} caller=#{event[:context].user.email} error=#{event[:error]}"
+end
+```
+
+The keys are `tool`, `era` (`"modern"` or `"legacy"`), `context` (what your block returned),
+`arguments` (as they came off the wire), `error`, `bytes` (of the response, nil if the tool
+raised), `duration_ms` and `exception` (nil unless the tool raised). With an `on_call` the logger no longer gets a line per call, since yours replaces it.
+An `on_call` that raises is logged and otherwise ignored. It runs after the tool, so it can't wrap the tool's own logging -
+put log tags in `#invoke` for that.
 
 ## Public API
 
@@ -198,7 +221,7 @@ This is all of it. Everything else is private, whatever Ruby visibility it happe
 - `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)`.
+- `NanoMCP::Server`: `.new(name:, version:, tools:, title:, instructions:, allowed_origins:, logger:, on_call:, &authenticate)` and `#call(env)`.
   The block is called with `(env, meta)`
 
 ## Protocol behaviour

data/lib/nano_mcp/result.rb

@@ -12,17 +12,16 @@ module NanoMCP
       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.
+    # Structured data. A current client gets it as `structuredContent`, with `summary`
+    # in the text block next to it - or, without one, a line like "12 workflows in
+    # structuredContent.". An older client gets the data serialized into the text block.
     #
     # @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)
+      new((summary || summarize(value)).to_s, value, false)
     end
 
     # A refusal or failure the agent should read and act on. Same as raising ToolError.
@@ -33,7 +32,18 @@ module NanoMCP
       new(message.to_s, nil, true)
     end
 
-    private_class_method :new
+    # The spec suggests repeating the data as JSON in the text block, but a client
+    # asking for the current revision reads structuredContent, and a second copy of a
+    # large answer just fills the agent's context window
+    def self.summarize(value)
+      count, noun = case value
+      when Array then [value.length, "items"]
+      when Hash then value.select { |_key, member| member.is_a?(Array) }.max_by { |_key, member| member.length }&.then { |key, member| [member.length, key] }
+      end
+      count ? "#{count} #{noun} in structuredContent." : "See structuredContent."
+    end
+
+    private_class_method :new, :summarize
 
     # @return [String, nil] the text, or the summary of a structured result
     attr_reader :text

data/lib/nano_mcp/server.rb

@@ -71,11 +71,12 @@ module NanoMCP
     # @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
+    # @param logger [Logger, nil] gets every internal error, and a line per tool call unless there is an `on_call`
+    # @param on_call [#call, nil] receives a frozen Hash after every tool call - see the README
     # @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)
+    def initialize(name:, version:, tools:, title: nil, instructions: nil, allowed_origins: [], logger: nil, on_call: 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
@@ -84,6 +85,7 @@ module NanoMCP
       @instructions = instructions&.to_s
       @allowed_origins = Array(allowed_origins).map(&:to_s)
       @logger = logger
+      @on_call = on_call
       @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
@@ -264,24 +266,37 @@ module NanoMCP
       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
+      era = modern ? "modern" : "legacy"
+      begin
+        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)
+        bytes = JSON.generate(shaped).bytesize
+      rescue => e
+        exception = e
+        raise
+      ensure
         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}"
+        error = exception ? true : result.error?
+        log(:info) { "tool=#{name} era=#{era} error=#{error} bytes=#{bytes || "-"} duration_ms=#{elapsed_ms}" } unless @on_call
+        report_call(tool: name, era: era, context: context, arguments: params["arguments"], error: error,
+          bytes: bytes, duration_ms: elapsed_ms, exception: exception)
       end
       shaped
     end
 
+    def report_call(event)
+      @on_call&.call(event.freeze)
+    rescue => e
+      log(:error) { "on_call raised #{e.class}: #{e.message}" }
+    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
+    # data as JSON in prose. A current one gets the data once, plus the summary. 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?
@@ -294,7 +309,7 @@ module NanoMCP
       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}
+      {content: [text_block(result.text)], structuredContent: result.structured, isError: false}
     end
 
     def text_block(string)

data/lib/nano_mcp/tool.rb

@@ -61,12 +61,13 @@ module NanoMCP
       end
 
       # Behaviour hints for the client, passed through verbatim. Use the spec's names:
-      # `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`.
+      # `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`. Set on a
+      # base class, they apply to its subclasses until one sets its own.
       #
       # @param value [Hash]
       def annotations(value = nil)
         @annotations = Ractor.make_shareable(value, copy: true) if value
-        @annotations
+        @annotations || (superclass.annotations unless superclass == Tool)
       end
 
       # The `tools/list` entry for this tool. Override it (calling super) to vary the

data/lib/nano_mcp/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nano_mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Julik Tarkhanov