libtmux-mcp 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a25cba0abc2b1a7f75709296e55caf0eecebcc0f73e9f1f17b35425f6f2779d2
-  data.tar.gz: 18773f3f297f70ec862a674841e297d757c25045975133a1770f6d76e9fca750
+  metadata.gz: e455168a6f0c00704e8728c52c33cd6cd0ae786648a9be633aafd5ff469e1b24
+  data.tar.gz: 836e5048e210aed6fabb35d5ca57e031eb9a9a6adb1bb736877df77f47393aa6
 SHA512:
-  metadata.gz: 3268471fc74ba19a01585df6ff499fa608d9abbecc69d3a059b9b733c9c646c03c3562d724904de5cfae59632e142a21435af9c6d59357b41eda6e9cf26688d6
-  data.tar.gz: 1591c3f7db07082e5d926412a4aa06cae2dff75a4499f589b1b611395f16bdc31472d53a35b75a41ee0337348910af37f41aed19d2acac19d57e1c13fe90cf91
+  metadata.gz: 2d72cb649f7ddd031b3aeae5dea7d390fbb641b6ba33fcba233058fc370fdb3b807ee910daf8264638f6de2de1634f01c1a2c93222f6716d35f4fb94268e4de2
+  data.tar.gz: dcf5d44e2e4acf56a7155c654a52d214761fa3fb456c4d2678c2c001c2869f3828fcaec6f56881d6688c390f7b7c31078c82784aeb5ef4393d96b879c1a8ff8a

