PL/SQL Intelligence

PL/SQL Intelligence Engine

Offline, package-aware Oracle PL/SQL code intelligence in Rust, with a self-healing coverage flywheel.

[](https://github.com/MuhDur/plsql-intelligence/actions/workflows/ci.yml) [](https://github.com/MuhDur/plsql-intelligence/actions/workflows/usr.yml) [](#license) [](#design-commitments) [](rust-toolchain.toml)

> Know what breaks before you change Oracle PL/SQL.

# Build the workspace and run the default test profile
git clone https://github.com/MuhDur/plsql-intelligence
cd plsql-intelligence
cargo build --workspace && cargo test --workspace

---

TL;DR

The problem. In a large Oracle estate, PL/SQL packages, views, triggers and tables form a deep dependency web. Change one column type or one package spec and you can silently invalidate hundreds of downstream objects; you find out in a failed production recompile. Existing tools each cover a slice (SQL deployment, lineage products, SAST scanners, Oracle's own SQLcl MCP server), but none give offline, package-aware PL/SQL semantics with explicit uncertainty reporting, dependency reasoning, and recompile planning in one workflow.

The solution. A layered Rust workspace that parses PL/SQL with a real ANTLR backend, builds a semantic IR with name resolution and a dependency graph, and reports change impact. When the analyzer cannot be certain it says so, as a typed UnknownReason, instead of reporting a false-clean result. That honest-uncertainty exhaust feeds the USR Loop, which turns recorded gaps into proven, privacy-clean parser and lowering repairs so coverage compounds with use.

Two MCP servers: oraclemcp and plsql-mcp

This repo ships the full PL/SQL Intelligence MCP server, plsql-mcp: live Oracle DB tools plus offline PL/SQL intelligence (parse/analyze, dependency graph, lineage, SAST) and guarded writes. Its engine-free core was extracted to a standalone, published sibling, oraclemcp:

| | oraclemcp | plsql-mcp (this repo) | |---|---|---| | Scope | Guarded live Oracle DB access | The superset: DB access + PL/SQL intelligence + guarded writes | | Build | Engine-free, lean, fast | Full pure-Rust ANTLR engine | | Install | cargo install oraclemcp · docker run -i ghcr.io/muhdur/oraclemcp | cargo install plsql-mcp · docker run -i ghcr.io/muhdur/plsql-mcp | | MCP registry | io.github.MuhDur/oraclemcp | io.github.MuhDur/plsql-mcp |

Reach for oraclemcp when an agent just needs governed database access; use plsql-mcp when you want deep PL/SQL code understanding and the superset write surface. plsql-mcp is not presented as an intrinsically harmless server: destructive operations sit behind the shared guard ladder, operating levels, confirmations, and typed degradation responses inherited from the oraclemcp-* core.

> Independent open-source project; not affiliated with Oracle. The Docker images > ship the project binaries only; Oracle client libraries are not included.

Why use it?

| Capability | What it does | |------------|--------------| | Offline-first | Reads code and an Oracle catalog snapshot in place; no live database required for analysis, no telemetry by default | | Real parser backend | antlr4rust (plsql-parser-antlr), pure Rust, no JVM, with a lossless token tape (reconstruct(tape) == input) | | Honest uncertainty | Where analysis cannot be certain it emits a typed UnknownReason; the completeness report is never false-clean | | Dependency reasoning | Semantic IR, name resolution, a privilege model, and a dependency graph cross-checkable against ALL_DEPENDENCIES | | USR Loop | A self-healing flywheel: captured gaps become privacy-proven fixtures, candidate patches, and a 9-stage fail-closed conformance gate | | Verified accretion | A monotone coverage_index with a CI tripwire makes "coverage compounds" a checked property, not a slogan | | Memory safety | The whole workspace is #![forbid(unsafe_code)] |

How it compares

| | Live DB needed | Package-aware PL/SQL semantics | Honest uncertainty | Offline analysis | |---|:---:|:---:|:---:|:---:| | SQL deployment tools (Liquibase, Flyway) | yes | no | no | no | | Lineage / catalog products | varies | partial | no | varies | | Generic SAST scanners | no | no | no | yes | | Oracle SQLcl MCP server | yes | partial | no | no | | PL/SQL Intelligence Engine | no | yes | yes | yes |

---

Status

The latest completed release is v0.6.0, the line for trio stack-doctor parity and publication hardening. The project is still pre-1.0, so APIs can change before the 1.0 line. plan.md remains the authoritative specification and docs/ARCHITECTURE.md is the technical architecture snapshot.

• The v0.6.0 line adds the plsql-mcp doctor contract needed for

stack-wide parity with oraclemcp and rust-oracledb: doctor, doctor health, doctor capabilities, doctor robot-docs, doctor ls, doctor diff, doctor undo, and guarded doctor gc.

• The Cargo workspace has 26 members: 21 plsql-* engine and analysis

crates plus 5 tool crates (crates/, tools/). Release binaries are produced for plsql, plsql-depgraph, and plsql-mcp.

• The engine-free MCP server core lives in the standalone, published

oraclemcp repo. plsql-mcp consumes the published oraclemcp-* crates from crates.io instead of reimplementing that core locally. The PL/SQL layer adds the parser, semantic model, dependency graph, lineage, SAST, change-impact, and USR Loop surfaces.

• The one-way boundary holds: oraclemcp-* never imports a plsql-*

engine crate. This repo also gates the PL/SQL layer so it does not reach around the published oraclemcp-db adapter into Oracle drivers or async/server runtimes directly.

• The old Java parser crate is not part of the workspace or release path.

Parser work goes through the backend-independent plsql-parser surface and the pure-Rust antlr4rust backend in plsql-parser-antlr.

• The USR Loop (Layer 5) is implemented end to end: the

plsql-accretion library, the usr-loop tool, the sha-pinned conformance gate, the monotone tripwire, and the re-runnable acceptance proof scripts/usr_acceptance.sh.

• The post-v0.5.0 fast-follow lane is closed in v0.6.0: upstream

driver gaps needed by plsql-mcp are filed as rust-oracledb#13, oraclemcp#2, and oraclemcp#3. The live timeout adapter gap found during release testing is tracked as oraclemcp#4. The plsql-* crates are published on crates.io with explicit versioned internal dependencies.

• AGENTS.md describes how automated agents work in this repo.

---

Testing and Verification

The default local test profile is green on current main through GitHub Actions, including:

• cargo fmt --all -- --check
• cargo clippy --workspace --all-targets -- -D warnings
• cargo test --workspace --all-targets
• cargo test --workspace --doc
• cargo bench --workspace --no-run
• cargo deny check
• plan-lint, corpus license checks, parse-success checks, lab goldens,

demo-no-db, honesty grep, boundary lint, and the oraclemcp-* pin guard.

Live Oracle coverage is not hidden inside the default cargo test run. It is a separate feature-gated path: CI starts Oracle Free 23ai with make demo-oracle-xe-ci and runs the plsql-mcp JSON-RPC live-wire test under --features live-xe. The live catalog snapshot tests are wired the same way for developer or orchestrated runs with the container available.

Do not read this as "there are no test doubles anywhere." The repo contains deliberate test stubs and mocks where they pin a boundary: the feature-off live-XE sentinels, GitHub Action posting self-tests, fail-closed bindgen wrappers for invalid identifiers, hermetic Oracle connection doubles, and the deterministic USR proposer path. Those are not unfinished production placeholders. The production plsql-mcp serve surface has a drift guard that rejects "unimplemented" and "not wired" claims from the agent-facing contract; the release-visible docs also pass the broader honesty-grep gate.

The private-estate Definition of Done is honest about its boundary. When PLSQL_PRIVATE_ESTATE is absent, scripts/usr_acceptance.sh exits successfully with an estate-absent banner and does not claim the full estate proof. The nightly workflow keeps that script exercised up to the estate boundary; the binding full proof requires an estate-bearing host.

---

Quick Example

# Build the workspace and run the default test profile
cargo build --workspace
cargo test --workspace

# Clippy with the project's deny-warning policy
cargo clippy --workspace --all-targets -- -D warnings

# Inspect the MCP server and its machine-readable contract
cargo run -p plsql-mcp -- info
cargo run -p plsql-mcp -- --robot-json capabilities
cargo run -p plsql-mcp -- --json doctor
cargo run -p plsql-mcp -- --json doctor health

# Drive the USR Loop against an estate (read in place, nothing copied out)
cargo run -p usr-loop -- scan    /path/to/estate
cargo run -p usr-loop -- cluster /path/to/estate
cargo run -p usr-loop -- propose /path/to/estate --from-scan
cargo run -p usr-loop -- doctor

# The re-runnable Definition of Done for the USR Loop
scripts/usr_acceptance.sh

---

The USR Loop (self-healing coverage flywheel)

Most analyzers discard parse errors and unresolved references as failure. This one records them as typed, provenanced, minimizable, offline artifacts, then repairs them. The full normative specification is docs/plans/2026-05-19-usr-loop-self-healing-coverage-flywheel.md; the repair-class policy and gate honesty manifest are in docs/decisions/D3-usr-repair-class-policy.md.

 estate (read in place; no byte copied out)
   │  plsql-engine analyze → typed diagnostics + UnknownReason + provenance
   ▼
 [A] GAP CAPTURE      filter repairable diagnostic classes → GapRecord
   ▼                  (provenance only, never source bytes)
 [B] MINIMIZE +       smallest input that still triggers the same
     PRIVACY-PROVE     signature; every literal/identifier re-synthesized;
   ▼                  a redaction-delta manifest proves zero leak
 [C] CLUSTER/DEDUP    N occurrences → 1 GapCluster, K representative
   ▼                  fixtures
 [D] PROPOSE          one candidate diff, exactly one repair class
   ▼                  (g grammar / l lowering / d typed degradation)
 [E] CONFORMANCE GATE the 9-stage, fail-closed, sha-pinned bar
   ▼ pass                       ▼ fail
 [F] LAND + LEDGER     [F'] QUARANTINE-AS-OPEN-BEAD
   apply on branch,    file a provenanced bead naming the failing
   add the fixture +   stage; the gate is never weakened to admit it
   a pinned test,
   append one
   content-addressed
   ledger entry
   ▼
 [G] ACCRETION TRIPWIRE  the monotone coverage_index, CI-checked

Invariants (the spec's spine; each is enforced, not aspirational)

| Invariant | What it guarantees | |-----------|--------------------| | I-PRIVACY | No customer byte leaves the estate. Every persisted artifact is a re-synthesized, structurally-equivalent minimal reproduction, proven leak-free per artifact (gate stage G8). A failed privacy proof aborts the run and persists nothing. | | I-NO-REGRESSION | A patch lands only if proven behavior-preserving on the whole corpus: lossless round-trip, backend conformance, golden isomorphism, monotonic non-regression. Propose, prove, then land; never auto-merge unproven. | | I-NO-GAMING | A coverage gain counts only with a commensurate, measured rise in extracted semantics for the targeted signature. Suppressing a diagnostic to "fix" a gap is auto-rejected at G7. | | I-DETERMINISM | Same estate plus same engine commit yields byte-identical gap records, fixtures, signatures, and candidate set. No wall-clock, no RNG, no map-iteration order in any persisted artifact. | | I-PROVENANCE | Every record, fixture, candidate, verdict, and landed patch is content-addressed and traces estate-run to diagnostic to fixture to diff to gate result. The ledger is append-only. | | I-ISOLATION | Patches touch only the .g4 grammar, plsql-parser-antlr codegen / lowering, or the typed-degradation classifier; never make a downstream crate depend on ANTLR types or break public contracts non-additively. | | I-MONOTONIC-VALUE | The tracked coverage_index is monotone non-decreasing across releases. A release that lowers it fails CI. |

The conformance gate

scripts/usr_gate.sh runs nine ordered stages, all must pass, fail-closed. Any non-pass rejects the candidate and files it as a bead; the gate is never weakened to admit a patch.

| Stage | Check | |-------|-------| | G1 | Builds: plsql-parser-antlr --features antlr-codegen and the workspace | | G2 | Lossless round-trip over the full corpus and every prior MinFixture | | G3 | Backend conformance (plsql-parser/tests/conformance.rs) | | G4 | Golden isomorphism, or an explicitly listed and justified golden delta | | G5 | Never-panic plus the fuzz targets, zero crashes | | G6 | Monotonic non-regression (scripts/estate_correctness.sh, metrics at or above baseline) | | G7 | Anti-gaming and honesty: diagnostics fall only with a commensurate extraction rise; posture not weakened | | G8 | Privacy: redaction-delta verified over the candidate and every added fixture; a leak aborts the run | | G9 | The added regression test is mutation-killed (fails if the patch is reverted) |

The gate script is content-pinned: crates/plsql-accretion/gate.sha256 holds the expected sha256 and plsql-accretion's gate runner aborts on a mismatch. Changing the gate requires a deliberate, human-reviewed commit plus a sha bump. crates/plsql-accretion/tests/gate_selftest.rs feeds the gate an adversarial trio (a suppression-only patch, a privacy-leaking fixture, a round-trip-breaking patch) and asserts each is rejected at its named stage.

coverage_index and the tripwire

coverage_index = extracted_semantics_ratio        (frozen public corpus
                                                    benchmark, never
                                                    private estate code)
               + distinct_resolved_gap_signatures  (signature classes the
                                                    loop has permanently
                                                    closed, from the
                                                    append-only ledger)

scripts/accretion_tripwire.sh (a required CI check) asserts coverage_index(HEAD) >= coverage_index(last release tag) and extracted_semantics_ratio(HEAD) >= extracted_semantics_ratio(last release). Fresh CI checkouts compare against the tracked deterministic seed in crates/plsql-accretion/accretion_floor.json, so the first floor is durable even though .usr/ledger/ is scratch. A release that lowers either metric fails. The coverage_index-over-time table lives in CHANGELOG.md.

Definition of Done

scripts/usr_acceptance.sh is the single re-runnable acceptance contract. It is not a "looks built" check: it drives the loop to close a real, currently-open gap in a private estate end to end and asserts every invariant held (provenance, privacy-proven fixture, gate exit 0 or correct quarantine, strict signature decrease, strict extracted_semantics_ratio increase, preserved posture, ledger appended exactly once, mutation-killed test, green adversarial gate self-test, byte-identical double run). When no private estate is configured the script exits 0 with a loud "estate-absent" banner, stating that the DoD is not prove

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MuhDur
• Source: MuhDur/plsql-intelligence
• License: Apache-2.0
• Homepage: https://github.com/MuhDur/plsql-intelligence

Install and usage instructions live in the source repository linked above.