band-mcp-server 1.0.0

data/lib/band_mcp/tools/list_bands.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class ListBands < MCP::Tool
+      extend Helpers
+
+      FIELDS = %w[name band_key member_count].freeze #: Array[String]
+
+      tool_name "list_bands"
+      description "List the BANDs the user has joined. Returns each band's name, band_key and member_count; use the " \
+                  "band_key to refer to a band in other tools."
+      input_schema(properties: {})
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true)
+
+      #: (**untyped) -> untyped
+      def self.call(**)
+        with_client do |client|
+          bands = client.get("/v2.1/bands")["bands"]
+          json_response(bands.is_a?(Array) ? bands.map { |band| band.slice(*FIELDS) } : [])
+        end
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/list_comments.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class ListComments < MCP::Tool
+      extend Helpers
+
+      NEWEST_FIRST_SORT = "-created_at" #: String
+
+      # BAND's cursor only works with the sort it came from; paired with the wrong one it silently skips and repeats
+      # comments. So next_after carries the order as a tag, and a cursor without one is refused.
+      ORDER_TAGS = { false => "oldest", true => "newest" }.freeze #: Hash[bool, String]
+      TAGGED_CURSOR = /\A(?<tag>#{ORDER_TAGS.values.join('|')}):(?<cursor>.+)\z/m #: Regexp
+
+      BAD_CURSOR = "after must be a next_after value from a previous list_comments result, passed back unchanged " \
+                   "(it starts with oldest: or newest:). Leave after out to start from the first page." #: String
+
+      tool_name "list_comments"
+      description "List the comments on a post in a BAND, oldest first unless newest_first is true, with each " \
+                  "comment's comment_key, text, author, time and emotion count. BAND chooses the page size (20 when " \
+                  "tested). If next_after in the result is not null, there are more comments: pass it unchanged as " \
+                  "`after` to get the next page; it remembers the order, so newest_first only matters for the " \
+                  "first page. Find band_key with " \
+                  "list_bands and post_key with list_posts."
+      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 whose comments to read, from list_posts." },
+          after: { type: "string", minLength: 1,
+                   description: "The next_after value from a previous result, unchanged." },
+          newest_first: { type: "boolean",
+                          description: "List the newest comments first. Defaults to false. Ignored when `after` " \
+                                       "is given." }
+        },
+        required: %w[band_key post_key]
+      )
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true)
+
+      #: (band_key: String, post_key: String, ?after: String?, ?newest_first: bool, **untyped) -> untyped
+      def self.call(band_key:, post_key:, after: nil, newest_first: false, **)
+        if after
+          newest_first, cursor = parse_cursor(after)
+          return text_response(BAD_CURSOR, error: true) unless cursor
+        end
+        with_client do |client|
+          sort = NEWEST_FIRST_SORT if newest_first
+          params = { "band_key" => band_key, "post_key" => post_key, "after" => cursor, "sort" => sort }.compact
+          data = client.get("/v2/band/post/comments", params)
+          paged_response(data, "comments", prefix: "#{ORDER_TAGS[newest_first]}:") { |item| summarize_comment(item) }
+        end
+      end
+
+      # The order and BAND's cursor out of a next_after value, or nil for the cursor when it isn't one of ours.
+      #: (String after) -> [bool, String?]
+      def self.parse_cursor(after)
+        match = TAGGED_CURSOR.match(after)
+        return [false, nil] unless match
+
+        [ORDER_TAGS.key(match[:tag]) || false, match[:cursor]]
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/list_posts.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class ListPosts < MCP::Tool
+      extend Helpers
+
+      DEFAULT_LOCALE = "en_US" #: String
+
+      tool_name "list_posts"
+      description "List recent posts in a BAND, most recently modified first, with each post's text, author, time " \
+                  "and comment/emotion counts. BAND chooses the page size. If next_after in the result is not " \
+                  "null, pass it as `after` to get the next page. Find band_key with list_bands."
+      input_schema(
+        properties: {
+          band_key: { type: "string", minLength: 1, description: "Band to read, from list_bands." },
+          after: { type: "string", minLength: 1, description: "The next_after value from a previous result." },
+          locale: { type: "string", minLength: 1,
+                    description: "Region and language for BAND's response. Defaults to en_US." }
+        },
+        required: %w[band_key]
+      )
+      annotations(read_only_hint: true, destructive_hint: false, idempotent_hint: true)
+
+      #: (band_key: String, ?after: String?, ?locale: String, **untyped) -> untyped
+      def self.call(band_key:, after: nil, locale: DEFAULT_LOCALE, **)
+        with_client do |client|
+          params = { "band_key" => band_key, "locale" => locale, "after" => after }.compact
+          data = client.get("/v2/band/posts", params)
+          paged_response(data, "posts") { |item| summarize_post(item) }
+        end
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/ping.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+module BandMCP
+  module Tools
+    # Connectivity check. Makes no network call and never reveals the token, only whether one is configured.
+    class Ping < MCP::Tool
+      tool_name "ping"
+      description "Check that the server is up and whether BAND_ACCESS_TOKEN is configured."
+      input_schema(properties: {})
+
+      #: (**untyped) -> untyped
+      def self.call(**)
+        MCP::Tool::Response.new([{ type: "text", text: "pong (BAND_ACCESS_TOKEN set: #{Config.access_token?})" }])
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/remove_comment.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class RemoveComment < MCP::Tool
+      extend Helpers
+
+      UNCERTAIN_OUTCOME = "The comment may already have been removed. Check with list_comments before retrying, " \
+                          "paging through with `after` if the post has many comments: if its comment_key is " \
+                          "gone, the removal worked." #: String
+
+      tool_name "remove_comment"
+      description "Permanently delete a comment from a post in a BAND. It disappears for every member and cannot " \
+                  "be undone, so confirm the comment with the user first, e.g. by showing them list_comments' " \
+                  "result. BAND's docs say only comments made through this app can be removed, and " \
+                  "contents_deletion (check_permissions) does not cover authorship, so removing someone else's " \
+                  "comment can still fail. comment_key is only meaningful together with its post_key; find it " \
+                  "with list_comments. BAND can answer 'Cool down time restriction' (1003) right after another " \
+                  "write; wait a minute 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 the comment is on, from list_posts." },
+          comment_key: { type: "string", minLength: 1, description: "Comment to delete, from list_comments." }
+        },
+        required: %w[band_key post_key comment_key]
+      )
+      annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: true)
+
+      #: (band_key: String, post_key: String, comment_key: String, **untyped) -> untyped
+      def self.call(band_key:, post_key:, comment_key:, **)
+        with_write_client(UNCERTAIN_OUTCOME) do |client|
+          keys = { "band_key" => band_key, "post_key" => post_key, "comment_key" => comment_key }
+          client.post("/v2/band/post/comment/remove", keys)
+          json_response(keys.merge("removed" => true))
+        end
+      end
+    end
+  end
+end

