ktworkflow-mcp/README.md

KT Workflow MCP

ktWorkflow 是 KT 工作区的可复用 MCP 能力包，用来把根目录 AGENTS.md、SKILLS.md、TASKS.md 中的协作流程变成可调用工具。

能力边界

• 读取 KT 工作区上下文：项目清单、硬性规则、协作技能、最近任务记录。
• 检查子项目环境：Git/SVN、包管理器、Node 版本、env 文件、Git 状态。
• 生成防偏差工作包：把开工前检查、禁止项、风险扫描、验证计划汇总成一份可执行清单。
• 生成验证建议：按后端、前端、样式、页面、部署、MCP 等变更类型给出轻量验证命令。
• 生成页面测试用例：内置“先写用例、可视化证据、事不过三”的测试闭环。
• 生成接口测试计划：接口改动后输出真实调用命令和统一返回结构断言。
• 生成验证进程清理计划：按项目路径和端口给出 PowerShell 检查命令，不直接杀进程。
• 清理历史产物：按目录最近修改时间只保留最近 3 轮测试/验证产物，模板目录永久保留。
• 检查 env 策略和变更风险：提醒真实配置、锁文件、核心表格组件、部署链路等高风险改动。
• 生成或写入 TASKS.md 改动记录：默认 dryRun=true，确认后再落盘。
• 生成提交前检查清单：校验 KT commit message 约定。

安装

cd D:/MyFiles/KT/mcp/ktWorkflow
pnpm install
pnpm run self-test
pnpm run cleanup-history -- --dry-run

MCP 客户端配置

把下面配置加入支持 stdio MCP 的客户端配置里：

{
  "mcpServers": {
    "ktWorkflow": {
      "command": "node",
      "args": ["D:/MyFiles/KT/mcp/ktWorkflow/src/server.mjs"],
      "env": {
        "KT_WORKSPACE_ROOT": "D:/MyFiles/KT"
      }
    }
  }
}

工具列表

工具	用途
kt_read_context	读取 KT 根目录上下文和最近任务记录
kt_inspect_project	检查子项目仓库、包管理器、Node、env 和 Git 状态
kt_inspect_all_projects	一次性检查所有 KT 项目，适合多仓库联动任务
kt_guardrails	按任务类型生成开工、改动、禁止项和验证约束
kt_prepare_task	生成完整 work packet，降低开工偏差
kt_suggest_verification	生成轻量验证命令和注意事项
kt_create_page_test_case	生成页面级可视化测试用例
kt_api_test_plan	生成接口真实调用测试计划
kt_cleanup_history	清理历史测试/验证产物，默认预览，执行时只保留最近 3 轮
kt_cleanup_process_plan	生成验证进程清理检查命令
kt_env_policy	检查 env 文件现状和提交策略
kt_risk_scan	扫描当前或传入变更文件的偏差风险
kt_append_task_record	预览或写入 TASKS.md 改动记录
kt_commit_checklist	生成提交前检查清单并校验 commit message

项目别名

别名	路径
root	D:/MyFiles/KT
mcp	mcp/ktWorkflow
api	Node/kt-template-online-api
admin	Vue/kt-template-admin
web	Vue/kt-template-online-web
playground	Vue/kt-template-online-playground

使用建议

• 写代码前先调用 kt_prepare_task；只需要单项信息时再调用 kt_read_context 或 kt_inspect_project。
• 多项目联动时先调用 kt_inspect_all_projects。
• 不确定任务边界时调用 kt_guardrails，先拿到“能做什么、不能做什么、怎么验证”。
• 验证前调用 kt_suggest_verification，避免盲跑全量构建。
• 页面测试前调用 kt_create_page_test_case，再执行 Playwright/浏览器测试。
• 接口改动后调用 kt_api_test_plan，并真实请求一次接口。
• 验证启动过本地服务后调用 kt_cleanup_process_plan，清掉本次进程。
• 每轮测试/验证结束后调用 kt_cleanup_history，或运行 pnpm run cleanup-history -- --keep=3，让历史产物只保留最近 3 轮。
• 改完文件后用 kt_append_task_record 先 dryRun 预览记录，再决定是否写入。
• 提交前调用 kt_commit_checklist，确认文件范围和提交信息。