DEV Community: Atanas Oreshkov

Let your AI assistant read Oracle Forms — without Forms Builder

Atanas Oreshkov — Sat, 22 Aug 2026 05:38:21 +0000

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.

Try it

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.

Give your AI agent the real sources of any Kotlin/Java library

Atanas Oreshkov — Thu, 23 Jul 2026 20:02:14 +0000

Your AI coding assistant will confidently hand you a Kotlin method signature that does not exist. For a strongly-typed ecosystem, "plausible but wrong" is the worst failure mode — it compiles in your head and breaks in the build.

Here's it reading the real sources instead:

One prompt. kotlin-lib-mcp downloaded Ktor's sources jar, parsed it with the Kotlin Analysis API (the same K2/FIR front-end that powers the IDE), and answered from the actual code.

One coordinate, ten tools

fetch_library("io.ktor:ktor-client-core:3.5.1")

That's the whole setup. The server downloads the sources jar, extracts it, analyzes it once, and caches the parsed index on disk. Your agent then has ten tools over it:

list_packages / list_declarations — the public API surface
get_api_signature — a type-resolved signature (generics, nullability, receiver)
get_kdoc — KDoc as structured data, not an HTML page
get_source / search_source — the real implementation + bounded search
get_dependencies — the dependency tree from .pom / .module
list_versions / get_latest_version — resolve "latest stable" from Maven metadata

Pinned to the exact version you depend on, offline after the first fetch. No drift between "the docs" and the version in your build.

Why "resolved" is the whole point

Regex over source gives you a signature-shaped string. The Analysis API actually ran the compiler front-end — so you get the resolved type, not a guess. When a transitive dependency is missing it degrades to a best-effort PSI signature and flags it bestEffort: true, instead of failing. Graceful degradation over an empty answer.

Two Kotlin-specific things made this more than "unzip a jar":

KMP sources jars are per-target. A Multiplatform library publishes -jvm-sources.jar, a common one, and so on — resolved via .module Gradle metadata, with every symbol tagged by target.
The Analysis API is version-fragile. Standalone mode must be version-locked to the exact Kotlin release, so it's quarantined behind one SourceAnalyzer interface.

Try it in ~60 seconds

Docker, no build required:

claude mcp add kotlin-lib -- docker run -i --rm -v kotlin-lib-mcp-cache:/home/mcp/.cache ghcr.io/aoreshkov/kotlin-lib-mcp

Or grab the release zip (Java 21+), or install from the official MCP registry as io.github.aoreshkov/kotlin-lib-mcp. Then ask your agent to fetch a library and explain an API — it answers from the code.

It's also a tidy reference build: all three MCP primitives (tools, resources per cached library + a resource template, and a prompt), plus per-tool behavior annotations, typed outputSchema, progress notifications, and server→client log forwarding. Built on the current stable MCP spec (2025-11-25); the 2026 roadmap's stateless core and Tasks/Apps extensions are the natural next step.

GitHub: https://github.com/aoreshkov/kotlin-lib-mcp — Apache-2.0. Analysis-API edge cases especially welcome.

Enjoyed this? I also wrote about generating a full Kotlin Multiplatform app in one dialog.

Generate a production-grade Kotlin Multiplatform app (Compose, Room 3, Navigation 3, Koin) in one dialog

Atanas Oreshkov — Mon, 20 Jul 2026 20:54:23 +0000

Generate a production-grade Kotlin Multiplatform app (Compose, Room 3, Navigation 3, Koin) in one dialog

Starting a Kotlin Multiplatform project has a strange cost curve. The first Hello, world is cheap — the IDE's built-in wizard gives you a shared module and platform targets in a minute. The next two weeks are where the real setup lives: choosing an architecture, wiring a KMP-ready database, getting type-safe navigation working, setting up DI without service-locator soup, structuring Gradle so the build doesn't rot, and writing enough tests to trust any of it.

This article walks through one opinionated answer to that setup — the architecture decisions themselves, and why they're baked the way they are. The vehicle is KMP Project Wizard, an open-source IntelliJ IDEA / Android Studio plugin I built that generates the whole thing from File → New Project, but every decision below stands on its own — you can apply them by hand to any KMP codebase.