data/lib/band_mcp/tools/remove_post.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "helpers"
+
+module BandMCP
+  module Tools
+    class RemovePost < MCP::Tool
+      extend Helpers
+
+      UNCERTAIN_OUTCOME = "The post may already have been removed. Check with get_post before retrying: BAND " \
+                          "reporting it as deleted or not found means the removal worked." #: String
+
+      tool_name "remove_post"
+      description "Permanently delete a post from a BAND. It disappears for every member and cannot be undone, so " \
+                  "confirm the band and post with the user first, e.g. by showing them get_post's result. " \
+                  "Check contents_deletion with check_permissions beforehand; that permission does not cover " \
+                  "authorship, so removing someone else's post can still fail. Find band_key with list_bands and " \
+                  "post_key with list_posts. BAND can answer 'Cool down time restriction' (1003) right after another " \
+                  "write; wait a minute 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 delete, from list_posts or create_post." }
+        },
+        required: %w[band_key post_key]
+      )
+      annotations(read_only_hint: false, destructive_hint: true, idempotent_hint: true)
+
+      #: (band_key: String, post_key: String, **untyped) -> untyped
+      def self.call(band_key:, post_key:, **)
+        with_write_client(UNCERTAIN_OUTCOME) do |client|
+          client.post("/v2/band/post/remove", { "band_key" => band_key, "post_key" => post_key })
+          json_response({ "band_key" => band_key, "post_key" => post_key, "removed" => true })
+        end
+      end
+    end
+  end
+end

