Skip to main content

Metadata MCP Server

The BimlFlex Metadata MCP Server is a Model Context Protocol (MCP) server over a BimlFlex file-mode metadata store. It speaks MCP over stdio and exposes read tools an agent can use to explore the store (entity enumeration, addressed lookup, text search, store-level settings and conventions, lineage traversal, and full store validation) plus exactly one guarded write path, propose_changes, which records a validated batch of edits as a new git branch for human review and never touches your checkout.

Two properties define the server:

  • It is a deterministic metadata tool surface. The server makes no LLM calls and no network calls of any kind at runtime; its only I/O is the store directory it is pointed at and its own stdin/stdout. It has no drafting intelligence of its own: it is tooling that an agent (or any MCP client) drives.
  • Your checkout is never written. The read tools write nothing at all. propose_changes writes exactly one thing: a new git branch (objects plus one ref) inside the store repository's .git directory. The working tree, index, and checked-out branch are byte-identical before and after every call, including every failure path.

All store parsing, validation, and identity derivation goes through the BimlFlex metadata file-format engine: the server never re-implements format rules, and it surfaces the engine's own diagnostics.

The server targets file-mode metadata stores by design, not as an interim limitation: file mode is the direction for BimlFlex metadata, and this tool surface is built for it.

Connecting a client​

The server ships as a dotnet tool package that you build yourself from the repository. Building requires the repository and its documented prerequisites; from the repository root:

dotnet pack src/BimlFlex.Mcp -c Release -o ./artifacts
dotnet tool install Varigence.BimlFlex.Mcp --tool-path ~/.bimlflex-mcp --add-source ./artifacts

That places a self-contained bimlflex-mcp executable at ~/.bimlflex-mcp/bimlflex-mcp (the metadata engine assemblies ride inside the package).

Point your MCP client at the absolute path to that executable, with the store root (the directory containing bimlflex.json) as the --store argument. For example, in an .mcp.json client registration:

{
  "mcpServers": {
    "bimlflex": {
      "command": "/path/to/.bimlflex-mcp/bimlflex-mcp",
      "args": ["--store", "/path/to/metadata-store"]
    }
  }
}

The tools​

Eight tools, in the order an exploration usually runs:

  • list_entities: enumerate the store's entities, optionally by kind, with identity and parent.
  • get_entity: one full entity document by name or uid: every property, references resolved.
  • search_metadata: case-insensitive text search over entity names and text-valued properties.
  • get_settings: the store's Setting entities as full documents.
  • get_conventions: the store manifest's header and conventions block.
  • validate: re-read the store from disk and return the engine's full diagnostic report (the edit-then-recheck loop).
  • get_lineage: traverse the authored-reference graph upstream or downstream from one entity (downstream is the impact set of a change).
  • propose_changes: apply a validated batch of edits as a new git branch in the store repository for human review; the checkout is never touched.

Every tool returns a single JSON document with stable field names, and orderings are deterministic throughout.

The edit-then-recheck loop​

The read tools serve a catalog loaded once at startup. Changes made to the store files while the server is running are not observed by them; restart the server to refresh the catalog.

The validate tool is the deliberate exception: it re-reads the store from disk on every call and always reflects the current on-disk state. That is what makes the edit-then-recheck loop work: change files on disk, call validate, fix what it reports, and call it again; no restart needed for validation, only for the other read tools to see the new state.

validate returns the engine's own diagnostics at every severity (errors, warnings, and infos, not just errors) with structured attribution fields (code, severity, file, and related file where relevant). A store the engine refuses to load does not take the server down: the read tools return an error result carrying the load diagnostics, while validate answers a refused store with the full report, because a refused store is exactly what it exists to diagnose.

Diagnostic code values (BFXF…) come from the engine's catalog, which can grow over time. Treat codes as opaque stable identifiers, and never depend on message wording.

Proposing changes for review​

propose_changes is the server's single write path, and it fails closed. It applies a batch of change operations (upsert and delete) to a fresh snapshot of the on-disk store, validates the result through the engine, and, only on clean validation, commits the emitted store to a new git branch in the store repository. The batch is whole-batch-atomic: any refused operation rejects the entire batch, and a proposal that would not validate is never committed anywhere. The branch's parent is the repository's current HEAD commit, and the snapshot's file layout is preserved so the branch diff reads as the change.

The review workflow is ordinary git: the agent proposes, a human reviews the branch diff, and merges or deletes the branch with normal git tooling.

One review caveat: the proposal branch carries the store alone. Non-store files committed in the repository (a README, .gitignore, CI configuration) are absent from the branch tree, so a raw branch-vs-HEAD diff shows them as deletions, and a plain git merge of the branch would delete them from the checkout. Review the store paths and apply them selectively (for example git checkout <branch> -- <store paths>, or a cherry-pick) rather than merging the branch wholesale when the repository carries such files.

File-mode metadata stores​

The server works against a BimlFlex file-mode metadata store: metadata stored as files on disk, with bimlflex.json at the store root. A git repository is a requirement of the propose_changes write path only, which records proposals as branches in the store repository. File mode is the direction for BimlFlex metadata, and the Metadata MCP Server is part of that direction: it is built for file-mode projects by design.