Oracle Forms MCP

An MCP server that serves the content of Oracle Forms modules (.fmb forms, .mmb menus, .pll PL/SQL libraries, .olb object libraries) found in a directory, so AI assistants can inspect blocks, items, triggers, program units, and raw object XML without opening Forms Builder.

Built as a Kotlin Multiplatform core (pure @Serializable models and ports) with a JVM MCP server on top: declarative tool adapters over a single FormsService, stdio and HTTP transports, and a fingerprint-based on-disk cache. Oracle tool conversion feeds a streaming StAX parser that turns Forms XML into a structured index.

Why

Oracle Forms applications from the 1990s–2000s are still running critical business processes, but their logic is locked inside binary .fmb/.pll modules that only Forms Builder can open. That makes them opaque to modern AI tooling and painful to review, document, or migrate.

Oracle Forms MCP turns those modules into structured, queryable content so an AI assistant can:

• Understand a legacy app — enumerate blocks, items, triggers, and program units without a Forms IDE.
• Review & document PL/SQL — pull decoded trigger and program-unit bodies straight into the model's context.
• Assist modernization — feed decades-old business logic to an assistant for migration to APEX, Java, or a rewrite, and search across every module's source.
• Capture & retain knowledge — let the assistant record notes, tags, and cross-references on individual elements that persist across sessions and re-indexing, building up a durable map of a form no one fully remembers.

It is aimed at developers and teams doing Oracle Forms modernization, reverse engineering, code review, and documentation — anyone who needs to read Forms logic faster than opening it by hand.

See it work

A typical session against the bundled sample-forms directory:

You:  What does ORDERS.fmb do?
AI →  list_modules                 → ORDERS.fmb (NOT_CACHED), MAINMENU.mmb, UTILS.pll …
AI →  fetch_module ORDERS.fmb      → converted + indexed (3 blocks, 3 triggers, 3 program units)
AI →  get_module_overview ORDERS   → blocks, triggers, LOVs, record groups, windows, canvases …
You:  Show me the validation logic on the ORDERS block.
AI →  list_triggers block=ORDERS   → WHEN-VALIDATE-ITEM (on ORDER_ID), WHEN-VALIDATE-RECORD
AI →  get_trigger ORDERS WHEN-VALIDATE-ITEM  → the decoded PL/SQL body
You:  Where else is the CALC_TOTAL procedure called?
AI →  search_source "calc_total" scope=plsql  → hits across triggers and program units
You:  That validation is the legacy pre-2010 path — note it so we remember.
AI →  annotate_element ORDERS trigger WHEN-VALIDATE-ITEM kind=note "Legacy pre-2010 validation path" → saved
      (next session)  get_trigger ORDERS WHEN-VALIDATE-ITEM → body + the stored note inline

How it works

1. list_modules scans the configured --forms-dir (non-recursive) and reports each module's cache status: NOT_CACHED, CACHED, STALE (source changed on disk), or SOURCE_MISSING. A production forms directory holds thousands of modules, so the answer is filtered and paged: narrow with pattern/type/status, follow nextCursor for the rest, and read countsByStatus for the shape of the whole match.
2. fetch_module produces the module's text form in the cache and indexes it:
   • ORACLE_HOME set — binaries are converted with the Oracle tools in %ORACLE_HOME%\bin: frmf2xml for .fmb/.mmb/.olb (XML), frmcmp_batch (Module_Type=LIBRARY Script=YES) for .pll (a .pld text dump).
   • ORACLE_HOME not set — pre-converted files are expected next to the modules (orders_fmb.xml, dupes_fmb.xml, picker_fmb.xml, toolbar_fmb.xml, mainmenu_mmb.xml, objects_olb.xml, utils.pld) and copied into the cache.
3. A single StAX pass parses the XML into a structured index (blocks with items, triggers with decoded PL/SQL, program units, LOVs, record groups, windows, canvases, …). PL/SQL bodies are extracted to .sql sidecar files; every named XML element gets a line-range reference so get_object_xml can slice it back out of the converted file.
4. The other tools read the cached index. Caching is fingerprint-based (size + mtime + sha256 of the source file): editing a module marks it STALE and read tools ask for a re-fetch.
5. annotate_element and relate_elements let the assistant write durable meta-information back about individual elements (notes, tags, summaries, classifications, cross-references). This is kept in a separate store — not the derived index — so it survives re-fetching, and the read tools surface it inline. An annotation made before a source change is flagged, never dropped.

Tools

Every tool checks its arguments against its own input schema before running. An argument it does not have is never silently dropped: the call fails with every problem listed at once (unknown arguments with the name most likely meant, missing ones with their permitted values, values outside an enum), plus an example call where the tool has one.

Where an object's meaning lives

Two Forms properties carry more meaning than anything else in a module, and both used to be reachable only one get_object_xml call at a time.

An item's property class is usually its role: Forms shops name their classes for what the object does, so a push button is an LOV button and a text item is a filter field only because of the class it inherits. get_block reports propertyClass on every item and block, confirmed against the classes the module actually declares.

A window's modality decides how a form is read — a modal window is a dialog, so the code that fills it and the code that consumes the result sit on opposite sides of one interaction. get_module_overview(verbosity: "detailed") returns the window and canvas objects behind two of its name lists: modality, size, toolbar canvases, and the window each canvas sits on.

A property Forms did not write comes back as null, meaning the object keeps the Forms default — never false. On an item that has a property class it does not even mean the default: the class supplies the value, and in a real form that is where most of an item's behaviour lives. So get_block(verbosity: "detailed") returns both — items[].dml, what the item itself wrote, and effectiveDml, the same properties with the class applied (item, then class, then whatever that class is based on, followed into other modules that are already fetched). An item is listed in effectiveDml only when that chain resolved to the end, so a null there really is the Forms default. Every other item is a row of unresolvedItems, with the reason and — when fetching fixes it — the module to fetch; propertyClasses and the result's hint give the same account per class and name the fetch_module call. items: [...] narrows all of it to the items a question is about.