@octanejs/mcp-server 0.2.0

package/src/index.js

@@ -0,0 +1,428 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { bridgeReport, KNOWN_BINDINGS } from './bridge.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const PACKAGE_ROOT = resolve(dirname(__filename), '..');
+
+// Bundled skills ship with the npm package and work in ANY project using
+// octane. Repo skills live in the octane monorepo's .ai/skills and are only
+// available when the server runs against a checkout (they cover maintainer
+// workflows: triage, PRs, core changes).
+export const BUNDLED_SKILLS = {
+	'bridge-react-package': 'skills/bridge-react-package.md',
+	'migrate-react-component': 'skills/migrate-react-component.md',
+	'react-divergences': 'skills/react-divergences.md',
+	'setup-ssr': 'skills/setup-ssr.md',
+};
+
+export const REPO_SKILLS = {
+	'bug-hunter': '.ai/skills/bug-hunter.md',
+	'create-a-pr': '.ai/skills/create-a-pr.md',
+	'handle-issue': '.ai/skills/handle-issue.md',
+	'octane-core-extend': '.ai/skills/octane-core-extend.md',
+	'performance-audit': '.ai/skills/performance-audit.md',
+	'react-library-port': '.ai/skills/react-library-port.md',
+	triage: '.ai/skills/triage.md',
+};
+
+const BENCHMARKS = {
+	dbmon: '@benchmarks/dbmon',
+	'js-framework': 'octane-js-framework-benchmarks',
+	news: '@benchmarks/news',
+	'recursive-context': '@benchmarks/recursive-context',
+	'signal-favoring': '@benchmarks/signal-favoring',
+};
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export function text(content) {
+	return { content: [{ type: 'text', text: content }] };
+}
+
+export function isOctaneRepo(root) {
+	return existsSync(resolve(root, 'packages/octane/src/runtime.ts'));
+}
+
+export function areaForPath(path) {
+	if (path.startsWith('packages/octane/src/compiler/')) return 'compiler';
+	if (path.startsWith('packages/octane/src/server/') || path.includes('runtime.server'))
+		return 'ssr';
+	if (path.startsWith('packages/octane/src/runtime') || path === 'packages/octane/src/index.ts') {
+		return 'core-runtime';
+	}
+	if (path.startsWith('packages/octane/tests/')) return 'core-tests';
+	if (path.startsWith('packages/vite-plugin-octane/')) return 'vite-plugin';
+	if (path.startsWith('packages/octane-mcp-server/')) return 'mcp-server';
+	if (/^packages\/(zustand|query|motion|stylex|router|lexical|floating-ui|radix)\//.test(path)) {
+		return 'ecosystem-binding';
+	}
+	if (path.startsWith('benchmarks/')) return 'benchmark';
+	if (path.startsWith('.rulesync/')) return 'rulesync-source';
+	if (path.startsWith('.ai/') || path.startsWith('.codex/') || path.startsWith('.claude/')) {
+		return 'agent-instructions';
+	}
+	if (path.startsWith('docs/') || path.endsWith('.md')) return 'docs';
+	return 'repo-tooling';
+}
+
+export function validationFor(paths, taskKind) {
+	const areas = new Set(paths.map(areaForPath));
+	const commands = new Set();
+
+	if (areas.has('rulesync-source')) commands.add('pnpm rules:generate');
+	if (
+		areas.has('core-runtime') ||
+		areas.has('compiler') ||
+		areas.has('ssr') ||
+		areas.has('core-tests')
+	) {
+		commands.add('./node_modules/.bin/vitest run packages/octane/tests --project octane');
+	}
+	if (areas.has('ecosystem-binding')) {
+		for (const path of paths) {
+			const match = path.match(
+				/^packages\/(zustand|query|motion|stylex|router|lexical|floating-ui|radix)\//,
+			);
+			if (match)
+				commands.add(
+					`./node_modules/.bin/vitest run packages/${match[1]}/tests --project ${match[1]}`,
+				);
+		}
+	}
+	if (areas.has('mcp-server')) {
+		commands.add(
+			'./node_modules/.bin/vitest run packages/octane-mcp-server --project octane-mcp-server',
+		);
+	}
+	if (areas.has('vite-plugin')) commands.add('pnpm typecheck');
+	if (areas.has('benchmark') || taskKind === 'performance') commands.add('pnpm bench');
+	if (taskKind === 'api' || taskKind === 'core' || taskKind === 'package')
+		commands.add('pnpm typecheck');
+	commands.add('pnpm format:check');
+
+	return [...commands];
+}
+
+export function runCommand(command, args, options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+	return new Promise((resolvePromise) => {
+		const child = spawn(command, args, {
+			cwd,
+			env: { ...process.env, ...options.env },
+			stdio: ['ignore', 'pipe', 'pipe'],
+		});
+		let stdout = '';
+		let stderr = '';
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			child.kill('SIGTERM');
+			resolvePromise({
+				code: null,
+				signal: 'SIGTERM',
+				stdout,
+				stderr: `${stderr}\nCommand timed out after ${timeoutMs}ms`,
+			});
+		}, timeoutMs);
+
+		child.stdout.on('data', (chunk) => {
+			stdout += chunk;
+		});
+		child.stderr.on('data', (chunk) => {
+			stderr += chunk;
+		});
+		child.on('error', (error) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolvePromise({ code: null, signal: null, stdout, stderr: `${stderr}\n${error.message}` });
+		});
+		child.on('close', (code, signal) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			resolvePromise({ code, signal, stdout, stderr });
+		});
+	});
+}
+
+function commandResult(result) {
+	return text(JSON.stringify(result, null, 2));
+}
+
+export async function scaffoldReactPort(repoRoot, input) {
+	const args = ['scripts/scaffold-react-port.mjs', input.reactTestFile];
+	if (input.outFile) args.push('--out', input.outFile);
+	const result = await runCommand(process.execPath, args, {
+		cwd: repoRoot,
+		timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+	});
+	return { command: [process.execPath, ...args], ...result };
+}
+
+export async function runBenchmark(repoRoot, input) {
+	const args =
+		input.benchmark === 'all'
+			? ['bench']
+			: ['--filter', BENCHMARKS[input.benchmark], 'run', 'bench'];
+	const result = await runCommand('pnpm', args, {
+		cwd: repoRoot,
+		timeoutMs: input.timeoutMs ?? 300_000,
+	});
+	return { command: ['pnpm', ...args], benchmark: input.benchmark, ...result };
+}
+
+export async function issueContext(repoRoot, input) {
+	const fields =
+		'number,title,body,author,labels,state,comments,assignees,milestone,url,createdAt,updatedAt';
+	const result = await runCommand('gh', ['issue', 'view', String(input.issue), '--json', fields], {
+		cwd: repoRoot,
+		timeoutMs: input.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+	});
+	if (result.code !== 0)
+		return { command: ['gh', 'issue', 'view', String(input.issue), '--json', fields], ...result };
+
+	let issue;
+	try {
+		issue = JSON.parse(result.stdout);
+	} catch (error) {
+		return {
+			command: ['gh', 'issue', 'view', String(input.issue), '--json', fields],
+			parseError: error.message,
+			...result,
+		};
+	}
+
+	const body = `${issue.title}\n${issue.body ?? ''}`.toLowerCase();
+	const labels = issue.labels?.map((label) => label.name) ?? [];
+	const suggestedArea =
+		body.includes('compiler') || body.includes('tsrx')
+			? 'compiler'
+			: body.includes('hydration')
+				? 'hydration'
+				: body.includes('ssr')
+					? 'ssr'
+					: body.includes('performance') || body.includes('perf')
+						? 'performance'
+						: 'triage-needed';
+	return {
+		command: ['gh', 'issue', 'view', String(issue.number ?? input.issue), '--json', fields],
+		issue,
+		triage: {
+			suggestedArea,
+			labels,
+			state: issue.state,
+			url: issue.url,
+		},
+	};
+}
+
+function registerUserTools(server, repoRoot, repoMode) {
+	const skills = repoMode ? { ...BUNDLED_SKILLS, ...REPO_SKILLS } : BUNDLED_SKILLS;
+
+	server.registerTool(
+		'octane_skill',
+		{
+			title: 'Octane skill',
+			description:
+				'Return an Octane agent skill by name. Bundled skills cover working WITH octane in any project: bridging React packages, migrating React components to .tsrx, intentional React divergences, and SSR setup.' +
+				(repoMode ? ' Repo skills cover octane maintainer workflows.' : ''),
+			inputSchema: {
+				name: z.enum(Object.keys(skills)),
+			},
+		},
+		async ({ name }) => {
+			const root = name in BUNDLED_SKILLS ? PACKAGE_ROOT : repoRoot;
+			const body = await readFile(resolve(root, skills[name]), 'utf8');
+			return text(body);
+		},
+	);
+
+	server.registerTool(
+		'octane_bridge_react_package',
+		{
+			title: 'Bridge a React package to Octane',
+			description:
+				'Scan a React package (from node_modules by name, or any source directory by path) for React API usage and return an Octane compatibility report: which APIs map 1:1, which need rewrites (forwardRef, useDebugValue, lazy, class components), whether a framework-agnostic core can be reused verbatim, whether an official @octanejs binding already exists, and a step-by-step bridge plan. Follow up with the bridge-react-package skill for the full workflow.',
+			inputSchema: {
+				package: z
+					.string()
+					.optional()
+					.describe('npm package name to scan, resolved from projectRoot/node_modules.'),
+				path: z
+					.string()
+					.optional()
+					.describe('Directory of source files to scan instead of an installed package.'),
+				projectRoot: z
+					.string()
+					.optional()
+					.describe('Project to resolve node_modules from. Defaults to the server cwd.'),
+			},
+		},
+		async (input) => {
+			if (!input.package && !input.path) {
+				return text(JSON.stringify({ error: "Provide either 'package' or 'path'." }, null, 2));
+			}
+			const report = await bridgeReport({
+				packageName: input.package,
+				path: input.path,
+				projectRoot: input.projectRoot,
+			});
+			return text(JSON.stringify(report, null, 2));
+		},
+	);
+
+	server.registerTool(
+		'octane_bindings',
+		{
+			title: 'List official Octane bindings',
+			description:
+				'Return the map of React packages that already have maintained @octanejs/* Octane ports. Check here before bridging by hand.',
+			inputSchema: {},
+		},
+		async () => text(JSON.stringify(KNOWN_BINDINGS, null, 2)),
+	);
+}
+
+function registerRepoTools(server, repoRoot) {
+	server.registerTool(
+		'octane_project_map',
+		{
+			title: 'Octane project map',
+			description:
+				'Return Octane repository map, source ownership, validation commands, and skill paths.',
+			inputSchema: {},
+		},
+		async () => {
+			const projectMap = await readFile(resolve(repoRoot, '.ai/project-map.md'), 'utf8');
+			return text(projectMap);
+		},
+	);
+
+	server.registerTool(
+		'octane_triage_paths',
+		{
+			title: 'Triage Octane paths',
+			description: 'Classify changed paths by Octane repo area.',
+			inputSchema: {
+				paths: z.array(z.string()).describe('Repository-relative paths'),
+			},
+		},
+		async ({ paths }) => {
+			const rows = paths.map((path) => ({ path, area: areaForPath(path) }));
+			return text(JSON.stringify({ repoRoot, paths: rows }, null, 2));
+		},
+	);
+
+	server.registerTool(
+		'octane_validate_plan',
+		{
+			title: 'Octane validation plan',
+			description: 'Recommend validation commands for changed paths and task kind.',
+			inputSchema: {
+				paths: z.array(z.string()).default([]).describe('Repository-relative changed paths'),
+				taskKind: z
+					.enum([
+						'bug',
+						'feature',
+						'docs',
+						'test',
+						'performance',
+						'core',
+						'compiler',
+						'package',
+						'api',
+						'unknown',
+					])
+					.default('unknown'),
+			},
+		},
+		async ({ paths, taskKind }) => {
+			return text(
+				JSON.stringify({ repoRoot, taskKind, commands: validationFor(paths, taskKind) }, null, 2),
+			);
+		},
+	);
+
+	server.registerTool(
+		'octane_scaffold_react_port',
+		{
+			title: 'Scaffold React test port',
+			description: 'Run scripts/scaffold-react-port.mjs for a React upstream test file.',
+			inputSchema: {
+				reactTestFile: z
+					.string()
+					.describe('Path to the upstream React test file, relative to repo root or absolute.'),
+				outFile: z
+					.string()
+					.optional()
+					.describe('Optional output file for the generated Vitest skeleton.'),
+				timeoutMs: z.number().int().positive().optional(),
+			},
+		},
+		async (input) => commandResult(await scaffoldReactPort(repoRoot, input)),
+	);
+
+	server.registerTool(
+		'octane_benchmark',
+		{
+			title: 'Run Octane benchmark',
+			description:
+				'Run one of the known Octane benchmark workspaces, or all benchmarks via pnpm bench.',
+			inputSchema: {
+				benchmark: z.enum(['all', ...Object.keys(BENCHMARKS)]).default('all'),
+				timeoutMs: z.number().int().positive().optional(),
+			},
+		},
+		async (input) => commandResult(await runBenchmark(repoRoot, input)),
+	);
+
+	server.registerTool(
+		'octane_issue_context',
+		{
+			title: 'Fetch Octane issue context',
+			description:
+				'Fetch a GitHub issue with gh and return structured context plus lightweight triage hints.',
+			inputSchema: {
+				issue: z
+					.union([z.number().int().positive(), z.string()])
+					.describe('Issue number or URL accepted by gh issue view.'),
+				timeoutMs: z.number().int().positive().optional(),
+			},
+		},
+		async (input) => commandResult(await issueContext(repoRoot, input)),
+	);
+}
+
+export function createServer(options = {}) {
+	const repoRoot = resolve(options.repoRoot || process.env.OCTANE_REPO_ROOT || process.cwd());
+	const repoMode = isOctaneRepo(repoRoot);
+	const server = new McpServer({ name: 'octane', version: '0.2.0' });
+	registerUserTools(server, repoRoot, repoMode);
+	if (repoMode) registerRepoTools(server, repoRoot);
+	return server;
+}
+
+export async function main() {
+	const server = createServer();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === __filename) {
+	main().catch((error) => {
+		console.error(error);
+		process.exit(1);
+	});
+}

