{"id":31663983,"url":"https://github.com/inqwise/inqwise-mcp-site2ts","last_synced_at":"2026-04-11T17:42:50.861Z","repository":{"id":313916981,"uuid":"1053404958","full_name":"inqwise/inqwise-mcp-site2ts","owner":"inqwise","description":"Convert existing websites into TypeScript Next.js apps via an MCP server (Rust) with a Node/Playwright helper. ARM-first, Tailwind-first, sandboxed under `.site2ts/`","archived":false,"fork":false,"pushed_at":"2025-10-03T14:35:08.000Z","size":352,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-03T16:29:33.457Z","etag":null,"topics":["arm64","headless-browser","mcp","nextjs","playwright","rust","tailwindcss","typescript","web-crawler"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inqwise.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T12:03:17.000Z","updated_at":"2025-10-03T14:35:12.000Z","dependencies_parsed_at":"2025-09-09T15:39:22.674Z","dependency_job_id":"1d35cc1d-47c9-4e1d-812f-04dae31baa7d","html_url":"https://github.com/inqwise/inqwise-mcp-site2ts","commit_stats":null,"previous_names":["inqwise/inqwise-mcp-site2ts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/inqwise/inqwise-mcp-site2ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise%2Finqwise-mcp-site2ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise%2Finqwise-mcp-site2ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise%2Finqwise-mcp-site2ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise%2Finqwise-mcp-site2ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inqwise","download_url":"https://codeload.github.com/inqwise/inqwise-mcp-site2ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inqwise%2Finqwise-mcp-site2ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278846326,"owners_count":26056090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm64","headless-browser","mcp","nextjs","playwright","rust","tailwindcss","typescript","web-crawler"],"created_at":"2025-10-07T20:52:54.639Z","updated_at":"2025-10-07T20:52:58.403Z","avatar_url":"https://github.com/inqwise.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Inqwise MCP Site2TS\n\nConvert existing websites into TypeScript-based Next.js apps via an MCP server (Rust) and a Node helper (Playwright + Next.js). ARM-first (macOS/Linux). See `SITE2TS_MISSION_SPEC.md` for the authoritative MVP contract.\n\n## Quick Start\n- Read the mission spec: `SITE2TS_MISSION_SPEC.md`.\n- Track progress: `PROGRESS.md` (human) and `progress.json` (machine-readable).\n- Commit policy: only at important milestones or task completion.\n\n## Repo Layout\n- `.site2ts/` (runtime sandbox; generated during runs)\n- `SITE2TS_MISSION_SPEC.md` (MVP rules and API)\n- `PROGRESS.md` and `progress.json` (tasks + statuses)\n\n## Project Management Rules\n- Tasks are defined in `PROGRESS.md` and mirrored in `progress.json`.\n- We update progress as tasks complete; only one active in-progress task at a time.\n- Commits are reserved for important milestones or completion of a task.\n\n## Remote Repository\nPlanned GitHub remote: `git@github.com:inqwise/inqwise-mcp-site2ts.git` (confirm or provide a different name).\n\nSetup (once the remote exists):\n\n```\n# Initialize and set remote\ngit init\ngit remote add origin git@github.com:inqwise/inqwise-mcp-site2ts.git\n\n# First milestone commit will be pushed like:\n# git push -u origin main\n```\n\nIf creating the repo via GitHub UI, choose: Owner `inqwise`, repo name `inqwise-mcp-site2ts`, default branch `main`.\n\n## Prerequisites (runtime)\n- Node 20 LTS, npm\n- Playwright (Chromium installed on first init)\n- Git (recommended)\n\n## Status\nMVP spec authored; implementation tasks planned. See `PROGRESS.md`.\n\nRecent updates:\n- Diff runs now emit per-route summaries (`summary.json`) with heatmaps and DOM selectors for automation.\n- `tools/rpc.sh` accepts custom timeouts (`--timeout` / `RPC_TIMEOUT_SEC`), optional output capture (`--capture`), and prints a one-line summary for each RPC.\n- `tools/full_flow.sh` can optionally append an `improve` RPC via `--improve-route` / `--improve-note` after the apply step.\n- `tools/plan-improvements.js` proposes follow-up actions based on diff output + logged improvement requests.\n\n## License\nApache-2.0 — see `LICENSE` for details.\n\n## Runbook\nSee `docs/RUNBOOK.md` for the end-to-end flow and artifact locations.\n\nMore examples: `docs/API_EXAMPLES.md`.\n\n## Build and Run Locally\n- Build worker (TS) and server (Rust), then send one JSON-RPC request:\n  - `tools/rpc.sh '{\"jsonrpc\":\"2.0\",\"method\":\"init\",\"params\":{\"projectRoot\":\".\"},\"id\":1}'`\n- Send subsequent requests by calling `tools/rpc.sh` again with a single-line JSON object (each run builds if needed and executes one request).\n\nNotes:\n- The Rust server spawns the Node worker from `node/site2ts-worker/dist/index.js`, so the worker must be built first (`npm run build`). The script does this for convenience.\n- For interactive sessions (multiple requests in one process), you can run the server directly and feed it one JSON line per request via stdin.\n\n## Diff Summaries \u0026 Improvement Planning\n- After running `diff`, inspect `.site2ts/reports/diff/\u003cdiffId\u003e/\u003croute\u003e/summary.json` for the per-route heatmap and DOM-zone rankings.\n- Use `node tools/plan-improvements.js` to generate an orchestration payload summarising the latest diff and suggesting next actions. The script also suppresses issues already logged via the `improve` MCP method.\n- Improvement requests are persisted under `.site2ts/reports/improve/\u003cjobId\u003e.json` so LLM/tooling can track what has already been attempted.\n- At present we iterate on each failing DOM zone by looping on **diff → improve** until the per-zone ratio drops below the 1 % threshold (starting with the highest element from top to bottom). Each `improve` call should describe the exact element or logical block to rewrite; after every iteration we re-run `diff`, assess the new `summary.json`/`metrics.json`, and then move to the next offending element.\n\n## Dependencies Policy\n- Rust crates: pinned to latest minor/patch series for stability (see `rust/site2ts-server/Cargo.toml`). We periodically bump to latest stable; breaking bumps are handled explicitly.\n- Node (worker):\n  - TypeScript toolchain uses caret ranges to pick up minor/patch updates automatically:\n    - `typescript` (\u003e=5.5), `@typescript-eslint/*` (v8), `eslint` (v9), `prettier` (v3), `eslint-plugin-import`, `eslint-config-prettier`.\n  - Runtime deps (`playwright`, `playwright-core`, `pixelmatch`, `pngjs`, `get-port`, etc.) also use caret ranges for minor/patch updates.\n- Generated staging app:\n  - `next` pinned to a secure version (currently 14.2.32) to avoid known CVEs.\n  - Dev toolchain uses caret ranges for minor/patch updates (TypeScript, Tailwind, PostCSS stack).\n\n## Roadmap / Next Improvements\n- Tailwind mapping: expand utilities (colors, shadows, line-height/letter-spacing mapping), reduce CSS fallback footprint.\n- Visual diff: harden Next.js start/screenshot timing; support multiple viewports (mobile).\n- Visual diff UX: generate an HTML dashboard that stitches together per-route screenshots and\n  summary JSON from `.site2ts/reports/diff` for easier review.\n- Apply: deeper route-aware deletions; additional safety prompts in plan mode.\n- Tests: unit tests for HTML→TSX and `mapInlineStyleToTw` to avoid regressions.\n- Packaging: optional CLI wrapper for JSON-RPC; simple config file support.\n- Platform: Windows support (non-goal for MVP) to be evaluated later.\n\nWe will open GitHub Issues to track these items; for now this section serves as the authoritative TODO list.\n\n## Troubleshooting\n- Playwright/Chromium missing: run `npx playwright install chromium` (the server also attempts this during `init`). Ensure Node 20 LTS is active.\n- Next.js build errors in staging: run `npm install` (or `npm ci` if a lockfile exists) in `.site2ts/staging/` before `audit`/`diff`.\n- Port conflicts when starting staging app for diffs: the worker auto-picks a free port; if it still fails, re-run `diff` or kill stray `node`/`next` processes.\n- Timeouts on slow sites: lower `maxPages`/`maxDepth` or increase thresholds; re-run `crawl` with `delayMs` \u003e 0 to be polite.\n- Clean slate: remove `.site2ts/` to reset caches and staging.\n\n## JSON-RPC Examples (MVP)\n\n- `init`\n  - Request: `{ \"method\": \"init\", \"params\": { \"projectRoot\": \".\" }, \"id\": 1 }`\n  - Result: `{ \"ok\": true, \"pinned\": { \"node\": \"20.x\", \"next\": \"14.x\", \"ts\": \"5.x\", \"playwright\": \"1.x\" } }`\n\n- `crawl`\n  - Request: `{ \"method\": \"crawl\", \"params\": { \"startUrl\": \"https://example.com\", \"sameOrigin\": true, \"maxPages\": 25, \"maxDepth\": 3 }, \"id\": 2 }`\n  - Result: `{ \"jobId\": \"01...\", \"siteMapId\": \"01...\", \"pages\": [{\"url\":\"...\",\"hash\":\"...\"}] }`\n\n- `analyze`\n  - Request: `{ \"method\": \"analyze\", \"params\": { \"siteMapId\": \"01...\" }, \"id\": 3 }`\n  - Result: `{ \"jobId\": \"01...\", \"analysisId\": \"01...\", \"routes\": [...], \"assets\": {...} }`\n\n- `scaffold`\n  - Request: `{ \"method\": \"scaffold\", \"params\": { \"analysisId\": \"01...\", \"appRouter\": true }, \"id\": 4 }`\n  - Result: `{ \"jobId\": \"01...\", \"scaffoldId\": \"01...\", \"outDir\": \".site2ts/staging\" }`\n\n- `generate`\n  - Request: `{ \"method\": \"generate\", \"params\": { \"analysisId\": \"01...\", \"scaffoldId\": \"01...\", \"tailwindMode\": \"full\" }, \"id\": 5 }`\n  - Result: `{ \"jobId\": \"01...\", \"generationId\": \"01...\" }`\n\n- `diff`\n  - Request: `{ \"method\": \"diff\", \"params\": { \"generationId\": \"01...\", \"baselines\": \"recrawl\", \"viewport\": {\"w\":1280,\"h\":800,\"deviceScale\":1}, \"threshold\": 0.01, \"renderReport\": true }, \"id\": 6 }`\n  - Result: `{ \"jobId\": \"01...\", \"diffId\": \"01...\", \"perRoute\": [...], \"summary\": {\"passed\":1,\"failed\":0,\"avg\":0.004}, \"reportPath\": \".site2ts/reports/diff/01.../index.html\" }`\n\n- `audit`\n  - Request: `{ \"method\": \"audit\", \"params\": { \"generationId\": \"01...\", \"tsStrict\": true, \"eslintConfig\": \"recommended\" }, \"id\": 7 }`\n  - Result: `{ \"jobId\": \"01...\", \"auditId\": \"01...\", \"tsc\": {\"errors\":0, \"reportPath\":\"...\"}, \"eslint\": {\"errors\":0, \"warnings\":2, \"reportPath\":\"...\"} }`\n\n- `apply`\n  - Request: `{ \"method\": \"apply\", \"params\": { \"generationId\": \"01...\", \"target\": \"./\", \"dryRun\": false }, \"id\": 8 }`\n  - Result: `{ \"jobId\": \"01...\", \"applied\": true, \"changedFiles\": [\"app/...\"], \"deletedFiles\": {\"removed\":[...], \"skipped\":[...]} }`\n\n- `improve`\n  - Request: `{ \"method\": \"improve\", \"params\": { \"generationId\": \"01...\", \"route\": \"/\", \"instructions\": \"note for the next pass\" }, \"id\": 9 }`\n  - Result: `{ \"jobId\": \"01...\", \"acknowledged\": true, \"planPath\": \".site2ts/reports/improve/01....json\" }`\n\n- `assets`\n  - Request: `{ \"method\": \"assets\", \"params\": { \"generationId\": \"01...\" }, \"id\": 9 }`\n  - Result: `{ \"jobId\": \"01...\", \"manifestPath\": \".site2ts/reports/assets-manifest.json\" }`\n\n- `pack`\n  - Request: `{ \"method\": \"pack\", \"params\": { \"generationId\": \"01...\" }, \"id\": 10 }`\n  - Result: `{ \"jobId\": \"01...\", \"tarPath\": \".site2ts/exports/site2ts-mvp.tgz\" }`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finqwise%2Finqwise-mcp-site2ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finqwise%2Finqwise-mcp-site2ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finqwise%2Finqwise-mcp-site2ts/lists"}