@tsrx/mcp 0.0.0

package/src/format.js

@@ -0,0 +1,138 @@
+import path from 'node:path';
+import { format, resolveConfig, resolveConfigFile } from 'prettier';
+import * as tsrx_prettier_plugin from '@tsrx/prettier-plugin';
+import { resolve_cwd_context } from './target.js';
+
+const BUILTIN_DEFAULTS = {
+	printWidth: 100,
+	tabWidth: 2,
+	useTabs: true,
+	singleQuote: true,
+};
+
+/**
+ * @typedef {{
+ *   message: string,
+ *   name: string | null,
+ *   loc: unknown,
+ * }} NormalizedFormatError
+ *
+ * @typedef {{
+ *   ok: boolean,
+ *   filename: string,
+ *   cwd: string,
+ *   message: string | null,
+ *   configPath: string | null,
+ *   formatted: string | null,
+ *   changed: boolean,
+ *   errors: NormalizedFormatError[],
+ *   check: boolean | null,
+ * }} FormatResult
+ */
+
+/**
+ * @param {unknown} error
+ * @returns {NormalizedFormatError}
+ */
+function normalize_error(error) {
+	if (error && typeof error === 'object') {
+		const candidate = /** @type {Record<string, unknown>} */ (error);
+		return {
+			message: candidate.message ? String(candidate.message) : String(error),
+			name: candidate.name ? String(candidate.name) : null,
+			loc: candidate.loc ?? null,
+		};
+	}
+	return {
+		message: String(error),
+		name: null,
+		loc: null,
+	};
+}
+
+/**
+ * @param {{
+ *   printWidth?: number,
+ *   tabWidth?: number,
+ *   useTabs?: boolean,
+ *   singleQuote?: boolean,
+ * }} input
+ */
+function pick_user_overrides(input) {
+	/** @type {Record<string, unknown>} */
+	const overrides = {};
+	if (input.printWidth !== undefined) overrides.printWidth = input.printWidth;
+	if (input.tabWidth !== undefined) overrides.tabWidth = input.tabWidth;
+	if (input.useTabs !== undefined) overrides.useTabs = input.useTabs;
+	if (input.singleQuote !== undefined) overrides.singleQuote = input.singleQuote;
+	return overrides;
+}
+
+/**
+ * @param {{
+ *   code: string,
+ *   filename?: string,
+ *   cwd?: string,
+ *   printWidth?: number,
+ *   tabWidth?: number,
+ *   useTabs?: boolean,
+ *   singleQuote?: boolean,
+ *   check?: boolean,
+ * }} input
+ * @returns {Promise<FormatResult>}
+ */
+export async function format_tsrx(input) {
+	const filename = input.filename ?? 'Component.tsrx';
+	const cwd_context = resolve_cwd_context(input.cwd);
+	const cwd = cwd_context.cwd;
+	const resolved_filename = path.isAbsolute(filename)
+		? path.resolve(filename)
+		: path.resolve(cwd, filename);
+
+	let project_config = /** @type {Record<string, unknown> | null} */ (null);
+	let config_path = /** @type {string | null} */ (null);
+	try {
+		project_config = await resolveConfig(resolved_filename, { editorconfig: true });
+		config_path = await resolveConfigFile(resolved_filename);
+	} catch {
+		// Treat unreadable Prettier config as "no project config" rather than failing.
+	}
+
+	const user_overrides = pick_user_overrides(input);
+	const options = {
+		...BUILTIN_DEFAULTS,
+		...(project_config ?? {}),
+		...user_overrides,
+		filepath: resolved_filename,
+		parser: 'ripple',
+		plugins: [tsrx_prettier_plugin],
+	};
+
+	try {
+		const formatted = await format(input.code, options);
+
+		return {
+			ok: true,
+			filename,
+			cwd,
+			message: cwd_context.hint,
+			configPath: config_path,
+			formatted,
+			changed: formatted !== input.code,
+			errors: [],
+			check: input.check ? formatted === input.code : null,
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			filename,
+			cwd,
+			message: cwd_context.hint,
+			configPath: config_path,
+			formatted: null,
+			changed: false,
+			errors: [normalize_error(error)],
+			check: input.check ? false : null,
+		};
+	}
+}

