DefectAssessment MCP Server (Node.js)

通过 MCP (Model Context Protocol) 暴露 DefectAssessment 的桥梁、边坡、工地、评估等操作，供 Cursor 等 MCP 客户端使用。Node.js 实现，支持 npx 运行。

• 内置 AGENTS.md 与 Cursor 规则，AI 识别关键词（桥梁、边坡、工地等）时自动优先调用本 MCP 工具

前置条件

1. DefectAssessment API 已启动（默认端口 8333）
2. 已创建 API Token：在 DefectAssessment 中登录后，调用 POST /api/auth/api-tokens 创建长期 Token
3. Node.js 16+（推荐 18+）

获取 Token

1. 使用 DefectAssessment 正常登录：POST /api/auth/login（用户名+密码）
2. 使用返回的 token 调用：POST /api/auth/api-tokens，Body: {"name": "MCP Server"}
3. 响应中的 token 字段即为长期 Token（仅展示一次，请妥善保存）

安装

cd DefectAssessmentMCP_Node
npm install
npm run build

使用方式

通过 npx（推荐）

若已发布到 npm（作用域包）：

npx @codevdynamics/defect-assessment-mcp

若未发布，使用本地路径：

npx /path/to/DefectAssessmentMCP_Node

或在项目目录内：

npx .

直接运行

node dist/index.js

配置 Cursor

在 ~/.cursor/mcp.json 中新增：

{
  "mcpServers": {
    "defect-assessment": {
      "command": "npx",
      "args": ["@codevdynamics/defect-assessment-mcp"],
      "env": {
        "DEFECT_ASSESSMENT_BASE_URL": "http://localhost:8333",
        "DEFECT_ASSESSMENT_TOKEN": "<你的 token>"
      }
    }
  }
}

若未发布到 npm，可改用本地路径：

"defect-assessment": {
  "command": "npx",
  "args": ["/absolute/path/to/DefectAssessmentMCP_Node"],
  "env": {
    "DEFECT_ASSESSMENT_BASE_URL": "http://localhost:8333",
    "DEFECT_ASSESSMENT_TOKEN": "<你的 API Token>"
  }
}

DEFECT_ASSESSMENT_TOKEN 必填，否则 MCP 启动会报错。

配置完成后，若在本项目目录下使用 Cursor，AGENTS.md 与 .cursor/rules/ 中的规则会使 AI 在收到「列出桥梁」「所有工地」等指令时自动调用对应 MCP 工具。

可用工具

| 分类 | 工具 | 说明 | 自然语言示例 | | ---- | ---- | ---- | ------------ | | 桥梁 | create_bridge, list_bridges, get_bridge, update_bridge, delete_bridge, get_bridge_defect_statistics | 桥梁 CRUD 与缺陷统计 | 「列出所有桥梁」→ list_bridges | | 边坡 | create_slope, list_slopes, get_slope, update_slope, delete_slope, get_slope_defect_statistics | 边坡 CRUD 与缺陷统计 | 「边坡列表」→ list_slopes | | 工地 | create_construction_site, list_construction_sites, get_construction_site, update_construction_site, delete_construction_site, get_construction_site_defect_statistics | 工地 CRUD 与缺陷统计 | 「所有工地」→ list_construction_sites | | 评估 | list_assessments, get_assessment, bulk_delete_assessments, get_assessment_defect_results | 评估查询与缺陷结果 | 「评估列表」→ list_assessments |

资源（供 AI 生成简报时读取）

| URI | 说明 | | ------------------------------------ | --------------------------------------------------------------------------- | | defect://overview | 全系统概览：桥梁、边坡、工地、评估汇总数据 | | defect://briefing-data/{entity_type} | 按实体类型筛选的简报数据，entity_type 为 bridge、slope 或 construction_site |

提示词

| 名称 | 说明 | | ------------------------- | ----------------------------------------------------- | | generate_defect_briefing | 生成缺陷评估简报。参数：scope、focus_entity_id、style | | manage_bridges | 管理桥梁：列出、创建、编辑、删除的操作指引 | | manage_slopes | 管理边坡：列出、创建、编辑、删除的操作指引 | | manage_construction_sites | 管理工地：列出、创建、编辑、删除的操作指引 |

使用方式：简单查询（如「列出桥梁」）会由 AGENTS.md 规则引导 AI 直接调用工具；复杂操作可先调用 manage_* 提示词获取指引再执行；简报类可先读取 defect://overview 再使用 generate_defect_briefing。

AI 工具优先使用规则

项目内置规则文件，让 AI 在识别到关键词时自动优先使用 defect-assessment MCP 工具，无需先搜索其他工具：

| 文件 | 适用 | 说明 | |------|------|------| | AGENTS.md | Cursor、Copilot、Claude Code、Windsurf 等 25+ AI 工具 | 项目根目录，符合 AGENTS.md 标准，自动被多数 AI 发现并读取 | | .cursor/rules/defect-assessment-mcp.mdc | Cursor | Cursor 专用规则，更细粒度的工具映射 |

触发关键词：桥梁、边坡、工地、评估、缺陷 → 对应 list_bridges、list_slopes、list_construction_sites 等工具。

项目结构

DefectAssessmentMCP_Node/
├── AGENTS.md              # AI 工具通用指令（桥梁/边坡/工地等关键词 → 优先本 MCP）
├── .cursor/rules/         # Cursor 专用规则
├── src/index.ts           # MCP 服务入口
└── README.md

环境变量

| 变量 | 默认值 | 说明 | | -------------------------- | ------------------------- | ------------------------- | | DEFECT_ASSESSMENT_BASE_URL | http://192.168.1.103:8333 | DefectAssessment API 地址 | | DEFECT_ASSESSMENT_TOKEN | (必填) | 长期 API Token |

发布到 npm

1. 注册 npm 账号：https://www.npmjs.com/signup
2. 登录：npm login
3. 构建并发布：npm publish

若使用作用域包（如 @your-org/defect-assessment-mcp），发布时需加 --access public：

npm publish --access public

发布后，用户可直接运行：npx @codevdynamics/defect-assessment-mcp。

DefectAssessment 数据库迁移

首次使用前，需在 DefectAssessment 中执行 api_tokens 表迁移：

mysql -u user -p defect_assessment_db < DefectAssessment/migrations/002_add_api_tokens.sql