data/lib/band_mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module BandMCP
+  VERSION = "1.0.0" #: String
+end

data/lib/band_mcp.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "mcp"
+
+require_relative "band_mcp/version"
+require_relative "band_mcp/config"
+require_relative "band_mcp/error"
+require_relative "band_mcp/client"
+require_relative "band_mcp/tools/ping"
+require_relative "band_mcp/tools/list_bands"
+require_relative "band_mcp/tools/create_post"
+require_relative "band_mcp/tools/get_post"
+require_relative "band_mcp/tools/list_posts"
+require_relative "band_mcp/tools/check_permissions"
+require_relative "band_mcp/tools/remove_post"
+require_relative "band_mcp/tools/list_comments"
+require_relative "band_mcp/tools/create_comment"
+require_relative "band_mcp/tools/remove_comment"
+
+module BandMCP
+  TOOLS = [
+    Tools::Ping, Tools::ListBands, Tools::CreatePost, Tools::GetPost, Tools::ListPosts, Tools::CheckPermissions,
+    Tools::RemovePost, Tools::ListComments, Tools::CreateComment, Tools::RemoveComment
+  ].freeze #: Array[singleton(MCP::Tool)]
+
+  #: () -> untyped
+  def self.build_server
+    MCP::Server.new(name: "band-mcp-server", version: VERSION, tools: TOOLS)
+  end
+
+  # Entry point shared by the gem's executable and the checkout's launcher.
+  #: () -> untyped
+  def self.run
+    Config.load_dotenv
+    MCP::Server::Transports::StdioTransport.new(build_server).open
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: band-mcp-server
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Keith T. Garner
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+description: A Model Context Protocol server, served over stdio, that lets MCP clients
+  list bands and read, post, and comment on BAND posts through the BAND Open API.
+email:
+- kgarner@kgarner.com
+executables:
+- band-mcp-server
+extensions: []
+extra_rdoc_files: []
+files:
+- API_DISCREPANCIES.md
+- CHANGELOG.md
+- LICENSE
+- README.md
+- exe/band-mcp-server
+- lib/band_mcp.rb
+- lib/band_mcp/client.rb
+- lib/band_mcp/config.rb
+- lib/band_mcp/error.rb
+- lib/band_mcp/tools/check_permissions.rb
+- lib/band_mcp/tools/create_comment.rb
+- lib/band_mcp/tools/create_post.rb
+- lib/band_mcp/tools/get_post.rb
+- lib/band_mcp/tools/helpers.rb
+- lib/band_mcp/tools/list_bands.rb
+- lib/band_mcp/tools/list_comments.rb
+- lib/band_mcp/tools/list_posts.rb
+- lib/band_mcp/tools/ping.rb
+- lib/band_mcp/tools/remove_comment.rb
+- lib/band_mcp/tools/remove_post.rb
+- lib/band_mcp/version.rb
+homepage: https://github.com/ktgeek/ruby-band-mcp-server
+licenses:
+- GPL-3.0-only
+metadata:
+  source_code_uri: https://github.com/ktgeek/ruby-band-mcp-server
+  changelog_uri: https://github.com/ktgeek/ruby-band-mcp-server/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/ktgeek/ruby-band-mcp-server/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.10
+specification_version: 4
+summary: MCP server for the BAND Open API
+test_files: []