Oracle Forms 的 MCP 服务器：让 AI 读懂 1998 年的二进制模块

Somewhere in your organization there is an Oracle Forms application from 1998 that still runs payroll. Its logic lives in binary .fmb and .pll modules that exactly one program can open — Forms Builder — and the developer who wrote it retired years ago. Your AI assistant, which will happily read any Kotlin file you point it at, is completely blind to it.

That's an input problem, not a model problem. Oracle Forms MCP is an MCP server that solves it: point it at a directory of modules and it converts them to text, indexes them, and serves the pieces — blocks, items, triggers, program units, PL/SQL — as MCP tools and resources. Kotlin Multiplatform core, JVM server, Apache-2.0.

You:  What does ORDERS.fmb do?
AI →  list_modules                 → ORDERS.fmb (NOT_CACHED), MAINMENU.mmb, UTILS.pll …
AI →  fetch_module ORDERS.fmb      → converted + indexed (2 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:  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 path" → saved

The hard part is the front door, not the protocol

Writing the MCP layer took days. Getting text out of a .fmb took considerably longer, and it shaped everything above it.

Oracle ships the only converters — frmf2xml for .fmb/.mmb/.olb, frmcmp_batch for .pll — and they are proprietary, so nothing can bundle them. Three modes fall out of that, in strict precedence: a site-supplied --convert-command, then an ORACLE_HOME installation, then copy-mode, where pre-converted orders_fmb.xml / utils.pld files already sit next to the modules. Copy-mode is what makes the Docker image and the bundled sample forms work on a laptop with no Oracle anything.

The tools themselves are 1990s-era and behave like it. frmf2xml writes into the process working directory, so the server runs it with the output directory as its cwd rather than passing a path. Exit codes are unreliable, so success is judged by the output file existing, being non-empty, and being newer than the invocation — which has the amusing consequence that a wrapper script using cp -p to copy a pre-generated file is rejected, because it preserved the source's mtime.

The resulting XML is large and version-dependent, so parsing is a single streaming StAX pass with one firm rule: the parser never fails on unknown vocabulary. An element nobody has seen before is skipped generically rather than throwing. A parser that dies on an unfamiliar tag is worthless against thirty years of Forms releases.

Designing the tool surface

Current MCP guidance converges on a few principles — one bounded context per server, a curated tool surface, bounded resources, reads cheap and writes deliberate. Here's how those landed in practice.

Sixteen tools is more than "curated" likes. I'll defend it anyway: they aren't sixteen peers. They're two verbs — list_* and get_* — over one noun space, plus a five-tool annotation layer. The server's instructions field states the entry sequence explicitly (list_modules → fetch_module → get_module_overview → drill down), which is what actually keeps a model from flailing. Tool count is a bad proxy; tool shape is the real thing.

Every tool declares its behaviour. All eleven read tools carry readOnlyHint = true, destructiveHint = false, idempotentHint = true, openWorldHint = false — a closed, local, side-effect-free domain. Clients that gate or auto-approve on annotations can do so correctly instead of guessing.

Every tool declares an outputSchema and returns both shapes. One DTO is serialized once and handed back twice: as structuredContent matching the schema, and as pretty JSON text for clients without structured-output support. DTO fields are all defaulted, so adding one is forward-compatible rather than a breaking change. A ToolRegistrationTest fails the build if any tool ships without a title, annotations, and a schema — the convention is enforced, not documented.

Errors are content, not exceptions. Expected failures — a bad argument, an un-fetched module, a conversion that died — come back as isError results whose text is written for the model: every message names the tool call that fixes the situation. "Module ORDERS is stale, call fetch_module" is a message an agent can act on. A stack trace is not.

Token cost is a design constraint. search_source paginates via offset/nextOffset. The list tools take verbosity=concise|detailed, defaulting to concise. And the index itself stays small by construction: PL/SQL bodies never live in index.json — they're extracted to .sql sidecars and referenced by line range, so get_trigger reads exactly one body instead of the model paying for a megabyte of JSON to find it.

Annotations: letting the model write back

The part I'd build again first. Reading a form is only half the job — the other half is remembering what you worked out about it, because nobody fully understands these applications on the first pass.

So the server has a small write surface: annotate_element (notes, tags, summaries, classifications) and relate_elements (directed cross-references — this trigger calls that program unit). Three rules make it durable:

Asserted, never derived. Annotations live in their own store, not in the fingerprinted cache. Deleting the cache or re-fetching a module doesn't touch them.

Keyed by identity, not position. The key is module + kind + name + owner path — never a line range. Re-indexing moves line numbers; it doesn't move a trigger's name.

Drift is flagged, never deleted. If the source changed after a note was written, the note comes back marked staleAgainstSource. Silently dropping a colleague's reasoning because a file was edited is the wrong default in every direction.

The read tools surface an element's annotations inline, so knowledge accumulated in March shows up in August's session without anyone asking for it.

Where the spec is going, and where Kotlin is

The 2026-07-28 specification is a bigger jump than the version string suggests. The protocol core went stateless: the initialize/initialized handshake and Mcp-Session-Id are gone, each request carries its protocol version and client identity in _meta, and any request can hit any instance behind a load balancer. Server-initiated round trips are replaced by MRTR — a tool returns input_required, the client retries with inputResponses. tools/list and friends gained ttlMs and cacheScope. Tasks moved out of the experimental core into a formal io.modelcontextprotocol/tasks extension. And there's finally a deprecation policy, which immediately put Roots, Sampling, Logging and the legacy HTTP+SSE transport on a twelve-month clock.

Honest status: this server speaks 2025-11-25, and that is the newest the Kotlin SDK offers. The Tier 1 SDKs (TypeScript, Python, Go, C#) shipped 2026-07-28; Rust is in beta; the Kotlin SDK's LATEST_PROTOCOL_VERSION is still 2025-11-25 as of today. If you build MCP servers in Kotlin, that gap is the thing to plan around — not the thing to be surprised by.

The good news is that most of the migration is architecture I'd want regardless. The server holds no per-session state: everything durable is on disk, fingerprinted, and addressed by a stable key, which is precisely the shape a stateless core wants. Cacheable list results are a near-free win for a tool list that never changes. The one real casualty is the logging capability — server→client log forwarding is deprecated, so that plumbing is now on a countdown rather than a foundation.

One protocol detail that will bite you

On stdio, stdout is the protocol channel. Any library that prints a banner, any stray println, any logger defaulting to console output corrupts the JSON-RPC stream, and the failure looks like a mysterious client-side parse error rather than "something printed." Here every log goes Kermit → SLF4J → Logback → stderr, and the routing is installed before the SDK constructs its first logger. Budget an afternoon for this on any stdio server; it is never the bug you expect.

Claude Code, two lines and no clone:

/plugin marketplace add aoreshkov/oracle-forms-mcp
/plugin install oracle-forms@oracle-forms-mcp

Claude Desktop gets a one-click .mcpb bundle from the latest release; everything else can run the GHCR image or the release zip, and it's listed on the MCP Registry as io.github.aoreshkov/oracle-forms-mcp. The repo ships sample forms, so you can see the whole pipeline work before pointing it at anything real:

server --forms-dir sample-forms

Source (Apache-2.0): https://github.com/aoreshkov/oracle-forms-mcp — issues and Forms-XML edge cases especially welcome. If you have a .fmb this parser chokes on, I want it.