The reference-app principle: templates that can't go stale by construction

The most important decision isn't in the generated code at all. The templates aren't hand-authored files that drift out of date — they're generated from kmp-ledger, a real, working, MIT-licensed double-entry ledger app that builds, tests, and runs on all three platforms. At plugin build time, concrete names (app.oreshkov.ledger, Posting, Ledger) are replaced with placeholders; at generation time, your names are substituted back in — package, app name, feature name, entity fields, everywhere including directory names.

The consequence: if the reference app compiles and its tests pass, so does your generated project. "Template rot" — the classic starter-kit disease — becomes a build failure in my pipeline instead of a runtime surprise in your project.

Architecture: Clean layers with a feature API/impl split

The generated project is modular from the first commit:

Domain / Data / UI layers per feature, with the dependency arrow always pointing inward — UI and Data both depend on Domain; Domain depends on nothing.
A feature API/impl split: each feature exposes a small api module (public contracts) and keeps its impl private. Other features depend on api only, so feature boundaries survive growth and builds stay parallelizable.
Binary-compatibility validation: the Kotlin BCV plugin's apiDump snapshots every module's public ABI, and apiCheck fails the build when a public contract changes accidentally. (A detail I got wrong the first time: ABI dumps are compiler-output snapshots — symbol names, declaration order, and Compose lambda keys derive from your names, so shipping the reference app's dumps with names substituted can never match. The wizard instead runs apiDump after your project's first Gradle sync, so the baseline is generated from your code.)

The stack, and why each piece

Compose Multiplatform for shared UI across Android, iOS, and Desktop — one rendering model, platform entry points kept thin.
Navigation 3 for type-safe routing: destinations are serializable types, not string routes, so a refactor that breaks navigation breaks the compile.
Room 3 for persistence — the KMP-ready generation of Room, meaning the same DAO and entity definitions run on all targets, with SQLite under the hood.
Koin + KSP annotations for DI: annotation-driven definitions with compile-time processing, no reflective magic on the hot path, and no hand-maintained module lists.
Coroutines & Flow end to end — repositories expose Flow, use cases suspend, UI collects with lifecycle awareness.

Gradle that scales: convention plugins + version catalog

All build logic lives in convention plugins (build-logic/), applied by module type — a feature impl module's build file is a few lines naming its type and dependencies. Versions are centralized in gradle/libs.versions.toml. Adding a fifteenth module costs the same as adding the second, and a dependency bump is a one-line change.

Tests as part of the template

Every generated project ships a passing suite: unit tests for domain and data (including an in-memory Room setup) and Compose UI tests. Not because sample tests are valuable in themselves, but because a testing pattern you can copy beats a blank src/test directory every time you add a feature.

What the one dialog actually asks

Package name, app name, one feature name, one entity with a test value, and target platforms (Android / iOS / Desktop). From that it derives every identifier — PascalCase types, camelCase members, snake_case resources — and renders the whole tree with your names, then triggers Gradle sync and generates the ABI baselines.

The plugin's core is free (all three platforms, the full architecture and tests). A paid Pro tier adds two things to the generated project: Claude Code agent config (CLAUDE.md, .claude/ skills) and GitHub Actions CI (.github/) — flat files, no runtime services, and the same content you can inspect in kmp-ledger.

DEV Community: Atanas Oreshkov

Let your AI assistant read Oracle Forms — without Forms Builder

The hard part is the front door, not the protocol

Designing the tool surface

Annotations: letting the model write back

Where the spec is going, and where Kotlin is

One protocol detail that will bite you

Try it

Give your AI agent the real sources of any Kotlin/Java library

One coordinate, ten tools

Why "resolved" is the whole point

Try it in ~60 seconds

Generate a production-grade Kotlin Multiplatform app (Compose, Room 3, Navigation 3, Koin) in one dialog

Generate a production-grade Kotlin Multiplatform app (Compose, Room 3, Navigation 3, Koin) in one dialog

The reference-app principle: templates that can't go stale by construction

Architecture: Clean layers with a feature API/impl split

The stack, and why each piece

Gradle that scales: convention plugins + version catalog

Tests as part of the template

What the one dialog actually asks

Links