java-to-html-mcp

通用 stdio MCP 服务：把 Java API 接口 / DTO 转成 HTML 文档，并支持字段定位、增删改与变更说明生成。

| | | | --- | --- | | npm | java-to-html-mcp | | CLI / bin | java-to-html-mcp | | MCP server 名 | java-to-html | | 当前版本 | 见 package.json（要求 Cursor 侧 ≥ 1.0.3） |

本包只做本地文件与文本处理，不绑定任何业务系统、文档库或代码托管平台。落库、发 MR、业务 profile 等由调用方自行编排。

能力

• 解析 Java → HTML + metaData
• 在给定目录下定位、增删改 DTO 字段（默认 不写 @ApiModelProperty）
• 生成通用变更说明（change_summary / change_json）
• 对 before/after Java 文本做字段级 diff
• package_info 返回运行中版本，便于排查 npx 缓存旧包

MCP Tools

| Tool | 作用 | | --- | --- | | package_info | 运行中包名/版本门禁 | | regenerate_html | entryFiles + 可选 path 入参/出参 / merge → HTML + meta | | locate_field | 在 searchRoots 下按 className / fieldName 定位 | | apply_field_change | add / update / remove 字段；支持 dryRun | | build_changelog | 通用变更说明；最终预览 versionNo 须用沙盒返回值；对外文案传 includePreview=false + fieldLabelStyle="path" | | diff_java_fields | before/after Java 文本 → FieldChange[] |

build_changelog 对外文案约定

面向外部读者（如渠道方）的 change_summary 不应暴露内部类名与不可访问的预览链接：

| 参数 | 用途 | |------|------| | includePreview | false 时不渲染「- 预览：…」行；此时 previewBaseUrl 可省略 | | fieldLabelStyle | path：用 changes[].fieldPath（缺省退化为 fieldName）+ 语义类型（List<FooDto> → 对象数组，FooDto → 对象），不输出类名 | | changes[].fieldPath / displayType | 逐条覆盖参数路径与类型文案 |

change_json 仍保留 className 等结构化信息，供调用方内部使用。

regenerate_html 大文档约定

| 参数 | 用途 | |------|------| | existingMetaDataPath | 从文件读旧 meta，避免把 40KB+ JSON 塞进工具入参 | | outputDir | 写出 documentHtml.html / metaData.json，默认响应不回传全文 | | mergeExistingApis | 默认 true：保留 entry 未解析到的既有 API path |

公共 npm（必须 pin 版本）

{
  "mcpServers": {
    "java-to-html": {
      "command": "npx",
      "args": ["-y", "[email protected]"]
    }
  }
}

Windows 若找不到 npx，将 command 改为 npx.cmd。

本地开发

npm install
npm run build
npm test
npm run mcp

构建使用 esbuild。相对路径基于进程 cwd；无必须环境变量。

发布

npm install
npm run build
npm test
npm publish

发布后通知调用方：更新 pin 版本并重载 MCP。

gen-doc-core

包内 src/gen-doc-core 基于独立的 Java→HTML 生成逻辑（parser / documentGen / types），不依赖 IDE 插件运行时。

目录结构

├── package.json
├── README.md
├── scripts/
│   └── build.mjs
└── src/
    ├── index.ts              # MCP 入口
    ├── javaFieldEditor.ts
    ├── changelogBuilder.ts
    ├── docRegenerator.ts
    ├── types.ts
    ├── gen-doc-core/
    └── test/