MyBatis MCP Server

MyBatis 字段名与数据库列名一致性检查工具

这是一个 MyBatis 配置验证工具，用于检查实体类（POJO）的字段名与数据库表的列名是否一致，以及相关的 MyBatis 配置是否正确。

功能特性

该工具提供以下 7 个 MCP 工具函数：

1. `check_entity_fields()`

检查实体类字段定义，列出所有字段名并检查与数据库列名的对应关系。

2. `check_result_maps()`

检查 Mapper XML 中的 resultMap 配置：

• resultMap 的 id 和 type 是否正确
• 每个 <result> 的 column 属性是否与 SQL 查询列名一致
• 每个 <result> 的 property 属性是否与实体类字段名一致
• 嵌套对象的字段映射是否正确

3. `check_mapper_annotations()`

检查 Mapper 接口中的 @Results 注解配置：

• @Results 数组中每个 @Result 的 column 和 property 是否正确
• @ResultMap 引用的 resultMap id 是否与 XML 中定义的完全一致

4. `check_sql_aliases()`

检查 SQL 语句中的列别名配置：

• 对于使用 resultType 的查询，SQL 语句中是否通过 AS 为列起别名
• 列别名是否与实体字段名匹配（考虑驼峰转换）

5. `check_join_queries()`

检查联合查询中的字段重复或歧义问题：

• 涉及多表关联的查询，是否存在同名字段
• 是否为重复列使用了唯一别名
• 在 resultMap 中是否正确映射

6. `check_type_handlers()`

检查特殊类型字段的类型处理器配置：

• 实体字段类型与数据库列类型不完全匹配的字段
• 是否配置了自定义 TypeHandler
• 检查全局配置、resultMap 和注解中的 typeHandler 属性

7. `generate_detailed_report()` ⭐

生成详细的 MyBatis 配置检查报告，只显示发现的问题，每个问题都以可直接使用的 prompt 格式呈现。

配置文件

在项目根目录创建 config.json 文件，配置以下路径：

{
  "entity_paths": [
    "src/main/java/com/example/entity",
    "src/main/java/com/example/model"
  ],
  "mapper_paths": [
    "src/main/resources/mapper",
    "src/main/java/com/example/mapper"
  ],
  "sql_files": [
    "src/main/resources/sql/schema.sql",
    "src/main/resources/db/migration/V1__init.sql"
  ],
  "report_path": "reports/mybatis_check_report.txt"
}

配置说明

• entity_paths: 实体类（POJO）的目录路径或文件路径，支持多个路径
• mapper_paths: Mapper XML 文件和 Mapper 接口的目录路径，支持多个路径
• sql_files: 数据库建表 SQL 文件的路径，支持多个文件
• report_path: 报告输出路径（可选，默认为 mybatis_check_report.txt）

重要特性

✅ 递归扫描: 工具会自动递归扫描配置目录中的所有子文件夹 ✅ 多路径支持: 支持配置多个 entity_paths、mapper_paths 和 sql_files ✅ 报告路径配置: 可自定义报告输出路径，支持绝对路径和相对路径 ✅ 自动创建目录: 如果报告目录不存在，工具会自动创建

使用方式

作为 MCP 服务器运行

python main.py

工具会自动加载 config.json 配置，并启动 MCP 服务器。

独立模式运行（用于测试）

如果未安装 mcp 包，工具会以独立模式运行，输出 JSON 格式的检查结果。

生成检查报告

使用 generate_detailed_report() 函数生成详细报告：

from main import generate_detailed_report

report = generate_detailed_report()
print(report)

报告会自动保存到配置的 report_path 路径。

检查报告格式

generate_detailed_report() 生成的报告只包含发现的问题，不显示正确的配置。报告包含以下部分：

1. 检查 Mapper XML 中的 resultMap

详细列出所有 resultMap 配置问题，每个问题都附带修复 prompt。

2. 检查 Mapper 接口中的 @Results 注解

检查注解配置问题，提供详细的修复指导。

3. 检查 SQL 语句中的列别名

验证列别名与实体字段的匹配情况。

4. 检查联合查询字段重复或歧义

识别多表关联查询中的潜在问题。

5. 检查特殊类型字段的类型处理器

标记需要自定义 TypeHandler 的复杂类型字段。

6. 检查总结

提供统计信息和整体评估。

问题级别

• ERROR: 严重问题，必须修复
• WARNING: 警告，建议尽快处理
• INFO: 信息提示，可能需要关注

示例输出

================================================================================
报告已保存到: D:\Workspace\project\reports\mybatis_check_report.txt

================================================================================
MyBatis 配置检查详细报告
================================================================================

【检查项 1】检查 Mapper XML 中的 resultMap
--------------------------------------------------------------------------------
检查内容：
  - resultMap 的 id 和 type 是否正确
  - 每个 <result> 的 column 属性是否与 SQL 查询列名一致
  - 每个 <result> 的 property 属性是否与实体类字段名一致
  - 嵌套对象的字段映射是否正确

发现 2 个问题：

  1. 问题级别: ERROR
     问题类型: RESULTMAP_PROPERTY
     问题描述: Property "deleteFlag" not found in entity Student
     位置: D:\Workspace\project\src\main\resources\mapper\student\StudentMapper.xml:BaseResultMap
     建议: 检查 Student 实体类是否存在 deleteFlag 字段，或修改 resultMap 中的 property 属性

  Prompt（用于修复此问题）：
  --------------------------------------------------------------------------------
  请修复以下 MyBatis resultMap 配置问题：

  问题级别: ERROR
  问题类型: RESULTMAP_PROPERTY
  问题描述: Property "deleteFlag" not found in entity Student
  位置: D:\Workspace\project\src\main\resources\mapper\student\StudentMapper.xml:BaseResultMap
  建议: 检查 Student 实体类是否存在 deleteFlag 字段，或修改 resultMap 中的 property 属性

  请：
  1. 打开文件: D:\Workspace\project\src\main\resources\mapper\student\StudentMapper.xml:BaseResultMap
  2. 根据问题描述定位问题
  3. 检查 resultMap 的 type 属性是否正确指向实体类
  4. 检查每个 <result> 的 property 属性是否与实体类字段名完全一致（区分大小写）
  5. 检查每个 <result> 的 column 属性是否与 SQL 查询中的列名一致
  6. 提供修复后的代码

【检查项 2】检查 Mapper 接口中的 @Results 注解
--------------------------------------------------------------------------------
检查内容：
  - Mapper 接口方法上的 @Results 或 @ResultMap 注解
  - @Results 数组中每个 @Result 的 column 和 property 是否正确
  - @ResultMap 引用的 resultMap id 是否与 XML 中定义的完全一致

发现 4 个问题：
  ...

================================================================================
检查总结
================================================================================

实体类数量: 142
数据库表数量: 44
ResultMap 数量: 2
Mapper 方法数量: 15

问题统计:
  - 错误 (ERROR): 4
  - 警告 (WARNING): 0
  - 信息 (INFO): 56
  - 总计: 60

⚠️  发现严重问题，请优先处理错误级别的问题！

================================================================================

依赖项

• Python 3.7+
• mcp>=0.9.0（可选，用于 MCP 服务器模式）

安装依赖

pip install -r requirements.txt

注意事项

1. 确保配置的路径正确且可访问
2. SQL 文件中的