package/src/generated/docs.js

@@ -0,0 +1,79 @@
+// This file is generated by packages/tsrx-mcp/scripts/generate-docs-index.js.
+// Do not edit it directly.
+
+/** @typedef {{ slug: string, title: string, use_cases: string, content: string }} DocumentationSection */
+
+/** @type {DocumentationSection[]} */
+export const documentation_sections = [
+	{
+		slug: 'overview',
+		title: 'TSRX Overview',
+		use_cases:
+			'always, introduction, explain tsrx, compare jsx, language model context, runtime targets',
+		content:
+			'# TSRX Overview\n\nTSRX is a TypeScript language extension for authoring declarative UI in .tsrx files. It adds a small set of syntax forms on top of TypeScript, while letting each target compiler define the runtime semantics.\n\nCore ideas:\n- component declarations use the component keyword.\n- JSX-like elements can be written as statements inside component bodies.\n- control-flow statements can contain template output.\n- expression-position JSX must use <>...</> or <tsx>...</tsx>.\n- lazy destructuring uses &[] and &{} for by-reference bindings.\n\nThe core language docs should stay target-neutral. After identifying the active runtime target, use target-specific docs, prompts, or skills for runtime imports, bundler setup, and semantics that are not defined by TSRX itself.\n\nSource: website-tsrx/src/pages/specification.tsrx',
+	},
+	{
+		slug: 'components',
+		title: 'Component Declarations',
+		use_cases:
+			'components, component keyword, props, authoring .tsrx files, no jsx return syntax',
+		content:
+			'# Component Declarations\n\nComponents are declared with the component keyword, not as functions returning JSX.\n\n```tsx\ncomponent Button(props: { label: string }) {\n  <button>{props.label}</button>\n}\n```\n\nInside a component body, template elements are statements. Do not generate `return <div />` from a component body. Use a bare `return;` only as a guard exit after emitting fallback template statements.\n\nSpecification grammar:\n\n```text\nComponentDeclaration :\n  component BindingIdentifier ( FormalParametersopt ) { ComponentBody }\n\nComponentExpression :\n  component BindingIdentifieropt ( FormalParametersopt ) { ComponentBody }\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#components',
+	},
+	{
+		slug: 'text-and-template-expressions',
+		title: 'Text and Template Expressions',
+		use_cases:
+			'text children, quoted text, raw text errors, html, text directive, string literals',
+		content:
+			'# Text and Template Expressions\n\nRaw unquoted text children are not valid TSRX. Static text should be written as a direct double-quoted child, and dynamic values should be wrapped in braces.\n\n```tsx\ncomponent Greeting({ name }: { name: string }) {\n  <h1>"Hello"</h1>\n  <p>{name}</p>\n}\n```\n\nSingle-quoted strings and template literals remain JavaScript expressions, so they must be inside braces. Use `{text expression}` for explicit text and `{html expression}` only for trusted HTML.\n\nSpecification grammar:\n\n```text\nDoubleQuotedTextChild :\n  " JSXStringCharactersopt "\n\nTemplateExpression :\n  { AssignmentExpression }\n  { text AssignmentExpression }\n  { html AssignmentExpression }\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#templates',
+	},
+	{
+		slug: 'tsx-expression-values',
+		title: 'TSX Expression Values',
+		use_cases:
+			'fragments, tsx tag, pass jsx as prop, return jsx from helper, expression position jsx',
+		content:
+			'# TSX Expression Values\n\nRegular template elements in component bodies are statements and have no value. When JSX must be used in expression position, wrap it in `<>...</>` or `<tsx>...</tsx>`.\n\n```tsx\ncomponent App() {\n  const title = <><span>"Settings"</span></>;\n\n  <Card title={title} />\n}\n```\n\nUse this for assigning JSX to variables, returning JSX from helper functions, or passing JSX as props. Do not write `const el = <div />` directly in TSRX component code.\n\nSpecification grammar:\n\n```text\nTsxElement :\n  <tsx> TsxChildrenopt </tsx>\n\nTsxCompatElement :\n  <tsx: IdentifierName> TsxChildrenopt </tsx: IdentifierName>\n\nTsxFragmentShorthand :\n  <> TsxChildrenopt </>\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#tsx-islands',
+	},
+	{
+		slug: 'control-flow',
+		title: 'Control Flow',
+		use_cases:
+			'if else, for loops, switch, try catch, conditional rendering, lists, guard returns',
+		content:
+			'# Control Flow\n\nStandard JavaScript control flow can contain template statements inside component bodies and nested element children.\n\n```tsx\ncomponent List({ items }: { items: string[] }) {\n  if (items.length === 0) {\n    <p>"No items"</p>\n    return;\n  }\n\n  <ul>\n    for (const item of items) {\n      <li>{item}</li>\n    }\n  </ul>\n}\n```\n\nA bare `return;` exits the current render path. A return with a value is invalid inside a TSRX component body.\n\nSource: website-tsrx/src/pages/features.tsrx#if',
+	},
+	{
+		slug: 'lazy-destructuring',
+		title: 'Lazy Destructuring',
+		use_cases: 'reactivity, lazy binding, ampersand destructuring, &[], &{}',
+		content:
+			'# Lazy Destructuring\n\nTSRX supports lazy binding patterns prefixed with `&`. They bind by reference rather than by value. The target compiler provides the runtime semantics.\n\n```tsx\nlet &[count] = source;\nlet &{ name, age } = props;\n```\n\nThe language defines the syntax and AST shape. Target-specific docs should explain what source values are valid and how reads and writes are lowered for the active runtime.\n\nSpecification grammar:\n\n```text\nLazyAssignmentStatement :\n  LazyObjectBindingPattern = AssignmentExpression ;\n  LazyArrayBindingPattern = AssignmentExpression ;\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#lazy',
+	},
+	{
+		slug: 'style-and-server',
+		title: 'Style and Server Extensions',
+		use_cases:
+			'#style, scoped css, #server, server blocks, compile-time identifiers',
+		content:
+			'# Style and Server Extensions\n\n`#style` is a compile-time identifier for scoped CSS class names declared in the current module.\n\n```tsx\n<div class={#style.card} />\n```\n\n`#server { ... }` marks a lexical region intended for server compile targets. TSRX parses the block; target compilers decide how to emit or strip it.\n\nSpecification grammar:\n\n```text\nStyleIdentifier :\n  #style\n\nStyleAccess :\n  #style . IdentifierName\n  #style [ StringLiteral ]\n\nServerIdentifier :\n  #server\n\nServerBlock :\n  #server { StatementListopt }\n\nServerMemberAccess :\n  #server . IdentifierName\n```\n\nSource: website-tsrx/src/pages/specification.tsrx#style',
+	},
+	{
+		slug: 'target-integration',
+		title: 'Target Integration',
+		use_cases:
+			'runtime target, compiler package, target-specific setup, skills, runtime semantics',
+		content:
+			'# Target Integration\n\nTSRX authoring syntax is shared, but output and runtime semantics are target-defined.\n\nThe core MCP server should detect the target, then hand off runtime-specific questions to a target-specific skill, prompt, resource set, or compiler-backed tool.\n\nTarget-specific layers should own:\n- package installation and bundler setup\n- runtime imports and helper APIs\n- compatibility blocks and escape hatches\n- compiler warnings and semantic restrictions\n- examples that depend on a specific rendering runtime\n\nWhen helping in an existing project, detect the target before generating code. If no target-specific layer is available, stay within target-neutral TSRX syntax and ask for confirmation before assuming runtime APIs.\n\nSource: website-tsrx/src/pages/getting-started.tsrx',
+	},
+	{
+		slug: 'tooling',
+		title: 'Tooling',
+		use_cases:
+			'typescript plugin, typecheck, prettier, eslint, vscode, editor setup, diagnostics',
+		content:
+			"# Tooling\n\nCommon TSRX tooling packages:\n\n- `@tsrx/typescript-plugin` for TypeScript integration and `tsrx-tsc`.\n- `@tsrx/prettier-plugin` for formatting .tsrx files.\n- `@tsrx/eslint-plugin` for linting.\n- language server and editor integration packages for diagnostics, hover, completion, and definitions.\n\nUse the project package manager and match the active target runtime's compiler and bundler integration.\n\nSource: website-tsrx/src/pages/getting-started.tsrx#tooling-install",
+	},
+];

