@exeris/ai-bridge
OfficialServer Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| EXERIS_LSP_JAR | No | Launch exeris-platform-lsp explicitly via jar. | none |
| EXERIS_DOCS_ROOT | No | The exeris-docs checkout to read. | a sibling exeris-docs checkout if present, else the bundled snapshot |
| EXERIS_KERNEL_JAR | No | Launch the kernel diagnostics CLI explicitly via jar. | resolved from the local repository |
| EXERIS_MAVEN_REPO | No | Where published jars are looked up. | <localRepository> in ~/.m2/settings.xml, then ~/.m2/repository |
| EXERIS_BRIDGE_MODE | No | contributor for work on Exeris itself: source checkouts win over published jars. | app |
| EXERIS_LSP_COMMAND | No | Launch exeris-platform-lsp explicitly via command. | none |
| EXERIS_PROJECT_ROOT | No | The project build-*, caps-* and sdk-* report on. | nearest pom.xml above the working directory |
| EXERIS_LSP_WORKSPACE | No | The workspace the language server indexes. | the working directory |
| EXERIS_KERNEL_COMMAND | No | Launch the kernel diagnostics CLI explicitly via command. | resolved from the local repository |
| EXERIS_KERNEL_VERSION | No | The diagnostics CLI version to launch. | newest release in the local repository |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
exeris-ai-bridge publishes the Exeris ecosystem to you as read-only tools. Every tool is a read. Nothing here writes a file, edits a project, or changes kernel state — when a change is decided, you make it with your own tools.
Before writing Exeris code, correct one default: Exeris is not Spring. The kernel
is Spring-free as an architectural invariant (ADR-006), and there is no Spring
application context, no dependency-injection container, and no JPA or Hibernate
anywhere in the kernel, SDK or build tooling. Applications are declared with
@ExerisDomain and the SDK annotation set, and the build generates the runtime
artefacts from that declaration — handlers, repositories, SQL migrations, clients.
Two failure modes follow, and both are common:
transferring a Spring/Jakarta/Hibernate idiom by analogy. It will look plausible and be wrong. Check it with
docs-searchordocs-get_adrfirst.hand-writing something the build already generates (schema DDL is the usual one). Check what is generated before writing it by hand.
Tool names are family-tool:
docs-* ADR registry, high-level architecture, whitepaper, per-repo docs
sdk-* the @ExerisDomain authoring contract — annotation catalog, attribute
contracts, scoping rules, deprecations, AST schema; use sdk-describe_annotation
for attribute contracts, sdk-get_scoping_rules for @Field vs @Validation
scoping rules, and sdk-list_deprecations for replacement guidance
lsp-* the @ExerisDomain source model — domains, fields, relations, actions,
and in-memory mutation preview (lsp-preview_mutation)
kernel-* read-only introspection of a RUNNING kernel (providers, bootstrap
DAG, subsystem detail, resolved JVM ergonomics)
build-* what YOUR OWN project's last build emitted — the DomainMetadata AST
the code generators consume, plus the generated tree itself and who
owns it. Codegen already emits the schema, handlers, services,
repositories and OpenAPI for an entity; ask build-explain_artefacts
before hand-writing any of them, and build-get_detach_state before
editing a generated file, or the next build silently discards it.
build-explain_diagnostic decodes an error the build printed, and
build-get_starter returns the pom.xml / package.json for a NEW
application — ask it before hand-writing either.
build-preview_generation runs the project's pinned generator over
the emitted metadata and returns what it would write, diffed against
the committed tree, without writing to the project.
build-validate_brief checks the project's discovery briefs
(docs/briefs/.brief.yaml) against the brief schema and says
whether each is ready; it is local only and writes nothing
caps-* the capability composition of YOUR OWN project, from the
cap-manifest.json produced at build time — modules, provided services, init order, stamp
bridge-* this server itself; never unavailable
Resolved for this session: docs=unavailable lsp=unavailable kernel=unavailable build=unavailable caps=unavailable sdk=unavailable.
A family whose dependency did not resolve still answers: every call returns
{"error": "family_unavailable"} with a reason and a remedy. That is an answer to
relay, not a transport fault to retry. bridge-health reports the whole picture.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
| prompts | {} |
| resources | {
"subscribe": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| docs-list_adrsA | List all ADRs from the Exeris ecosystem registry. Each entry carries number, title, owning repo, scope, visibility, status, and link. Optional |
| docs-get_adrA | Fetch the full markdown body of a specific ADR by number. Resolves the link from the registry against the ecosystem root, so cross-repo ADRs (those whose content lives in a sibling repo) are read from their authoritative source. |
| docs-get_templateA | Fetch one of the canonical decision-doc templates from exeris-docs/templates/. Three kinds: ADR (decision made), RFC (multi-option strategic question), RESEARCH (falsifiable hypothesis, lab-notebook shape). |
| docs-get_hlaA | Fetch the High-Level Architecture document (high-level-architecture.md) from exeris-docs. Canonical narrative of the three-tier model. |
| docs-get_whitepaperA | Fetch the B2B technical whitepaper (b2b-technical-whitepaper.md) from exeris-docs. |
| docs-searchA | Search exeris-docs for a literal substring (case-insensitive). Returns the path, line number, and snippet of each match, capped by maxResults. Optional pathFilter narrows to files whose docs-root-relative path contains the substring (e.g. 'adr/' to scope to ADR files). Scope is the docs root only; cross-repo content is reachable via get_adr. |
| docs-list_reposA | List sibling Exeris repos under the ecosystem root that publish a |
| docs-list_repo_docsA | List markdown documents under |
| docs-get_repo_docA | Fetch a specific markdown document from |
| lsp-list_domainsB | List all @ExerisDomain types known to the active LSP session. |
| lsp-describe_domainA | Return the source-model description of an @ExerisDomain type: fields, actions, relationships, generated artefacts, and the |
| lsp-list_actionsB | List all @Action methods across the workspace, with their owning @ExerisDomain. |
| lsp-preview_mutationA | Preview how the SDK's canonical writer would change an @ExerisDomain source file for one mutation, applied in memory. Returns |
| kernel-list_providersA | List all SPI providers registered with the running kernel, including driver origin (community/enterprise priority). |
| kernel-get_bootstrap_dagA | Snapshot of the kernel bootstrap dependency DAG — nodes (subsystems) with their phase, declared dependencies, and running state. |
| kernel-describe_subsystemB | Detail for a single kernel subsystem by name (e.g. memory, crypto, persistence, graph, transport, events, flow, http, security). |
| kernel-get_jvm_ergonomicsA | What the JVM running the kernel actually resolved at startup: selected GC, max/committed heap, visible processors, and the container limits it detected (cgroup CPU quota/period, memory cap, cpuset) plus large-page, CDS and AOT-cache state. Null fields mean the kernel could not determine that value. A kernel that does not implement this answers a snapshot with gcName 'unknown' and -1 byte counts. |
| build-list_domainsA | List what this project's last build emitted into target/classes/exeris-metadata: every @ExerisDomain entity, plus the enums, capabilities and views the processor wrote alongside them, each with its kind. Use it to discover names before calling build-get_domain_metadata. A project that has not been built, or has no @ExerisDomain sources, returns present:false rather than an error. |
| build-get_domain_metadataA | Fetch the DomainMetadata JSON the annotation processor emitted for one declaration of this project — the authoritative AST the code generators consume, including fields, actions, events, relationships and the system-field flags. |
| build-explain_artefactsA | List the files Exeris codegen has generated into this project, each with the generator that produced it and when that generator emits — handlers, services, repositories, domain errors, event publishers, graph projections, sagas, Flyway migrations, OpenAPI specs, and the project-wide bootstrap. Ask this BEFORE hand-writing SQL, a DTO or a controller for an Exeris entity: the build usually already emits it. Optional |
| build-get_detach_stateA | Report whether this project's generated code is still pipeline-owned (L1, src/main/generated/java — regenerated on every build, so edits are lost) or has been detached into the developer's own sources (L2, src/main/java — owned, safe to edit). Ask this before editing anything under a generated tree. Returns the state, the observations behind it, and how many files the pipeline claims. |
| build-explain_diagnosticA | Decode an error, warning or note exeris-tooling printed — an annotation-processor message, a codegen plugin goal failure or warning, a capability-graph or cap-tier Wall refusal, a missing runtime driver, a code-generation pipeline or CodegenMain line, or an exeris-initializr error. Paste the diagnostic text verbatim; returns what it means, the rule behind it, and what to do. Looks each diagnostic up by its stable EXT- identifier (ADR-095), which exeris-tooling prints from 0.9.0, and falls back to message text only for output that carries none. An identifier with no catalogue entry is named back as a catalogue gap, and a diagnostic it does not recognise is reported as not in the catalogue — never as not being an Exeris problem. |
| build-get_starterA | Return the build files for a NEW Exeris application and write none: for 'backend', a pom.xml whose parent is exeris-app-parent and which depends on exeris-app-starter; for 'frontend', a package.json with @exeris/codegen-ts and its exeris-gen generate script; for 'both', the two under backend/ and frontend/. Ask this BEFORE hand-writing a pom.xml or package.json for an Exeris application: the starter already wires the annotation processor, the codegen goals and the dependency set. Every version comes from the exeris-app-bom the bridge was released with, which names one tested tooling + kernel + SDK triple; the tool reports it as bomVersion and triple. |
| build-preview_generationA | Preview what the code generator would write for this project's current metadata (target/classes/exeris-metadata), without writing anything into the project. It runs the project's own generator in a separate process — for 'ts' the @exeris/codegen-ts installed in the project's node_modules, confined by Node's permission model to write only its scratch directory; for 'java' the eu.exeris:exeris-codegen-cli jar from the local Maven repository at the version the project pins — never downloaded and never substituted; when none resolves, a structured generator_unavailable with a reason and remedy. Returns the files it produced as added, changed, unchanged and removed against the committed generated tree (src/main/generated/java for Java, the codegen outputPath for TypeScript), a unified diff for each added or changed file, and the run's diagnostics with every EXT- identifier decoded as build-explain_diagnostic does. 'unchanged' includes hand-written files already in the committed tree, which the run starts from; the generator's own manifest file is not listed. Unlike the present:false answers of the other build-* tools, this one cannot answer without metadata, so a project that has not been built returns the error metadata_missing: run the project build first (mvn compile). Metadata whose names could not be a Java identifier or a package are refused as metadata_invalid before any generator starts. Bounded by a timeout and by output and file-size caps; a run over one is stopped and the limit is named. Local only; the output exists in a temporary directory removed when the call returns. |
| build-validate_briefA | Check the pre-construction brief(s) of this project, docs/briefs/.brief.yaml, against the brief schema (ADR-106) and say whether each is ready for authoring. Reads only the brief files, the project's pom.xml (and the app BOM poms it inherits from, read from the local Maven repository), the brief schema and, when present, target/classes/exeris-metadata; writes nothing, starts no process and uses no network, and is local only: the family needs the project root, so private product intent never reaches a hosted endpoint. The schema is the one inside the project's pinned eu.exeris:exeris-sdk-source-model jar in the local Maven repository (never downloaded), else the schema bundled with this bridge; |
| caps-list_capabilitiesA | List the capability modules composed into this project, from the build-time cap-manifest.json: each module's qualified name, the services it provides with their versions, and which module owns the lifecycle. Also returns initOrder exactly as the manifest states it. A project with no capabilities returns an empty list, not an error. |
| caps-describe_compositionA | Report the composition stamp from cap-manifest.json: whether the capability graph validated, the composition version, and the content binding digest, alongside the manifest schema version, the module count and initOrder. Answers 'is this build's composition trustworthy, and which build is it'. A project with no capabilities returns a present:false answer, not an error. |
| sdk-list_annotationsA | List Exeris SDK annotations from the authoring contract: name, qualified name, package, targets, retention, and purpose. Supports optional filtering by package (e.g. 'system', 'security', 'capability', or full package name), target (e.g. 'METHOD', 'TYPE', 'FIELD'), or query string. |
| sdk-describe_annotationA | Describe a specific Exeris SDK annotation: simple and qualified name, owning package rationale, targets, retention, purpose, detailed description, all attributes (with types, defaults, required-ness, descriptions, and deprecations), and annotation-level deprecation status. |
| sdk-get_scoping_rulesB | Get canonical authoring contract scoping rules for Exeris SDK annotations (including @Field vs @Validation split, FieldMetadata as single AST carrier per ADR-054, derived SQL NOT NULL and API not-blank generator semantics, form lifecycle scoping, deprecations, and sibling vs nested form trap). Supports optional filtering by rule ID or query string. |
| sdk-list_deprecationsA | List all deprecated Exeris SDK annotations and attributes across the authoring contract, including replacement guidance, since version, and forRemoval status. Supports filtering by package or forRemoval only. |
| sdk-get_ast_schemaA | Get JSON Schema for the Exeris build-time DomainMetadata AST and sibling records. If 'definition' is omitted, returns the top-level schema envelope, reader requirements (such as Jackson 3 constraints), and definition list. If 'definition' is specified (e.g. 'DomainMetadata', 'FieldMetadata', 'ActionMetadata'), returns the schema definition for that specific record. |
| bridge-versionA | Identify this MCP server: package name and version, the Node runtime it is running on, which persona mode it resolved to, and what bundled reference data it carries. Use it to confirm which bridge build an answer came from, and which upstream release that data reflects. |
| bridge-healthA | Report which tool families can serve requests and why the others cannot. Each family carries its state and, when unavailable, the reason and the remedy. Families backed by a child process also report that process's current state — without starting it. Call this first when a tool returns 'family_unavailable'. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| review-three-tier-violations | Pre-loads the high-level architecture, ADR-006 and ADR-024 and the cap-tier Wall rule, then scans a diff for the known drift patterns of the three-tier model. |
| draft-adr | Pre-loads the ADR template and the registry index, asks the Research / RFC / ADR shape question first, and reserves the number in the index before any content is written. |
| route-this-task | Pre-loads the ecosystem's top-level routing rules when the bridge runs from an ecosystem checkout, and has the agent name the owning repository before touching anything. Without a checkout it says routing needs one. |
| wall-audit | Pre-loads ADR-006 and scans a file or pull request for Spring, Netty and servlet types that cross the kernel boundary. The target is named by the user; the bridge never reads it. |
| author-domain | Pre-loads the SDK scoping rules and the AST schema, walks the agent through the @Field / @Validation split, and has it preview the change with lsp-preview_mutation instead of hand-writing it. Validates the discovery brief first with build-validate_brief when one exists. |
| explain-my-build | Has the agent call build-explain_artefacts and build-get_detach_state to answer what the build produced and which of it may be edited. Both steps need a local server. |
| diagnose-build-failure | Has the agent decode pasted javac or Maven output with build-explain_diagnostic, with the SDK deprecation list pre-loaded. The decoding step needs a local server. |
| migrate-sdk-version | Pre-loads the SDK deprecation list and has the agent find the usages in the project that the next SDK bump will break. Runs without a local server. |
| discover-requirements | Walks the agent through purpose, actors, workflows, data intent, non-functional requirements, non-goals and open questions, has it write the discovery brief under docs/briefs/ in the shape of the SDK brief schema, then validate it with build-validate_brief until it is ready. Nothing is pre-loaded: the schema is the exeris://sdk/brief-schema resource. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| adr-index | The ecosystem ADR registry: number, title, owning repo, scope, visibility, status and link of every record. Subscribable: from an exeris-docs checkout a notification follows each change to the file; from the bundled snapshot the content is immutable for the process, so a subscription is accepted and never fires. |
| hla | The canonical narrative of the three-tier model. |
| whitepaper | The B2B technical whitepaper. |
TDQS
Scored across 34 tools
The seven family prefixes (docs-, lsp-, build-, kernel-, caps-, sdk-, bridge-) draw clean lines between domains, and most tools within a family target a distinct artefact. However, `lsp-list_domains` vs `build-list_domains` and `lsp-describe_domain` vs `build-get_domain_metadata` genuinely overlap — both surface fields, actions and relationships for an @ExerisDomain — and only long descriptions (live LSP session vs emitted target/classes metadata) separate them. `lsp-preview_mutation` and `build-preview_generation` are also adjacent preview concepts, though clearly differentiated.
Every tool follows a strict `family-verb_noun` pattern in snake_case (docs-get_adr, build-explain_artefacts, sdk-list_annotations, lsp-preview_mutation). The rare exceptions (docs-search, bridge-version, bridge-health) are still readable and consistent with the hyphen-prefix convention, so tool selection by name alone is predictable.
34 tools is heavy and sits above the comfortable band, but the surface is unusually broad (docs, live LSP, build/codegen, kernel runtime, capabilities, SDK contract, meta) and each family carries a small, coherent 2-9 tool set that mostly earns its place. It is still at the upper edge where an agent must first pick a family before picking a tool.
Coverage across inspection domains is strong: docs reading, ADR registry, domain/action introspection, mutation preview, build metadata, artefact and diagnostic explanation, kernel state, capability composition, SDK contract and health checks. The notable gap is that the docs root has `docs-search` and a few named fetchers but no generic `docs-list_docs`/`docs-get_doc` by path, and mutations are preview-only with no post-apply verification tool.