pikuri-mcp 0.0.7 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8eea96fdc325316f284a0af4b04409190da30a250b183dc260e6bc238631780f
-  data.tar.gz: 886eed8a4913860b9571c75f71a5ff91860f9d73d8489b0c64e14e5e034ced16
+  metadata.gz: c0a2f932c3cd9c179cf9ad0bc3f2ec0d74fa4fe0c2b465e868665521253eb6a7
+  data.tar.gz: ecb49fc2d8b17be786f100e2aa037ef8133ca7beb80ae14746cf80112ee01e6f
 SHA512:
-  metadata.gz: fafa923f924cfd8a39a8e88776828badd61b551a5c7165c292831b6185972267d2cb420a406e3578b65e443ff8bc2ead11e770f68c2dd12372416beba001500b
-  data.tar.gz: cc6dc8b41f9978413dcc1ac81c15a26ea2f3c844be5b58adce4c8246bafbdfccb216f43f8a732d1ebe9429334022e078c23d4b5300bfdd15fb38e0d802145033
+  metadata.gz: be21898aa50c5bc6677117311426444e4bec1f475b8307221261fc0e266e61affdb45503e97e3f0086a0d4448758c5dafbe5370549a5a12d7d1b76c44f6bc312
+  data.tar.gz: 8c471fdb29e9afd66ec2c77dbd72f1ba60da7dc663ab03b68d7d489c8c3147de0bca6fdbb137fab6630031006ef3b01a09032db7e35d296679e0963447f1d5a8

data/README.md

@@ -23,7 +23,7 @@ Adds:
   server, the community [Open Library
   catalogue reader](https://github.com/8enSmith/mcp-open-library)
   running in a locally-built Docker container, plus `calculator`.
-  The worked example of guide chapter 5.
+  The worked example of the guide's MCP chapter.
 
 ## Install
 
@@ -61,12 +61,11 @@ activation set.
 
 ## Further reading
 
-- **Narrative walkthrough:** [chapter 5 of the
-  guide](../docs/guide/05-mcp.md) is the gentle MCP intro — one
+- **Narrative walkthrough:** [the MCP chapter of the guide](../book/mcp.md) is the gentle MCP intro — one
   low-stakes server in a locally-built container (run via
   `bin/pikuri-openlibrary`), rootless Docker as the boundary, the
   verifier and synthesizer in depth.
-  [Chapter 10](../docs/guide/10-mcp-revisited.md) picks
+  [The MCP-revisited chapter](../book/mcp-revisited.md) picks
   the thread back up at the harder end: the official GitHub MCP
   in Docker, npx- and pip-based community servers, Playwright,
   and the full threat model.

data/lib/pikuri/mcp/cache.rb

@@ -5,75 +5,40 @@ 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.
+    # On-disk cache for the per-server descriptions {Synthesizer} 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 output, so an unchanged surface short-circuits and a changed
+    # one auto-invalidates. The key hashes canonical JSON over: +model_id+
+    # (quality varies by model), +prompt_version+, the transport descriptor
+    # (argv or URL), server name+version, and the full tools surface (name,
+    # description, +input_schema+ including nested properties), canonicalised by
+    # recursive sort so a reordered tools array / schema keys don't blow the
+    # cache. The server's registry *id* is deliberately excluded — a rename
+    # doesn't change what the server does.
     #
-    # == 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.
+    # +ttl: Float::INFINITY+: no time expiry, entries valid until the keyed
+    # surface changes; force a full rebuild by +rm+-ing {DIR} or bumping the
+    # prompt version. {#fetch} mirrors {UrlCache#fetch} (yield on miss, persist
+    # the result); callers rescue around it for corrupt-file robustness.
     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.
+      # 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}
+      # @param model_id [String, nil] model id; folded into the key so a model
+      #   swap doesn't serve stale output.
+      # @param prompt_version [Integer] the caller's +PROMPT_VERSION+; folded in
+      #   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 one-shot thinker-agent run inside
-      # {Servers#try_synthesize_description}), persist the result, and
-      # return it.
+      # Return the cached description for the +(entry, client, tools)+ triple, or
+      # yield to compute + persist + return it on a miss.
       #
       # @param entry [Registry::StdioEntry, Registry::HttpEntry]
       # @param client [MCP::Client] for +server_info+ (name + version)
@@ -84,10 +49,9 @@ module Pikuri
         @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.
+      # The canonical fingerprint for a +(entry, client, tools)+ triple —
+      # {Pikuri::UrlCache} SHA-256s it into the filename; we return the raw JSON
+      # (not a hash) so it's inspectable in tests.
       #
       # @return [String] canonical JSON over the keyed inputs
       def key_for(entry, client, tools)
@@ -123,10 +87,9 @@ module Pikuri
         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+).
+      # Recursively normalize so semantically-equal inputs produce
+      # byte-identical JSON: Hash keys stringified + sorted, Arrays left in
+      # order (order is meaningful in JSON Schema's +required+).
       def canonicalize(obj)
         case obj
         when Hash
@@ -139,11 +102,9 @@ module Pikuri
         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 cache: always misses, never persists — the default when no real
