terret-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c688ebfcf594669b85992b1b0c6a293c28c74141410866539a03367292be1cb8
+  data.tar.gz: 389073f6762a2d3558e1e8717c7292fdd22bbd73ff5c95fd3c1e3f2205645041
+SHA512:
+  metadata.gz: eeba3604c890223502eda72ed686ce1bde508f0117bcc582b3baebe868ab0d46a284b88b30adc5c0a1d23459d6fb573aafd497d91e54fa61fd33ca54e44f3f80
+  data.tar.gz: 8b84eff300b7dca33c7771c43e737a7018d0c04d8b3a99ece0f246268f85043f281b7b4bc56ca87461b44df8243996f51f8a90ec2c281981f2c12af28953288b

data/lib/terret/mcp/service.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require_relative "translate"
+
+module Terret
+  module MCP
+    # ctx[:mcp] — mounts MCP servers as namespaced tool sources (docs/mcp.md).
+    # The client is injectable (client_factory config) so tests run on fakes;
+    # the default factory builds a manceps client, lazily required so nothing
+    # here needs manceps until something actually connects.
+    class Service < Hames::Service
+      service_key :mcp
+      inject :tools, :prompt
+      # client_factory: is an injectable seam (tests pass a factory), not YAML
+      # config, so it is absent from the schema. servers: is an open map of
+      # name => { url|command, args, env, bearer, approval, timeout }.
+      config_schema strict:  { type: [TrueClass, FalseClass], default: false,
+                               doc: "when true, a server that fails to mount fails the boot" },
+                    servers: { type: Hash, default: {},
+                               doc: "name => server config (url or command, args, env, bearer, " \
+                                    "approval, timeout)" }
+
+      DEFAULT_TIMEOUT = 30
+
+      def start(ctx)
+        @ctx = ctx
+        @strict = !!config[:strict]
+        @factory = config[:client_factory] || method(:default_client)
+        @servers = {}
+        @mounted = {} # name => { client:, disposers:, tool_names: }
+        (config[:servers] || {}).each do |name, cfg|
+          name = Translate.assert_server_name!(name)
+          unless cfg[:url].nil? ^ cfg[:command].nil?
+            raise ArgumentError, "server #{name}: exactly one of url:/command: required"
+          end
+
+          @servers[name] = cfg
+        end
+      end
+
+      def stop(_ctx) = @mounted.keys.each { |n| unmount!(n) }
+
+      def mounted = @mounted.keys
+
+      def mount!(*names)
+        names = @servers.keys if names.empty?
+        names.each { |n| mount_one(n.to_s) }
+      end
+
+      # Reverses every registration the server contributed and disconnects.
+      def unmount!(name)
+        entry = @mounted.delete(name.to_s) or return
+        entry[:listener]&.stop
+        entry[:resource_disposers].reverse_each(&:call)
+        entry[:disposers].reverse_each(&:call)
+        begin
+          entry[:client].disconnect
+        rescue StandardError => e
+          warn "terret-mcp: #{name}: disconnect failed: #{e.class}: #{e.message}"
+        end
+      end
+
+      # Reads the resource once and registers its text as a prompt section
+      # (docs/mcp.md); live refresh on resources/updated is deferred until a
+      # consumer needs it. Returns the section's disposer.
+      def register_resource_section(server, uri, name:, priority: 100)
+        entry = @mounted.fetch(server.to_s) { raise ArgumentError, "server #{server.inspect} is not mounted" }
+        body = entry[:client].read_resource(uri).text.to_s
+        disposer = @ctx.with_owner("mcp:#{server}") do
+          @ctx[:prompt].register_section(name, priority: priority) { body }
+        end
+        entry[:resource_disposers] << disposer
+        disposer
+      end
+
+      private
+
+      def mount_one(name)
+        cfg = @servers[name] or
+          raise ArgumentError, @strict ? "strict mode: server #{name.inspect} is not in this row's config" :
+                                         "unknown server #{name.inspect}"
+        return if @mounted.key?(name)
+
+        client = @factory.call(name, cfg)
+        client.connect
+        entry = { client: client, disposers: [], tool_names: [],
+                  lock: (cfg[:command] ? Mutex.new : nil), resource_disposers: [] }
+        begin
+          sync_tools(name, entry, cfg)
+        rescue StandardError
+          entry[:disposers].reverse_each(&:call)
+          begin
+            client.disconnect
+          rescue StandardError => e
+            warn "terret-mcp: #{name}: disconnect after failed mount: #{e.class}: #{e.message}"
+          end
+          raise
+        end
+        @mounted[name] = entry
+        entry[:client].on("notifications/tools/list_changed") do |_params|
+          # a straggler notification after unmount (or from a superseded
+          # mount) must not resurrect tools from a dead entry
+          next unless @mounted[name].equal?(entry)
+
+          begin
+            sync_tools(name, entry, cfg)
+          rescue StandardError => e
+            # a transient relist failure must not kill the listener or take
+            # down the roster; sync_tools already left it in place (fetch
+            # happens before disposal) — just retry on the next notification
+            warn "terret-mcp: #{name}: reconcile failed: #{e.class}: #{e.message}"
+          end
+        end
+        start_listener(entry)
+        entry
+      end
+
+      # manceps' listen is a blocking dispatch loop; give it its own task
+      # when a reactor exists. Without one there is nothing to run it on —
+      # notifications are skipped (docs/mcp.md documents this).
+      def start_listener(entry)
+        task = defined?(Async) ? Async::Task.current? : nil
+        return unless task
+
+        entry[:listener] = task.async do
+          entry[:client].listen
+        rescue StandardError => e
+          warn "terret-mcp: listener died: #{e.class}: #{e.message}"
+        end
+      end
+
+      def sync_tools(name, entry, cfg)
+        approval = cfg[:approval] || :policy
+        timeout = cfg[:timeout] || DEFAULT_TIMEOUT
+        # fetch before disposing anything: a relist failure (network blip,
+        # server hiccup) must leave the current roster registered, not tear
+        # it down and then have nothing to put back.
+        tools = entry[:client].tools
+
+        entry[:disposers].reverse_each(&:call)
+        entry[:disposers].clear
+        entry[:tool_names].clear
+
+        @ctx.with_owner("mcp:#{name}") do
+          tools.each do |tool|
+            # The name is remote input interpolated into the tool id and the log;
+            # one entry with an unsafe name is skipped rather than mounted, and
+            # the rest of the roster still comes up (Translate.valid_tool_name?).
+            unless Translate.valid_tool_name?(tool.name)
+              warn "terret-mcp: #{name}: skipping tool with an unsafe name #{tool.name.inspect}"
+              next
+            end
+
+            args = Translate.definition_args(server: name, tool: tool, approval: approval)
+            remote = tool.name
+            entry[:disposers] << @ctx[:tools].register(**args) do |**call_args|
+              call_remote(name, entry, remote, call_args, timeout)
+            end
+            entry[:tool_names] << args[:name]
+          end
+        end
+      end
+
+      def call_remote(name, entry, remote, call_args, timeout)
+        if (lock = entry[:lock])
+          # stdio replies correlate by order, not id: the whole
+          # heal+call sequence must serialize per server, so a waiter
+          # re-checks the poison flag after the loser's timeout lands.
+          lock.synchronize { locked_call(name, entry, remote, call_args, timeout) }
+        else
+          locked_call(name, entry, remote, call_args, timeout)
+        end
+      end
+
+      def locked_call(name, entry, remote, call_args, timeout)
+        if entry[:poisoned]
+          # claim the heal before reconnecting (reconnect! yields): a second
+          # fiber arriving mid-heal proceeds against the reconnecting client
+          # and at worst gets a transport error that re-poisons. A waiting
+          # latch would be race-free; that arrives with the M6 lifecycle work.
+          entry[:poisoned] = false
+          begin
+            entry[:client].reconnect!
+          rescue StandardError
+            entry[:poisoned] = true
+            raise Terret::Tools::Failure, "mcp #{name}: reconnect failed"
+          end
+        end
+        result = with_timeout(timeout) { entry[:client].call_tool(remote, **call_args) }
+        error = Translate.result_error(result)
+        raise Terret::Tools::Failure, error if error
+
+        Translate.result_content(result)
+      rescue *timeout_errors
+        entry[:poisoned] = true
+        raise Terret::Tools::Failure, "mcp timeout after #{timeout}s"
+      rescue *transport_errors => e
+        entry[:poisoned] = true
+        raise Terret::Tools::Failure, "mcp #{name}: #{e.class}: #{e.message}"
+      end
+
+      def with_timeout(seconds, &block)
+        task = defined?(Async) ? Async::Task.current? : nil
+        return yield unless task
+
+        task.with_timeout(seconds) { block.call }
+      end
+
+      # Async is optional for terret-mcp; a rescue clause must not name a
+      # constant the host may never load. Evaluated at exception time, so a
+      # late `require "async"` still matches.
+      def timeout_errors
+        defined?(Async::TimeoutError) ? [Async::TimeoutError] : []
+      end
+
+      def transport_errors
+        defined?(Manceps::Error) ? [Manceps::Error] : [IOError]
+      end
+
+      def default_client(name, cfg)
+        require "manceps"
+        if cfg[:url]
+          auth = cfg[:bearer] ? Manceps::Auth::Bearer.new(cfg[:bearer]) : Manceps::Auth::None.new
+          Manceps::Client.new(cfg[:url], auth: auth)
+        else
+          Manceps::Client.new(cfg[:command], args: cfg[:args] || [], env: cfg[:env])
+        end
+      end
+    end
+  end
+end

