hub_kernel-mcp 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbd198a0ec695b49e09abc0435889275eb2d8d56197496bad51fcdc7698582d8
-  data.tar.gz: 3d2e0d358be8c253b6996977d8687ed6b46509e4d33a16f5c74f76e5ca25a836
+  metadata.gz: c892de0b21d83e1d2068595a30e59930be423fa5b30dc539ffaedf3c304be263
+  data.tar.gz: 22114b0e2e4a5aa6c3389dc7c7580079a9091a5ac46bcfc6e7b53585eddcce16
 SHA512:
-  metadata.gz: 18a08e74dfccbf30a4db3cd6831119ce1cc5ad447a4080d1c47e5a208d1b73504f99ec42ed00b3a60dea04286679fdc6ba8713a5ad9eb5cee403104d252a2e9c
-  data.tar.gz: '028002bdb287b6828ce5e73f8130ab2b818d8710deba05335c508121d27619770848026156cb9bf93e721bd15d001faefd3bb1890dd31643ff343f6bfa8a64c0'
+  metadata.gz: 507a819510592862a8a2641075062fecf56f052de877ee8b7dc2fc7dd1ac66b7aace212dd7272cc33c6c65d80a1f9dbd792c7b63cf326a378fdbacca0a257dfb
+  data.tar.gz: b9e8d051ef5ef2f781499d69d17866e29b91475a7ba9e49f3648a8c10fcaa3f644da6acac643398d06421ee58e89479dd80c99dc3f7e50456bb848c0b6e3fc4f

data/Rakefile

@@ -4,3 +4,5 @@ APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
 load "rails/tasks/engine.rake"
 
 require "bundler/gem_tasks"
+
+require "the_local/rake"

data/lib/hub_kernel/mcp/version.rb

@@ -1,5 +1,5 @@
 module HubKernel
   module Mcp
-    VERSION = "0.6.0"
+    VERSION = "0.7.0"
   end
 end

data/the_local/agents/hub_kernel-mcp-develop.md

