hyperclient-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 788205f7a40dcce22ef7e160e7077833c28666c7ad27f0564916a1d18e6a7679
+  data.tar.gz: fead56f84529c880a3524e9b0ed732bf1838c6eb14db400b1b659904cd28e11a
+SHA512:
+  metadata.gz: ca6f4fe3fcfb2ffaaeb03aae44736f1746da4b41fe22f8f0eb76fb12c9f70eb79a24b5411962b38497f0265649c0fb7b463ff103b35d1fac22140efaaeed985c
+  data.tar.gz: e0fd1072626e0a35b370ab595edf0a81990aaed104e4afae01e9918ea7103d8e913303e55a696da933ebc6fafdae8738c91477512a73807de59f2e30ffe84265

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+### 0.1.0 (2025/09/12)
+
+* Initial public release - [@dblock](https://github.com/dblock).

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2018 Daniel Doubrovkine and Contributors
+
+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,80 @@
+# Hyperclient Mcp
+
+[![Gem Version](https://badge.fury.io/rb/hyperclient-mcp.svg)](https://badge.fury.io/rb/hyperclient-mcp)
+[![Test](https://github.com/dblock/hyperclient-mcp/actions/workflows/test.yml/badge.svg?branch=master)](https://github.com/dblock/hyperclient-mcp/actions/workflows/test.yml)
+
+Turn any hypermedia api into an mcp server.
+
+## Installation
+
+Add to Gemfile.
+
+```
+gem 'hyperclient-mcp'
+```
+
+Run `bundle install`.
+
+## Usage
+
+### Identify a Hypermedia API
+
+The S'Up service at [sup2.playplay.io](https://sup2.playplay.io) generates fresh triads of team members in Slack to meet for coffee every week in an informal standup. It has a Hypermedia API under [sup2.playplay.io/api](https://sup2.playplay.io/api) that can be enabled with `set api on` and accessed with a token obtained using `set api token`. We'll export TOKEN in a shell for future use.
+
+```bash
+export TOKEN=...
+```
+
+The Hypermedia client to this api is as follows.
+
+```ruby
+api = Hyperclient.new('https://sup2.playplay.io/api') do |client|
+  client.headers['X-Access-Token'] = ENV.fetch('TOKEN', nil)
+end
+```
+
+### Use Hyperclient MCP
+
+To turn any hypermedia API into an MCP, create an mcp wrapper and register its `resources` with FastMcp and mount it as usual.
+
+```ruby
+hyperclient_mcp = Hyperclient::Mcp::Api.new(api)
+
+mcp_server = FastMcp::Server.new(name: "S'Up", version: '0.0.1')
+mcp_server.register_resources(*hyperclient_mcp.resources)
+
+use FastMcp::Transports::RackTransport, mcp_server
+```
+
+### See It
+
+The MCP code in [examples/sup.playplay.io](examples/sup.playplay.io/) can be directly used with Claude.
+
+```bash
+bundle install
+bundle exec ruby mcp.rb
+```
+
+```bash
+claude mcp add --transport sse local http://127.0.0.1:4567/mcp/sse
+```
+
+![](examples/sup.playplay.io/mcp.gif)
+
+## Examples
+
+See [examples/grape-with-roar](examples/grape-with-roar/) for a complete example.
+
+## Upgrading
+
+See [UPGRADING](UPGRADING.md).
+
+## Contributing
+
+See [CONTRIBUTING](CONTRIBUTING.md).
+
+## Copyright and License
+
+Copyright (c) 2025, [Daniel Doubrovkine](https://twitter.com/dblockdotorg) and [Contributors](CHANGELOG.md).
+
+This project is licensed under the [MIT License](LICENSE.md).

data/lib/hyperclient-mcp/api.rb

@@ -0,0 +1,68 @@
+module Hyperclient
+  module Mcp
+    class Api
+      attr_reader :api
+
+      def initialize(api)
+        @api = api
+      end
+
+      def resources
+        @resources ||= _resources(@api)
+      end
+
+      private
+
+      def _resources(api, name = 'root')
+        api._links.map do |key, link|
+          name = key unless key == 'self'
+
+          href = link.instance_variable_get('@link')['href'].gsub(api.to_s, '')
+
+          klass = Class.new(Hyperclient::Mcp::Resource) do
+            uri "api://#{href}" # TODO: configure api prefix
+            resource_name name
+            mime_type 'application/json'
+            api api
+            key key
+            link link
+
+            def content
+              JSON.generate(
+                api.send(
+                  key, params
+                )._resource._attributes.to_h
+              )
+            end
+          end
+
+          # Assign a stable constant name like Hyperclient::Mcp::Resources::<CamelizedName>
+          const_module = Hyperclient::Mcp.const_defined?(:Resources) ? Hyperclient::Mcp::Resources : Hyperclient::Mcp.const_set(:Resources, Module.new)
+          const_name = name.to_s
+                           .gsub(/[^a-zA-Z0-9]+/, '_')
+                           .split('_')
+                           .reject(&:empty?)
+                           .map { |part| part[0].upcase + part[1..].to_s.downcase }
+                           .join
+          const_name = 'Root' if const_name.empty?
+
+          # Avoid collisions by appending a numeric suffix if needed
+          candidate = const_name
+          suffix = 2
+          while const_module.const_defined?(candidate)
+            candidate = "#{const_name}#{suffix}"
+            suffix += 1
+          end
+          const_module.const_set(candidate, klass)
+
+          klass.class_eval do
+            @api = api
+            @key = key
+          end
+
+          klass
+        end
+      end
+    end
+  end
+end

data/lib/hyperclient-mcp/resource.rb

@@ -0,0 +1,21 @@
+module Hyperclient
+  module Mcp
+    class Resource < FastMcp::Resource
+      %i[api key link].each do |f|
+        self.class.send :define_method, f do |val|
+          instance_variable_set "@#{f}", val
+        end
+
+        send :define_method, f do
+          self.class.instance_variable_get("@#{f}")
+        end
+      end
+
+      # class << self
+      #   def inspect
+      #     "#<Class:#{object_id} uri=#{uri}, name=#{resource_name}>"
+      #   end
+      # end
+    end
+  end
+end

data/lib/hyperclient-mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Hyperclient
+  module Mcp
+    VERSION = '0.1.0'
+  end
+end

data/lib/hyperclient-mcp.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'hyperclient'
+require 'fast_mcp'
+
+require_relative 'hyperclient-mcp/version'
+require_relative 'hyperclient-mcp/resource'
+require_relative 'hyperclient-mcp/api'

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: hyperclient-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel Doubrovkine
+bindir: bin
+cert_chain: []
+date: 2025-09-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fast-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: hyperclient
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+email: dblock@dblock.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- lib/hyperclient-mcp.rb
+- lib/hyperclient-mcp/api.rb
+- lib/hyperclient-mcp/resource.rb
+- lib/hyperclient-mcp/version.rb
+homepage: http://github.com/dblock/hyperclient-mcp
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Turn any Hypermedia api into an mcp server.
+test_files: []