sqling-mcp
Ask an AI assistant about an Oracle Forms and Reports application: which
forms update a table, where a procedure is called, what fires when a button
is pressed, why an item looks the way it does, what a report's formulas do
and which forms run it. sqling-mcp is an
MCP server that answers those questions
from a metadata database built from your .fmb, .mmb, .pll, .olb and
.rdf files, so the assistant can search the whole application at once
instead of you opening modules one at a time in Form Builder or Reports
Builder.
- Read-only. The database is opened read-only, and the tools only read.
- Local. The server is a program on your own computer. It makes no network connections, and your forms never leave the machine you build the database on.
- No Oracle install. You don't need Forms Builder,
frmf2xmlor anORACLE_HOMEto build the database or to run the server. - Works with Claude Desktop, VS Code with GitHub Copilot, Claude Code, and any other client that speaks MCP over stdio.
Getting started
Four steps: install the package, build a database from your modules, register it with your AI client, and ask.
1. Install
sqling-mcp is a Python package. It needs Python 3.10 or later.
Windows
-
If
python --versionin a Command Prompt doesn't print 3.10 or later, install Python from python.org/downloads. On the installer's first screen, tick Add python.exe to PATH. -
Open a new Command Prompt and run:
python -m pip install sqling-mcp -
Check it:
sqling-mcp --versionIf Windows says
sqling-mcpis not recognised, pip's Scripts folder isn't on your PATH. Nothing is wrong with the install: usepython -m sqling_mcp.serverwherever this guide sayssqling-mcp(note the underscore).
macOS and Linux
Use pipx, which installs command-line tools in a
place of their own (a plain pip install is refused by Homebrew's Python
and by most Linux distributions):
brew install pipx # macOS; on Linux: sudo apt install pipx, or your distribution's package
pipx ensurepath # once; then open a new terminal
pipx install sqling-mcp
sqling-mcp --version
uv works too: uv tool install sqling-mcp.
Upgrading later: python -m pip install --upgrade sqling-mcp on Windows,
pipx upgrade sqling-mcp elsewhere. On Windows, quit your AI client first
(see Troubleshooting).
2. Build the metadata database
The database is built in your browser, by a free page that reads your modules on your own computer. Nothing is uploaded, and there is nothing to install: no Oracle software, no Java.
Forms, menus and libraries
-
Open the Batch Oracle Forms page: sqling.com/tools/fmb2xml.html. If your network blocks sqling.com, the same page is at www.ddginc-usa.com/fmb2xml.html.
-
Click Choose folder and pick the folder that holds the application's
.fmbforms,.mmbmenus,.plllibraries and.olbobject libraries. Leave Include subfolders ticked if they're spread over several. Your browser asks permission to read the folder; allow it. -
Under Produce, pick A metadata database, and leave plus a ready-made
.sqliteticked. -
Choose where the results go: into the same folder, a separate output folder, or a download. (Edge and Chrome offer all three; Firefox and Safari download.)
-
Click Convert files. The first run takes a little longer while the page loads its engine. When the status line says Done, you have two files:
File What it is forms-metadata.sqliteThe database sqling-mcp opens. forms-metadata.sqlThe same contents as a SQL script, to load into another database if you want to. sqling-mcp doesn't use it. -
Move
forms-metadata.sqlitesomewhere permanent and name it after the application, for exampleC:\sqling\billing.sqliteor~/sqling/billing.sqlite. The next step registers this path with your AI client, so don't leave it in Downloads.
Include every .pll and .olb your forms use, even ones kept in
another folder: copy them in beside the forms before you choose the
folder. Without them, what subclassed objects inherit stays unknown, and
the tools say so (see
Subclassing). A module that can't be read is listed with a
warning; the rest of the database is still built.
Reports (optional)
The same steps on the Batch Oracle Reports page,
sqling.com/tools/rdf2xml.html
(or www.ddginc-usa.com/rdf2xml.html):
choose the folder of .rdf files, pick A metadata database, and keep the
reports-metadata.sqlite it writes beside the forms one, for example
C:\sqling\billing-reports.sqlite. sqling-mcp opens the two together, so
it can answer which forms run which reports.
When the modules change, build again and replace the file. Your AI client sees the new contents the next time it starts the server.
3. Register it with your AI client
sqling-mcp setup C:\sqling\billing.sqlite
With reports too:
sqling-mcp setup C:\sqling\billing.sqlite --reports C:\sqling\billing-reports.sqlite
setup checks that the file is a Forms metadata database and that the server
starts. Then it adds the server to every client it finds on this computer:
| Client | Where it goes |
|---|---|
| Claude Desktop | claude_desktop_config.json (mcpServers) |
| VS Code (GitHub Copilot) | your user mcp.json (servers), or <folder>/.vscode/mcp.json with --workspace <folder> |
| Claude Code | claude mcp add --scope user |
It keeps your other servers and settings and writes a .bak of each file
first. It won't touch a file it can't parse, such as a mcp.json with
comments; it prints the entry for you to paste instead. Run it again any
time; it changes nothing when the entry is already right.
sqling-mcp setup myapp.sqlite --name myapp # choose the server's name (default: from the file name)
sqling-mcp setup myapp.sqlite --client vscode # only this client (claude-desktop, vscode, claude-code)
sqling-mcp setup myapp.sqlite --dry-run # show what would change
sqling-mcp setup myapp.sqlite --print # print every client's entry, change nothing
sqling-mcp setup myapp.sqlite --replace # overwrite an entry of the same name
sqling-mcp setup --remove myapp # take it out again
4. Restart the client and ask
- Claude Desktop: quit it completely (from the tray icon on Windows, or the menu bar on a Mac) and open it again. The server's tools appear under the tools button in the chat box.
- VS Code: open Copilot Chat, switch to Agent mode, and turn the server on in the tools picker. If it isn't listed, run MCP: List Servers from the Command Palette. Your organisation's Copilot policy must allow MCP servers.
- Claude Code: start a new session;
/mcplists the server.
Then ask:
- Which forms update the ORDERS table?
- Show me the WHEN-VALIDATE-ITEM trigger on EMP.SAL in the EMPLOYEES form.
- Where is
pkg_billing.post_invoicecalled? - Which blocks have no data source, and which forms have the most triggers?
One database per application
Each application gets its own database and its own server name:
sqling-mcp setup C:\sqling\billing.sqlite
sqling-mcp setup C:\sqling\scheduling.sqlite
Setting it up by hand
sqling-mcp setup --print <database> prints the exact entry for each client.
The server is a stdio command:
python -m sqling_mcp.server /path/to/myapp.sqlite
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"myapp": {
"command": "python",
"args": ["-m", "sqling_mcp.server", "C:/sqling/myapp.sqlite"]
}
}
}
VS Code (mcp.json):
{
"servers": {
"myapp": {
"type": "stdio",
"command": "python",
"args": ["-m", "sqling_mcp.server", "C:/sqling/myapp.sqlite"]
}
}
}
In JSON, write Windows paths with forward slashes or doubled backslashes. If
the client can't find python, give the full path to python.exe. setup
always writes the full path, which is why it's the easier route.
The tools
| Tool | Answers |
|---|---|
list_modules |
every module by its file, with its kind and how many blocks, items, triggers and program units it holds |
describe_form(file) |
one module's blocks and their data sources, every trigger and what it fires on, its program units, a menu's code, the tables it uses, and the reports it runs |
describe_report(file) |
one report's parameters, queries with their SQL and groups, formulas and placeholders, report triggers, every program unit and what it is used as (a formula, a format trigger, the before-report trigger), and the forms that run it |
read_code(file, unit, on=) |
the source of one trigger, program unit, menu item (ORDERS or MAIN_MENU.ORDERS) or menu startup code (STARTUP_CODE). A trigger name repeats across a module, so on= picks the object (TOOLBAR.PB_SAVE) |
search(text, limit=) |
every line of PL/SQL in the application that mentions something -- triggers, program units, menu item commands and menu startup code -- with file, object and line number |
list_code(file=, kind=, name=, module_kind=) |
the code without its source, across the application or in one file: every ON-ERROR, every menu item, every program unit in the libraries, every report query. name= takes % as a wildcard |
where_used(table) |
which modules read, insert, update or delete a table, which blocks are based on it, and where its name turns up in code |
effective(file, object, table=) |
one object as the form runs it: what it sets itself, what it takes from the object library or property class it is subclassed from, and the two merged |
calls(file) |
what one file navigates to, call by call -- CALL_FORM, OPEN_FORM, NEW_FORM, GO_FORM, RUN_PRODUCT, rp2rro_run_product, SRW.RUN_REPORT, RUN_REPORT_OBJECT, its menu module -- with where each call is and the file it leads to, or why it can't be followed |
called_by(file) |
everything that navigates to one file |
reachable(start, max_depth=) |
every file reachable from a starting form, how many steps away and by what path, and what isn't reached |
never_called(kind=) |
forms, menus and reports nothing calls: dead code, or entry points |
query(sql, limit=) |
your own SELECT over the metadata tables, when none of the above fits |
schema(table=) |
the tables with row counts, or one table's columns: what query has to work with |
query is what makes questions about the whole application possible, such
as "every form that updates ORDERS and also calls COMMIT_FORM" or "trigger
counts per module". The assistant writes the SQL; schema tells it what's
there.
Navigation
When the database is built, every call each piece of code makes is recorded
with where it is: in triggers (with the code a subclassed trigger inherits),
program units, menu commands and a menu's startup code, and in reports.
calls, called_by, reachable and never_called follow them to the
loaded files, by file name, never by module name.
A call names its target as a file -- CALL_FORM('E:\APP\ORDERS.fmx') leads to
ORDERS.fmb -- and RUN_REPORT_OBJECT is followed through the form's report
object to its .rdf. Reports run through Oracle's migration library
(rp2rro.rp2rro_run_product) are followed like RUN_PRODUCT.
Some calls can't be followed, and each says why: a target the code works out at
run time (CALL_FORM(v_form)), a file that isn't loaded, a report object whose
file is set at run time. never_called and called_by say how many run-time
targets there are, because "nothing calls X" is only as sure as that.
A database built before calls were recorded says so; build it again on the Batch page to get them.
Reports
A report's PL/SQL is all program units -- every formula, format trigger and
report trigger is one -- and objects point at the unit they use by name.
describe_report reads those pointers and says what each unit is used as, so
cf_taxformula is "formula of formula CF_TAX" and f_totalformattrigger is
"format trigger of field F_TOTAL". A unit nothing points at is listed too:
other PL/SQL may call it, and search will say where.
A form's report objects name the .rdf they run. With both databases open,
describe_form says which loaded report each one is, by file name, and
describe_report says which forms run it. A report object whose file isn't
loaded is listed as such.
Reports open three ways: a forms database with --reports beside it, a
reports database on its own, or one file that holds both.
Subclassing
An object subclassed from an object library sets almost nothing itself. An
alert's title, style and buttons, or an item's font and format mask, all come
from the library. Read on its own, the object's row looks like an object with
nothing on it. The database records where each object comes from, and
effective puts the two halves together:
effective ORDERS DELETE_CONFIRM
sets itself: nothing
from STD_OBJECTS.STD_CONFIRM:
alert_message Delete this record?
alert_style Caution
button1_label Yes
button2_label No
describe_form says which objects are subclassed and from where. When it
reports unresolved parents, the library they come from wasn't in the
folder the database was built from. Rebuild with the library included, or
what those objects inherit stays unknown. "Inherited from a library I can't
see" and "inherits nothing" are different answers, and only one of them is
true of the application.
Privacy and security
- The server reads one SQLite file, opened read-only (
mode=roandPRAGMA query_only).queryrefuses anything but a singleSELECT: noATTACH, noPRAGMA, no second statement. - It makes no network connections and writes no files. Only
setupwrites anything, and only to the client config files listed above. - What your AI client does with the answers is up to the client. When the assistant calls a tool, the result (form structure, PL/SQL source) goes into the conversation, and so to whichever model provider the client uses. That's the same as opening the code in an editor with an AI assistant turned on. Use a client and provider your organisation has approved for that code.
See SECURITY.md to report a vulnerability.
Troubleshooting
- "is not a Forms or Reports metadata database": the file wasn't built by the
Batch Oracle Forms page with A metadata database chosen. Use
forms-metadata.sqlite, notforms-metadata.sql; an XML export or some other SQLite file won't do either. - The client says the server failed to start: run
sqling-mcp setup --print <database>, copy the command it shows for "any other MCP client", and run it in a terminal. It should sit waiting quietly; an error there is the reason. - VS Code shows no tools: Copilot Chat must be in Agent mode, and your organisation's policy must allow MCP servers in Copilot.
sqling-mcpis not recognised (Windows): pip's Scripts folder isn't on your PATH. Runpython -m sqling_mcp.server setup <database>instead; it's the same command. The module name has an underscore,sqling_mcp; only the package you install is speltsqling-mcp.setupsays your database is an unrecognised argument: an older copy withoutsetupis still installed.python -m sqling_mcp.server --versionshould print a version; if it errors, reinstall withpip install --force-reinstall sqling-mcp.- Reinstalling fails because a file is in use (Windows): your AI client is still running the server. Quit Claude Desktop from its tray icon (closing the window leaves it running) and close VS Code, then install again.
License
MIT. sqling-mcp is part of SQLing, tools for running and modernizing Oracle Forms and Reports applications.
Metadata
Release files for sqling-mcp 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sqling_mcp-0.2.0.tar.gz | 76.8 kB | With provenance | Details for sqling_mcp-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sqling_mcp-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for sqling_mcp-0.2.0-py3-none-any.whl |
Total release size: 128.4 kB
Release files / sqling_mcp-0.2.0.tar.gz
| Download URL | sqling_mcp-0.2.0.tar.gz |
|---|---|
| Size | 76.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9a327b6290792b364c6f7fccc24acaf00013545ccae6a56714b0303641e18f91
|
|
BLAKE2b-256 checksum How to use checksums |
33eac150093dc3b97bcfd419d259741210b472300138d8246c2721f1959c20dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / sqling_mcp-0.2.0-py3-none-any.whl
| Download URL | sqling_mcp-0.2.0-py3-none-any.whl |
|---|---|
| Size | 51.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8e97bce25deea64bc3769fa4dc5546fb7876dccd045ee2998ec8f21f7b87394a
|
|
BLAKE2b-256 checksum How to use checksums |
cbbc7b57171038a08e4f0d2eb29df70b8b37692f01a8a19e95346a092506c7fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for sqling-mcp 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sqling_mcp-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.