react-tourlight-mcp 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# react-tourlight-mcp
+
+## 0.1.1
+
+### Patch Changes
+
+- Prepare the local MCP server for npm distribution with installation instructions, repository and funding metadata, and an included MIT license. Report the package version during the MCP handshake.
+- Updated dependencies [cab6376]
+  - react-tourlight@0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-tourlight contributors
+
+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,64 @@
+# React Tourlight MCP
+
+Local tools for authoring portable Tourlight documents. MIT licensed. Requires Node.js 20+.
+
+The server accepts JSON and returns JSON or generated source. It never reads application files, writes changes, executes callbacks, opens a browser, or sends data to a model provider. The MCP host supplies the model and any file/browser access.
+
+## Install and run
+
+Requires `react-tourlight` 0.5.0 or later, installed automatically as a dependency.
+For the 0.1.1 release, configure your preferred client with:
+
+```sh
+claude mcp add --transport stdio tourlight -- npx -y react-tourlight-mcp@0.1.1
+codex mcp add tourlight -- npx -y react-tourlight-mcp@0.1.1
+```
+
+Use one command for your chosen client. These commands require the corresponding
+npm releases to be published; for an unreleased checkout use the source setup below.
+
+## Run from this repository
+
+After `pnpm install` and `pnpm build` at the repository root:
+
+```sh
+node /absolute/path/to/react-tourlight/packages/tourlight-mcp/index.mjs
+```
+
+Configure a local client using that exact absolute path:
+
+```sh
+claude mcp add --transport stdio tourlight -- node /absolute/path/to/react-tourlight/packages/tourlight-mcp/index.mjs
+codex mcp add tourlight -- node /absolute/path/to/react-tourlight/packages/tourlight-mcp/index.mjs
+```
+
+The commands are alternative client configurations, not prerequisites for each other. Stdio intentionally prints protocol messages only; the process waits for a client connection.
+
+## Tools
+
+| Tool | Input | Result |
+| --- | --- | --- |
+| `tourlight_schema` | `{}` | Full JSON Schema |
+| `tourlight_template` | Optional `id`, `name` | Starter document |
+| `tourlight_validate` | `document` | Validity and field-level issues |
+| `tourlight_inspect` | `document` | Routes, targets, and required handlers |
+| `tourlight_format` | `document` | Canonical JSON string |
+| `tourlight_generate_tests` | `document`, `baseUrl` | Playwright target smoke-test source |
+
+Every tool is read-only and deterministic. Validation does not check live selectors. Generated tests skip steps requiring application-specific setup; extend them before claiming full journey coverage.
+
+## Client boundaries
+
+- Claude Code and Codex support local stdio MCP servers. The protocol test verifies a real SDK client handshake, discovery, valid/invalid inputs, and all six tools. It is not a claim that every client version has been manually tested.
+- ChatGPT web needs a supported remote/private connection path; it cannot directly launch this local stdio process. This package does not ship HTTP transport, authentication, a tunnel, or a published ChatGPT plugin. Follow the [current connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt) when adding a separate hosted adapter.
+- The portable `skills/tourlight` workflow can be installed in [Claude Code](https://code.claude.com/docs/en/skills), [Codex](https://learn.chatgpt.com/docs/build-skills), or [OpenClaw](https://docs.openclaw.ai/tools/skills) using each host's documented skill directory. A copied skill is not a verified marketplace integration.
+
+SDK reference: [MCP TypeScript SDK v2](https://ts.sdk.modelcontextprotocol.io/v2/), protocol 2026-07-28. SDK 2.1.0 is the verified baseline.
+
+## Support Tourlight
+
+This server and the Tourlight package are free under MIT. You can
+[give once](https://buy.stripe.com/fZu14m0FO3v050PfqP3ks00) or explore
+[monthly sponsorship](https://react-tourlight.vercel.app/support) to support maintenance,
+documentation, and new features. Sponsorship does not unlock additional tools or dedicated support.
+Stripe checkout uses our existing GPT Hotline account name and logo.

package/index.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio'
+import { createTourlightServer } from './server.mjs'
+
+const server = createTourlightServer()
+await server.connect(new StdioServerTransport())

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "react-tourlight-mcp",
+  "version": "0.1.1",
+  "description": "Local MCP tools for authoring, validating, and testing portable Tourlight documents",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/btahir/react-tourlight.git",
+    "directory": "packages/tourlight-mcp"
+  },
+  "homepage": "https://react-tourlight.vercel.app/docs/agents",
+  "bugs": {
+    "url": "https://github.com/btahir/react-tourlight/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://react-tourlight.vercel.app/support"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "react-tourlight-mcp": "./index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "server.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.1.0",
+    "zod": "^4.6.5",
+    "react-tourlight": "0.5.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "^2.1.0"
+  },
+  "scripts": {
+    "test": "node --test protocol.test.mjs"
+  }
+}

package/server.mjs

@@ -0,0 +1,28 @@
+import { McpServer } from '@modelcontextprotocol/server'
+import * as z from 'zod/v4'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { createTourDocument, formatTourDocument, generateTourTest, inspectTourDocument, parseTourDocument, validateTourDocument } from 'react-tourlight/document'
+
+const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+const require = createRequire(import.meta.url)
+const { version } = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'))
+const documentInput = z.object({ document: z.unknown().describe('A Tourlight schemaVersion 1 JSON object. Content is plain text; callbacks are registered names, never code.') })
+const output = (value) => ({ content: [{ type: 'text', text: JSON.stringify(value, null, 2) }], structuredContent: value })
+
+export function createTourlightServer() {
+  const server = new McpServer({ name: 'react-tourlight', version }, {
+    instructions: 'Author source-owned Tourlight JSON documents. These tools only transform input and return results. They do not read project files, inspect a browser, execute handlers, save changes, or publish. Obtain actual selectors from the user application. Validate documents and verify the live journey before describing a tour as working.',
+  })
+  const register = (name, description, inputSchema, run) => server.registerTool(name, { description, inputSchema, annotations }, async (args) => {
+    try { return output(await run(args)) }
+    catch (error) { return { ...output({ error: error.message, ...(error.issues ? { issues: error.issues } : {}) }), isError: true } }
+  })
+  register('tourlight_schema', 'Get the full JSON Schema for portable Tourlight documents. Unique step ids are additionally checked by tourlight_validate.', z.object({}), () => JSON.parse(readFileSync(require.resolve('react-tourlight/schema.json'), 'utf8')))
+  register('tourlight_template', 'Create a valid starter document to customize with real application targets and meaningful onboarding copy.', z.object({ id: z.string().optional(), name: z.string().optional() }), (args) => ({ document: createTourDocument(args) }))
+  register('tourlight_validate', 'Validate a tour document, returning exact field paths and actionable errors. Does not resolve selectors in a browser.', documentInput, ({ document }) => validateTourDocument(document))
+  register('tourlight_inspect', 'Summarize routes, selectors, action names, and conditions that an application must provide. Static analysis only.', documentInput, ({ document }) => inspectTourDocument(parseTourDocument(document)))
+  register('tourlight_format', 'Return canonical JSON for review or saving by the caller. Does not write a file.', documentInput, ({ document }) => ({ json: formatTourDocument(parseTourDocument(document)) }))
+  register('tourlight_generate_tests', 'Generate Playwright target smoke checks. Setup-dependent steps are explicitly skipped. Add app authentication, setup, tour navigation, and task outcome assertions; these checks alone do not prove the user journey.', z.object({ document: z.unknown(), baseUrl: z.string() }), ({ document, baseUrl }) => ({ filename: 'tourlight.targets.spec.ts', source: generateTourTest(parseTourDocument(document), baseUrl) }))
+  return server
+}