ask-anychat-mcp 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e4c8dd1fbdd06af3eea37bc761e1181b0b1fd6b8a4b9a192d87cbdce9ec76bd6
+  data.tar.gz: a028698b40e423aa5494609fae8674f6a0cc986d6d07c16f0771f653022b5bb6
+SHA512:
+  metadata.gz: 6bc18d87d53dbe770e28801ed7ea9e497adc8aa7181147255a64ed824114a12abd3d3ea27efaba1c26ae1a2d4d9171dbfc16f02890f8ba5d5893d317463afe6b
+  data.tar.gz: ab7a9c27147b4688673098b9def67d76bd5085b51c8139e81bc9c26f414382a0fbf47520075aa353d34ab76d92c77dc5c56df2175179db9d28dff6199910205c

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+## [0.1.0] - 2026-09-17
+
+### Added
+
+- **An MCP server for Anychat**, served over stdio —
+  `Ask::AnyChat::MCP.start` and the `ask-anychat-mcp` executable. Tool names are
+  prefixed `ask_anychat_` so they cannot collide with a client's own tools of the
+  same name, as the other ask MCP servers are.
+
+- **Five tools, one per operation** — `ask_anychat_list_agents`,
+  `ask_anychat_get_agent`, `ask_anychat_create_agent`,
+  `ask_anychat_update_agent` and `ask_anychat_delete_agent`. Every one names a
+  workspace, because a workspace is what a token reaches.
+
+- **Arguments checked before the call** — a missing or misspelled argument is
+  named, with the ones that were on offer, rather than being dropped and
+  surfacing later as an unexplained result. The schema each tool declares is
+  also enforced at the protocol boundary.
+
+- **Refusals come back as text** — the sentence the API wrote, prefixed with
+  `Error:`, so a model can act on it instead of being handed an exception that
+  ends the conversation.
+
+- **`Ask::AnyChat::MCP.tools(client:)`** — the client can be supplied, which is
+  how a host points the server at a particular deployment and how the tests hold
+  the API still.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,74 @@
+# Ask::AnyChat::MCP
+
+MCP server for [Anychat](https://anywaye.com), for the
+[ask-rb](https://github.com/ask-rb) ecosystem.
+
+Exposes the agents a workspace owns as callable tools over stdio, so a client
+that speaks the Model Context Protocol can create and manage them without
+knowing anything about the API underneath. The tool shell lives here; the API
+client is [ask-anychat](https://github.com/ask-rb/ask-anychat).
+
+## Installation
+
+```ruby
+gem "ask-anychat-mcp"
+```
+
+## Usage
+
+Register the executable with an MCP client:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "ask-anychat-mcp": {
+        "type": "stdio",
+        "command": "ask-anychat-mcp",
+        "env": { "ANYCHAT_TOKEN": "..." }
+      }
+    }
+  }
+}
+```
+
+Set `ANYCHAT_BASE_URL` too when pointing at a deployment that is not the hosted
+app. Mint a token in Anychat under Settings → API tokens.
+
+### Tools
+
+| Tool | What it does |
+| --- | --- |
+| `ask_anychat_list_agents` | Every agent a workspace owns, with the address each answers on |
+| `ask_anychat_get_agent` | One agent, by the address it answers on |
+| `ask_anychat_create_agent` | Bring a new agent into being — a name is all it takes |
+| `ask_anychat_update_agent` | Change one; only the arguments you pass are written |
+| `ask_anychat_delete_agent` | Retire one; its address becomes free |
+
+Every tool names a workspace, because a workspace is what a token reaches.
+
+Names are prefixed `ask_anychat_` to keep them from colliding with a client's own
+tools of the same name, as the other ask MCP servers are.
+
+### What comes back
+
+A refusal is text the model can act on rather than an exception that ends the
+conversation, and it carries the sentence the API wrote:
+
+```
+Error: No agent at /anywaye/nope.
+```
+
+The same is true of an argument that was missing or misspelled — a model that
+typed `name` where `display_name` was wanted is told so, rather than having the
+value quietly dropped.
+
+## Contributing
+
+Run `bin/setup` once, then `bundle exec rake test`. Until `ask-anychat` and
+`ask-mcp` are released, the Gemfile consumes both from the working copies
+alongside this one.
+
+## License
+
+MIT.

data/bin/ask-anychat-mcp

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ask/anychat/mcp"
+
+Ask::AnyChat::MCP.start

data/lib/ask/anychat/mcp/tool.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    module MCP
+      # The duck type the MCP adapter expects: a name, a description, a JSON
+      # Schema, and a call.
+      #
+      # Arguments are checked here rather than at the API, so a model that
+      # misspells a parameter is told which one it typed and which were on
+      # offer — instead of being handed a status code it cannot read. Failures
+      # come back as text for the same reason: this is a conversation.
+      class Tool
+        class << self
+          # Not `name`: that is already how a class answers to itself, and
+          # taking it over breaks more than it tells.
+          def tool_name(value = nil)
+            @tool_name = value if value
+            @tool_name
+          end
+
+          def description(text = nil)
+            @description = text if text
+            @description
+          end
+
+          def params(schema = nil)
+            @params = schema if schema
+            @params || {}
+          end
+        end
+
+        def initialize(client: nil)
+          @client = client
+        end
+
+        def name
+          self.class.tool_name
+        end
+
+        def description
+          self.class.description
+        end
+
+        def params_schema
+          self.class.params
+        end
+
+        def call(arguments = {})
+          args = stringify(arguments)
+          violation = violation(args)
+          return violation if violation
+
+          run(args)
+        rescue AnyChat::Error => e
+          "Error: #{e.message}"
+        end
+
+        private
+
+        attr_reader :client
+
+        # Built once per call and only if a tool needs it, so the server can be
+        # started without a token in the environment.
+        def anychat
+          @anychat ||= client || AnyChat.client
+        end
+
+        def run(_args)
+          raise NotImplementedError, "#{self.class} must implement #run"
+        end
+
+        def stringify(arguments)
+          arguments.each_with_object({}) { |(key, value), out| out[key.to_s] = value }
+        end
+
+        # Unknown and missing arguments are named, not ignored: a model that
+        # typed `name` where `display_name` was wanted should hear about it.
+        def violation(args)
+          allowed = params_schema[:properties].to_h.keys.map(&:to_s)
+          required = Array(params_schema[:required]).map(&:to_s)
+
+          missing = required - args.keys
+          if missing.any?
+            return "Error: missing required argument(s): #{missing.join(', ')}. Expected: #{allowed.join(', ')}"
+          end
+
+          extra = args.keys - allowed
+          return "Error: unknown argument(s): #{extra.join(', ')}. Expected: #{allowed.join(', ')}" if extra.any?
+
+          nil
+        end
+
+        # Only what the caller actually sent: an omitted optional argument is an
+        # omission, not a nil to write over what is already there.
+        def writable(args, *names)
+          names.each_with_object({}) do |name, out|
+            key = name.to_s
+            out[name.to_sym] = args[key] if args.key?(key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/anychat/mcp/tools/create_agent.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    module MCP
+      module Tools
+        # A new agent for a workspace.
+        class CreateAgent < Tool
+          tool_name "ask_anychat_create_agent"
+          description "Bring a new agent into being in a workspace. Only a name is needed; " \
+                      "the address it answers on is derived from that name, and a taken one " \
+                      "is handed the first free variant rather than failing. Pass handle to " \
+                      "choose the address yourself."
+          params(
+            type: "object",
+            properties: {
+              workspace: {
+                type: "string",
+                description: "The workspace's username, the first half of /<workspace>/<agent>"
+              },
+              display_name: {
+                type: "string",
+                description: "What the agent is called, e.g. \"Support\""
+              },
+              handle: {
+                type: "string",
+                description: "The address to answer on. Defaults to one derived from the name."
+              },
+              description: {
+                type: "string",
+                description: "One line about what this agent is for."
+              },
+              public: {
+                type: "boolean",
+                description: "Whether the world can find it. Defaults to true."
+              }
+            },
+            required: %w[workspace display_name]
+          )
+
+          private
+
+          def run(args)
+            agent = anychat.create_workspace_agent(
+              args["workspace"],
+              **writable(args, :display_name, :handle, :description, :public)
+            )
+
+            "Created #{agent['display_name']} at #{agent['address']}."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/anychat/mcp/tools/delete_agent.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    module MCP
+      module Tools
+        # An agent leaves the workspace, and its address becomes free.
+        #
+        # Conversations customers had with it are kept, so a retired agent still
+        # appears in that history — which is worth saying, because an owner who
+        # expects the record gone would be wrong to.
+        class DeleteAgent < Tool
+          tool_name "ask_anychat_delete_agent"
+          description "Retire an agent from a workspace. Its address becomes free for another " \
+                      "agent to take. Conversations it already had are kept."
+          params(
+            type: "object",
+            properties: {
+              workspace: {
+                type: "string",
+                description: "The workspace's username, the first half of /<workspace>/<agent>"
+              },
+              agent: {
+                type: "string",
+                description: "The address it answers on, the second half of /<workspace>/<agent>"
+              }
+            },
+            required: %w[workspace agent]
+          )
+
+          private
+
+          def run(args)
+            anychat.destroy_workspace_agent(args["workspace"], args["agent"])
+
+            "Retired the agent at /#{args['workspace']}/#{args['agent']}. The address is free again."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/anychat/mcp/tools/get_agent.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    module MCP
+      module Tools
+        # One agent, by the address it answers on.
+        class GetAgent < Tool
+          tool_name "ask_anychat_get_agent"
+          description "Read one agent of a workspace, by the address it answers on. Use " \
+                      "ask_anychat_list_agents first if you do not know the address."
+          params(
+            type: "object",
+            properties: {
+              workspace: {
+                type: "string",
+                description: "The workspace's username, the first half of /<workspace>/<agent>"
+              },
+              agent: {
+                type: "string",
+                description: "The address it answers on, the second half of /<workspace>/<agent>"
+              }
+            },
+            required: %w[workspace agent]
+          )
+
+          private
+
+          def run(args)
+            agent = anychat.workspace_agent(args["workspace"], args["agent"])
+
+            [
+              "#{agent['display_name']} at #{agent['address']}",
+              agent["description"].to_s.strip.empty? ? nil : agent["description"],
+              agent["public"] ? "Public" : "Private"
+            ].compact.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/anychat/mcp/tools/list_agents.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    module MCP
+      module Tools
+        # The agents a workspace owns, oldest first.
+        class ListAgents < Tool
+          tool_name "ask_anychat_list_agents"
+          description "List the agents a workspace owns, oldest first, with the address each " \
+                      "answers on. Read this before creating or changing one — it is how you " \
+                      "learn which addresses are already taken."
+          params(
+            type: "object",
+            properties: {
+              workspace: {
+                type: "string",
+                description: "The workspace's username, the first half of /<workspace>/<agent>"
+              }
+            },
+            required: ["workspace"]
+          )
+
+          private
+
+          def run(args)
+            agents = anychat.workspace_agents(args["workspace"])
+            return "This workspace has no agents yet." if agents.empty?
+
+            agents.map { |agent| line(args["workspace"], agent) }.join("\n")
+          end
+
+          def line(workspace, agent)
+            parts = ["#{agent['display_name']} at /#{workspace}/#{agent['handle']}"]
+            parts << "— #{agent['description']}" if agent["description"].to_s.strip.length.positive?
+            parts << "(private)" unless agent["public"]
+            parts.join(" ")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/anychat/mcp/tools/update_agent.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    module MCP
+      module Tools
+        # What an existing agent becomes.
+        #
+        # The address being changed and the address being changed *to* are two
+        # different things, so they are two different arguments: `agent` says
+        # which one, `handle` says what to move it to. One name for both would
+        # be a sentence that cannot be read.
+        class UpdateAgent < Tool
+          tool_name "ask_anychat_update_agent"
+          description "Change an agent a workspace already owns. Only the arguments you pass " \
+                      "are written — anything left out keeps its value. Pass handle to move " \
+                      "the address it answers on."
+          params(
+            type: "object",
+            properties: {
+              workspace: {
+                type: "string",
+                description: "The workspace's username, the first half of /<workspace>/<agent>"
+              },
+              agent: {
+                type: "string",
+                description: "The address it answers on now, the second half of /<workspace>/<agent>"
+              },
+              display_name: {
+                type: "string",
+                description: "What the agent is called."
+              },
+              handle: {
+                type: "string",
+                description: "The address to move it to. A taken one is given the first free variant."
+              },
+              description: {
+                type: "string",
+                description: "One line about what this agent is for."
+              },
+              public: {
+                type: "boolean",
+                description: "Whether the world can find it."
+              }
+            },
+            required: %w[workspace agent]
+          )
+
+          private
+
+          def run(args)
+            attributes = writable(args, :display_name, :handle, :description, :public)
+            return nothing_to_change if attributes.empty?
+
+            agent = anychat.update_workspace_agent(args["workspace"], args["agent"], **attributes)
+
+            "Updated #{agent['display_name']} at #{agent['address']}."
+          end
+
+          def nothing_to_change
+            "Error: nothing to change. Pass at least one of display_name, handle, description, public."
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ask/anychat/mcp/tools.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "tools/list_agents"
+require_relative "tools/get_agent"
+require_relative "tools/create_agent"
+require_relative "tools/update_agent"
+require_relative "tools/delete_agent"
+
+module Ask
+  module AnyChat
+    module MCP
+      # Every tool this server exposes, in the order a model should reach for
+      # them: read, then write, then retire.
+      module Tools
+        ALL = [
+          ListAgents,
+          GetAgent,
+          CreateAgent,
+          UpdateAgent,
+          DeleteAgent
+        ].freeze
+      end
+    end
+  end
+end

data/lib/ask/anychat/mcp/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ask
+  module AnyChat
+    module MCP
+      VERSION = "0.1.1"
+    end
+  end
+end

data/lib/ask/anychat/mcp.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "ask/mcp"
+require "ask-anychat"
+require_relative "mcp/version"
+require_relative "mcp/tool"
+require_relative "mcp/tools"
+
+module Ask
+  module AnyChat
+    # MCP (Model Context Protocol) server for Anychat.
+    #
+    # Exposes workspace agent CRUD over MCP, so a client that speaks the
+    # protocol can create and manage a workspace's agents without knowing
+    # anything about this API. Tool names are prefixed `ask_anychat_` to keep
+    # them from colliding with a client's own tools of the same name.
+    module MCP
+      # Every tool, each holding the client it was given — or building one from
+      # the environment on first use, which is what the executable relies on.
+      def self.tools(client: nil)
+        Tools::ALL.map { |tool| tool.new(client: client) }
+      end
+
+      # Serve over stdio. Blocking — the last line of an entry-point script.
+      #
+      #   $ ask-anychat-mcp
+      #
+      # Register it with an MCP client by command; set ANYCHAT_TOKEN and, if it
+      # is not the hosted app, ANYCHAT_BASE_URL in the server's environment.
+      def self.start(client: nil)
+        Ask::MCP::Server.start_stdio(
+          name: "ask-anychat-mcp",
+          version: VERSION,
+          tools: tools(client: client),
+          capabilities: { tools: {} },
+          debug: ENV["DEBUG"] == "1"
+        )
+      end
+    end
+  end
+end

data/lib/ask-anychat-mcp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "ask/anychat/mcp"

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: ask-anychat-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ask-anychat
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: ask-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.5.0
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A minimal MCP (Model Context Protocol) server that exposes the agents
+  an Anychat workspace owns as callable tools over stdio — list them, read one, bring
+  a new one into being, change one, or retire one. Designed for clients that speak
+  MCP (ZCode, Claude Code, and the like). The tool shell (name, schema, call) lives
+  here, wrapping ask-anychat; the API client itself is that gem's.
+email:
+- kaka@myrrlabs.com
+executables:
+- ask-anychat-mcp
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- bin/ask-anychat-mcp
+- lib/ask-anychat-mcp.rb
+- lib/ask/anychat/mcp.rb
+- lib/ask/anychat/mcp/tool.rb
+- lib/ask/anychat/mcp/tools.rb
+- lib/ask/anychat/mcp/tools/create_agent.rb
+- lib/ask/anychat/mcp/tools/delete_agent.rb
+- lib/ask/anychat/mcp/tools/get_agent.rb
+- lib/ask/anychat/mcp/tools/list_agents.rb
+- lib/ask/anychat/mcp/tools/update_agent.rb
+- lib/ask/anychat/mcp/version.rb
+homepage: https://github.com/ask-rb/ask-anychat-mcp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ask-rb/ask-anychat-mcp
+  source_code_uri: https://github.com/ask-rb/ask-anychat-mcp
+  changelog_uri: https://github.com/ask-rb/ask-anychat-mcp/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: MCP server for Anychat
+test_files: []