@octanejs/mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+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

@@ -0,0 +1,129 @@
+# @octanejs/mcp-server
+
+MCP server for agents working with [Octane](https://github.com/octanejs/octane).
+
+It serves two audiences:
+
+- **Octane users** (any project): skills and tools for bridging React packages
+  to Octane, migrating React components to `.tsrx`, understanding Octane's
+  intentional divergences from React, and setting up SSR. These work anywhere;
+  the skills ship inside this package.
+- **Octane maintainers** (the octane monorepo): repo triage, validation
+  planning, benchmark and React-test-port automation. These tools register
+  only when the server detects an octane monorepo checkout at its root.
+
+## Install
+
+```bash
+npm install -g @octanejs/mcp-server
+```
+
+For local development inside the octane repository:
+
+```bash
+pnpm --filter @octanejs/mcp-server start
+```
+
+## MCP transport
+
+The server uses stdio transport.
+
+```json
+{
+  "mcpServers": {
+    "octane": {
+      "command": "octane-mcp-server"
+    }
+  }
+}
+```
+
+Set `OCTANE_REPO_ROOT` to point the server at an octane checkout (enables the
+maintainer tools):
+
+```json
+{
+  "mcpServers": {
+    "octane": {
+      "command": "octane-mcp-server",
+      "env": {
+        "OCTANE_REPO_ROOT": "/path/to/octane"
+      }
+    }
+  }
+}
+```
+
+## Tools (always available)
+
+### `octane_bridge_react_package`
+
+Scans a React package (by name from `node_modules`, or any source directory by
+path) for React API usage and returns an Octane compatibility report: which
+APIs map one-to-one, which need rewrites (`forwardRef`, `useDebugValue`,
+`lazy`, class components, synthetic `onChange`), whether a framework-agnostic
+core can be reused verbatim, whether an official `@octanejs/*` binding already
+exists, an overall verdict (`bridgeable`, `bridgeable-with-rewrites`,
+`needs-rework`), and a step-by-step plan.
+
+```json
+{ "package": "jotai", "projectRoot": "/path/to/my-app" }
+```
+
+### `octane_bindings`
+
+Returns the map of React packages with maintained `@octanejs/*` ports
+(zustand, query, motion, stylex, router, lexical, floating-ui, radix).
+
+### `octane_skill`
+
+Returns a skill by name. Bundled skills (shipped with this package):
+
+- `bridge-react-package` — the full workflow for porting a React library.
+- `migrate-react-component` — React JSX to `.tsrx` conversion reference.
+- `react-divergences` — Octane's intentional differences from React.
+- `setup-ssr` — server rendering and hydration setup.
+
+When running inside the octane monorepo, the maintainer skills from
+`.ai/skills` are also available: `react-library-port`, `bug-hunter`,
+`create-a-pr`, `handle-issue`, `octane-core-extend`, `triage`,
+`performance-audit`.
+
+## Tools (octane monorepo only)
+
+### `octane_project_map`
+
+Returns `.ai/project-map.md` with package layout, authoritative sources,
+invariants, and validation commands.
+
+### `octane_triage_paths`
+
+Classifies repository-relative paths by Octane area (compiler, core runtime,
+SSR, ecosystem binding, mcp-server, benchmark, docs, RuleSync source).
+
+### `octane_validate_plan`
+
+Recommends validation commands for changed paths and task kind.
+
+### `octane_scaffold_react_port`
+
+Runs `scripts/scaffold-react-port.mjs` for an upstream React test file and
+optionally writes the generated Vitest skeleton to an output file.
+
+### `octane_benchmark`
+
+Runs a known benchmark workspace (`news`, `js-framework`, `recursive-context`,
+`signal-favoring`, `dbmon`) or all benchmarks.
+
+### `octane_issue_context`
+
+Uses the GitHub CLI (`gh`) to fetch an issue and returns structured issue
+context plus lightweight triage hints. Requires `gh` installed and
+authenticated.
+
+## Development
+
+```bash
+pnpm --filter @octanejs/mcp-server test
+pnpm --filter @octanejs/mcp-server start
+```

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@octanejs/mcp-server",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "MCP server exposing Octane repository automation for coding agents.",
+  "license": "MIT",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/octane-mcp-server"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "skills",
+    "README.md"
+  ],
+  "bin": {
+    "octane-mcp-server": "src/index.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.21.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "cd ../.. && vitest run --project octane-mcp-server"
+  }
+}