+      # cache is provided, so callers +@cache.fetch(...)+ unconditionally
+      # instead of branching on +nil+. Same shape as {Pikuri::UrlCache::NULL}.
       NULL = Object.new
       def NULL.fetch(entry:, client:, tools:)
         yield

data/lib/pikuri/mcp/client_wrapper.rb

@@ -4,44 +4,25 @@ 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.
+    # Wraps one +MCP::Client+ + its transport with retry-and-restart on
+    # stdio-subprocess death. On construction it builds a fresh transport and
+    # runs the +initialize+ handshake; on a subprocess-died {#call_tool} it
+    # closes the dead transport, respawns, re-handshakes, and retries up to
+    # {MAX_CALL_ATTEMPTS} times, after which the +RequestHandlerError+ propagates
+    # (the synthesized tool's closure turns it into an +Error: ...+ observation).
     #
-    # == Why only subprocess-death messages
+    # Only subprocess-death messages trigger the restart: once an stdio
+    # subprocess dies, +MCP::Client::Stdio+ is irreversibly broken
+    # (+@wait_thread.alive?+ stays false, every call raises from
+    # +ensure_running!+), so restarting is the only way back. Other
+    # +RequestHandlerError+s (protocol mismatch, JSON parse, ValidationError)
+    # leave the transport usable — a restart would just retry the same mistake.
+    # {Registry::HttpEntry} is accepted but no HTTP failure matches those
+    # patterns, so the wrapper is a pass-through for HTTP.
     #
-    # 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.
+    # Lifecycle: if the handshake fails, {#initialize} closes its own half-opened
+    # transport before re-raising — a caller who saw +ClientWrapper.new+ raise
+    # need not close anything (fully-initialized object, or no object at all).
     class ClientWrapper
       LOGGER = Pikuri.logger_for('Mcp::ClientWrapper')
       private_constant :LOGGER
@@ -51,17 +32,10 @@ module Pikuri
       # 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.
