MCP DB Wizard

MCPDBWizard

一个基于你选择的对象构建的 Oracle MCP 服务。 在控制台中勾选 PL/SQL 包、 表、序列和你自行测试过的 SQL 语句，它便会生成一个 Model Context Protocol 服务， 将且仅将这些对象作为类型化工具提供给 AI Agent——每个工具都包含一个根据过程真实签名推导出的 JSON Schema。

这里没有 run-sql 工具。 任何未选中的内容都不会有工具、方法或类：它不会在运行时被拒绝，而是根本不存在于二进制文件中。运行时也不会拼接查询——生成的代码是包含固定 SQL 语句和类型化绑定的普通 Java，MCP 服务调用这些封装，而不是编写供模型执行的 SQL。

生成这个服务也意味着生成整个调用层，因此你还会获得：类型化 DAO 工厂、可调用语句封装、表管理器以及可选的 SOAP 层。它们本身也很实用，但 MCP 服务才是重点。

支持 Oracle 12c 至 26ai，并已针对覆盖该范围的六个实时实例进行回归测试。

完整产品的组成方式。本仓库包含生成器——配置文件、生成并编译，以及生成的 MCP 服务。Design 页面、Runtime 页面和代理位于 Docker 镜像中的 Web 控制台；在这里，你可以改用 Swing 工具或配置文件选择对象，生成的服务也可以独立运行。

---

难点所在

通常的做法是给 Agent 一个 run-sql 工具，但当面对真实的架构时，这种方法就会失效：与整洁的基准测试相比，已发布的 text‑to‑SQL 准确率在企业规模的架构上会大幅下降；而一个错误的 UPDATE 不是错误答案，而是一次事故。

另一种做法是精心设计工具——但手动为每个过程编写一个工具，数量多了就难以扩展；而且 PL/SQL 特别不适合自动推导：

• 一个过程可以有任意数量的 OUT 和 IN OUT 参数，而不只是单个返回值
• 参数可以是记录（包括嵌套在其他记录中的记录）、集合、 %ROWTYPE、REF CURSOR、包类型和重载
• Oracle 自身的数据字典在不同版本中的描述方式各不相同

本项目会完成这一推导。每个生成的 MCP 工具都包含根据过程实际签名构建的真实 JSON Schema，因此 Agent 会被告知参数是什么，而不是从说明文字中自行推断。

oracle:  PROCEDURE order_summary(p_customer IN  NUMBER,
                                 p_totals   OUT summary_rec,
                                 p_lines    OUT SYS_REFCURSOR)

tool:    order_summary { "p_customer": <number> }
      -> { "p_totals": { "orderCount": 12, "value": 4210.55 },
           "p_lines":  [ { "sku": "AB-1", "qty": 3 }, ... ] }

记录会以 JSON 对象形式传递，REF CURSOR 会以行对象数组形式传递，DATE 会以 ISO‑8601 字符串形式传递，RAW 和二进制向量会以 base64 形式传递，CLOB 会以文本形式传递，BLOB 会以 base64 形式传递。

---

快速开始

需要 Java 21 和 Maven。Oracle JDBC 驱动（com.oracle.database.jdbc:ojdbc11） 来自 Maven Central——无需手动安装。

mvn clean package

这会在 target/ 中生成两个 jar：一个普通 jar，以及一个内置驱动的独立 mcpdbwizard-app-<version>-shaded.jar。

# Interactive (Swing) -- pick objects and options, save a config
java -jar target/mcpdbwizard-app-*-shaded.jar <log_dir> myconfig.pb2

# Batch -- regenerate from a saved config
java -jar target/mcpdbwizard-app-*-shaded.jar <log_dir> build myconfig.pb2

如果 <log_dir> 不存在，则会创建它。

2026-08 年变更： 以前命令开头有一个 <access_code> 参数。该参数已 移除，仍然传入该参数的命令行会将其视为日志目录。 该参数只会验证格式——至少 19 个字符、不是路径、不是字面值 build—— 随后便会被忽略，因此不会进行任何身份验证。请从任何传入该参数的脚本中将其删除。

配置文件可以是 .pb2（扁平属性文件）或 .json；两种格式都可接受，并且可以无损地双向转换：

java -cp target/mcpdbwizard-app-*-shaded.jar \
     com.mcpdbwizard.schema.ConfigConverter myconfig.pb2 myconfig.json

---

生成内容

DAO 工厂	每个配置对应一个入口点，用于配置连接和日志记录
PL/SQL 包装器	每个过程/函数对应一个类——setParamX、executeProc、getParamY
表管理器	按主键执行行 CRUD，以及按唯一键、索引和外键子表查找
SQL 语句类	你自己的 SQL，带有类型化绑定参数
SOAP 服务层	可选
JSON / JSON-RPC 连接器	可选
MCP 服务	可选（需要 Java 17+ 才能使用 MCP SDK）

生成的代码仅依赖本仓库中的运行时库 com.mcpdbwizard.pub。

MCP 服务

生成一个 <Factory>McpServer.java，默认通过 stdio 通信，也可在使用 http [port] 启动时通过 Streamable HTTP 通信。可选的 bearer-token 身份验证和 TLS 都会在运行时从环境变量读取密钥；如果密钥未设置，则会安全失败，因此生成的源代码中不会包含任何密钥。

它会公开 PL/SQL 例程、表行 CRUD 和二级查找、用户 SQL 语句、序列，以及——在 23ai 上——支持文档 CRUD 和 etag 乐观锁定的 JSON 关系型双向视图。

公开内容在生成时确定，而非运行时。 未选择的对象完全不会生成代码；TABLE_MCP_CRUD_<i> 可将表的操作范围缩小到创建/读取/更新/删除的任意子集。未公开的操作不会生成工具方法——它们不会存在于二进制文件中，而不仅仅是未注册。