package/skills/bridge-react-package.md

@@ -0,0 +1,117 @@
+# Skill: Bridge a React package to Octane
+
+Use this when a user wants a React ecosystem library to work in their Octane app.
+
+## Check for an official binding first
+
+These libraries already have maintained Octane ports. Install the binding instead
+of bridging by hand:
+
+| React package | Octane binding |
+| --- | --- |
+| `zustand` | `@octanejs/zustand` |
+| `@tanstack/react-query` | `@octanejs/query` |
+| `framer-motion` / `motion` | `@octanejs/motion` |
+| `@stylexjs/stylex` | `@octanejs/stylex` |
+| `react-router` / `react-router-dom` | `@octanejs/router` |
+| `@lexical/react` | `@octanejs/lexical` |
+| `@floating-ui/react` | `@octanejs/floating-ui` |
+| `radix-ui` | `@octanejs/radix` |
+
+For anything else, run the `octane_bridge_react_package` tool to get a scan of the
+package's React API usage and a tailored plan, then follow the workflow below.
+
+## Mental model
+
+Octane is a compiler framework, not a runtime VDOM. Two consequences drive
+everything:
+
+1. Compiled React JSX (`jsx()` / `createElement` trees) cannot render on Octane.
+   Components must be authored in `.tsrx` (or `.tsx` compiled by the Octane
+   compiler).
+2. Every Octane hook call is bound to a compiler-injected slot. A slotless
+   `useState(0)` coming from a React build throws immediately.
+
+So a bridge never means "run the React package unchanged". It means:
+
+- Reuse the package's framework-agnostic core verbatim (store, query client,
+  state machine, form engine). Code with zero `react` imports runs on Octane
+  as-is.
+- Re-implement the thin React binding layer (usually a handful of hooks) against
+  Octane's identically named hooks.
+- Re-author any shipped JSX components in `.tsrx`.
+
+## Workflow
+
+1. **Classify the library.** Find its vanilla core (`zustand/vanilla`,
+   `@tanstack/query-core`, `jotai/vanilla`, `xstate`, `@floating-ui/dom`, a
+   `*-core` dependency, or a pure internal module). Identify the React surface:
+   hooks, components, providers, portals, refs.
+
+2. **Map the React APIs.** Same-name and same-semantics in Octane: `useState`,
+   `useReducer`, `useEffect`, `useLayoutEffect`, `useInsertionEffect`, `useMemo`,
+   `useCallback`, `useRef`, `useContext`, `useId`, `useImperativeHandle`,
+   `useSyncExternalStore` (full React 19 shape, including `getServerSnapshot`),
+   `useTransition`, `useDeferredValue`, `useActionState`, `useOptimistic`,
+   `useEffectEvent`, `use`, `startTransition`, `memo`, `createContext`,
+   `Suspense`, `createPortal`, `flushSync`, `createRoot`, `hydrateRoot`.
+   Everything imports from `octane` (no separate `react-dom`).
+
+3. **Handle the gaps:**
+   - `forwardRef`: does not exist. Accept `ref` as a normal prop (React 19
+     style) and drop the wrapper.
+   - `useDebugValue`: shim as a no-op.
+   - `lazy`: use dynamic `import()` plus `use()` inside a `Suspense` boundary.
+   - Class components: rewrite as function components. Error boundary classes
+     become `<ErrorBoundary>` or the `@try { } @catch (e) { }` directive.
+   - Synthetic `onChange` on text inputs: use native `onInput`. Octane events
+     are native and delegated.
+   - Controlled inputs: Octane inputs are uncontrolled and native; `value` and
+     `checked` are plain attributes. Port controlled-input logic to
+     read-from-DOM plus explicit writes, or keep state in the store and write
+     the attribute on change.
+   - StrictMode double-invoke: does not exist; delete test expectations that
+     count double renders.
+
+4. **Custom hooks in plain `.ts` files.** Octane's compiler auto-slots hook
+   calls in files it compiles. A binding published as plain `.ts` that calls
+   hooks internally must forward the caller's slot: accept a trailing `slot`
+   argument and derive stable child slots per call site. The convention used by
+   the official bindings:
+
+   ```ts
+   import { useMemo, useRef } from 'octane';
+
+   export function subSlot(slot: symbol | undefined, tag: string) {
+   	return slot !== undefined ? Symbol.for((slot.description ?? '') + ':' + tag) : undefined;
+   }
+
+   export function useControllableState(opts, slot?: symbol) {
+   	const valueRef = useRef(opts.defaultValue, subSlot(slot, 'value'));
+   	return useMemo(() => build(valueRef), [opts.value], subSlot(slot, 'memo'));
+   }
+   ```
+
+   Callers compiled from `.tsrx`/`.tsx` pass their injected slot automatically as
+   the trailing argument when the hook file itself is excluded from the compiler's
+   auto-slotting pass. The simpler alternative: keep the binding in compiled
+   files so slots are injected for you.
+
+5. **Re-author shipped components in `.tsrx`.** `props.children` works, refs are
+   props, lists use `@for (const x of xs; key x.id) { }`, conditionals use
+   `@if`, dynamic text holes use `{expr as string}` unless the expression is
+   provably a string.
+
+6. **Validate.** Drive real DOM events against the bridged binding and, where
+   possible, run the same fixture against the React original and compare
+   rendered HTML after each step. Also test what HTML comparison cannot see:
+   render counts, subscription add/remove, effect ordering, ref lifecycle.
+
+## Verdict guide for the scan tool
+
+- `bridgeable`: only same-name hooks used; a mechanical rename of imports to
+  `octane` plus a `.tsrx` re-author of components is enough.
+- `bridgeable-with-rewrites`: needs the `forwardRef` / `useDebugValue` / `lazy` /
+  event rewrites above, but no architectural blockers.
+- `needs-rework`: class components, `renderToPipeableStream`, `findDOMNode`, or
+  React internals. Bridge the core, redesign the binding.

