What aimdb-dev/aimdb does
aimdb-dev/aimdb exposes a Model Context Protocol interface for running AimDB instances. It lets an MCP client discover available instances, inspect their metadata and records, read or update writable values, infer JSON schemas, and drain buffered data for analysis.
The server also provides visibility into AimDB's dependency graph. Agents can inspect nodes, directed data-flow edges, and initialization order. Optional profiling and metrics features add per-stage timing and live buffer counters, including produced, consumed, dropped, and current occupancy values.
A separate architecture-agent capability works with .aimdb/state.toml. It can inspect the recorded architecture and create proposed schema or topology edits. Changes follow a proposal-and-resolution process rather than being applied immediately.
How it works
MCP clients communicate with the Rust executable over stdio using JSON-RPC 2.0. The executable translates tool calls through the AimDB client to a selected running instance. Unix domain sockets can be written as unix:// or uds:// URLs, and a bare socket path is also accepted.
Each instance-oriented tool accepts an optional endpoint. If that argument is absent, the server checks the startup --connect option and then AIMDB_CONNECT. This allows a deployment to pin one target while keeping endpoint selection out of individual model requests.
Serial endpoints use the form serial:///dev/ttyACM0?baud=115200. Serial support is disabled in the default build and requires the transport-serial Cargo feature.
Setup and configuration
Build the executable from the AimDB repository with Cargo:
cargo build --release -p aimdb-mcp
The resulting binary is target/release/aimdb-mcp. Configure an MCP client to launch that binary as a stdio server. VS Code reads a server entry from .vscode/mcp.json; Claude Desktop uses its claude_desktop_config.json MCP server configuration.
A fixed target can be configured with either a command argument:
{
"args": ["--connect", "unix:///tmp/aimdb-demo.sock"]
}
or an environment entry:
{
"env": { "AIMDB_CONNECT": "unix:///tmp/aimdb-demo.sock" }
}
To enable serial transport, rebuild with --features transport-serial. The example remote-access demo can be started from examples/remote-access-demo and creates an instance at /tmp/aimdb-demo.sock.
Tools and capabilities
The server provides 30 tools in total. The main introspection and operations set includes:
- Discovering running instances and retrieving instance information
- Listing records and reading or writing record values
- Inferring JSON Schema from record contents
- Draining accumulated record values in chronological order
- Listing dependency-graph nodes, edges, and topological order
- Reading and resetting per-stage profiling data
- Reading and resetting buffer metrics
Profiling reports call counts and timing statistics for named or indexed stages and identifies the highest-average-time stage. The target instance must be built with the profiling feature. Buffer metrics likewise require the target to be built with the metrics feature.
Architecture tools read and update .aimdb/state.toml, validate proposed changes, and can generate Mermaid and Rust artifacts after confirmation. Proposal, removal, and rename operations create pending changes that a later resolution step can confirm, reject, or revise.
Limitations and notes
Public mode advertises only discover_instances, list_records, and get_record. It also removes client-provided endpoints, so tools use the server-pinned --connect setting or AIMDB_CONNECT value instead of probing arbitrary host paths.
Profiling and buffer counters are unavailable unless the connected AimDB instance includes the corresponding build feature. Reset operations require write permission. Draining is destructive: it consumes values accumulated since the previous drain, and the first call starts empty.
Architecture editing is unavailable in public mode. Serial connectivity adds a Linux libudev dependency through the serial transport stack, which is why that feature is opt-in.