band-mcp-server 1.0.0

data/README.md

@@ -0,0 +1,192 @@
+# ruby-band-mcp-server
+
+An [MCP](https://modelcontextprotocol.io) server for the [BAND Open API](https://developers.band.us/develop/guide/api),
+written in Ruby on the official [`mcp` gem](https://github.com/modelcontextprotocol/ruby-sdk) and served over stdio.
+
+## Tools
+
+| Tool                | What it does                                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------------------- |
+| `ping`              | Reports that the server is up and whether `BAND_ACCESS_TOKEN` is configured (never its value). |
+| `list_bands`        | Lists the bands you have joined, with the `band_key` the other tools need.                     |
+| `create_post`       | Publishes a text post to a band. Members are push-notified only if `do_push` is true.          |
+| `get_post`          | Fetches one post by `band_key` and `post_key`, e.g. to confirm a `create_post` landed.         |
+| `list_posts`        | Lists a band's recent posts, newest-modified first, paged with an `after` cursor.              |
+| `check_permissions` | Reports which of `posting`, `commenting` and `contents_deletion` the user has in a band.       |
+| `remove_post`       | Permanently deletes a post by `band_key` and `post_key`. It cannot be undone.                  |
+| `list_comments`     | Lists a post's comments, oldest first unless `newest_first`, paged with `after`.               |
+| `create_comment`    | Adds a comment to a post. BAND does not return its key; find it with `list_comments`.          |
+| `remove_comment`    | Permanently deletes a comment by `comment_key`. It cannot be undone.                           |
+
+A typical flow is `list_bands` to find the band, `create_post` to publish, then `get_post` with the returned
+`post_key` to confirm. `create_post` is marked as not read-only, so MCP clients such as Claude Desktop can ask before
+running it.
+
+To browse what is already in a band, use `list_posts`. BAND picks the page size (20 posts); when the result's
+`next_after` is not null, pass it back as `after` to get the next page.
+
+To read the discussion on a post, use `list_comments` with the post's `band_key` and `post_key`. Comments come oldest
+first; set `newest_first` to reverse that. BAND chose a page size of 20 when tested. Pass `next_after` back as `after` exactly as
+returned: it remembers the order, so a page after the first needs no `newest_first`.
+
+To join in, use `create_comment`. BAND confirms the comment without saying what its key is, so call `list_comments`
+afterwards to confirm it landed and to get its `comment_key`.
+
+To take a post down, use `remove_post`; it is marked destructive, so clients can ask before running it. Run
+`check_permissions` with `contents_deletion` first. BAND's docs say that permission does not check authorship, so
+removing someone else's post can still fail. `remove_comment` works the same way on a `comment_key` from
+`list_comments`, and BAND's docs add that it can only remove comments made through this app.
+
+## Requirements
+
+Ruby 4.0 or newer.
+
+## Install
+
+```sh
+gem install band-mcp-server
+```
+
+This puts a `band-mcp-server` executable on your `PATH`. To run it without installing, RubyGems can fetch and run it
+on demand (the gem and executable share a name, but `gem exec` needs the gem named explicitly):
+
+```sh
+gem exec -g band-mcp-server band-mcp-server
+```
+
+### Getting a BAND access token
+
+Register an app on the [BAND developer site](https://developers.band.us) and get an access token for it; the
+[API guide](https://developers.band.us/develop/guide/api) covers the details. The server only consumes the token and
+sends it to BAND as an `Authorization: Bearer` header. It does not run any OAuth flow itself.
+
+### Configuring the token
+
+Put the token in `~/.config/band-mcp-server/config` (or `$XDG_CONFIG_HOME/band-mcp-server/config` if you set that):
+
+```sh
+mkdir -p ~/.config/band-mcp-server
+echo 'BAND_ACCESS_TOKEN=your-token' > ~/.config/band-mcp-server/config
+chmod 600 ~/.config/band-mcp-server/config
+```
+
+A value already set in the environment (for example through the MCP client's `env` setting) takes precedence over
+the file.
+
+## Running
+
+Register it with Claude Code:
+
+```sh
+claude mcp add band -- band-mcp-server
+```
+
+The server speaks MCP over stdio, so it is normally launched by a client rather than run by hand.
+
+### Claude Desktop
+
+Claude Desktop starts servers with a minimal environment, so a version manager such as chruby is not active and
+the installed executable's `#!/usr/bin/env ruby` finds the wrong Ruby (the system Ruby, if any). With chruby, launch
+the server through [`chruby-exec`](https://github.com/postmodern/chruby#chruby-exec), which selects the Ruby and its
+`GEM_HOME` for you.
+
+`chruby-exec` does that by running the command in a login shell (`$SHELL -l -c`), so two things must hold. chruby has
+to be loaded by a startup file that a non-interactive login shell reads (for zsh, `~/.zprofile` or `~/.zshenv`, not
+only `~/.zshrc`). And those startup files must not print anything to stdout: it would land in front of the protocol
+stream and Desktop could not parse the handshake.
+
+1. Find where `chruby-exec` is installed with `which chruby-exec`. That depends on how you installed chruby, and the
+   path has to be absolute because Desktop's `PATH` is minimal.
+2. Open Settings → Developer → Edit Config (on macOS this is
+   `~/Library/Application Support/Claude/claude_desktop_config.json`) and add a `band` entry to `mcpServers`:
+
+   ```json
+   {
+     "mcpServers": {
+       "band": {
+         "command": "/path/to/chruby-exec",
+         "args": ["ruby-4", "--", "band-mcp-server"]
+       }
+     }
+   }
+   ```
+
+   chruby matches `ruby-4` against the installed Rubies by name, so it picks a 4.x Ruby; use a fuller name such as
+   `ruby-4.0.5` to pin one. Run `gem install band-mcp-server` under that same Ruby.
+
+   Keep the token in the config file described above; it is loaded by absolute path, so the working directory does not
+   matter. Setting `BAND_ACCESS_TOKEN` in an `env` map instead also works and takes precedence, but puts the secret in
+   Desktop's config file.
+
+   Without chruby, use the absolute path of the installed executable (`which band-mcp-server`) as `command`. If that
+   Ruby is not the first `ruby` on Desktop's minimal `PATH`, use the absolute path of a Ruby 4.0 or newer as `command`
+   instead, put the executable in `args`, and set `GEM_HOME` to the directory holding the installed gems
+   (`gem env gemdir` prints it):
+
+   ```json
+   {
+     "mcpServers": {
+       "band": {
+         "command": "/path/to/ruby",
+         "args": ["/path/to/band-mcp-server"],
+         "env": { "GEM_HOME": "/path/to/gem/dir" }
+       }
+     }
+   }
+   ```
+3. Quit Claude Desktop completely (Cmd-Q) and reopen it. The `band` tools appear in the tools menu of a new chat.
+
+Then ask Claude to run `ping`, which reports whether the token is set without showing it, and try "Which bands am I
+in?" to confirm the connection. Desktop asks before it runs a tool unless you have set that tool to always allow.
+Keep the prompt on for `create_post` and `create_comment`: they publish to every member of the band. Read the band and
+the wording in the request before approving. For `create_post`, members are push-notified only if the request sets
+`do_push`. Keep the prompt on for `remove_post` and `remove_comment` too: what they delete is gone for every member and
+cannot be restored, so check the keys before approving.
+
+To check the launch command outside Desktop, run it with a bare environment. A JSON `initialize` response means the
+server starts under that Ruby with its gems; it does not check the token, which `ping` does:
+
+```sh
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"check","version":"0"}}}' |
+  env -i HOME="$HOME" PATH=/usr/bin:/bin "$(which chruby-exec)" ruby-4 -- band-mcp-server
+```
+
+If the tools do not show up, read `~/Library/Logs/Claude/mcp-server-band.log`:
+
+| Symptom in the log or tool result               | Cause                                                                          |
+| ----------------------------------------------- | ------------------------------------------------------------------------------ |
+| `spawn … ENOENT`                                | `command` is not an absolute path to an existing `chruby-exec` (or Ruby).      |
+| `chruby: unknown Ruby: …`                       | No installed Ruby matches the name in `args`; compare with the output of `chruby`. |
+| `Could not find dotenv-…, mcp-…` (gems missing) | `gem install` was run under a different Ruby; run it under the one in args.  |
+| `requires Ruby version >= 4.0`                  | The chosen Ruby is older than 4.0; point `args` (or `command`) at a 4.x Ruby.  |
+| `BAND_ACCESS_TOKEN is not set`                  | No config file with the token, and no `BAND_ACCESS_TOKEN` in an `env` map.     |
+| `command not found: chruby`                     | chruby is only loaded in `~/.zshrc`; load it in `~/.zprofile` or `~/.zshenv`.  |
+| Desktop cannot parse the server's output        | A shell startup file prints to stdout; `chruby-exec` runs a login shell.       |
+| `BAND API error 10401`                          | BAND's "Unauthorized" code: the token is missing, invalid or expired.          |
+
+## Development
+
+From a checkout, use Bundler instead of the installed gem. A `.env` in the checkout root takes priority over the
+user config file, and `bin/band-mcp-server` (which sets up Bundler itself) replaces `band-mcp-server`:
+
+```sh
+chruby ruby-4.0.5   # or any manager that reads .ruby-version
+bundle install
+cp .env.example .env    # then set BAND_ACCESS_TOKEN
+claude mcp add band -- /path/to/ruby-band-mcp-server/bin/band-mcp-server
+```
+
+```sh
+bundle exec rake    # rubocop, rbs drift check, steep, rspec
+bundle exec rake -T # every task, including audit
+```
+
+`lib/` is typed with [rbs-inline](https://github.com/soutaro/rbs-inline) annotations and checked by
+[Steep](https://github.com/soutaro/steep); regenerate `sig/generated/` with `bundle exec rake rbs:generate` after
+changing them. See [AGENTS.md](AGENTS.md) for conventions and architecture.
+
+`main` is protected: changes land through a pull request with green CI.
+
+## License
+
+GPL-3.0. See [LICENSE](LICENSE).

data/exe/band-mcp-server

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "band_mcp"
+
+BandMCP.run

data/lib/band_mcp/client.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "config"
+require_relative "error"
+
+module BandMCP
+  # Minimal BAND Open API client. Callers pass the full versioned path (`/v2.1/bands`) because BAND versions each
+  # endpoint separately. Both verbs return the response's `result_data` and raise BandMCP::Error on any failure.
+  class Client
+    BASE_URL = "https://openapi.band.us" #: String
+    SUCCESS_CODE = 1 #: Integer
+    OPEN_TIMEOUT = 10 #: Integer
+    READ_TIMEOUT = 30 #: Integer
+    NETWORK_ERRORS = [
+      SocketError, SystemCallError, IOError, EOFError, Timeout::Error, OpenSSL::SSL::SSLError,
+      Net::ProtocolError, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError
+    ].freeze #: Array[Class]
+
+    # @rbs @access_token: String
+
+    #: (?access_token: String?) -> void
+    def initialize(access_token: Config.access_token)
+      raise Error, "BAND_ACCESS_TOKEN is not set" if access_token.nil?
+
+      @access_token = access_token
+    end
+
+    #: (String path, ?Hash[String, untyped] params) -> Hash[String, untyped]
+    def get(path, params = {})
+      uri = uri_for(path)
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      perform(uri, Net::HTTP::Get.new(uri))
+    end
+
+    #: (String path, ?Hash[String, untyped] params) -> Hash[String, untyped]
+    def post(path, params = {})
+      uri = uri_for(path)
+      request = Net::HTTP::Post.new(uri)
+      request.set_form_data(params)
+      perform(uri, request)
+    end
+
+    private
+
+    #: (String path) -> URI::Generic
+    def uri_for(path)
+      URI("#{BASE_URL}#{path}")
+    end
+
+    #: (URI::Generic uri, Net::HTTPRequest request) -> Hash[String, untyped]
+    def perform(uri, request)
+      request["Authorization"] = "Bearer #{@access_token}"
+      response = Net::HTTP.start(uri.hostname.to_s, uri.port, use_ssl: true, open_timeout: OPEN_TIMEOUT,
+                                                              read_timeout: READ_TIMEOUT) do |http|
+        http.request(request)
+      end
+      parse(response)
+    rescue *NETWORK_ERRORS => e
+      # Only the exception class: the message can echo the request URL, which must stay free of credentials.
+      raise NetworkError, "BAND request failed (#{e.class})"
+    end
+
+    # BAND reports failures as JSON with a non-1 result_code, often alongside a 4xx status, so the body is parsed
+    # before the HTTP status is consulted. A body that isn't BAND's answer is a plain error for a 4xx (a rejection) but
+    # an uncertain outcome for a 5xx.
+    #: (Net::HTTPResponse response) -> Hash[String, untyped]
+    def parse(response)
+      body = JSON.parse(response.body.to_s)
+      code = body["result_code"] if body.is_a?(Hash)
+      raise unreadable_response(response, "an unexpected response") unless code.is_a?(Integer)
+
+      data = body["result_data"]
+      data = empty_data unless data.is_a?(Hash)
+      return data if code == SUCCESS_CODE
+
+      raise APIError.new(code, error_message(data))
+    rescue JSON::ParserError
+      raise unreadable_response(response, "a non-JSON response")
+    end
+
+    #: (Net::HTTPResponse response, String what) -> Error
+    def unreadable_response(response, what)
+      error_class = response.code.to_i >= 500 ? UncertainResponseError : Error
+      error_class.new("BAND returned #{what} (HTTP #{response.code})")
+    end
+
+    #: () -> Hash[String, untyped]
+    def empty_data
+      {}
+    end
+
+    #: (Hash[String, untyped] data) -> String
+    def error_message(data)
+      [data["message"], data["detail"]].compact.join(": ").then { |text| text.empty? ? "unknown error" : text }
+    end
+  end
+end

data/lib/band_mcp/config.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "dotenv"
+
+module BandMCP
+  module Config
+    ROOT = File.expand_path("../..", __dir__.to_s) #: String
+
+    # The per-user config file an installed gem reads, following the XDG base directory convention. It uses .env
+    # syntax (KEY=value) but is named for its role.
+    #: () -> String
+    def self.user_config_path
+      config_home = ENV.fetch("XDG_CONFIG_HOME", "")
+      # The XDG spec says to ignore a relative path, which would otherwise resolve against the client's cwd.
+      config_home = File.join(Dir.home, ".config") unless config_home.start_with?("/")
+      File.join(config_home, "band-mcp-server", "config")
+    end
+
+    # Loads .env files by absolute path so the server works from any cwd. Dotenv.load never overrides values already
+    # in ENV (which lets an MCP client's `env` setting win) or set by an earlier file, so the order is the priority:
+    # the checkout's own .env, which an installed gem does not have, then the user's.
+    #: () -> void
+    def self.load_dotenv
+      Dotenv.load(File.join(ROOT, ".env"), user_config_path)
+    end
+
+    #: () -> String?
+    def self.access_token
+      token = ENV.fetch("BAND_ACCESS_TOKEN", nil)
+      token unless token.nil? || token.empty?
+    end
+
+    #: () -> bool
+    def self.access_token?
+      !access_token.nil?
+    end
+  end
+end

data/lib/band_mcp/error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module BandMCP
+  # Raised for anything that stops a BAND request from producing a result. The message is safe to show to the model:
+  # it never contains the access token.
+  class Error < StandardError; end
+
+  # The request failed in transit, so it may or may not have reached BAND. Matters for writes, which must not be blindly
+  # retried.
+  class NetworkError < Error; end
+
+  # A 5xx whose body isn't BAND's own answer (an HTML error page, say). A gateway in front of BAND can forward a write
+  # and then fail, so like a dropped connection it says nothing about whether the write happened.
+  class UncertainResponseError < NetworkError; end
+
+  # BAND answered, but with a failure `result_code`. See https://developers.band.us/develop/guide/api/handle_errors.
+  class APIError < Error
+    attr_reader :code #: Integer
+
+    #: (Integer code, String message) -> void
+    def initialize(code, message)
+      @code = code
+      super("BAND API error #{code}: #{message}")
+    end
+  end
+end

data/lib/band_mcp/tools/check_permissions.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class CheckPermissions < MCP::Tool
+      extend Helpers
+
+      PERMISSIONS = %w[posting commenting contents_deletion].freeze #: Array[String]
+
+      tool_name "check_permissions"
+      description "Check what the user is allowed to do in a BAND before trying it: posting (create_post), " \
+                  "commenting, and contents_deletion (removing posts and comments). Band settings can deny these " \
+                  "even to members. Returns the granted and denied permissions. contents_deletion says nothing " \
+                  "about authorship, so removing someone else's post can still fail. Find band_key with list_bands."
+      input_schema(
+        properties: {
+          band_key: { type: "string", minLength: 1, description: "Band to check, from list_bands." },
+          permissions: {
+            type: "array", minItems: 1, uniqueItems: true, items: { type: "string", enum: PERMISSIONS },
+            description: "Permissions to check."
+          }
+        },
+        required: %w[band_key permissions]
+      )
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true)
+
+      #: (band_key: String, permissions: Array[String], **untyped) -> untyped
+      def self.call(band_key:, permissions:, **)
+        with_client do |client|
+          data = client.get("/v2/band/permissions", { "band_key" => band_key, "permissions" => permissions.join(",") })
+          granted = granted_permissions(data)
+          if granted
+            json_response({ "granted" => permissions & granted, "denied" => permissions - granted })
+          else
+            unexpected_format("permissions")
+          end
+        end
+      end
+
+      # BAND's docs show the result key as `permission` in an example, but the live API sends `permissions` (see
+      # API_DISCREPANCIES.md). Returns nil when that isn't a list, so a changed format isn't reported as everything
+      # denied. Entries that aren't strings can't match a requested permission and are dropped.
+      #: (Hash[String, untyped] data) -> Array[String]?
+      def self.granted_permissions(data)
+        granted = data["permissions"]
+        granted.grep(String) if granted.is_a?(Array)
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/create_comment.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class CreateComment < MCP::Tool
+      extend Helpers
+
+      # A blind retry would add a duplicate comment for every member to see.
+      UNCERTAIN_OUTCOME = "The comment may still have been added; check with list_comments before retrying." #: String
+
+      tool_name "create_comment"
+      description "Add a comment to a post in a BAND as the user. Visible to the band's members, so confirm the " \
+                  "post and wording with the user first. BAND does not return the new comment's key; call " \
+                  "list_comments to find it. Check the commenting permission with check_permissions if unsure. " \
+                  "Find band_key with list_bands and post_key with list_posts. BAND can answer 'Cool down time " \
+                  "restriction' (1003) when comments come in quick succession; leave about ten seconds between " \
+                  "comments, or wait that long and retry."
+      input_schema(
+        properties: {
+          band_key: { type: "string", minLength: 1, description: "Band the post belongs to, from list_bands." },
+          post_key: { type: "string", minLength: 1, description: "Post to comment on, from list_posts." },
+          content: { type: "string", pattern: "\\S", description: "Text of the comment. Must not be blank." }
+        },
+        required: %w[band_key post_key content]
+      )
+      annotations(read_only_hint: false, destructive_hint: false, idempotent_hint: false)
+
+      #: (band_key: String, post_key: String, content: String, **untyped) -> untyped
+      def self.call(band_key:, post_key:, content:, **)
+        with_write_client(UNCERTAIN_OUTCOME) do |client|
+          client.post("/v2/band/post/comment/create",
+                      { "band_key" => band_key, "post_key" => post_key, "body" => content })
+          json_response({ "band_key" => band_key, "post_key" => post_key, "created" => true })
+        end
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/create_post.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class CreatePost < MCP::Tool
+      extend Helpers
+
+      # A blind retry would duplicate the post for every member.
+      UNCERTAIN_OUTCOME = "The post may still have been published; check the band before retrying." #: String
+
+      tool_name "create_post"
+      description "Publish a text post to a BAND as the user. Visible to the band's members, so confirm the band " \
+                  "and wording with the user first. Returns the post_key; pass it to get_post to confirm the post " \
+                  "landed. Find band_key with list_bands. Members are only push-notified if do_push is true."
+      input_schema(
+        properties: {
+          band_key: { type: "string", minLength: 1, description: "Band to post to, from list_bands." },
+          content: { type: "string", pattern: "\\S", description: "Body of the post. Must not be blank." },
+          do_push: { type: "boolean", description: "Push-notify subscribed members. Defaults to false." }
+        },
+        required: %w[band_key content]
+      )
+      annotations(read_only_hint: false, destructive_hint: false, idempotent_hint: false)
+
+      #: (band_key: String, content: String, ?do_push: bool, **untyped) -> untyped
+      def self.call(band_key:, content:, do_push: false, **)
+        with_write_client(UNCERTAIN_OUTCOME) do |client|
+          data = client.post(
+            "/v2.2/band/post/create",
+            { "band_key" => band_key, "content" => content, "do_push" => do_push }
+          )
+          json_response(data.slice("band_key", "post_key"))
+        end
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/get_post.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class GetPost < MCP::Tool
+      extend Helpers
+
+      tool_name "get_post"
+      description "Fetch one post from a BAND by band_key and post_key, e.g. to confirm that a post made with " \
+                  "create_post was published. Returns the text, author, creation time and comment/emotion counts."
+      input_schema(
+        properties: {
+          band_key: { type: "string", minLength: 1, description: "Band the post belongs to, from list_bands." },
+          post_key: { type: "string", minLength: 1, description: "Post to fetch, e.g. from create_post." }
+        },
+        required: %w[band_key post_key]
+      )
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true)
+
+      #: (band_key: String, post_key: String, **untyped) -> untyped
+      def self.call(band_key:, post_key:, **)
+        with_client do |client|
+          data = client.get("/v2.1/band/post", { "band_key" => band_key, "post_key" => post_key })
+          post = data["post"]
+          if post.is_a?(Hash)
+            json_response(summarize_post(post))
+          else
+            text_response("BAND returned no post for that band_key and post_key", error: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/helpers.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "json"
+require "mcp"
+require "time"
+
+require_relative "../client"
+
+module BandMCP
+  module Tools
+    # Shared plumbing for tools that call BAND. Tool classes `extend` this so their `self.call` stays a one-liner and
+    # every failure reaches the model as a tool error rather than crashing the server.
+    module Helpers
+      POST_FIELDS = %w[post_key band_key content comment_count emotion_count].freeze #: Array[String]
+      COMMENT_FIELDS = %w[comment_key post_key content emotion_count].freeze #: Array[String]
+
+      # Yields a client and turns BandMCP::Error into an MCP error response.
+      #: () { (Client) -> untyped } -> untyped
+      def with_client
+        yield Client.new
+      rescue Error => e
+        text_response(e.message, error: true)
+      end
+
+      #: (untyped data) -> untyped
+      def json_response(data)
+        text_response(JSON.generate(data))
+      end
+
+      #: (String text, ?error: bool) -> untyped
+      def text_response(text, error: false)
+        MCP::Tool::Response.new([{ type: "text", text: text }], error: error)
+      end
+
+      # `with_client` for a write. When the connection drops, that says nothing about whether the write took effect,
+      # and a blind retry could repeat it, so the model is told to check first. `advice` says how.
+      #: (String advice) { (Client) -> untyped } -> untyped
+      def with_write_client(advice)
+        with_client do |client|
+          yield client
+        rescue NetworkError => e
+          text_response("#{e.message}. #{advice}", error: true)
+        end
+      end
+
+      # For a response whose shape BAND changed. Reporting it as an error keeps it from reading as an empty or
+      # all-denied answer.
+      #: (String what) -> untyped
+      def unexpected_format(what)
+        text_response("BAND returned #{what} in an unexpected format", error: true)
+      end
+
+      #: (Hash[String, untyped] post) -> Hash[String, untyped]
+      def summarize_post(post)
+        summarize_record(post, POST_FIELDS)
+      end
+
+      #: (Hash[String, untyped] comment) -> Hash[String, untyped]
+      def summarize_comment(comment)
+        summarize_record(comment, COMMENT_FIELDS)
+      end
+
+      # Answers a BAND page of items as `{key => [...], "next_after" => cursor}`, yielding each item to summarize it.
+      # A missing list means an empty page, but a list that isn't an array means BAND changed shape; saying "none"
+      # there would mislead the model.
+      # `prefix` is put in front of the cursor for tools that encode more than BAND's cursor in it.
+      #: (Hash[String, untyped] data, String key, ?prefix: String) { (Hash[String, untyped]) -> untyped } -> untyped
+      def paged_response(data, key, prefix: "", &)
+        items = data["items"]
+        return unexpected_format(key) unless items.nil? || items.is_a?(Array)
+
+        cursor = next_after(data)
+        json_response({ key => Array(items).grep(Hash).map(&),
+                        "next_after" => cursor && "#{prefix}#{cursor}" })
+      end
+
+      # BAND's next_params also carries the access token, so only the cursor is passed on. Nothing else from it may
+      # reach the model.
+      #: (Hash[String, untyped] data) -> String?
+      def next_after(data)
+        paging = data["paging"]
+        next_params = paging["next_params"] if paging.is_a?(Hash)
+        after = next_params["after"] if next_params.is_a?(Hash)
+        after if after.is_a?(String) && !after.empty?
+      end
+
+      # Keeps the listed fields and drops the photo/video payloads and author profile details, and turns BAND's epoch
+      # milliseconds into ISO 8601 so the model doesn't have to. Anything missing or oddly shaped is omitted rather
+      # than raised on.
+      #: (Hash[String, untyped] record, Array[String] fields) -> Hash[String, untyped]
+      def summarize_record(record, fields)
+        summary = record.slice(*fields)
+        author = record["author"]
+        summary["author"] = author["name"] if author.is_a?(Hash)
+        created_at = record["created_at"]
+        summary["created_at"] = Time.at(created_at / 1000, in: "UTC").iso8601 if created_at.is_a?(Integer)
+        summary
+      end
+    end
+  end
+end