package/skills/migrate-react-component.md

@@ -0,0 +1,98 @@
+# Skill: Migrate a React component to Octane
+
+Use this when converting React component source (JSX/TSX) into an Octane `.tsrx`
+component.
+
+## Imports
+
+Everything comes from `octane`. Replace `react`, `react-dom`, and
+`react-dom/client` imports:
+
+```ts
+import { useState, useEffect, createPortal, createRoot, hydrateRoot } from 'octane';
+```
+
+## Component shape
+
+Any function used at a `<Foo/>` site is a component. Two equivalent forms:
+
+```tsx
+export function Counter() @{
+	const [count, setCount] = useState(0);
+	<button onClick={() => setCount(count + 1)}>{'Count: ' + count}</button>
+}
+
+export function Counter() {
+	const [count, setCount] = useState(0);
+	return <button onClick={() => setCount(count + 1)}>{'Count: ' + count}</button>;
+}
+```
+
+The `@{ ... }` body must end with exactly one output node. Setup code (hooks,
+locals, early returns) stays above it.
+
+## Conversion table
+
+| React pattern | Octane pattern |
+| --- | --- |
+| `items.map(x => <li key={x.id}>...` | `@for (const x of items; key x.id) { <li>... }` with optional `@empty { }` |
+| `cond ? <A/> : <B/>` in JSX | `@if (cond) { <A/> } @else { <B/> }` |
+| `{cond && <A/>}` | `@if (cond) { <A/> }` |
+| switch on a value | `@switch (v) { @case (a) { } @default { } }` |
+| `<Suspense fallback={...}>` | `<Suspense>` or `@try { } @pending { }` |
+| Error boundary class | `<ErrorBoundary>` or `@try { } @catch (e) { }` |
+| `forwardRef((props, ref) => ...)` | plain function; `ref` arrives as a prop |
+| `<input onChange={...}>` | `<input onInput={...}>` (native event) |
+| controlled `value={state}` | uncontrolled; `value` is a plain attribute, read the DOM in handlers |
+| `className={clsx(...)}` | `class={[...]}` composes clsx-style natively |
+| `useDebugValue(x)` | delete it |
+| `React.lazy(() => import(...))` | dynamic `import()` + `use()` under Suspense |
+| `defaultProps` | parameter defaults / destructuring defaults |
+
+## Text holes
+
+A dynamic text hole needs `{expr as string}` unless the compiler can prove the
+expression is a string (string literal, template literal, `+` concatenation with
+a string, or a tracked local). A bare `{expr}` that is not provably a string is
+treated as a renderable (component, element, coerced primitive).
+
+```tsx
+<p>{'Elapsed: ' + seconds}</p>
+<p>{seconds as string}</p>
+```
+
+## Hooks
+
+The hook API matches React, and there are no rules of hooks: a hook may sit
+behind a condition, after an early return, or in a loop, because identity comes
+from the call site, not call order.
+
+```tsx
+export function Panel(props) @{
+	const [n, setN] = useState(0);
+	if (props.hidden) return;
+	useEffect(() => log(n), [n]);
+	<button onClick={() => setN(n + 1)}>{'count: ' + n}</button>
+}
+```
+
+## What does not port
+
+- Class components (rewrite as functions).
+- StrictMode double-invoke expectations (there is no double render; delete
+  render-count workarounds).
+- Server Components / `'use client'` directives.
+- Synthetic event pooling or `e.persist()` (events are native).
+- `React.Children` traversal over arbitrary VDOM (children are descriptors, not
+  a VDOM tree; prefer explicit props over children introspection).
+
+## Events
+
+Events are native, delegated DOM events. `onClick`, `onInput`, `onSubmit`,
+`onKeyDown` behave exactly like the platform. `onChange` on a text input fires
+on commit (native change), not per keystroke.
+
+## Refs
+
+React 19 style. `ref={cb}` with optional cleanup return, `ref={refObject}`, or
+an array `ref={[a, b]}` to compose. No `forwardRef` anywhere.

