oracle-forms-mcp: Instructions file for Claude Code

CLAUDE.md

MCP server serving Oracle Forms module content (.fmb/.mmb/.pll/.olb) from a --forms-dir. A KMP core of pure models + ports, with a JVM MCP server of declarative tool adapters over one FormsService.

Layout

• core/ — KMP library. commonMain: pure @Serializable models (ModuleIndex, ModuleKey, SourceRef, plus the annotation layer ElementId, Annotation/Relation/ModuleAnnotations), DTOs (dto/ToolResults.kt), and ports (ModuleConverter, ModuleParser, ModuleCache, AnnotationStore, FormsDirectoryScanner). jvmMain: implementations — OnDiskModuleCache, OnDiskAnnotationStore, FormsDirectoryScannerImpl, converters (convert/), parsers (parse/).
• server/ — JVM MCP app. FormsService is the single logic layer; tool files in tools/ are declarative adapters (parse args → service call → toolResult(dto)). The read tools plus the annotation tools (annotate_element, relate_elements, get_element_annotations, search_annotations, remove_annotation) and the oracleforms://{module}/annotations resource live here. Transports in transport/, resources/prompts in their packages, composition root McpServerFactory.
• build-logic/ — convention plugins kmp-library (toolchain 21, explicitApi, kover, KGP ABI validation) and jvm-application.
• Distribution — three channels, all cut by .github/workflows/release.yml from a v* tag: the GHCR image, the release zip (plus its .zip.sha256), and an .mcpb desktop bundle (server/mcpb/manifest.template.json → packageMcpb). server.json is the MCP Registry listing; the publish job rewrites its version, icon tag, and appends the mcpb package with the bundle's sha256.
• assets/icon.svg + assets/icon-512.png — generated artwork, not hand-edited. Both files are drawn from one geometry description by a generator kept outside this repo, and copied in; editing either in place is undone by the next redraw, and editing only one re-creates the divergence they were unified to fix (the SVG's gradients are per-shape, and a raster that uses one canvas-wide gradient instead draws a different icon). Consumed by server/build.gradle.kts (server resources), server/mcpb/manifest.template.json, and server.json's tag-pinned icons URLs — so a change here reaches the registry listing only at the next tag.
• plugins/oracle-forms/ + .claude-plugin/marketplace.json — the Claude Code plugin channel, served straight from the repo by /plugin marketplace add aoreshkov/oracle-forms-mcp. The plugin carries no jars: .mcp.json runs launcher/OracleFormsMcpLauncher.java in Java single-file source mode (hence a JDK 25+, not a JRE), which downloads the release zip, verifies its published sha256, unpacks it under ${CLAUDE_PLUGIN_DATA} (passed as OFMCP_PLUGIN_DATA; without it, a per-user OS data directory, so a host that sets only OFMCP_* variables can run it too), and loads it in-process. The launcher itself stays on the Java 21 language and API (CI compiles it with --release 21), so on a JDK older than the server needs it still starts and names the fix instead of failing to compile. The claude-code-plugin CI job validates the manifests and compiles the launcher — nothing else stands between a commit on main and a user's install. It also carries one skill, skills/trace-form/SKILL.md: the traversal order and the habit→tool mapping that the server's instructions state in brief, at the length a worked example needs. Both are guidance, not behaviour — keep them agreeing with each other and with the tools they name.