---

Oracle 数据类型支持

除常见标量类型和 LOB 外，还支持：12c 标识列和扩展的 VARCHAR2/RAW；21c 原生 JSON；23ai 原生 BOOLEAN、VECTOR（稠密、二进制和稀疏）以及 JSON 关系型双向视图。

已知缺口：TIMESTAMP WITH [LOCAL] TIME ZONE 和 BFILE 可作为过程参数传递，但尚不能用作表列；SDO_GEOMETRY 没有 JSON 映射，因此会跳过使用该类型的例程；FLOAT16 向量在服务端被禁用。

---

日志记录

生成的工厂会根据配置选择一种 LogInterface 实现：控制台、文本文件、java.util.logging、Log4j 1.x、SLF4J 或 Log4j 2。SLF4J 和 Log4j 2 后端位于 com.mcpdbwizard.pub 中，且仅依赖 facade jar；它是可选依赖——如果使用这些后端，请自行提供 api 和绑定。

---

测试

数据库无关测试套件无需任何配置，在全新克隆后即可通过：

mvn test

需要 Oracle 的测试设有门控：无法连接数据库时会跳过，而不是失败。 若要将它们指向你自己的实例，请复制模板——实际文件已加入 gitignore，且 不会离开你的计算机：

cp src/test/resources/test-boxes.properties.template src/test/resources/test-boxes.properties
cp Scripts/tns/tnsnames.ora.template                 Scripts/tns/tnsnames.ora
cp Scripts/boxes.env.template                        Scripts/boxes.env

对于每项设置，环境变量（MCPDBWIZARD_TEST_HOST 等）始终优先于文件，这样 一次运行就能选择不同的服务。

第三层测试依赖于生成器输出：Scripts/testrun_current.sh 会根据一组配置重新生成代码并进行编译，随后一系列测试框架会用该代码连接实时数据库进行测试。

**这一层不属于本仓库，其中所需的架构也不属于本仓库。**这些配置会检查 Oracle 架构，而这些架构的结构并非我们可以公开的——其中有些来自多年前的客户项目——并且配置会枚举其指向的架构，因此配置本身也不能随项目发布。测试框架也同样不能发布：它们会引用这些架构中的表和例程，并且只有针对重新生成的代码树才能编译，而这里不可能存在这样的代码树。

这对你意味着：运行生成器无需任何额外内容，运行测试套件也无需任何额外内容。在全新克隆后，数据库无关测试是完整且通过的；设有门控的实时测试则会跳过。你无法获得的是一套可供重新生成的现成样本。Scripts/check_provisioning.sh 仍会保留，它会准确列出配置所需的对象；如果你要构建自己的配置，可以从这里着手。

examples/generated-output/ 展示了生成器的输出，无需连接数据库。

---

仓库布局

路径	说明
src/main/java/com/mcpdbwizard/pub	生成代码所链接的运行时库
src/main/java/com/mcpdbwizard/app	生成器——引擎、Swing UI、共享辅助工具
src/main/java/com/mcpdbwizard/schema	配置的类型化模型；.pb2 ↔ .json
src/main/java/com/mcpdbwizard/mcpdbwizardconnector	JSON / JSON‑RPC 连接器生成器
examples/generated-output	已纳入版本控制的生成器输出示例，重新生成于 2026‑08‑07
Scripts/	重新生成、配置检查和导出门控
API 文档	为 com.mcpdbwizard.pub 生成的 javadoc，即你所链接的库

贡献者说明——架构、约定和积累的注意事项——见 CLAUDE.md。

---

API 文档

com.mcpdbwizard.pub 的 API 文档

这是生成代码所链接的运行时库，也是唯一有文档说明的包——生成器自身的内部实现不对外公开，发布这些内容会掩盖你实际调用的部分。包概要会说明应使用哪些内容，并包含兼容性约定：其中的签名对该生成器产出的所有程序都至关重要，因此只会增加方法，不会更改已有方法。

同一套页面也发布在项目网站的 mcpdbwizard.com/javadoc 上。两处文档都会在发布时从源代码重新生成，而不是相互复制。

在本地运行 mvn javadoc:javadoc，会将文档写入 target/reports/apidocs/。该命令启用了 failOnWarnings，因此失效的 @link 会导致构建失败，而不会让无效的交叉引用随版本发布。

---

已知问题

已知问题 — 问题是什么、调用方遇到问题时实际会看到什么，以及每个问题的解决方法。大多数问题不会主动显现：记录中的 JSON 键是生成的字段名而非列名、VECTOR 例程参数只能接受稠密数组，或配置中的工具数量超出了 Oracle 的 open_cursors。

其中每个尚未解决的问题也都是本仓库中的一个 issue，页面中附有对应链接。提交新 issue 前请先阅读；如果你正好遇到了其中某个问题，请在对应 issue 下说明，而不是另开一个。之所以有三个问题只记录了文档而尚未修复，是因为没人提出过需求，所以你的评论可能就能让“从来没人需要过”变成“有人需要”。

---

贡献

请参阅 CONTRIBUTING.md。打开拉取请求前，请先运行以下命令：

Scripts/export/check-export-clean.sh

如果代码库中混入了私有主机名、凭据或 jar 文件，该命令就会失败。

许可证

Apache License 2.0 — 请参阅 LICENSE 和 NOTICE。

此生成器生成的代码属于你自己的作品，不受本项目的许可证义务约束。它在运行时链接到 com.mcpdbwizard.pub，该库位于本仓库中，同样采用 Apache‑2.0 许可证，因此你可以按自己喜欢的条款发布生成的应用程序。