hyperclient-mcp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 788205f7a40dcce22ef7e160e7077833c28666c7ad27f0564916a1d18e6a7679
-  data.tar.gz: fead56f84529c880a3524e9b0ed732bf1838c6eb14db400b1b659904cd28e11a
+  metadata.gz: 1354eb080921be3ba1f7cb9403722f7206b7f1fbc1a720ccfe80a903642f4675
+  data.tar.gz: ed39ecbf6f6f92bfc9554916f4469874503259c05dea132c89e3942a40c1b135
 SHA512:
-  metadata.gz: ca6f4fe3fcfb2ffaaeb03aae44736f1746da4b41fe22f8f0eb76fb12c9f70eb79a24b5411962b38497f0265649c0fb7b463ff103b35d1fac22140efaaeed985c
-  data.tar.gz: e0fd1072626e0a35b370ab595edf0a81990aaed104e4afae01e9918ea7103d8e913303e55a696da933ebc6fafdae8738c91477512a73807de59f2e30ffe84265
+  metadata.gz: 6cd9503b583cd298b319d1309c954f67a6ba74255455be388e930a48bb3644ac8051e0134e957fafe113f8f6520e588900fb2162ee3e8ac84f0a835732cbecb4
+  data.tar.gz: befb7ebb79e55b542bba8795c1fb4c557309850a9c9673cec35309bff16673c2ba88f577f21fe9fc854d39e047fdbbfcf23d3946a2ba2e80f7778e786e6b8aed

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+### 0.2.0 (Next)
+
+* Added a command-line `hyperclient-mcp` tool - [@dblock](https://github.com/dblock).
+* Your contribution here.
+
 ### 0.1.0 (2025/09/12)
 
 * Initial public release - [@dblock](https://github.com/dblock).

data/README.md

@@ -35,7 +35,39 @@ 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.
+#### Command Line
+
+Start the Hyperclient MCP server for any existing API using the convenient command-line proxy.
+
+```bash
+hyperclient-mcp --api https://sup2.playplay.io/api --header X-Access-Token=$TOKEN start
+```
+
+Register with Claude.
+
+```bash
+claude mcp add --transport sse local http://127.0.0.1:9292/mcp/sse
+```
+
+Check that it was registered.
+
+```bash
+$ claude mcp list
+Checking MCP server health...
+local: http://127.0.0.1:9292/mcp/sse (SSE) - ✓ Connected
+```
+
+Run Claude, try asking a question.
+
+```bash
+$ claude "use the local mcp to find the name of the team with ID 64124ac95d758400015faecf"
+
+The team name is dblock.
+```
+
+#### Programmatically
+
+To turn any hypermedia API into an MCP in code, create an mcp wrapper and register its `resources` with FastMcp and mount it as usual.
 
 ```ruby
 hyperclient_mcp = Hyperclient::Mcp::Api.new(api)
@@ -46,9 +78,7 @@ 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.
+For example, the MCP code in [examples/sup.playplay.io](examples/sup.playplay.io/) starts an MCP server using code similar to above, and can be directly used with Claude.
 
 ```bash
 bundle install
@@ -61,9 +91,9 @@ claude mcp add --transport sse local http://127.0.0.1:4567/mcp/sse
 
 ![](examples/sup.playplay.io/mcp.gif)
 
-## Examples
+## More Examples
 
-See [examples/grape-with-roar](examples/grape-with-roar/) for a complete example.
+See [examples/grape-with-roar](examples/grape-with-roar/) for a complete example that uses the [grape-with-roar demo project](https://github.com/ruby-grape/grape-with-roar).
 
 ## Upgrading
 

data/bin/commands/resources.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Hyperclient
+  module Mcp
+    module Cli
+      class App
+        desc 'List resources.'
+        command 'resources' do |command|
+          command.action do |global, _options, _args|
+            global['mcp'].resources.each do |resource|
+              puts resource
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/bin/commands/start.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hyperclient
+  module Mcp
+    module Cli
+      class App
+        desc 'Start an MCP server.'
+        command 'start' do |command|
+          command.flag 'h', 'host', desc: 'server host', type: String, default_value: '0.0.0.0'
+          command.flag 'p', 'port', desc: 'server port', type: Integer, default_value: 9292
+          command.flag 'n', 'name', desc: 'mcp server name', type: String, default_value: 'Hyperclient MCP'
+          command.flag 'v', 'version', desc: 'mcp server version', type: String, default_value: '0.0.1'
+          command.action do |global, options, _args|
+            require 'sinatra'
+            require 'puma'
+            require 'rack/handler/puma'
+
+            mcp_server = FastMcp::Server.new(name: options['name'], version: options['version'])
+            mcp_server.register_resources(*global['mcp'].resources)
+
+            app = Class.new(Sinatra::Base) do
+              set :environment, ENV.fetch('RACK_ENV', 'development')
+
+              use FastMcp::Transports::RackTransport, mcp_server
+
+              get '/' do
+                'OK'
+              end
+            end
+
+            host = options['host'] || ENV.fetch('HOST', '0.0.0.0')
+            port = options['port'] || Integer(ENV.fetch('PORT', 9292))
+
+            Rack::Handler::Puma.run(app, Host: host, Port: port)
+          end
+        end
+      end
+    end
+  end
+end

data/bin/hyperclient-mcp

@@ -0,0 +1,65 @@
+#!/usr/bin/env ruby
+require 'gli'
+require 'hyperclient-mcp'
+
+module Hyperclient
+  module Mcp
+    module Cli
+      class App
+        extend GLI::App
+
+        version Hyperclient::Mcp::VERSION
+
+        arguments :strict
+        subcommand_option_handling :normal
+
+        program_desc 'Hypermedia API MCP Server.'
+
+        default_command :help
+
+        flag ['api'], desc: 'API endpoint.', type: String, must_match: /\A#{URI::DEFAULT_PARSER.make_regexp}\z/
+        flag %w[h header], desc: 'Additional HTTP request header(s).', multiple: true
+        flag ['vcr-cassette-name'], desc: 'Offline VCR cassette.'
+
+        commands_from File.expand_path('commands', __dir__)
+
+        pre do |global_options, _command, options, _args|
+          # Offline VCR cassette
+          if global_options['vcr-cassette-name']
+            require 'vcr'
+            VCR.configure do |config|
+              config.cassette_library_dir = File.expand_path('../spec/fixtures', __dir__)
+              config.default_cassette_options = { record: :new_episodes }
+              config.hook_into :faraday
+              # config.debug_logger = $stderr
+              config.filter_sensitive_data('<TOKEN>') do
+                ENV.fetch('TOKEN', nil)
+              end
+            end
+            VCR.insert_cassette global_options['vcr-cassette-name']
+          end
+
+          # remove any nil values from options
+          options.compact!
+
+          api = Hyperclient.new(global_options['api']) do |client|
+            global_options['header']&.each do |header|
+              k, v = header.split('=', 2)
+              client.headers[k] = v
+            end
+          end
+
+          global_options['mcp'] = Hyperclient::Mcp::Api.new(api)
+
+          true
+        end
+
+        post do |global_options, _command, _options, _args|
+          VCR.eject_cassette if global_options['vcr-cassette-name']
+        end
+      end
+    end
+  end
+end
+
+exit Hyperclient::Mcp::Cli::App.run(ARGV)

data/lib/hyperclient-mcp/version.rb

@@ -2,6 +2,6 @@
 
 module Hyperclient
   module Mcp
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hyperclient-mcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniel Doubrovkine
 bindir: bin
 cert_chain: []
-date: 2025-09-12 00:00:00.000000000 Z
+date: 2025-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: fast-mcp
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: gli
+  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
@@ -37,14 +51,46 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: puma
+  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: sinatra
+  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: []
+executables:
+- hyperclient-mcp
 extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE.md
 - README.md
+- bin/commands/resources.rb
+- bin/commands/start.rb
+- bin/hyperclient-mcp
 - lib/hyperclient-mcp.rb
 - lib/hyperclient-mcp/api.rb
 - lib/hyperclient-mcp/resource.rb