package/src/http.js

@@ -0,0 +1,99 @@
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createTSRXMcpServer } from './server.js';
+
+const DEFAULT_ALLOWED_METHODS = 'GET, POST, DELETE, OPTIONS';
+const DEFAULT_ALLOWED_HEADERS = [
+	'accept',
+	'authorization',
+	'content-type',
+	'last-event-id',
+	'mcp-protocol-version',
+	'mcp-session-id',
+].join(', ');
+const DEFAULT_EXPOSED_HEADERS = ['mcp-session-id', 'mcp-protocol-version'].join(', ');
+
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {{ origin?: string }} [options]
+ */
+function apply_cors_headers(res, options = {}) {
+	res.setHeader('Access-Control-Allow-Origin', options.origin ?? '*');
+	res.setHeader('Access-Control-Allow-Methods', DEFAULT_ALLOWED_METHODS);
+	res.setHeader('Access-Control-Allow-Headers', DEFAULT_ALLOWED_HEADERS);
+	res.setHeader('Access-Control-Expose-Headers', DEFAULT_EXPOSED_HEADERS);
+	res.setHeader('Vary', 'Origin');
+}
+
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {unknown} body
+ */
+function send_json(res, status, body) {
+	res.statusCode = status;
+	res.setHeader('Content-Type', 'application/json; charset=utf-8');
+	res.end(JSON.stringify(body, null, 2));
+}
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @param {{
+ *   cors?: boolean,
+ *   corsOrigin?: string,
+ *   bearerToken?: string,
+ *   enableJsonResponse?: boolean,
+ * }} [options]
+ */
+export async function handleTSRXMcpNodeRequest(req, res, options = {}) {
+	if (options.cors !== false) {
+		apply_cors_headers(res, { origin: options.corsOrigin });
+	}
+
+	if (req.method === 'OPTIONS') {
+		res.statusCode = 204;
+		res.end();
+		return;
+	}
+
+	if (options.bearerToken) {
+		const authorization = req.headers.authorization;
+		if (authorization !== `Bearer ${options.bearerToken}`) {
+			send_json(res, 401, {
+				error: 'unauthorized',
+				message: 'Missing or invalid bearer token.',
+			});
+			return;
+		}
+	}
+
+	if (req.method !== 'GET' && req.method !== 'POST' && req.method !== 'DELETE') {
+		send_json(res, 405, {
+			error: 'method_not_allowed',
+			message: 'TSRX MCP only accepts GET, POST, DELETE, and OPTIONS requests.',
+		});
+		return;
+	}
+
+	const server = createTSRXMcpServer({ remote: true });
+	const transport = new StreamableHTTPServerTransport({
+		sessionIdGenerator: undefined,
+		enableJsonResponse: options.enableJsonResponse ?? true,
+	});
+
+	try {
+		await server.connect(transport);
+		await transport.handleRequest(req, res);
+	} catch (error) {
+		if (!res.headersSent) {
+			send_json(res, 500, {
+				error: 'mcp_request_failed',
+				message: error instanceof Error ? error.message : String(error),
+			});
+		} else {
+			res.end();
+		}
+	} finally {
+		await server.close().catch(() => {});
+	}
+}