data/lib/terret/mcp/translate.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Terret
+  module MCP
+    # Pure translation between MCP shapes and terret shapes (docs/mcp.md).
+    # Duck-typed against manceps' value objects so it needs no manceps at
+    # test time and no network ever.
+    module Translate
+      NAME_RE = /\A[a-z0-9_-]+\z/
+
+      # A tool name comes from the server's tools/list — remote input, not the
+      # operator's config — and is interpolated into the `mcp__server__name` tool
+      # id and into every log line that names the call. A control-char or
+      # whitespace name would poison both, so a tool is held to a safe identifier
+      # charset before it is mounted (Service#sync_tools skips one that fails).
+      # It is broader than the operator-chosen server NAME_RE on purpose — real
+      # MCP tools are named in mixed case and sometimes carry dots — but it still
+      # admits nothing that is not a plain, log-safe identifier character.
+      TOOL_NAME_RE = /\A[A-Za-z0-9_.-]+\z/
+
+      module_function
+
+      def assert_server_name!(name)
+        name = name.to_s
+        raise ArgumentError, "server name must match #{NAME_RE.inspect}, got #{name.inspect}" unless name.match?(NAME_RE)
+
+        name
+      end
+
+      def valid_tool_name?(name) = name.is_a?(String) && name.match?(TOOL_NAME_RE)
+
+      def tool_name(server, tool) = "mcp__#{server}__#{tool}"
+
+      # Keyword args for Registry#register. Remote tools default to
+      # mutating: we cannot see their effects, so policy assumes the worst.
+      def definition_args(server:, tool:, approval:)
+        { name: tool_name(server, tool.name), description: tool.description.to_s,
+          params: tool.input_schema || {}, mutating: true, approval: approval }
+      end
+
+      # structured_content wins (already primitives); else text items join,
+      # binary/resource items degrade to a typed placeholder. nil for errors.
+      def result_content(result)
+        return nil if result.error?
+        return result.structured_content if result.structured?
+
+        result.content.map do |item|
+          item.type == "text" ? item.text : "[#{item.type} #{item.uri || item.mime_type || item.type}]"
+        end.join("\n")
+      end
+
+      def result_error(result)
+        return nil unless result.error?
+
+        text = result.text.to_s
+        text.empty? ? "tool failed with no message" : text
+      end
+    end
+  end
+end

data/lib/terret/mcp.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+begin
+  require "terret"
+rescue LoadError
+  require_relative "../../../terret-core/lib/terret" # monorepo path source
+end
+
+require_relative "mcp/translate"
+require_relative "mcp/service"

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: terret-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Obie Fernandez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: terret-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: manceps
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Mounts Model Context Protocol servers (stdio and streamable HTTP, via
+  the manceps client) as namespaced tool sources behind ctx.tools, with per-server
+  approval policy, per-call timeouts, and live tool-list reconciliation.
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/terret/mcp.rb
+- lib/terret/mcp/service.rb
+- lib/terret/mcp/translate.rb
+homepage: https://terret.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://terret.org
+  source_code_uri: https://github.com/terret-org/terret
+  bug_tracker_uri: https://github.com/terret-org/terret/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: MCP client plugin for the Terret agent harness
+test_files: []