@@ -0,0 +1,152 @@
+---
+name: hub_kernel-mcp-develop
+description: Use PROACTIVELY for calling a host's hub methods over MCP — connecting an MCP client to the endpoint, sending initialize and ping, listing the tools a signed-in person may call with tools/list, calling one with tools/call, and handling its tool errors and JSON-RPC errors — MUST BE USED instead of hand-rolling a JSON API or MCP server for the host's hubs.
+tools: Read, Write, Edit, Grep
+scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools
+---
+
+This local writes the code or configuration that talks to a host's hub_kernel-mcp
+endpoint, following these steps exactly. Where a step names a decision, it asks
+the developer and does not pick.
+
+## What hub_kernel-mcp is
+
+A JSON-RPC endpoint in a host Rails app that offers every method the host's hubs
+expose as an MCP tool, for the person and account the host's sign-in gives.
+Fire this local when code or a client needs to list or call those tools, or when
+a test needs to send requests to the endpoint.
+
+## Interface
+
+- `POST /` — the endpoint, at the path the host serves it under. It takes one
+  JSON-RPC 2.0 request per POST as a JSON body. A GET to the same path is
+  answered with status 405 and `Allow: POST`.
+- `initialize` — answers `protocolVersion`, `serverInfo` with name
+  `hub_kernel-mcp` and the gem's version, and `capabilities: { tools: {} }`.
+  `protocolVersion` is the one the client sent in `params.protocolVersion` when
+  it is one of `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05`, and
+  `2025-11-25` otherwise.
+- `ping` — answers an empty result, `{}`.
+- `tools/list` — answers `{ tools: [...] }`, one tool for each hub method the
+  signed-in person may call in their account, across every served hub.
+- `tools/call` — runs the hub method a tool names with `params.arguments`, for
+  the signed-in person and account, and answers the method's return value as
+  JSON text.
+
+## How to use it
+
+1. Find the path the host serves the endpoint at in its `config/routes.rb`. If
+   it is not there, stop and tell the developer the endpoint is not installed
+   yet.
+
+2. Ask the developer how the client signs in. Every request runs the host's own
+   sign-in first, so the client must send whatever that sign-in expects, such as
+   a session cookie or a token header. A request the sign-in refuses gets the
+   host's refusal, for example status 401, and no hub is asked. Do not choose the
+   credential yourself.
+
+3. Send every request as a POST with a JSON body holding exactly one request:
+
+   ```json
+   { "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
+   ```
+
+   `jsonrpc` must be `"2.0"` and `method` must be a string. A batch, a JSON array
+   of requests, is refused with -32600. A request with no `id` is a
+   notification: it is answered with status 202 and no body, and nothing is run.
+
+4. Send `initialize` first. Ask the developer which protocol version the client
+   supports, send it as `params.protocolVersion`, and use the version the answer
+   gives. Then send the `notifications/initialized` notification with no `id`.
+
+5. Send `tools/list` to get the tools. Each tool has this shape:
+
+   ```json
+   {
+     "name": "supplies__price_of",
+     "description": "Reads data from the supplies hub.",
+     "inputSchema": { "type": "object", "properties": { "item": {} } },
+     "annotations": { "readOnlyHint": true }
+   }
+   ```
+
+   `name` is `<served name>__<method>`, split at the first two underscores in a
+   row. `inputSchema.properties` names each value the method takes and gives no
+   type for any of them. A method that writes has `readOnlyHint: false` and the
+   description `Changes data in the <served name> hub.` The list depends on who
+   is signed in and in which account, so list again after either changes.
+
+6. Ask the developer whether the client must confirm with the person before it
+   calls a tool whose `readOnlyHint` is false. If it must, add that confirmation
+   before step 7.
+
+7. Send `tools/call` with the tool's name and its values:
+
+   ```json
+   {
+     "jsonrpc": "2.0",
+     "id": 2,
+     "method": "tools/call",
+     "params": { "name": "supplies__price_of", "arguments": { "item": "soap" } }
+   }
+   ```
+
+   Send only the values named in that tool's `inputSchema.properties`. A
+   successful call answers:
+
+   ```json
+   { "content": [ { "type": "text", "text": "\"soap costs 3\"" } ], "isError": false }
+   ```
+
+   `text` is the method's return value encoded as JSON, so parse it as JSON to
+   get the value back.
+
+8. Handle a tool error. These come back as a normal result with `isError: true`
+   and the reason as the text:
+
+   - The hub refused the call.
+   - A value the method requires is missing.
+   - A value the method is not listed with was sent, such as
+     `price_of does not take colour`.
+   - A record the call names does not exist, such as `No item has the id 9`.
+
+   Show the reason to the person or the model making the call. Do not retry it
+   unchanged.
+
+9. Handle a JSON-RPC error. These come back as `error: { code, message }` with
+   status 200, and with the request's `id` except for -32700 and -32600, whose
+   `id` is null:
+
+   | Code | Message | When |
+   |---|---|---|
+   | -32700 | `Parse error` | The body is not valid JSON. |
+   | -32600 | `Invalid Request` | The body is not one JSON-RPC 2.0 request. |
+   | -32601 | `Method not found: <method>` | The MCP method is not one of the four above. |
+   | -32602 | `Unknown tool: <name>` | The tool does not exist, names a hub the host does not serve, or is one the caller may not call. |
+   | -32603 | `Internal error` | A hub method raised an unexpected error. |
+
+   -32602 reads the same in all three cases, so do not tell the person a tool
+   does not exist when it may only be one they cannot call. -32603 never carries
+   the error's own message, so find the cause in the host app's error reporting.
+
+10. In a test of the host app, send requests the same way, as a JSON POST to the
+    endpoint's path, signed in as the host's tests sign in:
+
+    ```ruby
+    post "/mcp", params: { jsonrpc: "2.0", id: 1, method: "tools/list" }, as: :json
+    ```
+
+## Conventions
+
+- One request per POST, always with `"jsonrpc": "2.0"`, and an `id` on every
+  request that needs an answer.
+- Build tool names from `tools/list`, never by hand, since the list is what the
+  signed-in person may call.
+- Treat `isError: true` as an answer about the call, and a JSON-RPC `error` as an
+  answer about the request.
+- The endpoint offers no sessions and no server-sent events, so do not open a GET
+  stream or send a session header.
+- Out of scope: installing the endpoint, choosing its controller, sign-in, and
+  served hubs, and running the boot check, which belong to
+  `hub_kernel-mcp-install`, and setting which methods a hub exposes, who may
+  call them and their account scope, which belong to hub_kernel-interface.

data/the_local/agents/hub_kernel-mcp-info.md

