pikuri-mcp 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3b512b9e2c5bacf829cee8104a9198b36d94d7d09b110060e7524e5e82ae70a0
+  data.tar.gz: c36e458112d63a32ca0dad35c3b0ab4b07cd934347b7bfd4fe488ac252ccd64c
+SHA512:
+  metadata.gz: 89059a85a63a60cc2f69d64e881df7fb3fb005b64850040a5b696f4b4c6e862d28af77cb8e815f1a4bf259b3fd5ff720684c1a4fb5a16529c68596a7459ccd5e
+  data.tar.gz: 5e31d7cc61ba3f802b2888d9078ba22de7fd132b82f2874e7daf483212de42b53aa608aa76e961bb69f44877acfa03871139acbba2caf594d7c128f95eeafa45

data/README.md

@@ -0,0 +1,54 @@
+# pikuri-mcp
+
+[Model Context Protocol](https://modelcontextprotocol.io) support
+for the [pikuri](https://codeberg.org/mvysny/pikuri) AI-assistant
+toolkit.
+
+Adds:
+- `Pikuri::Mcp::Registry` — declarative config layer for stdio +
+  HTTP MCP servers.
+- `Pikuri::Mcp::Servers` — runtime that spawns the configured
+  servers via the [`mcp`](https://rubygems.org/gems/mcp) gem.
+- `Pikuri::Mcp::Synthesizer` — LLM-driven description summarizer
+  for MCP servers whose handshake omits useful instructions.
+- `Pikuri::Mcp::Verifier` — pre-flight prompt-injection scan of
+  every MCP server's tool surface before tools are advertised to
+  the LLM.
+- `Pikuri::Mcp::Cache` — on-disk cache of synthesized descriptions
+  and verifier results, keyed on the full server surface.
+- `Pikuri::Mcp::Extension` — wires everything into a
+  `Pikuri::Agent` via the `c.add_extension(...)` block API.
+
+## Install
+
+```ruby
+# Gemfile
+gem 'pikuri-mcp'
+```
+
+Adds the `mcp` gem as a runtime dep on top of `pikuri-core`.
+
+## Usage
+
+```ruby
+require 'pikuri-core'
+require 'pikuri-mcp'
+
+registry = Pikuri::Mcp::Registry.new(entries: [
+  Pikuri::Mcp::Registry::StdioEntry.new(id: 'gmail', command: %w[npx @gongrzhe/server-gmail-autoauth-mcp]),
+  Pikuri::Mcp::Registry::HttpEntry.new(id: 'hubspot', url: 'https://mcp.example.com/v1',
+                                       headers: { 'Authorization' => "Bearer #{ENV.fetch('HUBSPOT_TOKEN')}" })
+])
+
+agent = Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
+  c.add_extension(Pikuri::Mcp::Extension.new(registry: registry))
+end
+```
+
+The extension's `configure` builds the shared `Mcp::Servers` (which
+eager-starts every configured server), appends `<available_mcps>` to
+the system prompt, and registers a close handler so the agent's
+`#close` tears down the MCP subprocesses. Its `bind(agent)` adds a
+per-agent `mcp_connect` tool — sub-agents share the live MCP clients
+via the same extension instance but each has its own connect tool +
+activation set.

data/lib/pikuri/mcp/cache.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'json'
+
+module Pikuri
+  module Mcp
+    # On-disk cache for the per-server descriptions
+    # {Servers#try_synthesize_description} pays an LLM round-trip to
+    # produce. Wraps {Pikuri::UrlCache} for storage; this class owns
+    # the *key calculation* — the fingerprint of every input that
+    # could change the synthesized output, so an unchanged surface
+    # short-circuits to the stored description and a changed surface
+    # auto-invalidates.
+    #
+    # == What goes into the key
+    #
+    # The key hashes a canonical JSON serialization of:
+    #
+    # * +model_id+ — synthesis quality varies by model; cached output
+    #   from a different model should not be served.
+    # * +prompt_version+ — {Servers::PROMPT_VERSION}. Bumped when the
+    #   synthesizer prompt changes meaningfully so old cache entries
+    #   stop being served without having to delete the cache file.
+    # * Transport descriptor — for {Registry::StdioEntry}, the argv;
+    #   for {Registry::HttpEntry}, the URL.
+    # * Server name + version from +client.server_info['serverInfo']+.
+    # * Full tools surface: every tool's +name+, +description+, and
+    #   +input_schema+ — including nested property names, types, and
+    #   per-property descriptions. The surface is canonicalised
+    #   (recursive sort) so a server that reorders its tools array
+    #   or its schema keys doesn't blow the cache.
+    #
+    # The server's id from the registry is intentionally *not* part of
+    # the key — renaming a server entry in the registry doesn't change
+    # what the server actually does, and the id appears only as a
+    # passing reference in the synth prompt, never in the produced
+    # description.
+    #
+    # == Storage
+    #
+    # Reuses {Pikuri::UrlCache} with a +ttl: Float::INFINITY+. There is
+    # no time-based expiry — cache entries are valid forever, until
+    # the keyed surface changes. To force a rebuild of everything, +rm+
+    # the {DIR} directory (or bump {Servers::PROMPT_VERSION}).
+    #
+    # == Fail-soft contract
+    #
+    # {#fetch} mirrors {UrlCache#fetch} — yields on miss, returns the
+    # block's result, and persists it. {Servers} additionally rescues
+    # +StandardError+ around the {#fetch} call to keep startup robust
+    # against a corrupt cache file or a writer-side error.
+    class Cache
+      # Bumping {Servers::PROMPT_VERSION} invalidates every cached
+      # entry; this class doesn't define one of its own.
+
+      # On-disk root. Sibling of {Pikuri::UrlCache::ROOT_DIR} so all
+      # of pikuri's caches live under one path.
+      DIR = File.join(File.dirname(UrlCache::ROOT_DIR), 'mcp_descriptions').freeze
+
+      # @param model_id [String, nil] the synthesizer model id; folded
+      #   into the cache key so a model swap doesn't serve stale output
+      # @param prompt_version [Integer] {Servers::PROMPT_VERSION}; folded
+      #   into the key so a prompt edit invalidates the world
+      # @param dir [String] storage directory; defaults to {DIR}
+      def initialize(model_id:, prompt_version:, dir: DIR)
+        @model_id = model_id
+        @prompt_version = prompt_version
+        @url_cache = UrlCache.new(ttl: Float::INFINITY, dir: dir)
+      end
+
+      # Return the cached description for the given +(entry, client,
+      # tools)+ triple if a fresh entry exists, otherwise yield to
+      # compute it (typically a {Pikuri::Agent.think} call inside
+      # {Servers#try_synthesize_description}), persist the result, and
+      # return it.
+      #
+      # @param entry [Registry::StdioEntry, Registry::HttpEntry]
+      # @param client [MCP::Client] for +server_info+ (name + version)
+      # @param tools [Array<MCP::Client::Tool>] the server's tool list
+      # @yieldreturn [String] freshly-computed description
+      # @return [String] cached or freshly-computed description
+      def fetch(entry:, client:, tools:, &block)
+        @url_cache.fetch(key_for(entry, client, tools), &block)
+      end
+
+      # Compute the canonical fingerprint string for a +(entry, client,
+      # tools)+ triple. The fingerprint is what {Pikuri::UrlCache}
+      # SHA-256s into the on-disk filename; we don't hash here so the
+      # raw JSON is inspectable in tests.
+      #
+      # @return [String] canonical JSON over the keyed inputs
+      def key_for(entry, client, tools)
+        info = (client.server_info || {})['serverInfo'] || {}
+        fingerprint = {
+          'model_id' => @model_id,
+          'prompt_version' => @prompt_version,
+          'transport' => transport_descriptor(entry),
+          'server_name' => info['name'],
+          'server_version' => info['version'],
+          'tools' => tools_descriptor(tools)
+        }
+        JSON.generate(canonicalize(fingerprint))
+      end
+
+      private
+
+      def transport_descriptor(entry)
+        case entry
+        when Registry::StdioEntry then { 'kind' => 'stdio', 'command' => entry.command }
+        when Registry::HttpEntry  then { 'kind' => 'http',  'url' => entry.url }
+        else                           { 'kind' => 'unknown', 'class' => entry.class.to_s }
+        end
+      end
+
+      def tools_descriptor(tools)
+        tools.map do |t|
+          {
+            'name' => t.name,
+            'description' => t.description,
+            'input_schema' => t.input_schema || {}
+          }
+        end
+      end
+
+      # Recursively normalize a Hash/Array tree so semantically-equal
+      # inputs produce byte-identical JSON: Hash keys sorted, String
+      # vs Symbol keys both stringified, Arrays left in order (order
+      # is part of the meaning in JSON Schema's +required+).
+      def canonicalize(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), out| out[k.to_s] = canonicalize(v) }
+             .sort.to_h
+        when Array
+          obj.map { |v| canonicalize(v) }
+        else
+          obj
+        end
+      end
+
+      # Null cache: drop-in replacement that always misses and never
+      # persists. {Servers} uses this as the default when no real cache
+      # is provided, so the body of +#try_synthesize_description+ can
+      # call +@cache.fetch(...)+ unconditionally instead of branching
+      # on +nil+. Same shape as {Pikuri::UrlCache::NULL}.
+      NULL = Object.new
+      def NULL.fetch(entry:, client:, tools:)
+        yield
+      end
+      NULL.freeze
+    end
+  end
+end

data/lib/pikuri/mcp/client_wrapper.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require 'mcp'
+
+module Pikuri
+  module Mcp
+    # Wraps one +MCP::Client+ plus its transport with retry-and-restart
+    # semantics for stdio-subprocess death. The wrapper owns the
+    # client/transport lifecycle: on construction it builds a fresh
+    # transport and runs the +initialize+ handshake; on a
+    # subprocess-died failure during {#call_tool} it closes the dead
+    # transport, spawns a fresh one, re-handshakes, and retries — up
+    # to {MAX_CALL_ATTEMPTS} times total. After exhaustion the
+    # underlying +RequestHandlerError+ propagates and the synthesized
+    # tool's execute closure converts it to an +Error: ...+ observation
+    # like any other failure.
+    #
+    # == Why only subprocess-death messages
+    #
+    # Once an stdio subprocess dies, +MCP::Client::Stdio+'s state is
+    # irreversibly broken: +@wait_thread.alive?+ returns false forever
+    # and every subsequent call raises from +ensure_running!+ without
+    # ever talking to the server. Restarting is the only way back.
+    # Other +RequestHandlerError+ failures (protocol mismatch on the
+    # initialize handshake, JSON parse error, ValidationError on a
+    # malformed response) leave the transport usable; a restart there
+    # would just retry the same logical mistake and waste latency.
+    #
+    # == HTTP entries
+    #
+    # The wrapper accepts {Registry::HttpEntry} too, but no HTTP
+    # failure raises with the subprocess-death messages we match on,
+    # so the retry path naturally never triggers — the wrapper is a
+    # pass-through for HTTP. If transient HTTP retry is ever wanted,
+    # it should land here, not in {Servers}.
+    #
+    # == Lifecycle responsibility
+    #
+    # Spawning happens inside {#initialize} (via +spawn_fresh!+), and
+    # if the +initialize+ handshake fails the wrapper closes its own
+    # half-opened transport before re-raising. That means a caller
+    # who saw +ClientWrapper.new(entry)+ raise does NOT need to also
+    # close anything — the wrapper either returns a fully-initialized
+    # object or no object at all.
+    class ClientWrapper
+      LOGGER = Pikuri.logger_for('Mcp::ClientWrapper')
+      private_constant :LOGGER
+
+      # Maximum number of +call_tool+ attempts including the initial
+      # one, before propagating the underlying exception. 3 means: one
+      # normal try plus up to two restart-then-retry attempts.
+      MAX_CALL_ATTEMPTS = 3
+
+      # Substrings of +MCP::Client::RequestHandlerError#message+ that
+      # signal "the stdio subprocess is dead and the transport is
+      # unrecoverable." All three come from
+      # +mcp-X.Y.Z/lib/mcp/client/stdio.rb+:
+      #
+      # * +Server process has exited+ — +ensure_running!+ on a
+      #   +wait_thread+ that is no longer alive.
+      # * +Failed to write to server process+ — broken pipe on
+      #   write (+EPIPE+ / +IOError+).
+      # * +Server process closed stdout unexpectedly+ — +gets+
+      #   returned +nil+ mid-read because the pipe was closed.
+      SUBPROCESS_DEAD_PATTERNS = [
+        'Server process has exited',
+        'Failed to write to server process',
+        'Server process closed stdout unexpectedly'
+      ].freeze
+      private_constant :SUBPROCESS_DEAD_PATTERNS
+
+      # @return [Registry::StdioEntry, Registry::HttpEntry] the
+      #   registry entry the wrapper builds (and rebuilds) transports
+      #   from.
+      attr_reader :entry
+
+      # @return [MCP::Client] the *current* live client. Replaced on
+      #   each restart, so callers must not cache this across
+      #   {#call_tool} invocations. Exposed for one-shot boot-time
+      #   reads of +server_info+ / +tools+ by {Servers}, {Verifier},
+      #   {Synthesizer}, and {Cache}.
+      attr_reader :client
+
+      # @param entry [Registry::StdioEntry, Registry::HttpEntry] the
+      #   configured server.
+      # @raise [StandardError] anything raised by the underlying
+      #   transport's spawn / +connect+ handshake. The half-opened
+      #   transport is closed before the exception propagates.
+      def initialize(entry)
+        @entry = entry
+        @closed = false
+        spawn_fresh!
+      end
+
+      # Server's cached +InitializeResult+, as exposed by the
+      # transport. Delegates to {#client}.
+      #
+      # @return [Hash, nil]
+      def server_info
+        @client.server_info
+      end
+
+      # Enumerate the server's tools via +MCP::Client#tools+. Each
+      # call is a real round-trip — callers typically invoke this
+      # once at boot and cache the result.
+      #
+      # @return [Array<MCP::Client::Tool>]
+      def tools
+        @client.tools
+      end
+
+      # Call an MCP tool on the underlying server. On any failure
+      # whose message matches {SUBPROCESS_DEAD_PATTERNS}, closes the
+      # dead transport, spawns a fresh one, re-runs the +initialize+
+      # handshake, and retries the call — up to {MAX_CALL_ATTEMPTS}
+      # times total. Other failures (server-returned JSON-RPC errors
+      # don't reach this method — they come back inside the response
+      # Hash; non-recoverable transport errors like protocol-version
+      # mismatch or JSON parse errors) propagate on the first attempt
+      # without restart.
+      #
+      # @param tool [MCP::Client::Tool] the tool object obtained from
+      #   {#tools} at boot. Only +name+ is used at call time, so a
+      #   reference captured before a restart keeps working as long
+      #   as the new server still exposes that tool name.
+      # @param arguments [Hash] passed verbatim to the underlying
+      #   +call_tool+.
+      # @return [Hash] the JSON-RPC response.
+      # @raise [MCP::Client::RequestHandlerError] when retries are
+      #   exhausted, or on the first non-recoverable failure.
+      def call_tool(tool:, arguments:)
+        attempt = 1
+        begin
+          @client.call_tool(tool: tool, arguments: arguments)
+        rescue MCP::Client::RequestHandlerError => e
+          raise unless subprocess_dead?(e)
+          raise if attempt >= MAX_CALL_ATTEMPTS
+
+          LOGGER.warn(
+            "MCP server #{@entry.id.inspect} subprocess died " \
+            "(#{e.message.inspect}); restarting and retrying " \
+            "(attempt #{attempt + 1}/#{MAX_CALL_ATTEMPTS})."
+          )
+          restart!
+          attempt += 1
+          retry
+        end
+      end
+
+      # Close the underlying transport. Idempotent — subsequent calls
+      # are no-ops. After close, {#call_tool} will fail on the dead
+      # client.
+      #
+      # @return [void]
+      def close
+        return if @closed
+
+        begin
+          @transport&.close
+        rescue StandardError => e
+          LOGGER.warn(
+            "Error closing MCP transport for #{@entry.id.inspect}: " \
+            "#{e.class}: #{e.message}"
+          )
+        end
+        @closed = true
+      end
+
+      private
+
+      def spawn_fresh!
+        @transport = build_transport
+        begin
+          @client = MCP::Client.new(transport: @transport)
+          @client.connect
+        rescue StandardError
+          # The +initialize+ handshake (or the subprocess spawn it
+          # implicitly triggers for stdio) failed. Close whatever
+          # half-opened state we have so we don't leak a stdio
+          # subprocess that succeeded popen3 but failed handshake.
+          # The new transport is not retained — the wrapper either
+          # returns from initialize cleanly or raises with no live
+          # state.
+          begin
+            @transport.close
+          rescue StandardError
+            nil
+          end
+          raise
+        end
+      end
+
+      def restart!
+        begin
+          @transport.close
+        rescue StandardError
+          # The old transport's subprocess is presumed dead — close
+          # may raise (e.g. on an already-closed pipe). We don't
+          # care: we're about to discard the transport anyway, and
+          # the recovery is the fresh spawn below.
+          nil
+        end
+        spawn_fresh!
+      end
+
+      def build_transport
+        case @entry
+        when Registry::StdioEntry
+          MCP::Client::Stdio.new(
+            command: @entry.command.first,
+            args: @entry.command.drop(1)
+          )
+        when Registry::HttpEntry
+          MCP::Client::HTTP.new(url: @entry.url, headers: @entry.headers)
+        else
+          raise ArgumentError, "Unknown MCP entry type: #{@entry.class}"
+        end
+      end
+
+      def subprocess_dead?(error)
+        msg = error.message.to_s
+        SUBPROCESS_DEAD_PATTERNS.any? { |pat| msg.include?(pat) }
+      end
+    end
+  end
+end

data/lib/pikuri/mcp/extension.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Mcp
+    # An {Pikuri::Agent::Extension} that wires MCP (Model Context
+    # Protocol) support onto an agent: builds an {Mcp::Servers}
+    # runtime from a {Registry}, appends the +<available_mcps>+ block
+    # to the system prompt, registers an +on_close+ handler that
+    # tears down the live MCP clients, and (in +bind+) installs a
+    # per-agent +mcp_connect+ tool so the LLM can pull MCP-exposed
+    # tools into its toolset on demand.
+    #
+    # == Configure / bind split
+    #
+    # +configure+ runs once on the parent's Configurator and creates
+    # the *shared* {Mcp::Servers} runtime — that's the resource
+    # extensions own. +bind+ fires per agent (parent + each
+    # sub-agent in Step 4's world) and creates a *fresh* {Connect}
+    # tool keyed to whichever agent is being bound, registered via
+    # {Agent#internal_add_tool} so it lands only on that agent's
+    # +RubyLLM::Chat+ (not in pikuri's +@tools+ list — sub-agents
+    # therefore don't inherit the parent's connect tool through the
+    # snapshot, and each agent's activation Set stays per-agent).
+    #
+    # == Usage
+    #
+    #   registry = Pikuri::Mcp::Registry.new(entries: [
+    #     Pikuri::Mcp::Registry::StdioEntry.new(id: 'gmail', command: %w[gmail-mcp])
+    #   ])
+    #   Pikuri::Agent.new(transport: ..., system_prompt: ...) do |c|
+    #     c.add_extension Pikuri::Mcp::Extension.new(registry: registry)
+    #   end
+    #
+    # == Empty registry
+    #
+    # When the registry is {Registry#empty?}, the extension is a
+    # no-op — no Servers, no snippet, no tool, no on_close. Same
+    # semantics as the legacy +mcp_registry:+ kwarg on
+    # {Pikuri::Agent#initialize}, which routes through this
+    # extension as a transition layer.
+    class Extension
+      include Pikuri::Agent::Extension
+
+      # @param registry [Mcp::Registry] configured MCP servers.
+      #   Defaults to {Registry::EMPTY} — extension is a no-op then.
+      # @param synthesize_descriptions [Boolean] threads a
+      #   {Synthesizer} into {Servers} so servers without an
+      #   +instructions+ / +serverInfo.title+ field get an
+      #   LLM-synthesized description for the +<available_mcps>+
+      #   block. On by default — see the +synthesize_descriptions:+
+      #   kwarg on +Agent#initialize+ for the full rationale.
+      # @param verify_mcp_servers [Boolean] threads a {Verifier}
+      #   into {Servers} so every server's handshake + tool surface
+      #   is checked for prompt-injection patterns before tools can
+      #   register. On by default — see the +verify_mcp_servers:+
+      #   kwarg on +Agent#initialize+.
+      def initialize(registry: Registry::EMPTY,
+                     synthesize_descriptions: true,
+                     verify_mcp_servers: true)
+        @registry = registry
+        @synthesize_descriptions = synthesize_descriptions
+        @verify_mcp_servers = verify_mcp_servers
+        @servers = nil
+      end
+
+      # @return [Mcp::Servers, nil] the runtime built in +configure+,
+      #   or +nil+ when the registry was empty (extension is a
+      #   no-op).
+      attr_reader :servers
+
+      # Build the shared {Servers} runtime, append the
+      # +<available_mcps>+ block to the system prompt, and register
+      # the close handler. The +Synthesizer+ / +Verifier+ thinker
+      # closure captures the Configurator's transport + cancellable
+      # so the LLM-driven boot passes run against the same model
+      # the agent itself uses and honor the same cancel flag.
+      #
+      # @param c [Pikuri::Agent::Configurator]
+      # @return [void]
+      def configure(c)
+        return if @registry.empty?
+
+        if @synthesize_descriptions || @verify_mcp_servers
+          thinker = build_thinker(c.transport, c.cancellable)
+        end
+        synthesizer = build_synthesizer(thinker, c.transport.model) if @synthesize_descriptions
+        verifier    = build_verifier(thinker, c.transport.model)    if @verify_mcp_servers
+
+        @servers = Mcp::Servers.new(@registry, synthesizer: synthesizer, verifier: verifier)
+        c.append_system_prompt(@servers.system_prompt_snippet.lstrip) unless @servers.empty?
+        c.on_close { @servers.close }
+        nil
+      end
+
+      # Register a per-agent +mcp_connect+ tool on the agent's chat.
+      # The tool's +execute+ closure captures the agent reference so
+      # activations register their tools on the correct chat — see
+      # IDEAS.md §"Two invariants worth recording" for the
+      # static-vs-dynamic tool boundary.
+      #
+      # @param agent [Pikuri::Agent]
+      # @return [void]
+      def bind(agent)
+        return if @servers.nil? || @servers.empty?
+
+        if agent.tools.any?(Mcp::Servers::Connect)
+          raise 'Mcp::Servers::Connect cannot be passed in tools: when an MCP runtime is wired; ' \
+                'Agent auto-registers it.'
+        end
+
+        connect = @servers.build_mcp_connect_tool(agent)
+        agent.internal_add_tool(connect.to_ruby_llm_tool)
+        nil
+      end
+
+      private
+
+      def build_thinker(transport, cancellable)
+        ->(prompt) { Pikuri::Agent.think(transport: transport, prompt: prompt, cancellable: cancellable) }
+      end
+
+      def build_synthesizer(thinker, model_id)
+        Mcp::Synthesizer.new(
+          thinker: thinker,
+          cache: Mcp::Cache.new(
+            model_id: model_id,
+            prompt_version: Mcp::Synthesizer::PROMPT_VERSION
+          )
+        )
+      end
+
+      def build_verifier(thinker, model_id)
+        Mcp::Verifier.new(
+          thinker: thinker,
+          cache: Mcp::Cache.new(
+            model_id: model_id,
+            prompt_version: Mcp::Verifier::PROMPT_VERSION,
+            dir: File.join(File.dirname(Mcp::Cache::DIR), 'mcp_verifications')
+          )
+        )
+      end
+    end
+  end
+end