data/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+Notable changes to `libtmux-mcp`.
+
+Releases are numbered `0.1.N`, and each release increments `N`. The API is not
+settled: pin an exact version to avoid a break.
+
+The gems are released together at one version, so every release has a section
+here. Changes that span gems, such as documentation, CI and release tooling, are
+in the [main changelog](../../CHANGELOG.md).
+
+## 0.1.3 (unreleased)
+
+## 0.1.2 (2026-11-04)
+
+No entries for `libtmux-mcp`.
+
+## 0.1.1 (2026-10-31)
+
+- **Behavior change:** `libtmux-mcp` no longer needs `--socket` or
+  `--socket-name`, and still refuses both together. Without a flag it serves
+  the same choice as `Server.new`, so start it with `--socket-name` or
+  `LIBTMUX_SOCKET` when an agent needs a server of its own. (#71)
+
+## 0.1.0 (2026-10-25)
+
+No entries for `libtmux-mcp`.
+
+## 0.1.0.alpha.3 (2026-10-24)
+
+### libtmux-mcp
+
+- `tmux_wait` with `screen_contains` polls the pane screen on tmux older than
+  3.7 instead of attaching a control client, and uses control events from
+  3.7. (#37)
+- `tmux_wait` with `screen_contains` joins wrapped rows, so text that the pane
+  width split across rows now matches. (#37)
+- `tmux_wait` fails with the new `pane_died` code, `delivery: observed` and
+  the last rows read in `error.capture`, when the pane or its tmux server ends
+  before the text appears. That case used to return `stale_target`, or
+  `observation_lost` after a killed server. A control stream that ends while
+  the pane lives, such as after a detach, returns `observation_lost` instead
+  of raising `NoMethodError`. (#37)
+
+## 0.1.0.alpha.2 (2026-10-18)
+
+### libtmux-mcp
+
+- `libtmux-mcp` reports an unsupported tmux daemon as refused to start,
+  before any session exists. If the daemon changes while the server runs, a
+  tool call returns an `unsupported` result with `delivery: not_sent` and a
+  fixed line that names the floor and the remedy. (#36)
+- Declare object roots in tool output schemas so clients using the
+  2025-11-25 protocol accept the `tools/list` response with MCP SDK 1.5.1.
+
+## 0.1.0.alpha.1 (2026-09-20)
+
+### libtmux-mcp
+
+- Serve an explicit tmux endpoint over MCP stdio with `libtmux-mcp`, or embed
+  `Application` and `StdioTransport` in Ruby. Capability discovery and snapshot
+  queries are enabled by default. [Server setup](../../gems/libtmux-mcp/README.md#quick-start).
+- Opt into screen captures, event-driven waits, creation, input and close
+  tools. Snapshot cursors page one retained capture; resources expose metadata
+  and pane screens. [Protocol example](../../examples/mcp_protocol.rb).
+- Run scripts through `tmux_run` after explicitly enabling the tool and
+  enrolling a zsh shell. Results distinguish stdout, stderr and observed
+  completion. [Shell enrollment](../../gems/libtmux-mcp/README.md#run-a-script-in-a-pane).

data/README.md

@@ -20,6 +20,9 @@ tool at a time.
 [Guides](https://libtmux.org/en/ruby/latest/mcp/guides/) ·
 [RubyGems](https://rubygems.org/gems/libtmux-mcp)
 
+[![libtmux.org](https://img.shields.io/badge/docs-libtmux.org-0b7285)](https://libtmux.org/en/ruby/latest/mcp/)
+[![libtmux-mcp](https://img.shields.io/gem/v/libtmux-mcp?label=libtmux-mcp)](https://rubygems.org/gems/libtmux-mcp)
+
 </div>
 
 Part of [libtmux for Ruby](https://github.com/libtmux/libtmux-ruby#readme).
@@ -122,6 +125,15 @@ $ libtmux-mcp \
     --socket-name agent
 ```
 
+- With neither flag, the server borrows the socket in `LIBTMUX_SOCKET_PATH`,
+  else the name in `LIBTMUX_SOCKET`, else the server `TMUX` names when it runs
+  inside tmux, else tmux's default socket. When both variables are set, the
+  path wins, and an empty variable counts as unset. A flag ignores both
+  variables, and the two flags are refused together.
+- The server never starts a tmux server. When none answers at the socket it
+  chose, it exits with status 1.
+- Started from a tmux pane with no flag or variable, the server drives that
+  pane's server. Pass `--socket-name` to give an agent a server of its own.
 - EOF retires the clients the server owns and leaves the daemon running.
 - `--endpoint` sets the public alias in discovery and resource URIs, and
   defaults to `local`.
@@ -336,7 +348,10 @@ pass the invitation to [`accept_shell`][mcp-application-accept_shell].
 
 Releases are numbered `0.1.N`, and each release increments `N`. The API is not
 settled: any release may change or remove exported identifiers, and the
-changelog marks each break. Pin an exact version to avoid one.
+changelogs mark each break. Pin an exact version to avoid one.
+See the [changelog](CHANGELOG.md), and the [main
+changelog](https://github.com/libtmux/libtmux-ruby/blob/master/CHANGELOG.md)
+for changes that span gems.
 
 - **Ruby 3.3 or newer.** The gem depends on `libtmux` and `libtmux-async` at
   the same version, the `mcp` SDK 1.5, `digest` and `optparse`.
@@ -350,8 +365,10 @@ changelog marks each break. Pin an exact version to avoid one.
   client.
 - **Linux, including WSL, and macOS.** The core
   [compatibility workflow][compat] runs Ruby 3.3, 3.4 and 4.0 with tmux 3.3a
-  through 3.8 on Ubuntu 24.04. macOS is supported on a best-effort basis, and
-  CI coverage for it is highly limited.
+  through 3.8 on Ubuntu 24.04. A push and a pull request run the oldest and
+  newest of those releases, 3.3a and 3.8, and a release runs all of them. macOS
+  is supported on a best-effort basis, and CI coverage for it is highly
+  limited.
 
 ## Documentation
 

data/lib/libtmux/mcp/cli.rb

@@ -6,12 +6,12 @@ require "optparse"
 module LibTmux
   module MCP
     class CLI
-      def self.run(arguments, input: $stdin, out: $stdout, err: $stderr)
-        new(arguments, input, out, err).run
+      def self.run(arguments, input: $stdin, out: $stdout, err: $stderr, environment: ENV)
+        new(arguments, input, out, err, environment).run
       end
 
-      def initialize(arguments, input, output, error)
-        @arguments, @input, @output, @error = arguments.dup, input, output, error
+      def initialize(arguments, input, output, error, environment = ENV)
+        @arguments, @input, @output, @error, @environment = arguments.dup, input, output, error, environment
         @options = {endpoint_name: "local", executable: "tmux", tools: Catalog::READ_ONLY.dup,
           timeout: 5.0, concurrency: 4, max_requests: 32, max_frame_bytes: 1 << 20,
           max_output_bytes: 1 << 22, max_response_bytes: 1 << 20,
@@ -27,8 +27,7 @@ module LibTmux
           return 0
         end
         validate_arguments
-        endpoint = Endpoint.new(socket_path: @options[:socket_path], socket_name: @options[:socket_name],
-          executable: @options.fetch(:executable))
+        endpoint = build_endpoint
         Async do |task|
           begin
             serve(endpoint, task)
@@ -44,7 +43,7 @@ module LibTmux
           end
         end.wait
       rescue OptionParser::ParseError, ArgumentError => error
-        report("Invalid arguments; use --help for supported options.", 2, failure: error)
+        report(@invalid_endpoint || "Invalid arguments; use --help for supported options.", 2, failure: error)
       rescue Interrupt, LibTmux::Cancelled => error
         report("MCP interrupted; dispatched effects may remain.", 130, failure: error)
       rescue StandardError => error
@@ -53,6 +52,25 @@ module LibTmux
 
       private
 
+      # --socket and --socket-name win; otherwise the core reads the variables,
+      # TMUX and tmux's default.
+      def build_endpoint
+        socket_path = @options[:socket_path]
+        socket_path = expand_socket(socket_path) unless socket_path.nil? || socket_path.empty?
+        Endpoint.new(socket_path: socket_path, socket_name: @options[:socket_name],
+          executable: @options.fetch(:executable), environment: @environment)
+      rescue ArgumentError => error
+        @invalid_endpoint = "Invalid arguments: #{error.message}."
+        raise
+      end
+
+      # File.expand_path puts the user it cannot find in its message.
+      def expand_socket(socket)
+        File.expand_path(socket)
+      rescue ArgumentError
+        raise ArgumentError, "--socket cannot be expanded to a path; its leading ~ names no home directory"
+      end
+
       def serve(endpoint, task)
         Server.open(endpoint: endpoint) do |server|
           LibTmux::Async.open(server: server, parent: task) do |scope|
@@ -185,9 +203,12 @@ module LibTmux
 
       def parser
         @parser ||= OptionParser.new do |options|
-          options.banner = "Usage: libtmux-mcp (--socket PATH | --socket-name NAME) [options]"
-          options.on("--socket PATH", "Borrow this existing tmux Unix socket") { |value| @options[:socket_path] = value }
-          options.on("--socket-name NAME", "Borrow this explicit tmux socket name") { |value| @options[:socket_name] = value }
+          options.banner = "Usage: libtmux-mcp [--socket PATH | --socket-name NAME] [options]"
+          options.on("--socket PATH", "Borrow the tmux server at this Unix socket",
+            "Default: LIBTMUX_SOCKET_PATH, then LIBTMUX_SOCKET, then the",
+            "server TMUX names, then tmux's default socket") { |value| @options[:socket_path] = value }
+          options.on("--socket-name NAME", "Borrow the tmux server with this socket name",
+            "Not with --socket") { |value| @options[:socket_name] = value }
           options.on("--endpoint NAME", "Public endpoint alias (default: local)") { |value| @options[:endpoint_name] = value }
           options.on("--tmux EXECUTABLE", "Resolve and pin this tmux executable at startup") { |value| @options[:executable] = value }
           options.on("--enable-tool NAME", "Enable one additional tool; repeat as needed") { |value| @options.fetch(:tools) << value }
@@ -211,7 +232,7 @@ module LibTmux
 
       def validate_arguments
         raise ArgumentError unless @arguments.empty?
-        raise ArgumentError unless [@options[:socket_path], @options[:socket_name]].compact.length == 1
+        raise ArgumentError if @options[:socket_path] && @options[:socket_name]
         raise ArgumentError unless @options.fetch(:tools).all? { |name| Catalog::NAMES.include?(name) }
         raise ArgumentError unless /\A[A-Za-z0-9][A-Za-z0-9_.-]{0,127}\z/.match?(@options.fetch(:endpoint_name))
         raise ArgumentError unless @options.fetch(:timeout).finite? && @options.fetch(:timeout).positive?

data/lib/libtmux/mcp/version.rb

@@ -2,6 +2,6 @@
 
 module LibTmux
   module MCP
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/sig/libtmux-mcp.rbs

@@ -10,7 +10,7 @@ module LibTmux
     class CLI
       private def self.new: (*untyped, **untyped) -> instance
       def run: () -> Integer
-      def self.run: (Array[String], ?input: IO, ?out: untyped, ?err: untyped) -> Integer
+      def self.run: (Array[String], ?input: IO, ?out: untyped, ?err: untyped, ?environment: untyped) -> Integer
     end
     class Application
       attr_reader tools: Array[untyped]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libtmux-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - libtmux contributors
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: libtmux-async
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.1.0
+        version: 0.1.2
 - !ruby/object:Gem::Dependency
   name: mcp
   requirement: !ruby/object:Gem::Requirement
@@ -92,6 +92,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - assets/logo.png
@@ -118,7 +119,8 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/libtmux/libtmux-ruby
-  documentation_uri: https://libtmux.org/en/ruby/v0.1.0/mcp/
+  changelog_uri: https://github.com/libtmux/libtmux-ruby/blob/master/gems/libtmux-mcp/CHANGELOG.md
+  documentation_uri: https://libtmux.org/en/ruby/v0.1.2/mcp/
 rdoc_options: []
 require_paths:
 - lib