@@ -0,0 +1,66 @@
+---
+name: hub_kernel-mcp-info
+description: Use to learn what hub_kernel-mcp offers — serving a host's hubs as MCP tools, how tools are named and scoped, and the vocabulary the install and develop locals assume.
+tools: Read
+scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools
+---
+
+This local explains hub_kernel-mcp and makes no changes.
+
+## What hub_kernel-mcp is
+
+hub_kernel-mcp lets an MCP client, such as an AI assistant, call the methods a
+Rails host app's hubs expose. It reads the host's one served list from
+hub_kernel-interface, the same list every interface gem reads, and offers each
+method the caller may call as an MCP tool at a single JSON-RPC endpoint inside
+the host app.
+
+Reach for it when a host already serves hubs through hub_kernel-interface and
+wants an assistant to read or change that data on a person's behalf. Every call
+passes through the host's own sign-in first, then hub_kernel-interface's
+permission check and account scope, so a tool can do nothing the signed-in
+person could not already do. A boot check refuses to start a host whose served
+hubs cannot be turned into valid tool names.
+
+## Interface
+
+This local declares no entry points of its own.
+
+- Adding the gem to a host, mounting the endpoint, configuring which controller
+  and which person and account methods it uses, and running the boot check are
+  owned by the install local, `hub_kernel-mcp-install`.
+- The endpoint itself and the MCP requests it answers are owned by the develop
+  local, `hub_kernel-mcp-develop`.
+
+## How to use it
+
+- To put hub_kernel-mcp into a Rails app, or to fix a host whose boot check
+  fails, use `hub_kernel-mcp-install`.
+- To change what the endpoint answers, add support for another MCP request, or
+  change how tools are listed, called or refused, use `hub_kernel-mcp-develop`.
+- To decide which hubs are served at all, or to change permissions and account
+  scope, work in hub_kernel-interface, which owns the served list and those
+  checks.
+
+## Conventions
+
+- **Host** — the Rails app that mounts the endpoint and serves the hubs.
+- **Hub** — a hub_kernel object whose exposed methods are the units a caller may
+  call. hub_kernel-mcp defines no hubs.
+- **Served list and served name** — the host's one list of hubs in
+  hub_kernel-interface, where each hub is served under a name. A served name may
+  not hold two underscores in a row.
+- **Tool** — one exposed hub method, named `<served name>__<method>`, using only
+  letters, digits, underscores and hyphens, and at most 64 characters long. Its
+  input schema names the values the method takes.
+- **Reads and writes** — a tool for a method that writes is marked as not
+  read-only and described as changing data, so a client can ask before calling
+  it.
+- **Person and account** — who a request is made for and which account it is
+  scoped to, both supplied by methods on the host's own controller.
+- **Tool error and JSON-RPC error** — a hub's refusal, a missing or unlisted
+  value, or a record that does not exist comes back as a tool error carrying the
+  reason. A tool the caller may not call, or one that does not exist, comes back
+  as the same JSON-RPC error, `Unknown tool`, so a caller cannot tell the two
+  apart. An unexpected error is reported to the host's error reporting and its
+  message is never sent to the client.

data/the_local/agents/hub_kernel-mcp-install.md

