DBJavaGenix

DBJavaGenix

把"用 LLM 看着数据库做反向工程"做成一件可重复、可审计的事。 Skills 定义"怎么做" · MCP 提供"能做什么" · MCP Apps 让结果"看得见"。

graph LR
    Client[Claude Desktop / Cursor / Cherry] -->|Skill 加载| Skills
    Skills[".claude/skills/<br/>java-codegen-from-db<br/>springboot-migration"]
    Skills -->|按需调用| MCP

    subgraph MCP[MCP Server 34 工具]
        direction TB
        DB[db_* 连接 / 查询 / 描述]
        Atom[codegen_build_context<br/>codegen_render_entity/dao/service/<br/>controller/dto/mapper]
        Graph[schema_topo_order<br/>schema_cluster_tables<br/>schema_check_cycles]
        AI[ai_infer_business_names<br/>ai_recommend_template<br/>ai_summarize_schema]
        Vis[db_render_er_diagram]
        Obs[server_metrics / server_health<br/>ai_metrics / search_tools]
    end

    MCP -->|返回 _meta| Apps[MCP Apps 渲染]
    Apps -->|mermaid / dashboard / code-diff / tree| Client
    MCP -->|读取| Data[MySQL / PostgreSQL / SQLite + Mustache templates]

它解决什么问题

把数据库表反向生成成 Spring Boot 工程 (Entity/DAO/Service/Controller/DTO/Mapper) 不是新东西 —— EasyCode、MyBatis-Plus Generator、Renren-generator 都做了多年。LLM 时代的区别在于:

快速开始

Docker (推荐)

docker build -t dbjavagenix:latest .

在 claude_desktop_config.json 添加:

{
  "mcpServers": {
    "dbjavagenix": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "DBJAVAGENIX_PROGRESSIVE=1",
               "-e", "ANTHROPIC_API_KEY",
               "dbjavagenix:latest"]
    }
  }
}

本地 dev

git clone https://github.com/ZhaoXingPeng/DBJavaGenix.git
cd DBJavaGenix
uv venv && uv pip install -e ".[dev]"
PYTHONPATH=src python -m dbjavagenix.cli server

数据库支持范围

当前可连接、查询并读取元数据的数据库为 MySQL、PostgreSQL 和 SQLite。Oracle 与 SQL Server 的类型映射保留为后续扩展准备，但尚未实现运行时驱动和元数据契约，不能作为 当前可用数据库声明。

第一次使用

在 LLM 客户端里说 "从数据库 myapp 的 sys_user / sys_role / sys_user_role 三张表生成 Spring Boot 代码",Claude 会:

1. 加载 java-codegen-from-db Skill,按 5 阶段工作流推进
2. 调用 db_connect_test → db_table_describe → db_table_foreign_keys 收集 schema
3. 调用 db_render_er_diagram → 客户端渲染 Mermaid ER 图
4. 调用 ai_infer_business_names 推断 → sys_user_role 应是 UserRoleAssignment
5. 调用 ai_recommend_template 推荐 → 检测到 RBAC,推 MybatisPlus-Mixed
6. 用 codegen_build_context + 6 个 codegen_render_* 分层生成,每层返回 code-diff
7. 用户确认后写盘
8. 会话结束时调用 db_disconnect(connection_id) 释放连接

核心能力 (Phase 1 → 5)

Phase 1 现代化基础

• Python ≥ 3.11 / mcp ≥ 1.6 / Spring Boot 3.5 + Java 21 模板
• 单元测试 620+，GitHub Actions 分层 CI（提交策略、三版本质量、格式、数据库集成、模板、Docker、打包安装）
• 多阶段 Dockerfile (python:3.11-slim + 非 root 用户)

Phase 2 Skills 层与原子工具

• .claude/skills/java-codegen-from-db/SKILL.md 显式定义 5 阶段工作流
• db_codegen_generate 拆为 7 原子工具,context 显式传递
• search_tools 工具实现 progressive discovery,启动 token 节省 70.2%
• 第二个 Skill springboot-migration (2.7→3.x 升级 checklist)
• token usage benchmark

Phase 3 MCP Apps 集成

