# PL/SQL Intelligence > PL/SQL Intelligence MCP server — live Oracle DB tools + offline analyze/lineage/SAST (unofficial). - **Type:** MCP server - **Install:** `agentstack add mcp-muhdur-plsql-intelligence` - **Verified:** Pending review - **Seller:** [MuhDur](https://agentstack.voostack.com/s/muhdur) - **Installs:** 0 - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [MuhDur](https://github.com/MuhDur) - **Source:** https://github.com/MuhDur/plsql-intelligence - **Website:** https://github.com/MuhDur/plsql-intelligence ## Install ```sh agentstack add mcp-muhdur-plsql-intelligence ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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. ```sh # Build the whole workspace and run every test 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`**](https://github.com/MuhDur/oraclemcp): | | [`oraclemcp`](https://github.com/MuhDur/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 --path crates/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 (it includes everything `oraclemcp` does). > _Independent open-source project; not affiliated with Oracle. The Docker images > ship the project binaries only; they do not bundle Oracle Instant Client._ ### 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 This is pre-1.0 software under active development. `plan.md` is the authoritative specification; `docs/ARCHITECTURE.md` is the technical architecture snapshot. - The Cargo workspace ships 22 `plsql-*` engine and analysis crates plus 5 tool binaries (`crates/`, `tools/`). The engine-free MCP server core (8 `oraclemcp-*` crates: protocol, tool registry, the fail-closed SQL guard, audit sink, auth, telemetry, config, error envelope) was extracted to the standalone, published [`oraclemcp`](https://github.com/MuhDur/oraclemcp) repo; `plsql-mcp` now consumes them from crates.io. The one-way boundary (`oraclemcp-*` never imports a `plsql-*` engine crate) holds by construction and is enforced in the oraclemcp repo's CI. The foundation and product layers are implemented; live Oracle catalog extraction, the `verify`/CI-cascade path, and the live-DB MCP tool surface are feature-gated and exercised against a containerized Oracle 23ai (`live-xe` suites, `make demo-oracle-xe-ci`). - 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 API can change before 1.0. - `AGENTS.md` describes how automated agents work in this repo. --- ## Quick Example ```sh # Build the workspace and run the full test suite 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 # 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)`. A release that lowers it fails. The `coverage_index`-over-time table lives in `CHANGELOG.md`; the first release seeds the monotone floor deterministically. ### 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 proven in that environment. CI runs the full acceptance proof nightly (`.github/workflows/usr.yml`). --- ## Architecture The workspace is layered (full detail in `plan.md` §5 and `docs/ARCHITECTURE.md`). Downstream crates never depend on ANTLR-generated types. | Layer | Crates | What it owns | |-------|--------|--------------| | 0 | `plsql-core`, `plsql-output`, `plsql-render`, `plsql-store` | Diagnostics, completeness/uncertainty, output shapes, content-addressed cache | | 1 | `plsql-parser`, `plsql-parser-antlr` | Backend-independent parser surface plus the ANTLR backend | | 1.5 | `plsql-catalog` | Oracle catalog snapshot model plus live extraction | | 2 | `plsql-ir`, `plsql-symbols`, `plsql-privileges`, `plsql-depgraph` | Semantic IR, name resolution, privilege model, dependency graph | | 3 | `plsql-engine` | Orchestration: per-run `AnalysisRun`, `CompletenessReport` | | 4 | `plsql-lineage`, `plsql-doc`, `plsql-bindgen`, `plsql-cicd`, `plsql-sast` | Lineage, docs, Rust bindings, change-set planning, static analysis | | 5 | `plsql-mcp`, `plsql-accretion` | The unified MCP server plus the USR Loop library (no reverse deps) | | MCP core (external) | `oraclemcp-core`, `oraclemcp-guard`, `oraclemcp-db`, `oraclemcp-audit`, `oraclemcp-auth`, `oraclemcp-telemetry`, `oraclemcp-config`, `oraclemcp-error` | Engine-free MCP server core: protocol/registry, the fail-closed SQL guard and operating-level state, the connection layer, the out-of-band audit sink, transport auth, telemetry, config, and the structured error envelope. `#![forbid(unsafe_code)]`; never imports a `plsql-*` engine crate (one-way boundary). **Extracted to the standalone [`oraclemcp`](https://github.com/MuhDur/oraclemcp) repo and consumed from crates.io**: `plsql-mcp` depends on the published `oraclemcp-core`/`-guard`/`-error` rather than in-workspace copies | ``` PL/SQL source + Oracle catalog snapshot │ ▼ plsql-parser-antlr (lossless tape + AST) │ ▼ plsql-ir → plsql-symbols → plsql-depgraph │ ▼ plsql-engine: AnalysisRun + CompletenessReport │ │ ▼ ▼ product surfaces typed UnknownReason exhaust (lineage / docs / │ bindings / cicd / ▼ sast) plsql-accretion + usr-loop (capture → fixture → gate → land) ``` Tool binaries: `tools/usr-loop` (the USR Loop orchestrator), `tools/plan-lint` (structural lint of `plan.md`), `tools/corpus-license-check`, `tools/corpus-bench`, `tools/corpus-grow`. The MCP server (`plsql-mcp`) is a single binary built on the engine-free `oraclemcp-*` core. It completes the MCP handshake, advertises the full tool surface over `tools/list` — each tool carries a real argument JSON-Schema and read-only / destructive annotations — and dispatches `tools/call` end-to-end: static-analysis and change-impact tools execute in-process; live-DB tools dispatch and degrade with a typed `RuntimeStateRequired` response (naming the tool to call next) when no active Oracle connection is configured. A zero-argument `oracle_capabilities` tool reports the feature flags and surface so an agent can orient before its first call, and failed calls return a structured error envelope with a machine-readable class and a fuzzy "did you mean" suggestion. A lockstep test enforces that every tool the registry advertises has a d … ## 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](https://github.com/MuhDur) - **Source:** [MuhDur/plsql-intelligence](https://github.com/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. ## Pricing - **Free** — Free ## Versions - **0.1.0** — security scan: pending review — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-muhdur-plsql-intelligence - Seller: https://agentstack.voostack.com/s/muhdur - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.