@tsrx/mcp 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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,115 @@
+# @tsrx/mcp
+
+MCP server for TSRX language documentation and project context.
+
+## Usage
+
+Run the server over stdio:
+
+```bash
+npx -y @tsrx/mcp
+```
+
+Generic MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "tsrx": {
+      "command": "npx",
+      "args": ["-y", "@tsrx/mcp"]
+    }
+  }
+}
+```
+
+## Hosted HTTP
+
+Remote MCP clients need a hosted Streamable HTTP endpoint rather than a local
+stdio command. This monorepo includes a deployment-neutral endpoint app in
+`mcp-endpoint-website` that serves the same MCP server at `/mcp`.
+
+The hosted endpoint runs in remote-safe mode. It exposes documentation, prompts,
+`format-tsrx`, `compile-tsrx`, and `analyze-tsrx`, but omits local filesystem
+tools such as `inspect-project`, `detect-target`, and `validate-tsrx-file`.
+
+Set `TSRX_MCP_BEARER_TOKEN` in the endpoint environment to require bearer-token
+auth. Set `TSRX_MCP_CORS_ORIGIN` to restrict CORS for browser-based clients.
+
+For local development in this monorepo, point at the source entrypoint:
+
+```json
+{
+  "mcpServers": {
+    "tsrx": {
+      "command": "node",
+      "args": ["/absolute/path/to/ripple/packages/tsrx-mcp/src/stdio.js"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add the generic config above to `claude_desktop_config.json`.
+
+### Claude Code
+
+```bash
+claude mcp add tsrx -- npx -y @tsrx/mcp
+```
+
+For local development:
+
+```bash
+claude mcp add tsrx-local -- node /absolute/path/to/ripple/packages/tsrx-mcp/src/stdio.js
+```
+
+### Cursor
+
+Add the generic config above to your Cursor MCP settings.
+
+### Codex
+
+Add the generic config above to your Codex MCP configuration.
+
+## Tools
+
+- `list-sections` - list target-neutral TSRX documentation sections.
+- `get-documentation` - fetch one or more TSRX documentation sections.
+- `detect-target` - infer the active TSRX runtime target from project files.
+- `inspect-project` - inspect target signals, TSRX packages, tooling, scripts, and
+  likely project commands.
+- `compile-tsrx` - compile TSRX code with the inferred or explicit target compiler
+  and return diagnostics.
+- `format-tsrx` - format TSRX code using the official Prettier plugin.
+- `analyze-tsrx` - compile TSRX code and convert common diagnostics into
+  target-neutral authoring advice with linked docs resources.
+- `validate-tsrx-file` - read a `.tsrx` file and run formatting, compilation, and
+  diagnostic advice in one read-only pass.
+
+## Agent Workflows
+
+For an existing project, start with `inspect-project` to identify the TSRX target,
+installed tooling, and likely validation commands. Use `detect-target` when only
+the runtime target is needed.
+
+For generated code, run `format-tsrx` first, then `compile-tsrx` with the inferred
+or explicit target. If compilation fails, run `analyze-tsrx`, apply the advice,
+format again, and compile again.
+
+For an existing `.tsrx` file, prefer `validate-tsrx-file`. It reads the file and
+runs formatting, compilation, and diagnostic advice in one read-only pass.
+
+## Resources
+
+- `tsrx://docs/{slug}.md` - target-neutral TSRX documentation sections.
+- `tsrx://targets/{target}.md` - handoff guidance for target-specific layers.
+
+## Prompts
+
+- `tsrx-task` - target-aware workflow for TSRX coding tasks.
+
+The core server stays target-neutral. Runtime-specific imports, bundler setup, and
+framework semantics should live in target-specific skills, prompts, or resources
+layered on top.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@tsrx/mcp",
+  "description": "MCP server for TSRX documentation and project context",
+  "license": "MIT",
+  "author": "Dominic Gannaway",
+  "version": "0.0.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ripple-TS/ripple.git",
+    "directory": "packages/tsrx-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Ripple-TS/ripple/issues"
+  },
+  "homepage": "https://tsrx.dev",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "README.md",
+    "src"
+  ],
+  "bin": {
+    "tsrx-mcp": "./src/stdio.js"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "prettier": "^3.8.3",
+    "zod": "^4.3.6",
+    "@tsrx/core": "0.0.19",
+    "@tsrx/prettier-plugin": "0.3.39"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "generate:docs": "node scripts/generate-docs-index.js"
+  }
+}

package/src/analyze.js

@@ -0,0 +1,195 @@
+import { DIAGNOSTIC_CODES } from '@tsrx/core';
+import { compile_tsrx } from './compile.js';
+
+/**
+ * @typedef {{
+ *   kind: string,
+ *   severity: 'error' | 'warning' | 'info',
+ *   title: string,
+ *   message: string,
+ *   documentation: string[],
+ * }} TSRXAdvice
+ */
+
+/**
+ * @typedef {{
+ *   ok: boolean,
+ *   target: string | null,
+ *   errors: Array<{ message: string, code?: string | null }>,
+ * }} TSRXCompileSummary
+ */
+
+/**
+ * @param {{ compileResult: TSRXCompileSummary }} input
+ * @returns {TSRXAdvice[]}
+ */
+function create_advice(input) {
+	const { compileResult } = input;
+	/** @type {TSRXAdvice[]} */
+	const advice = [];
+	const error_codes = new Set(compileResult.errors.map((error) => error.code).filter(Boolean));
+
+	if (!compileResult.target) {
+		advice.push({
+			kind: 'missing-target',
+			severity: 'error',
+			title: 'Select a TSRX runtime target',
+			message:
+				'The compiler could not infer a runtime target. Call detect-target with a project cwd, or pass target as ripple, react, preact, solid, or vue.',
+			documentation: ['tsrx://docs/target-integration.md'],
+		});
+	}
+
+	const has_function_component_syntax = error_codes.has(DIAGNOSTIC_CODES.FUNCTION_COMPONENT_SYNTAX);
+	if (has_function_component_syntax) {
+		advice.push({
+			kind: 'function-component-syntax',
+			severity: 'warning',
+			title: 'Use TSRX component declarations',
+			message:
+				'.tsrx component files should use the component keyword. A React-style function returning JSX is usually the wrong authoring shape for TSRX.',
+			documentation: ['tsrx://docs/components.md'],
+		});
+	}
+
+	const fired_jsx_return = error_codes.has(DIAGNOSTIC_CODES.JSX_RETURN_IN_COMPONENT);
+
+	if (fired_jsx_return) {
+		advice.push({
+			kind: 'jsx-return-in-component',
+			severity: 'error',
+			title: 'Do not return JSX from component bodies',
+			message:
+				'Inside a TSRX component body, template elements are statements. Replace `return <div />` with a template statement like `<div />`; use bare `return;` only for guard exits.',
+			documentation: ['tsrx://docs/components.md', 'tsrx://docs/tsx-expression-values.md'],
+		});
+	}
+
+	if (error_codes.has(DIAGNOSTIC_CODES.UNCLOSED_TAG)) {
+		advice.push({
+			kind: 'unclosed-tag',
+			severity: 'error',
+			title: 'Close template tags',
+			message:
+				'The compiler found a template tag without a matching closing tag. Add the missing closing tag before changing target-specific code.',
+			documentation: ['tsrx://docs/components.md'],
+		});
+	}
+
+	if (error_codes.has(DIAGNOSTIC_CODES.MISMATCHED_CLOSING_TAG)) {
+		advice.push({
+			kind: 'mismatched-closing-tag',
+			severity: 'error',
+			title: 'Match closing tags',
+			message:
+				'The compiler found a closing tag that does not match the current open template tag. Align the tag names or close the inner tag first.',
+			documentation: ['tsrx://docs/components.md'],
+		});
+	}
+
+	if (error_codes.has(DIAGNOSTIC_CODES.JSX_EXPRESSION_VALUE)) {
+		advice.push({
+			kind: 'jsx-expression-value',
+			severity: 'info',
+			title: 'Wrap expression-position JSX',
+			message:
+				'When JSX is needed as a value, wrap it in a fragment `<>...</>` or `<tsx>...</tsx>` so TSRX knows it is an expression rather than a template statement.',
+			documentation: ['tsrx://docs/tsx-expression-values.md'],
+		});
+	}
+
+	if (advice.length === 0 && compileResult.ok) {
+		advice.push({
+			kind: 'compile-clean',
+			severity: 'info',
+			title: 'TSRX compiled successfully',
+			message:
+				'No target-neutral TSRX issues were found. For runtime API or bundler details, continue with the target-specific guidance for the detected target.',
+			documentation: ['tsrx://docs/target-integration.md'],
+		});
+	}
+
+	if (advice.length === 0) {
+		advice.push({
+			kind: 'compiler-diagnostic',
+			severity: 'error',
+			title: 'Compiler diagnostics need review',
+			message:
+				'The TSRX compiler returned diagnostics that do not match a known MCP hint yet. Use the normalized compiler errors and relevant docs sections to revise the source.',
+			documentation: ['tsrx://docs/overview.md'],
+		});
+	}
+
+	return advice;
+}
+
+/**
+ * @param {{
+ *   code: string,
+ *   compileResult: {
+ *     ok: boolean,
+ *     target: string | null,
+ *     compilerPackage: string | null,
+ *     filename: string,
+ *     cwd: string,
+ *     errors: Array<{
+ *       message: string,
+ *       code: string | null,
+ *       type: string | null,
+ *       fileName: string | null,
+ *       pos: number | null,
+ *       end: number | null,
+ *       raisedAt: number | null,
+ *       loc: unknown
+ *     }>
+ *   }
+ * }} input
+ */
+export function analyze_tsrx_result(input) {
+	const { compileResult } = input;
+	const advice = create_advice({
+		compileResult,
+	});
+
+	return {
+		ok: compileResult.ok,
+		target: compileResult.target,
+		compilerPackage: compileResult.compilerPackage,
+		filename: compileResult.filename,
+		cwd: compileResult.cwd,
+		errors: compileResult.errors,
+		advice,
+		nextSteps: compileResult.ok
+			? [
+					'Use target-specific resources for runtime semantics.',
+					'Compile again after changing generated TSRX.',
+				]
+			: [
+					'Apply the highest-severity advice first.',
+					'Fetch the linked docs resources for syntax details.',
+					'Run compile-tsrx again after revising the source.',
+				],
+	};
+}
+
+/**
+ * @param {{
+ *   code: string,
+ *   filename?: string,
+ *   target?: string,
+ *   cwd?: string,
+ *   collect?: boolean,
+ *   loose?: boolean,
+ *   mode?: 'client' | 'server'
+ * }} input
+ */
+export async function analyze_tsrx(input) {
+	const compileResult = await compile_tsrx({
+		...input,
+		includeCode: false,
+	});
+	return analyze_tsrx_result({
+		code: input.code,
+		compileResult,
+	});
+}

package/src/compile.js

@@ -0,0 +1,235 @@
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { detect_target, TARGET_CANDIDATES } from './target.js';
+
+const VALID_TARGETS = new Set(TARGET_CANDIDATES.map((candidate) => candidate.target));
+
+/**
+ * @typedef {{
+ *   message: string,
+ *   code: string | null,
+ *   type: string | null,
+ *   fileName: string | null,
+ *   pos: number | null,
+ *   end: number | null,
+ *   raisedAt: number | null,
+ *   loc: unknown
+ * }} NormalizedCompileError
+ */
+
+/**
+ * @param {string | null | undefined} target
+ */
+function get_target_candidate(target) {
+	if (!target) return null;
+	return TARGET_CANDIDATES.find((candidate) => candidate.target === target) ?? null;
+}
+
+/**
+ * @param {unknown} error
+ * @param {string} filename
+ * @returns {NormalizedCompileError}
+ */
+function normalize_error(error, filename) {
+	if (error && typeof error === 'object') {
+		const candidate = /** @type {Record<string, unknown>} */ (error);
+		return {
+			message: candidate.message ? String(candidate.message) : String(error),
+			code: candidate.code ? String(candidate.code) : null,
+			type: candidate.type ? String(candidate.type) : null,
+			fileName: candidate.fileName ? String(candidate.fileName) : filename,
+			pos: typeof candidate.pos === 'number' ? candidate.pos : null,
+			end: typeof candidate.end === 'number' ? candidate.end : null,
+			raisedAt: typeof candidate.raisedAt === 'number' ? candidate.raisedAt : null,
+			loc: candidate.loc ?? null,
+		};
+	}
+	return {
+		message: String(error),
+		code: null,
+		type: null,
+		fileName: filename,
+		pos: null,
+		end: null,
+		raisedAt: null,
+		loc: null,
+	};
+}
+
+/**
+ * @param {unknown} errors
+ * @param {string} filename
+ */
+function normalize_errors(errors, filename) {
+	return Array.isArray(errors) ? errors.map((error) => normalize_error(error, filename)) : [];
+}
+
+/**
+ * @param {string} cwd
+ * @param {string | null} package_json_path
+ */
+function create_project_require(cwd, package_json_path) {
+	return createRequire(package_json_path ?? path.join(path.resolve(cwd), 'package.json'));
+}
+
+/**
+ * @param {string} compiler_package
+ * @param {string} cwd
+ * @param {string | null} package_json_path
+ */
+async function import_compiler(compiler_package, cwd, package_json_path) {
+	const project_require = create_project_require(cwd, package_json_path);
+	const resolved = project_require.resolve(compiler_package);
+	return import(pathToFileURL(resolved).href);
+}
+
+/**
+ * @param {unknown} result
+ */
+function get_generated_code(result) {
+	if (!result || typeof result !== 'object') return null;
+	const output = /** @type {Record<string, unknown>} */ (result);
+	if (typeof output.code === 'string') return output.code;
+	if (
+		output.js &&
+		typeof output.js === 'object' &&
+		typeof (/** @type {Record<string, unknown>} */ (output.js).code) === 'string'
+	) {
+		return /** @type {string} */ (/** @type {Record<string, unknown>} */ (output.js).code);
+	}
+	return null;
+}
+
+/**
+ * @param {unknown} result
+ */
+function get_generated_css(result) {
+	if (!result || typeof result !== 'object') return null;
+	const output = /** @type {Record<string, unknown>} */ (result);
+	if (
+		output.css &&
+		typeof output.css === 'object' &&
+		typeof (/** @type {Record<string, unknown>} */ (output.css).code) === 'string'
+	) {
+		return /** @type {string} */ (/** @type {Record<string, unknown>} */ (output.css).code);
+	}
+	return null;
+}
+
+/**
+ * @param {{
+ *   code: string,
+ *   filename?: string,
+ *   target?: string,
+ *   cwd?: string,
+ *   collect?: boolean,
+ *   loose?: boolean,
+ *   includeCode?: boolean,
+ *   mode?: 'client' | 'server'
+ * }} input
+ */
+export async function compile_tsrx(input) {
+	const filename = input.filename ?? 'Component.tsrx';
+	const detection = detect_target(input.cwd);
+	const cwd = detection.cwd;
+	const target = input.target ?? detection.detectedTarget;
+
+	if (!target) {
+		return {
+			ok: false,
+			target: null,
+			compilerPackage: null,
+			filename,
+			cwd,
+			errors: [
+				{
+					message:
+						detection.confidence === 'ambiguous'
+							? detection.message
+							: `Could not infer a TSRX target. Pass target explicitly. ${detection.message}`,
+					code: null,
+					type: null,
+					fileName: filename,
+					pos: null,
+					end: null,
+					raisedAt: null,
+					loc: null,
+				},
+			],
+			code: null,
+			css: null,
+		};
+	}
+
+	if (!VALID_TARGETS.has(target)) {
+		return {
+			ok: false,
+			target,
+			compilerPackage: null,
+			filename,
+			cwd,
+			errors: [
+				{
+					message: `Unknown TSRX target "${target}".`,
+					code: null,
+					type: null,
+					fileName: filename,
+					pos: null,
+					end: null,
+					raisedAt: null,
+					loc: null,
+				},
+			],
+			code: null,
+			css: null,
+		};
+	}
+
+	const candidate = get_target_candidate(target);
+	if (!candidate) {
+		throw new Error(`Missing compiler candidate for target "${target}".`);
+	}
+
+	try {
+		const compiler = await import_compiler(
+			candidate.compilerPackage,
+			cwd,
+			detection.packageJsonPath,
+		);
+		if (typeof compiler.compile !== 'function') {
+			throw new Error(`${candidate.compilerPackage} does not export a compile() function.`);
+		}
+
+		const result = compiler.compile(input.code, filename, {
+			collect: input.collect ?? true,
+			loose: input.loose,
+			mode: input.mode,
+		});
+		const errors = normalize_errors(result?.errors, filename);
+		const code = get_generated_code(result);
+		const css = get_generated_css(result);
+
+		return {
+			ok: errors.length === 0,
+			target,
+			compilerPackage: candidate.compilerPackage,
+			filename,
+			cwd,
+			errors,
+			code: input.includeCode ? code : null,
+			css: input.includeCode ? css : null,
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			target,
+			compilerPackage: candidate.compilerPackage,
+			filename,
+			cwd,
+			errors: [normalize_error(error, filename)],
+			code: null,
+			css: null,
+		};
+	}
+}

package/src/docs.js

@@ -0,0 +1,50 @@
+export { documentation_sections } from './generated/docs.js';
+
+import { documentation_sections } from './generated/docs.js';
+
+/** @typedef {{ slug: string, title: string, use_cases: string, content: string }} DocumentationSection */
+
+/**
+ * @param {string} value
+ */
+function normalize(value) {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-|-$/g, '');
+}
+
+/**
+ * @returns {DocumentationSection[]}
+ */
+export function list_documentation_sections() {
+	return documentation_sections;
+}
+
+/**
+ * @param {string} section
+ */
+export function find_documentation_section(section) {
+	const normalized = normalize(section);
+	return (
+		documentation_sections.find(
+			(candidate) =>
+				candidate.slug === normalized ||
+				normalize(candidate.title) === normalized ||
+				candidate.slug === section,
+		) ?? null
+	);
+}
+
+/**
+ * @param {string} section
+ */
+export function find_similar_documentation_sections(section) {
+	const normalized = normalize(section);
+	return documentation_sections.filter(
+		(candidate) =>
+			candidate.slug.includes(normalized) ||
+			normalize(candidate.title).includes(normalized) ||
+			candidate.use_cases.toLowerCase().includes(section.toLowerCase()),
+	);
+}