@bezda/rhp-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Anas Bouzid
+
+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.

package/README.md

@@ -1,3 +1,223 @@
-# Temporary Holding Version
+# @bezda/rhp-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Make charts with [rhp](https://rhp.vercel.app) from any AI agent.
+rhp 2 came out in September 2026, after the training data of today's models, so an agent knows nothing about it until it reads rhp's guide.
+This package carries that guide (the workflow, the references and the tested recipes) and a checker that renders the agent's chart in a browser and reports what is wrong, with a fix for each problem and screenshots to look at.
+
+## Start here: the rhp skill
+
+In a coding agent (Claude Code, Cursor, Copilot, Codex, Gemini CLI and others), run this in your project:
+
+```sh
+npx skills add bezda-team/rhp
+```
+
+Then ask for a chart.
+The skill teaches the agent rhp and runs this package's checker by itself with `npx`, so you install nothing else.
+
+## The checker on the command line
+
+```sh
+npx -y @bezda/rhp-mcp check chart.html
+```
+
+It renders the chart at 1280px and 390px wide, tries its interactions, and prints what is wrong, each problem with what to change, then where it saved the screenshots.
+The exit code is 1 when the chart has errors.
+It checks an `.html` page, a Solid or React `.jsx` or `.tsx` component, or a `.js` module that uses `@bezda/rhp/standalone`.
+
+| Option | What it does |
+|---|---|
+| `--widths 1280,390` | The page widths to check; the interactions are tried at the first, and slats are tapped at phone widths (600px or less). |
+| `--dark` | Renders with a dark color scheme. |
+| `--no-interact` | Skips the interactions. |
+| `--settle-timeout <ms>` | How long the page may take to come to rest before it is measured, 100 to 30000 ms (10000 by default); raise it on a slow machine. |
+| `--format <format>` | `html`, `solid`, `react` or `module`, when the file's extension and code leave it unclear. |
+| `--json` | Prints the whole result as JSON. |
+| `--out <dir>` | Where the screenshots go (a folder in the system's temp folder by default). |
+
+`npx -y @bezda/rhp-mcp guide` prints the guide, for an agent that can run commands but has no skill installed.
+
+## The MCP server
+
+The server gives an agent the same guide, references, recipes and checker as four tools, and returns the checker's screenshots as images the agent sees.
+Use it in a client that has no shell (Claude Desktop), or when you would rather give the agent tools than a skill.
+The server alone is enough: its instructions tell the agent to read the guide before it writes any rhp code.
+
+Every client starts it with `npx -y @bezda/rhp-mcp`, which needs Node.js 20 or later.
+The first start downloads the package and its dependencies (about 80 MB).
+If your client gives up before the server is ready, run `npx -y @bezda/rhp-mcp --version` once in a terminal and restart the client.
+
+### Claude Code
+
+```sh
+claude mcp add rhp -- npx -y @bezda/rhp-mcp
+```
+
+Add `-s user` to have it in every project, or `-s project` to write it to the project's `.mcp.json` for everyone who works on it.
+
+Or install the Claude Code plugin, which carries the skill and this server together:
+
+```sh
+claude plugin marketplace add bezda-team/rhp
+claude plugin install rhp@rhp
+```
+
+The plugin's skill needs Claude Code 2.1.160 or later (2.1.141 loads only the server).
+
+### Claude Desktop
+
+Open Settings > Developer > Edit Config, and add the server to `claude_desktop_config.json` (in `~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows):
+
+```json
+{
+  "mcpServers": {
+    "rhp": { "command": "npx", "args": ["-y", "@bezda/rhp-mcp"] }
+  }
+}
+```
+
+### Cursor
+
+Open this link in a browser to install it in one click (Cursor's documented install link):
+
+```
+cursor://anysphere.cursor-deeplink/mcp/install?name=rhp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBiZXpkYS9yaHAtbWNwIl19
+```
+
+Or add the `mcpServers` entry shown for Claude Desktop to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project).
+
+### VS Code (GitHub Copilot)
+
+```sh
+code --add-mcp "{\"name\":\"rhp\",\"command\":\"npx\",\"args\":[\"-y\",\"@bezda/rhp-mcp\"]}"
+```
+
+Or add the `mcpServers` entry shown for Claude Desktop to `.mcp.json` at the workspace's root, or to `~/.copilot/mcp-config.json` for every workspace.
+The older `.vscode/mcp.json` takes the same entry under `servers`.
+
+### Windsurf (Devin Desktop)
+
+With the Devin CLI or the Devin Local agent:
+
+```sh
+devin mcp add -s user rhp -- npx -y @bezda/rhp-mcp
+```
+
+For the Cascade agent, add the `mcpServers` entry shown for Claude Desktop to `~/.config/devin/mcp_config.json` (`%APPDATA%\devin\mcp_config.json` on Windows).
+
+### Copilot CLI
+
+Type `/mcp add` in a session, or add the `mcpServers` entry shown for Claude Desktop to `~/.copilot/mcp-config.json`.
+
+### Zed
+
+Add the server to Zed's settings file (the command **zed: open settings file** opens it):
+
+```json
+{
+  "context_servers": {
+    "rhp": { "command": "npx", "args": ["-y", "@bezda/rhp-mcp"], "env": {} }
+  }
+}
+```
+
+### Codex
+
+```sh
+codex mcp add rhp -- npx -y @bezda/rhp-mcp
+```
+
+It writes this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.rhp]
+command = "npx"
+args = ["-y", "@bezda/rhp-mcp"]
+```
+
+### Gemini CLI
+
+```sh
+gemini mcp add --scope user rhp npx -- -y @bezda/rhp-mcp
+```
+
+Without `--scope user` it goes to the project's `.gemini/settings.json`.
+
+### The tools
+
+| Tool | What it returns |
+|---|---|
+| `rhp_guide` | The workflow from a request to a checked chart, the rules that prevent most bugs, and the names of the references and recipes. The agent calls it first. |
+| `rhp_reference` | One reference by `name`: `api`, `design`, `environments`, `forms`, `interaction`, `looks` or `pitfalls`. A long one comes back as its list of sections, and `section` (a number or a title) returns one of them. |
+| `rhp_recipe` | With no `type`, the list of recipes with what each is for; with a `type` such as `bar`, that recipe's whole HTML file, a tested chart page to start from. |
+| `rhp_check` | Renders the chart at `file` (an absolute path) or the `code` given, and returns the report (errors and warnings, each with a fix, and the interactions it tried) and the screenshots as images. Options: `format`, `widths` (`[1280, 390]` by default, up to six), `dark`, `interact`, `settleTimeout`. |
+
+`rhp_check` takes absolute paths only: some clients (Codex) start the server in its own folder, where a relative path would point at the wrong file.
+The server also has one prompt, `chart`, which clients show as a slash command: it asks for a chart and tells the agent to follow `rhp_guide` and to check with `rhp_check` until the report is clean.
+
+## The browser
+
+The checker renders charts in the first browser it finds:
+
+1. the executable in the `RHP_CHECK_BROWSER` environment variable;
+2. Playwright's Chromium (its headless shell first);
+3. Google Chrome;
+4. Microsoft Edge.
+
+With none of them, the check still reports what it can find without a browser, and says to run:
+
+```sh
+npx -y @bezda/rhp-mcp install-browser
+```
+
+It downloads Chromium's headless shell into Playwright's usual folder and leaves the other browsers there alone.
+Other options go to Playwright's installer: on Linux, `install-browser --with-deps` also installs the system libraries the browser needs.
+
+## Nothing leaves your machine
+
+The checker renders your chart in a browser on your machine, and your chart's code and screenshots stay there.
+It answers the page's requests for `@bezda/rhp` from the copy of rhp it ships with.
+The only other requests are the ones your chart's page makes itself, such as its Google Fonts, and each gets 5 seconds before the check goes on without it.
+There is no telemetry.
+
+## For maintainers
+
+```
+bin/rhp-mcp.js     the command: no arguments starts the server
+src/server.js      the MCP server: four tools, one prompt, one browser shared by every check
+src/skill.js       reads the skill: SKILL.md, the references (whole or by section) and the recipes
+src/check/         the checker (its README lists every finding and how each is tested)
+src/guard/         the wrapper around rhp that checks how a chart uses it, in the page
+scripts/build.js   copies ../skills/rhp into skill/ and rhp's LICENSE into this folder (npm pack runs it first)
+test/mcp.js        the build, the package, the Claude Code plugin's manifests, and the server through the SDK's client
+test/run.js        the checker
+```
+
+**Tests.**
+`npm test` runs `test/mcp.js`, then `test/run.js`.
+
+**The skill.**
+It lives in `skills/rhp/` at the repository's root.
+Inside the repository the server reads it there, so it is never stale; the published package reads its copy in `skill/`.
+
+**No `structuredContent`.**
+Claude Code shows the model a tool's `structuredContent` in place of its text, and Codex in place of all of its content, images included.
+The report or the screenshots would then never reach the agent, so `rhp_check` returns them as content only.
+
+**Publishing.**
+`@bezda/rhp` is `file:..` here, so that the tests check charts against this repository's build; an install from npm cannot resolve it.
+Publish this package after every rhp release, with the range set to that release and a new version of its own.
+The checker carries its own copy of rhp, and a page loads the latest rhp 2 from jsDelivr, so this keeps the two the same rhp; a new version also makes `npx` fetch the new pair:
+
+```sh
+npm pkg set dependencies.@bezda/rhp=^2.0.1   # the rhp version just published
+npm version patch --no-git-tag-version
+npm publish
+git checkout package.json
+```
+
+`npm publish` runs the build first, and `publishConfig` makes the package public.
+
+**The MCP SDK.**
+The server uses `@modelcontextprotocol/sdk` 1.x (the v1 line), because clients speak v1 today; v1 gets fixes for at least six months after v2's release in July 2026.
+Moving to v2 means importing `McpServer` from `@modelcontextprotocol/server`, giving each tool's `inputSchema` as `z.object({ ... })`, and starting the server with `serveStdio` from `@modelcontextprotocol/server/stdio`.

package/bin/rhp-mcp.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// rhp-mcp: the MCP server (no arguments), or a command (rhp-mcp --help lists them).
+import { fileURLToPath } from "url";
+import path from "path";
+import fs from "fs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const [command, ...args] = process.argv.slice(2);
+
+const USAGE = `rhp-mcp: make charts with rhp from an AI agent.
+
+  rhp-mcp                     the MCP server, over stdio
+  rhp-mcp check <file>        render a chart and report what is wrong with it (exit code 1 when it has errors)
+      --widths 1280,390       page widths to check (the interaction pass runs at the first)
+      --dark                  emulate a dark color scheme
+      --no-interact           skip the interaction pass
+      --settle-timeout <ms>   readiness wait budget, 100 to 30000 ms (default 10000)
+      --format <format>       html, solid, react or module (found from the file when left out)
+      --json                  print the whole result as JSON
+      --out <dir>             where the screenshots go (left out: a folder in the system's temp dir, so nothing is
+                              written next to the chart; the report gives each screenshot's path)
+  rhp-mcp guide               print the rhp skill's guide (SKILL.md), for an agent with no skill installed
+  rhp-mcp install-browser     download Chromium's headless shell for checking (when no Chrome, Edge or Chromium is found)
+  rhp-mcp --version           print this package's version
+`;
+
+const FLAGS = ["--dark", "--no-interact", "--json"];
+const VALUES = ["--widths", "--format", "--out", "--settle-timeout"];
+const FORMATS = ["html", "solid", "react", "module"];
+
+function usageError(message) {
+
+  process.stderr.write(`rhp-mcp: ${message}\n\n${USAGE}`);
+
+  return 2;
+}
+
+async function runCheck(argv) {
+
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const files = [];
+  const value = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (VALUES.includes(arg)) {
+      if (argv[i + 1] === undefined || argv[i + 1].startsWith("--")) return usageError(`${arg} needs a value`);
+      value[arg] = argv[++i];
+    } else if (arg.startsWith("-") && !FLAGS.includes(arg)) {
+      return usageError(`check has no option ${arg}`);
+    } else if (!arg.startsWith("-")) {
+      files.push(arg);
+    }
+  }
+
+  const widths = value["--widths"]?.split(",").map(Number);
+  const settleTimeout = value["--settle-timeout"] === undefined ? undefined : Number(value["--settle-timeout"]);
+  if (files.length !== 1) return usageError(files.length ? `check takes one file, not ${files.length}` : "check needs the chart's file");
+  if (widths && !widths.every((w) => Number.isInteger(w) && w >= 200 && w <= 2560)) return usageError("--widths takes page widths in px from 200 to 2560, for example 1280,390");
+  if (value["--format"] && !FORMATS.includes(value["--format"])) return usageError(`--format is one of ${FORMATS.join(", ")}`);
+  if (settleTimeout !== undefined && (!Number.isInteger(settleTimeout) || settleTimeout < 100 || settleTimeout > 30000)) return usageError("--settle-timeout takes milliseconds from 100 to 30000");
+
+  const { check } = await import("../src/check/index.js");
+  const result = await check({
+    file: files[0],
+    format: value["--format"],
+    widths,
+    dark: argv.includes("--dark"),
+    interact: !argv.includes("--no-interact"),
+    settleTimeout,
+    outDir: value["--out"],
+  });
+
+  process.stdout.write(argv.includes("--json") ? JSON.stringify(result, null, 2) + "\n" : result.text);
+
+  return result.ok ? 0 : 1;
+}
+
+// SKILL.md's body, after a line that says where the files it links are
+async function printGuide() {
+
+  const { SKILL_DIR, skillBody } = await import("../src/skill.js");
+  process.stdout.write(`The references/ and recipes/ this guide links are in ${SKILL_DIR}\n\n${skillBody()}`);
+
+  return 0;
+}
+
+// Playwright's Chromium headless shell, for the version of playwright-core this package uses (other browsers are kept)
+async function installBrowser(argv) {
+
+  const { spawnSync } = await import("child_process");
+  const { createRequire } = await import("module");
+  const cli = path.join(path.dirname(createRequire(import.meta.url).resolve("playwright-core/package.json")), "cli.js");
+  const r = spawnSync(process.execPath, [cli, "install", "--only-shell", "--no-remove", ...argv, "chromium"], { stdio: "inherit" });
+
+  return r.status ?? 1;
+}
+
+async function main() {
+
+  if (command === undefined) {
+    await import("../src/server.js");
+    return null;
+  }
+  if (command === "check") return runCheck(args);
+  if (command === "guide") return printGuide();
+  if (command === "install-browser") return installBrowser(args);
+  if (command === "--version" || command === "-v") {
+    process.stdout.write(JSON.parse(fs.readFileSync(path.join(here, "../package.json"), "utf8")).version + "\n");
+    return 0;
+  }
+  if (command === "--help" || command === "-h" || command === "help") {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  return usageError(`no command "${command}"`);
+}
+
+main().then((code) => {
+  if (code != null) process.exitCode = code;
+}, (e) => {
+  process.stderr.write(`rhp-mcp: ${e.stack ?? e}\n`);
+  process.exitCode = 2;
+});

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@bezda/rhp-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Make charts with rhp from any AI agent: an MCP server with rhp's guide, references and recipes, and a checker that renders a chart in a browser and reports what is wrong, with screenshots",
+  "keywords": [
+    "rhp",
+    "charts",
+    "data-visualization",
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "ai",
+    "agent",
+    "solidjs",
+    "checker"
+  ],
+  "author": {
+    "name": "Bouzid Anas",
+    "email": "anas.bouzid@bezda.net"
+  },
+  "license": "MIT",
+  "homepage": "https://rhp.vercel.app/ai/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bezda-team/rhp.git",
+    "directory": "mcp"
+  },
+  "type": "module",
+  "bin": {
+    "rhp-mcp": "bin/rhp-mcp.js"
+  },
+  "exports": {
+    ".": "./src/check/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "prepack": "npm run build",
+    "test": "node test/settle-regression.js && node test/mcp.js && node test/run.js"
+  },
+  "dependencies": {
+    "@babel/core": "^7.29.7",
+    "@bezda/rhp": "^2.0.3",
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "babel-preset-solid": "^1.9.15",
+    "esbuild": "^0.28.2",
+    "playwright-core": "^1.63.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "solid-js": "^1.9.15",
+    "zod": "^4.6.5"
+  }
+}