package/src/index.test.js

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'vitest';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+	areaForPath,
+	BUNDLED_SKILLS,
+	isOctaneRepo,
+	scaffoldReactPort,
+	validationFor,
+} from './index.js';
+
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+describe('@octanejs/mcp-server helpers', () => {
+	it('classifies Octane repository paths', () => {
+		expect(areaForPath('packages/octane/src/compiler/compile.js')).toBe('compiler');
+		expect(areaForPath('packages/octane/src/runtime.ts')).toBe('core-runtime');
+		expect(areaForPath('packages/octane/src/runtime.server.ts')).toBe('ssr');
+		expect(areaForPath('packages/zustand/src/index.ts')).toBe('ecosystem-binding');
+		expect(areaForPath('packages/radix/src/index.ts')).toBe('ecosystem-binding');
+		expect(areaForPath('packages/octane-mcp-server/src/index.js')).toBe('mcp-server');
+		expect(areaForPath('benchmarks/news/run.mjs')).toBe('benchmark');
+		expect(areaForPath('.rulesync/rules/project.md')).toBe('rulesync-source');
+	});
+
+	it('recommends validation commands from changed paths', () => {
+		const commands = validationFor(
+			[
+				'packages/octane/src/runtime.ts',
+				'packages/zustand/src/index.ts',
+				'packages/radix/src/index.ts',
+				'.rulesync/rules/project.md',
+			],
+			'core',
+		);
+
+		expect(commands).toContain('pnpm rules:generate');
+		expect(commands).toContain(
+			'./node_modules/.bin/vitest run packages/octane/tests --project octane',
+		);
+		expect(commands).toContain(
+			'./node_modules/.bin/vitest run packages/zustand/tests --project zustand',
+		);
+		expect(commands).toContain(
+			'./node_modules/.bin/vitest run packages/radix/tests --project radix',
+		);
+		expect(commands).toContain('pnpm typecheck');
+		expect(commands).toContain('pnpm format:check');
+	});
+
+	it('detects the octane monorepo for repo-mode tools', async () => {
+		expect(isOctaneRepo(resolve(PACKAGE_ROOT, '../..'))).toBe(true);
+		const elsewhere = await mkdtemp(join(tmpdir(), 'octane-mcp-test-'));
+		expect(isOctaneRepo(elsewhere)).toBe(false);
+	});
+
+	it('ships every bundled skill inside the package', async () => {
+		for (const file of Object.values(BUNDLED_SKILLS)) {
+			expect(existsSync(resolve(PACKAGE_ROOT, file))).toBe(true);
+			const body = await readFile(resolve(PACKAGE_ROOT, file), 'utf8');
+			expect(body).toMatch(/^# Skill:/);
+		}
+	});
+
+	it('runs the React port scaffolder wrapper', async () => {
+		const repoRoot = await mkdtemp(join(tmpdir(), 'octane-mcp-test-'));
+		await mkdir(join(repoRoot, 'scripts'), { recursive: true });
+		await mkdir(join(repoRoot, 'react'), { recursive: true });
+		await writeFile(
+			join(repoRoot, 'scripts/scaffold-react-port.mjs'),
+			"import { writeFileSync } from 'node:fs';\nconst out = process.argv[process.argv.indexOf('--out') + 1];\nwriteFileSync(out, 'generated');\nconsole.log('ok');\n",
+		);
+		await writeFile(join(repoRoot, 'react/source-test.js'), "it('works', () => {});\n");
+
+		const result = await scaffoldReactPort(repoRoot, {
+			reactTestFile: 'react/source-test.js',
+			outFile: 'ported.test.ts',
+		});
+
+		expect(result.code).toBe(0);
+		expect(result.stdout).toContain('ok');
+		await expect(readFile(join(repoRoot, 'ported.test.ts'), 'utf8')).resolves.toBe('generated');
+	});
+});