package/skills/react-divergences.md

@@ -0,0 +1,50 @@
+# Skill: Octane's intentional divergences from React
+
+Use this when behavior differs from React and you need to decide whether it is a
+bug or by design. Do not "fix" these toward React.
+
+## No rules of hooks
+
+Hooks are tracked by compiler-assigned call-site slot, not call order. A hook may
+sit behind a condition, after an early return, or in a loop. Code that relies on
+hook-order errors firing does not apply.
+
+## No controlled components, no synthetic onChange
+
+`value` and `checked` are plain attributes; inputs are uncontrolled and native.
+There is no per-keystroke synthetic `onChange`; use native `onInput`. React's
+controlled-input value-reassertion model does not exist and must not be added.
+
+## Native delegated events
+
+`onClick`, `onInput`, `onSubmit` etc. are real DOM events via delegation, not a
+synthetic layer. Timing, bubbling, and `event.target` semantics match the
+platform, not React's wrapper.
+
+## Keyed reconciler moves differ
+
+Reconciliation is LIS-based (minimal DOM moves), not React's `lastPlacedIndex`.
+The final DOM and survivor node identity are guaranteed identical to React; the
+set of physically moved nodes is not. Tests asserting which nodes moved will
+diverge; tests asserting final order and identity will pass.
+
+## class / className composes clsx-style
+
+Strings, numbers, arrays, objects, and nesting compose into a class string;
+falsy parts drop out. React coerces an array to `"a,b"`; Octane yields `"a b"`.
+
+## Not present at all
+
+- Class components.
+- Server Components / `'use client'` / `'use server'`.
+- StrictMode double-invoke (renders and effects run once).
+- `forwardRef` (refs are props, React 19 style).
+- `useDebugValue` (shim as no-op).
+- SuspenseList, Profiler, findDOMNode.
+
+## Everything else matches
+
+Observable hook, effect, Suspense, and transition semantics match React,
+including effect ordering (child-first on mount, parent-first cleanup on
+deletion), `Object.is` state bailouts, batching, and `useId` stability across
+server render and hydration.