4 个交互式 UI 组件:

客户端兼容性 + headless 验证。

Phase 4 AI 语义增强

• ai_infer_business_names: 15 条规则 + 可选 Claude API (Anthropic SDK + prompt caching)
• ai_recommend_template: 检测 RBAC / 电商 / CMS / 工单 4 种模式
• ai_summarize_schema: 整库自然语言概述
• ai_metrics: 暴露 cache_hit_rate / tokens_saved
• 设计取舍: 规则先于 LLM,无 ANTHROPIC_API_KEY 也能跑

Phase 5 可观测性与生产就绪

• server_metrics: 每个工具的 calls / avg_duration / error_rate
• server_health: Python / mcp / anthropic SDK 版本 + 模块导入状态
• 结构化日志: DBJAVAGENIX_LOG_FORMAT=json 可输出单行 JSON,适合 Loki/ELK
• 部署手册: 3 种部署模式 + 6 个排障场景

工具总览 (34 个)

与同类工具对比

技术架构

详见 iteration-plan/01-target-architecture.md。三层职责:

[ Skills 层 ]  定义"怎么做" — .claude/skills/*.md  显式 5 阶段工作流
       ↓
[ MCP 层 ]     提供"能做什么" — 34 个原子工具  context 显式传递
       ↓
[ Apps 层 ]    让结果"看得见" — 4 个 UI 组件 (mermaid/dashboard/code-diff/tree)

每层都做"工程克制":

• 不引入向量数据库 (schema 是结构化数据,LLM 直接读更准)
• 不引入 LangChain (Skill 已显式编排,不需要 chain 抽象)
• 不引入 prometheus_client / opentelemetry-sdk (stdio 单进程过度设计)

文档

路线图

• Phase 1: 基础设施现代化 (Python 3.11 / mcp 1.6 / Spring Boot 3.5 模板 / CI / Docker)
• Phase 2: Skills 层抽离 + 原子工具 + Progressive Discovery (token -70%)
• Phase 3: MCP Apps 集成 (4 个 UI 组件)
• Phase 4: AI 语义增强 (规则 + 可选 LLM)
• Phase 5: 可观测性 + 生产就绪
• Phase 6: 文档与演示
• v0.2.1: Java 工程补完 (schema 算法 3 个 / 工程规范配置生成器 / 设计模式 catalog)
• v0.2.2: MCP v3 + AI 工程化 (elicitation 表单 / sampling 借 LLM / 1h prompt caching / agentic-runner)

下一步 (v0.3 候选):

• 完整优先级、前置条件和验收证据见 docs/roadmap-v0.3.md。
• 当前列表仅代表候选工作，不代表已实现或预先承诺的性能收益；CI 收尾安排在功能冻结之后。

启动模式

两种模式共用同一 database.mcp_tools 注册表 (ADR-010)。

调试技巧

# 启用 progressive 模式 (仅暴露 6 个 always_visible 工具)
DBJAVAGENIX_PROGRESSIVE=1 PYTHONPATH=src python -m dbjavagenix.cli server

# JSON 日志 (适合 Loki / ELK)
DBJAVAGENIX_LOG_FORMAT=json DBJAVAGENIX_LOG_LEVEL=DEBUG \
  PYTHONPATH=src python -m dbjavagenix.cli server

# headless 验证所有 MCP App 组件
PYTHONPATH=src python scripts/verify_mcp_apps.py

贡献

1. Fork → 创建 feature/* 分支
2. 写测试 (tests/unit/),pytest tests/unit/ 应保持 620+ 全过
3. ruff check src/ tests/ 通过 (CI 会跑)
4. 提 PR,链接到对应的 iteration-plan 阶段

许可证

MIT — 见 LICENSE。

致谢

• EasyCode — 早期模板设计灵感
• Model Context Protocol — Anthropic / Linux Foundation
• Anthropic Claude — AI 语义层

联系

• 作者: ZXP · 邮箱: [email protected]
• 仓库: https://github.com/ZhaoXingPeng/DBJavaGenix
• Issues: https://github.com/ZhaoXingPeng/DBJavaGenix/issues