package/src/index.js

@@ -0,0 +1,25 @@
+export {
+	createTSRXMcpServer,
+	analyze_tsrx_handler,
+	compile_tsrx_handler,
+	detect_target_handler,
+	format_tsrx_handler,
+	get_documentation_handler,
+	inspect_project_handler,
+	list_sections_handler,
+	validate_tsrx_file_handler,
+} from './server.js';
+
+export { handleTSRXMcpNodeRequest } from './http.js';
+export { analyze_tsrx } from './analyze.js';
+export { compile_tsrx } from './compile.js';
+export { format_tsrx } from './format.js';
+export { inspect_project } from './inspect.js';
+export { validate_tsrx_file } from './validate.js';
+export { detect_target, TARGET_CANDIDATES } from './target.js';
+export {
+	documentation_sections,
+	find_documentation_section,
+	find_similar_documentation_sections,
+	list_documentation_sections,
+} from './docs.js';

package/src/inspect.js

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CONFIG_FILES, detect_target, TARGET_CANDIDATES } from './target.js';
+
+const DEPENDENCY_FIELDS = [
+	'dependencies',
+	'devDependencies',
+	'peerDependencies',
+	'optionalDependencies',
+];
+
+const TOOLING_PACKAGES = [
+	'@tsrx/prettier-plugin',
+	'@tsrx/eslint-plugin',
+	'@tsrx/typescript-plugin',
+	'@tsrx/language-server',
+	'@tsrx/vscode-plugin',
+];
+
+const PACKAGE_MANAGER_LOCKFILES = [
+	{ file: 'pnpm-lock.yaml', packageManager: 'pnpm' },
+	{ file: 'package-lock.json', packageManager: 'npm' },
+	{ file: 'yarn.lock', packageManager: 'yarn' },
+	{ file: 'bun.lock', packageManager: 'bun' },
+	{ file: 'bun.lockb', packageManager: 'bun' },
+];
+
+/**
+ * @param {Record<string, unknown>} package_json
+ */
+function get_dependencies(package_json) {
+	const dependencies = [];
+	for (const field of DEPENDENCY_FIELDS) {
+		const values = package_json[field];
+		if (!values || typeof values !== 'object') continue;
+		for (const [name, version] of Object.entries(values)) {
+			dependencies.push({
+				name,
+				version: typeof version === 'string' ? version : String(version),
+				field,
+			});
+		}
+	}
+	return dependencies.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * @param {string} root
+ */
+function find_config_files(root) {
+	return CONFIG_FILES.filter((file) => fs.existsSync(path.join(root, file)));
+}
+
+/**
+ * @param {string} root
+ * @param {Record<string, unknown>} package_json
+ */
+function detect_package_manager(root, package_json) {
+	if (typeof package_json.packageManager === 'string') {
+		return package_json.packageManager.split('@')[0] || package_json.packageManager;
+	}
+	const match = PACKAGE_MANAGER_LOCKFILES.find(({ file }) => fs.existsSync(path.join(root, file)));
+	return match?.packageManager ?? null;
+}
+
+/**
+ * @param {string | null} package_manager
+ */
+function runner(package_manager) {
+	if (package_manager === 'npm') return 'npm run';
+	if (package_manager === 'yarn') return 'yarn';
+	if (package_manager === 'bun') return 'bun run';
+	return 'pnpm';
+}
+
+/**
+ * @param {Record<string, unknown>} package_json
+ */
+function get_scripts(package_json) {
+	const scripts = package_json.scripts;
+	if (!scripts || typeof scripts !== 'object') return {};
+	/** @type {Record<string, string>} */
+	const normalized = {};
+	for (const [name, command] of Object.entries(scripts)) {
+		if (typeof command === 'string') normalized[name] = command;
+	}
+	return normalized;
+}
+
+/**
+ * @param {Record<string, string>} scripts
+ * @param {string | null} package_manager
+ */
+function get_likely_commands(scripts, package_manager) {
+	const run = runner(package_manager);
+	return {
+		format: scripts.format ? `${run} format` : null,
+		formatCheck: scripts['format:check'] ? `${run} format:check` : null,
+		typecheck: scripts.typecheck ? `${run} typecheck` : null,
+		test: scripts.test ? `${run} test` : null,
+	};
+}
+
+/**
+ * @param {Array<{ name: string, version: string, field: string }>} dependencies
+ */
+function get_tsrx_packages(dependencies) {
+	return dependencies.filter(
+		({ name }) =>
+			name === 'ripple' ||
+			name.startsWith('@tsrx/') ||
+			name.startsWith('@ripple-ts/') ||
+			name.includes('tsrx'),
+	);
+}
+
+/**
+ * @param {Array<{ name: string, version: string, field: string }>} dependencies
+ */
+function get_tooling(dependencies) {
+	return TOOLING_PACKAGES.map((name) => {
+		const dependency = dependencies.find((item) => item.name === name);
+		return {
+			name,
+			present: Boolean(dependency),
+			version: dependency?.version ?? null,
+			field: dependency?.field ?? null,
+		};
+	});
+}
+
+/**
+ * @param {Array<{ name: string, version: string, field: string }>} dependencies
+ */
+function get_target_package_status(dependencies) {
+	return TARGET_CANDIDATES.map((candidate) => {
+		const packages = [];
+		for (const signal of candidate.signals) {
+			const dependency = dependencies.find((item) => item.name === signal);
+			if (dependency) packages.push(dependency);
+		}
+		return {
+			target: candidate.target,
+			compilerPackage: candidate.compilerPackage,
+			present: packages.length > 0,
+			packages: packages.map((dependency) => ({
+				name: dependency.name,
+				version: dependency.version,
+				field: dependency.field,
+			})),
+		};
+	});
+}
+
+/**
+ * @param {{ cwd?: string }} input
+ */
+export function inspect_project(input = {}) {
+	const detection = detect_target(input.cwd);
+	const cwd = detection.cwd;
+	const package_json_path = detection.packageJsonPath;
+
+	if (!package_json_path) {
+		return {
+			cwd,
+			root: null,
+			packageJsonPath: null,
+			packageName: null,
+			packageManager: null,
+			target: detection,
+			configFiles: [],
+			tsrxPackages: [],
+			targetPackages: [],
+			tooling: [],
+			scripts: {},
+			commands: {
+				format: null,
+				formatCheck: null,
+				typecheck: null,
+				test: null,
+			},
+			message: detection.message,
+		};
+	}
+
+	const root = path.dirname(package_json_path);
+	/** @type {Record<string, unknown>} */
+	let package_json;
+	try {
+		package_json = JSON.parse(fs.readFileSync(package_json_path, 'utf8'));
+	} catch (error) {
+		return {
+			cwd,
+			root,
+			packageJsonPath: package_json_path,
+			packageName: null,
+			packageManager: null,
+			target: detection,
+			configFiles: find_config_files(root),
+			tsrxPackages: [],
+			targetPackages: [],
+			tooling: [],
+			scripts: {},
+			commands: {
+				format: null,
+				formatCheck: null,
+				typecheck: null,
+				test: null,
+			},
+			message: `Could not parse package.json: ${error instanceof Error ? error.message : String(error)}`,
+		};
+	}
+
+	const dependencies = get_dependencies(package_json);
+	const scripts = get_scripts(package_json);
+	const package_manager = detect_package_manager(root, package_json);
+	const tsrx_packages = get_tsrx_packages(dependencies);
+	const target_packages = get_target_package_status(dependencies);
+
+	return {
+		cwd,
+		root,
+		packageJsonPath: package_json_path,
+		packageName: typeof package_json.name === 'string' ? package_json.name : null,
+		packageManager: package_manager,
+		target: detection,
+		configFiles: find_config_files(root),
+		tsrxPackages: tsrx_packages,
+		targetPackages: target_packages,
+		tooling: get_tooling(dependencies),
+		scripts,
+		commands: get_likely_commands(scripts, package_manager),
+		message: `${detection.message} Found ${tsrx_packages.length} TSRX-related package${tsrx_packages.length === 1 ? '' : 's'}.`,
+	};
+}