package/skills/setup-ssr.md

@@ -0,0 +1,73 @@
+# Skill: Set up Octane SSR and hydration
+
+Use this when adding server-side rendering to an Octane app.
+
+## The API
+
+The entry points mirror React: `octane/server` (`react-dom/server`) has
+`renderToString` (sync) and `renderToStaticMarkup`; `octane/static`
+(`react-dom/static`) has `prerender` (async, awaits Suspense data). All return
+`{ html, css }`.
+
+```ts
+import { prerender } from 'octane/static';
+
+const { html, css } = await prerender(App, props, {
+	signal: request.signal,
+	nonce: cspNonce,
+	timeoutMs: 5000,
+});
+```
+
+- `html`: rendered markup with hydration markers, plus an inline suspense seed
+  script when anything resolved. Hoisted `<title>/<meta>/<link>` fold in
+  (spliced into `<head>` if present, else prepended).
+- `css`: deduped `<style data-octane>` tags from scoped styles; place inside
+  `<head>`.
+- Use `renderToString` (from `octane/server`) for a single synchronous pass that
+  leaves `@pending` fallbacks in place; use `prerender` to await the data.
+- Options are optional: `nonce` stamps CSP nonces on the emitted inline tags (all
+  renderers); `signal` aborts a suspended render with the request and `timeoutMs`
+  bounds how long a `use(thenable)` may take to settle (async `prerender`; global
+  default via `setSsrSuspenseTimeout`); `onError` observes render errors.
+
+On the client:
+
+```ts
+import { hydrateRoot } from 'octane';
+hydrateRoot(document.getElementById('app')!, App, props);
+```
+
+Pass the same component and props on both sides. `useId` and scoped styles are
+hydration-stable; the client adopts server DOM instead of rebuilding it.
+
+## Two integration paths
+
+1. **Vite plugin (dev SSR + routing)**: `@octanejs/vite-plugin` matches routes
+   from `octane.config.ts`, renders pages into `index.html` at
+   `<!--ssr-head-->` / `<!--ssr-body-->`, and wires hydration automatically.
+   Production server output is not generated yet; for production SSR today use
+   path 2.
+2. **Custom server**: write `entry-server.ts` exporting a function that calls
+   `prerender()` (or `renderToString()`) and splices the result into your HTML template, and
+   `entry-client.ts` calling `hydrateRoot`. Serialize app data (for example a
+   dehydrated query-client cache) into your own inline JSON script and read it
+   before hydrating.
+
+## Data and Suspense on the server
+
+`use(promise)` suspends a pass; `prerender()` awaits it and re-renders, so
+`@try { } @pending { }` boundaries resolve to their success arm in the emitted
+HTML. Resolved values serialize into the seed script and hydration consumes
+them without re-fetching. For query-style data, prefetch into a cache before
+rendering and dehydrate it yourself.
+
+## Constraints to remember
+
+- Effects never run on the server; state hooks return initial values;
+  `useSyncExternalStore` uses `getServerSnapshot`.
+- Server components must be compiled by the Octane compiler in server mode;
+  you cannot feed client-compiled output to the renderers.
+- Output is buffered, not streamed: send it as one response.
+- Render errors reject the promise unless an `ErrorBoundary`/`@catch` inside
+  the tree handles them; map rejections to HTTP status codes in your server.