Inqwise MCP Site2TS
通过MCP服务器（Rust）和Node助手（Playwright+Next.js）将现有网站转换为基于TypeScript的Next.js应用程序。ARM优先（macOS/Linux）。看 SITE2TS_MISSION_SPEC.md 获得权威MVP合同。
快速开始
- 阅读任务规范：
SITE2TS_MISSION_SPEC.md. - 跟踪进度：
PROGRESS.md（人类）和progress.json（机器可读）。 - 承诺政策：仅在重要里程碑或任务完成时。
回购布局
.site2ts/（运行时沙盒；在运行过程中生成）SITE2TS_MISSION_SPEC.md（MVP规则和API）PROGRESS.md和progress.json（任务+状态）
项目管理规则
- 任务定义见
PROGRESS.md并反映在progress.json. - 我们会在任务完成时更新进度；一次只有一个正在进行的任务。
- 提交是为重要的里程碑或任务的完成而保留的。
远程存储库
计划GitHub远程： git@github.com:inqwise/inqwise-mcp-site2ts.git （确认或提供其他名称）。
安装程序（一旦远程存在）：
# Initialize and set remote
git init
git remote add origin git@github.com:inqwise/inqwise-mcp-site2ts.git
# First milestone commit will be pushed like:
# git push -u origin main如果通过GitHub UI创建仓库，请选择：所有者 inqwise，回购名称 inqwise-mcp-site2ts，默认分支 main.
先决条件（运行时）
- Node 20 LTS，npm
- 剧作家（Chromium安装在第一个init上）
- Git（推荐）
状态
MVP规范编写；计划的实施任务。看 PROGRESS.md.
最近更新：
- Diff运行现在发出每条路线的摘要(
summary.json)使用热图和DOM选择器实现自动化。 tools/rpc.sh接受自定义超时(--timeout/RPC_TIMEOUT_SEC)，可选输出捕获(--capture)，并为每个RPC打印一行摘要。tools/full_flow.sh可以选择附加improveRPC通过--improve-route/--improve-note在应用步骤之后。tools/plan-improvements.js根据差异输出+记录的改进请求提出后续行动。
许可证
Apache-2.0--参见 LICENSE 了解详情。
运行手册
看 docs/RUNBOOK.md 用于端到端流和工件位置。
更多示例： docs/API_EXAMPLES.md.
在本地构建和运行
- 构建worker（TS）和server（Rust），然后发送一个JSON-RPC请求：
- tools/rpc.sh '{"jsonrpc":"2.0","method":"init","params":{"projectRoot":"."},"id":1}'
- 通过致电发送后续请求
tools/rpc.sh再次使用单行JSON对象（如果需要，每次运行都会构建并执行一个请求）。
笔记：
- Rust服务器从以下位置生成Node worker
node/site2ts-worker/dist/index.js，所以必须先造工人(npm run build).脚本这样做是为了方便。 - 对于交互式会话（一个进程中有多个请求），您可以直接运行服务器，并通过stdin为每个请求提供一行JSON。
差异总结和改进计划
- 运行后
diff，检查.site2ts/reports/diff///summary.json用于每条路线的热图和DOM区域排名。 - 使用
node tools/plan-improvements.js生成编排有效负载，总结最新差异并建议下一步行动。该脚本还抑制了已通过improveMCP方法。 - 改进请求在以下情况下持续存在
.site2ts/reports/improve/.json因此LLM/工具可以跟踪已经尝试过的操作。 - 目前，我们通过循环来迭代每个失败的DOM区域 diff → 改进 直到每区比率降至1以下 % 阈值（从上到下的最高元素开始）。每
improve调用应该描述要重写的确切元素或逻辑块；每次迭代后，我们都会重新运行diff，评估新summary.json/metrics.json，然后移动到下一个违规元素。
依赖关系策略
- 铁锈箱：固定在最新的次要/补丁系列上，以确保稳定性（见
rust/site2ts-server/Cargo.toml).我们定期跳到最新的稳定；破碎的凸起会被明确处理。 - 节点（工作者）：
- TypeScript工具链使用插入符号范围自动获取次要/补丁更新： - typescript (>=5.5), @typescript-eslint/* （v8）， eslint （v9）， prettier （v3）， eslint-plugin-import, eslint-config-prettier. - 运行时间deps(playwright, playwright-core, pixelmatch, pngjs, get-port等）也使用插入符号范围进行次要/补丁更新。
- 生成的暂存应用程序：
- next 固定到安全版本（当前为14.2.32）以避免已知的CVE。 - 开发工具链使用插入符号范围进行次要/补丁更新（TypeScript、Tailwind、PostCSS堆栈）。
路线图/下一步改进
- 顺风映射：扩展实用程序（颜色、阴影、线条高度/字母间距映射），减少CSS回退占用空间。
- 视觉差异：强化Next.js启动/截图时间；支持多个视口（移动）。
- Visual diff UX：生成一个HTML仪表板，将每条路线的屏幕截图和
JSON摘要来自 .site2ts/reports/diff 以便于审查。
- 应用：更深层次的路由感知删除；计划模式下的附加安全提示。
- 测试：HTML的单元测试→TSX和
mapInlineStyleToTw以避免倒退。 - 打包：JSON-RPC的可选CLI包装器；简单的配置文件支持。
- 平台：稍后将评估Windows支持（MVP的非目标）。
我们将打开GitHub Issues来跟踪这些项目；目前，本节作为权威的TODO列表。
故障排除
- 剧作家/Chromium失踪：运行
npx playwright install chromium（服务器在以下期间也会尝试此操作init).确保节点20 LTS处于活动状态。 - 转移中的Next.js构建错误：运行
npm install（或npm ci如果存在锁文件）.site2ts/staging/之前audit/diff. - 启动差异暂存应用程序时发生端口冲突：工作程序自动选择空闲端口；如果仍然失败，请重新运行
diff或杀死流浪狗node/next过程。 - 慢速站点的超时：更低
maxPages/maxDepth或提高阈值；重演crawl随着delayMs>0表示礼貌。 - 白板：删除
.site2ts/重置缓存和暂存。
JSON-RPC示例（MVP）
init
- 请求： { "method": "init", "params": { "projectRoot": "." }, "id": 1 } - 结果： { "ok": true, "pinned": { "node": "20.x", "next": "14.x", "ts": "5.x", "playwright": "1.x" } }
crawl
- 请求： { "method": "crawl", "params": { "startUrl": "https://example.com", "sameOrigin": true, "maxPages": 25, "maxDepth": 3 }, "id": 2 } - 结果： { "jobId": "01...", "siteMapId": "01...", "pages": [{"url":"...","hash":"..."}] }
analyze
- 请求： { "method": "analyze", "params": { "siteMapId": "01..." }, "id": 3 } - 结果： { "jobId": "01...", "analysisId": "01...", "routes": [...], "assets": {...} }
scaffold
- 请求： { "method": "scaffold", "params": { "analysisId": "01...", "appRouter": true }, "id": 4 } - 结果： { "jobId": "01...", "scaffoldId": "01...", "outDir": ".site2ts/staging" }
generate
- 请求： { "method": "generate", "params": { "analysisId": "01...", "scaffoldId": "01...", "tailwindMode": "full" }, "id": 5 } - 结果： { "jobId": "01...", "generationId": "01..." }
diff
- 请求： { "method": "diff", "params": { "generationId": "01...", "baselines": "recrawl", "viewport": {"w":1280,"h":800,"deviceScale":1}, "threshold": 0.01, "renderReport": true }, "id": 6 } - 结果： { "jobId": "01...", "diffId": "01...", "perRoute": [...], "summary": {"passed":1,"failed":0,"avg":0.004}, "reportPath": ".site2ts/reports/diff/01.../index.html" }
audit
- 请求： { "method": "audit", "params": { "generationId": "01...", "tsStrict": true, "eslintConfig": "recommended" }, "id": 7 } - 结果： { "jobId": "01...", "auditId": "01...", "tsc": {"errors":0, "reportPath":"..."}, "eslint": {"errors":0, "warnings":2, "reportPath":"..."} }
apply
- 请求： { "method": "apply", "params": { "generationId": "01...", "target": "./", "dryRun": false }, "id": 8 } - 结果： { "jobId": "01...", "applied": true, "changedFiles": ["app/..."], "deletedFiles": {"removed":[...], "skipped":[...]} }
improve
- 请求： { "method": "improve", "params": { "generationId": "01...", "route": "/", "instructions": "note for the next pass" }, "id": 9 } - 结果： { "jobId": "01...", "acknowledged": true, "planPath": ".site2ts/reports/improve/01....json" }
assets
- 请求： { "method": "assets", "params": { "generationId": "01..." }, "id": 9 } - 结果： { "jobId": "01...", "manifestPath": ".site2ts/reports/assets-manifest.json" }
pack
- 请求： { "method": "pack", "params": { "generationId": "01..." }, "id": 10 } - 结果： { "jobId": "01...", "tarPath": ".site2ts/exports/site2ts-mvp.tgz" }