+      # Substrings of +RequestHandlerError#message+ signalling "stdio subprocess
+      # dead, transport unrecoverable" — all from the +mcp+ gem's
+      # +client/stdio.rb+: exited +wait_thread+, broken write pipe (+EPIPE+), and
+      # +gets+ → +nil+ on a closed stdout.
       SUBPROCESS_DEAD_PATTERNS = [
         'Server process has exited',
         'Failed to write to server process',
@@ -109,25 +83,18 @@ module Pikuri
         @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.
+      # Call an MCP tool. On a {SUBPROCESS_DEAD_PATTERNS} failure, restart and
+      # retry up to {MAX_CALL_ATTEMPTS} times; other failures propagate on the
+      # first attempt (JSON-RPC errors don't reach here — they ride in the
+      # response Hash).
       #
-      # @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+.
+      # @param tool [MCP::Client::Tool] from {#tools} at boot. Only +name+ is
+      #   used at call time, so a reference captured before a restart keeps
+      #   working if the new server still exposes that 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.
+      # @raise [MCP::Client::RequestHandlerError] when retries exhaust, or on the
+      #   first non-recoverable failure.
       def call_tool(tool:, arguments:)
         attempt = 1
         begin
@@ -174,13 +141,9 @@ module Pikuri
           @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.
+          # Handshake (or the stdio spawn it triggers) failed — close the
+          # half-opened state so a subprocess that popen3'd but failed handshake
+          # doesn't leak.
           begin
             @transport.close
           rescue StandardError
@@ -209,7 +172,9 @@ module Pikuri
           MCP::Client::Stdio.new(
             command: @entry.command.first,
             args: @entry.command.drop(1),
-            env: @entry.env
+            # De-bundlerized, or a Ruby-written server resolves its own gems
+            # out of *pikuri's* bundle. The entry's own env wins over it.
+            env: Pikuri::BundlerEnv.clean_delta.merge(@entry.env)
           )
         when Registry::HttpEntry
           MCP::Client::HTTP.new(url: @entry.url, headers: @entry.headers)

data/lib/pikuri/mcp/extension.rb

@@ -2,28 +2,10 @@
 
 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 the
-    # extension owns. +bind+ fires once on the parent agent and
-    # installs a +Connect+ tool keyed to it, registered via
-    # {Pikuri::Agent::ExtensionContext#add_raw_tool} so the tool's
-    # +execute+ closure can call back into the right chat when the
-    # LLM activates a server.
-    # Sub-agents do not inherit extensions, so they receive neither
-    # the +Connect+ tool nor any MCP-backed tools — personas own
-    # their toolset by construction.
-    #
-    # == Usage
+    # An {Pikuri::Agent::Extension} wiring MCP support onto an agent: builds an
+    # {Mcp::Servers} runtime from a {Registry}, appends +<available_mcps>+ to the
+    # system prompt, arms an +on_close+ teardown, and (in +bind+) installs a
+    # per-agent +mcp_connect+ tool so the LLM pulls MCP tools in on demand.
     #
     #   registry = Pikuri::Mcp::Registry.new(entries: [
     #     Pikuri::Mcp::Registry::StdioEntry.new(id: 'gmail', command: %w[gmail-mcp])
@@ -32,13 +14,13 @@ module Pikuri
     #     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.
+    # +configure+ (once, on the parent's Configurator) builds the *shared*
+    # {Mcp::Servers} — the owned resource; +bind+ (once, on the parent agent)
+    # installs the +Connect+ tool keyed to it. Sub-agents don't inherit
+    # extensions, so they get neither — personas own their toolset. On a
+    # {Registry#empty?} registry the whole extension is a no-op (same semantics
+    # as the +mcp_registry:+ kwarg on {Pikuri::Agent#initialize}, which routes
+    # through here).
     class Extension
       include Pikuri::Agent::Extension
 
@@ -69,13 +51,10 @@ module Pikuri
       #   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} are
-      # handed the Configurator's transport + cancellable and build
-      # their own {Thinker} + production {Cache} from them, so the
-      # LLM-driven boot passes run against the same model the agent
-      # itself uses and honor the same cancel flag.
+      # Build the shared {Servers} runtime and arm its teardown. The
+      # {Synthesizer} / {Verifier} get the Configurator's transport + cancellable
+      # (building their own {Thinker} + {Cache}), so the boot passes run against
+      # the agent's own model and honor the same cancel flag.
       #
       # @param c [Pikuri::Agent::Configurator]
       # @return [void]
@@ -89,27 +68,30 @@ module Pikuri
           verifier = Mcp::Verifier.new(transport: c.transport, cancellable: c.cancellable)
         end
 
-        # Two-phase on purpose: construct (pure), arm cleanup, then
-        # start. Arming +on_close+ *before* the failure-prone
-        # +start_all+ is what makes a start failure (Cancelled,
-        # injection) non-leaking: +c.on_close+ writes straight to the
-        # agent's live handler list, so if +start_all+ raises, the
-        # agent's constructor rescue closes these half-started servers.
-        # See {Mcp::Servers}' "Lifecycle: two-phase, and the cleanup
-        # gap" and {Agent#run_configure}.
+        # Two-phase: construct (pure), arm cleanup, then start. Arming
+        # +on_close+ *before* the failure-prone +start_all+ is what makes a start
+        # failure non-leaking — see {Mcp::Servers}' "Lifecycle: two-phase, and
+        # the cleanup gap".
         @servers = Mcp::Servers.new(@registry, synthesizer: synthesizer, verifier: verifier)
         c.on_close { @servers.close }
         @servers.start_all
-
-        c.append_system_prompt(@servers.system_prompt_snippet.lstrip) unless @servers.empty?
         nil
       end
 
-      # Register a per-agent +mcp_connect+ tool on the agent's chat.
-      # The tool's +execute+ closure captures the {ExtensionContext}
-      # so activations register their tools on the correct chat — see
-      # IDEAS.md §"Two invariants worth recording" for the
-      # static-vs-dynamic tool boundary.
+      # The +<available_mcps>+ block for the started servers, from
+      # already-probed state (no re-probe), so it's cheap to re-pull on a
+      # conversation clear. +[]+ when no registry / no live servers.
+      #
+      # @return [Array<String>]
+      def system_prompt_snippets
+        return [] if @servers.nil? || @servers.empty?
+
+        [@servers.system_prompt_snippet.lstrip]
+      end
+
+      # Register the per-agent +mcp_connect+ tool; its closure captures +ctx+ so
+      # activations register on the correct chat (see
+      # {Pikuri::Agent::ExtensionContext#add_raw_tool}).
       #
       # @param ctx [Pikuri::Agent::ExtensionContext]
       # @return [void]
@@ -126,6 +108,35 @@ module Pikuri
         nil
       end
 
+      # The MCP surface's legs, attached here because MCP tools synthesize as
+      # raw +RubyLLM::Tool+ subclasses with no leg surface of their own (the
+      # MCP-tool bypass seam) — so nothing downstream can declare them.
+      #
+      # Hard +:untrusted+ and unreviewed, attacker-reachable egress, both
+      # unconditionally. A server's
+      # reachable set is unknown by construction: the tool list arrives at
+      # runtime from a server you didn't write, which is the whole-host case
+      # rather than the scoped one, and no trust claim can be honest about it.
+      # That is exactly {Pikuri::Tool::TrifectaLegs::ASSUMED}, reached
+      # independently — a foreign tool surface and an undeclared local tool are
+      # the same problem.
+      #
+      # +:private+ rides {Registry#private?}, so an open-data server next to a
+      # calculator stays silent and the same wiring beside a mail server does
+      # not.
+      #
+      # @param tools [Array<Pikuri::Tool>] unused; MCP contributes no children
+      # @return [Pikuri::Trifecta::Contribution, nil] +nil+ when no servers are
+      #   registered, so an unused extension adds nothing
+      def trifecta_contribution(tools)
+        return nil if @registry.empty?
+
+        Pikuri::Trifecta::Contribution.new(
+          label: '(mcp)',
+          legs: Pikuri::Tool::TrifectaLegs::ASSUMED.with(private: @registry.private?)
+        )
+      end
+
     end
   end
 end