@@ -0,0 +1,121 @@
+---
+name: hub_kernel-mcp-install
+description: Use to hook hub_kernel-mcp into a project — adding the gem, naming the controller the endpoint inherits from and the person and account methods on it, running the boot check after the served list is set, and mounting the engine.
+tools: Bash, Read, Edit
+scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools
+---
+
+This local follows these steps exactly and invents none. Where a step names a
+decision, it asks the developer and does not pick.
+
+## What hub_kernel-mcp is
+
+A Rails engine that serves every method the host's hubs expose as MCP tools at
+one JSON-RPC endpoint. Hook it in when the host already serves hubs through
+hub_kernel-interface and wants an MCP client to call them on a signed-in
+person's behalf.
+
+## Interface
+
+- `gem "hub_kernel-mcp"` — adds the gem to the host's `Gemfile`. It requires
+  Rails 8.1.3 or later and Ruby 3.2 or later, and brings in
+  `hub_kernel-interface` `~> 0.6`.
+- `mount HubKernel::Mcp::Engine` — mounts the endpoint in the host's
+  `config/routes.rb` at the path given. The path answers POST with JSON-RPC and
+  answers GET with status 405.
+- `HubKernel::Mcp.base_controller=` — the name, as a String, of the host
+  controller the endpoint inherits from. Its before-actions, including sign-in,
+  run before any hub is asked. Defaults to `"ActionController::API"`, which has
+  no sign-in.
+- `HubKernel::Mcp.person_method=` — the name, as a Symbol, of the method on the
+  base controller that returns the person a request is made for. No default.
+- `HubKernel::Mcp.account_method=` — the name, as a Symbol, of the method on the
+  base controller that returns the account a request is scoped to. No default.
+- `HubKernel::Mcp.check!` — the boot check. Raises
+  `HubKernel::Mcp::UnservableHubError` when any served hub cannot be served as
+  tools, and returns nothing otherwise.
+- `HubKernel::Mcp::UnservableHubError` — the error `check!` raises. Its message
+  names every problem found, one per line. It is the same class as
+  `HubKernel::Interface::UnservableHubError`, so rescuing either catches it.
+
+## How to use it
+
+1. Add the gem to the host's `Gemfile` and install it:
+
+   ```ruby
+   gem "hub_kernel-mcp"
+   ```
+
+   ```
+   bundle install
+   ```
+
+2. Ask the developer which host controller the endpoint should inherit from.
+   It must already sign the caller in and refuse a caller who is not signed in,
+   in a before-action, since the endpoint adds no sign-in of its own. It must
+   also accept a JSON POST with no CSRF token: an `ActionController::API`
+   subclass does, and an `ActionController::Base` subclass with forgery
+   protection refuses every request unless that protection is skipped for this
+   endpoint. Ask whether to use an existing controller or add a new one, and do
+   not choose the sign-in method yourself.
+
+3. Ask the developer which method on that controller returns the person a
+   request is made for, and which returns the account it is scoped to. Both are
+   called on the controller with no arguments, may be private, and must exist
+   on the base controller or a class it inherits from. If either is missing,
+   ask what it should return before adding it.
+
+4. Create `config/initializers/hub_kernel_mcp.rb` with the three answers:
+
+   ```ruby
+   HubKernel::Mcp.base_controller = "Api::HubBaseController"
+   HubKernel::Mcp.person_method = :current_person
+   HubKernel::Mcp.account_method = :current_account
+   ```
+
+   Set these in an initializer, not in `to_prepare`, so they are set before the
+   endpoint's controller loads. The controller name is a String. Leaving
+   `person_method` or `account_method` unset makes every `tools/list` and
+   `tools/call` request answer with JSON-RPC error -32603, `Internal error`.
+
+5. Find where the host sets its served list, `HubKernel::Interface.hubs = [...]`,
+   inside `Rails.application.config.to_prepare`. Add `HubKernel::Mcp.check!` on
+   the line after it, in the same block:
+
+   ```ruby
+   Rails.application.config.to_prepare do
+     HubKernel::Interface.hubs = [ Supplies, { "money" => Billing::Ledger } ]
+     HubKernel::Mcp.check!
+   end
+   ```
+
+   If the block already calls `HubKernel::Interface.check!`, keep or remove it
+   as the developer prefers, since `HubKernel::Mcp.check!` reports every problem
+   that check finds as well. If the host sets no served list yet, stop and tell
+   the developer that the hubs to serve are chosen in hub_kernel-interface
+   first, and do not invent the list.
+
+6. Ask the developer what path to mount the endpoint at, then add the mount to
+   `config/routes.rb`:
+
+   ```ruby
+   mount HubKernel::Mcp::Engine => "/mcp"
+   ```
+
+## Conventions
+
+- After installing, boot the app or run `bin/rails runner "HubKernel::Mcp.check!"`.
+  An `UnservableHubError` there lists every problem to fix, one per line: a
+  problem hub_kernel-interface's own check finds, a served name holding two
+  underscores in a row, a tool name holding a character other than a letter, a
+  digit, an underscore or a hyphen, or a tool name longer than 64 characters.
+  A tool name is `<served name>__<method>`.
+- Fix a check failure by changing the served name or the hub method in the host,
+  never by removing the check. Inside `to_prepare` the check runs again after
+  every code reload.
+- Run the check again whenever the served list changes or a hub gains a method.
+- A change to `config/initializers/hub_kernel_mcp.rb` takes effect only after
+  the app restarts.
+- Out of scope: choosing which hubs are served and setting permissions and
+  account scope, which belong to hub_kernel-interface, and changing what the
+  endpoint answers, which belongs to `hub_kernel-mcp-develop`.

data/the_local/interface.yml

@@ -0,0 +1,24 @@
+scope: hub MCP tools — serving the methods every hub a host serves, from hub_kernel-interface's one served list, as MCP tools at one JSON-RPC endpoint in a host Rails app, each call behind the host's own sign-in and hub_kernel-interface's permission check and account scope, with a boot check for hubs that cannot be served as tools
+
+install:
+  - gem "hub_kernel-mcp"
+  - mount HubKernel::Mcp::Engine
+  - HubKernel::Mcp.base_controller=
+  - HubKernel::Mcp.person_method=
+  - HubKernel::Mcp.account_method=
+  - HubKernel::Mcp.check!
+  - HubKernel::Mcp::UnservableHubError
+
+develop:
+  - POST /
+  - initialize
+  - ping
+  - tools/list
+  - tools/call
+
+sources:
+  - lib/hub_kernel/mcp.rb
+  - lib/hub_kernel/mcp/engine.rb
+  - config/routes.rb
+  - app/controllers/hub_kernel/mcp/messages_controller.rb
+  - README.md

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hub_kernel-mcp
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - tylercschneider
@@ -55,6 +55,10 @@ files:
 - lib/hub_kernel/mcp.rb
 - lib/hub_kernel/mcp/engine.rb
 - lib/hub_kernel/mcp/version.rb
+- the_local/agents/hub_kernel-mcp-develop.md
+- the_local/agents/hub_kernel-mcp-info.md
+- the_local/agents/hub_kernel-mcp-install.md
+- the_local/interface.yml
 homepage: https://github.com/DYB-Development/hub_kernel-mcp
 licenses:
 - MIT