aimdb-mcp
OfficialSummary: aimdb-mcp is an MCP server that lets an LLM introspect/debug live AimDB instances and manage an AimDB architecture workflow.
Discover running AimDB instances and inspect instance metadata, permissions, and capabilities.
List records, read current record values, query record schema/type info, and drain buffered values for batch or trend analysis.
Set writable records and reset profiling/buffer metrics when write tools are enabled with
--allow-writes; public mode restricts tools to discovery/list/get.Inspect the dependency graph via nodes, directed edges, and topological/initialization order.
Retrieve live buffer metrics and automatic stage profiling, including bottleneck detection.
Read
.aimdb/state.toml, propose changes to records, buffers, connectors, fields, key variants, tasks, and binaries, resolve proposals, and validate state against a live instance.Persist design rationale to
.aimdb/memory.mdand reset the architecture session.Expose instance resources and a troubleshooting prompt in non-public modes.
Allows the architecture agent to propose adding an MQTT connector to a record, so an AimDB topology can be wired up to MQTT topics as part of a proposed (and later confirmed) architecture change.
aimdb-mcp
Model Context Protocol (MCP) server for AimDB - enables LLM-powered introspection and debugging.
Overview
aimdb-mcp provides an MCP server implementation that enables Large Language Models (like Claude, GPT-4, etc.) to interact with running AimDB instances for introspection, debugging, and monitoring.
Key Features:
LLM-Powered: Natural language queries to AimDB instances
Auto-Discovery: Automatically finds running AimDB servers
Record Contracts: Reports each record's declared schema name and version
Rich Toolset: 13 tools covering introspection, record ops, the dependency graph, and metrics/profiling
VS Code Integration: Works seamlessly with GitHub Copilot
Related MCP server: Multi Database MCP Server
Architecture
┌──────────────────────────────┐
│ LLM Host (VS Code/Claude) │
│ - Natural language queries │
│ - Tool invocations │
└──────────────┬───────────────┘
│ stdio (JSON-RPC 2.0)
▼
┌──────────────────────────────┐
│ aimdb-mcp Server │
│ - Protocol translation │
│ - Tool implementations │
│ - Record introspection │
└──────────────┬───────────────┘
│ aimdb-client
▼
┌──────────────────────────────┐
│ AimDB Instances │
│ (Unix domain sockets) │
└──────────────────────────────┘Quick Start
Installation
Build from source:
cd /aimdb
cargo build --release -p aimdb-mcpBinary will be at target/release/aimdb-mcp.
VS Code Configuration
Add .vscode/mcp.json to your workspace:
{
"servers": {
"aimdb": {
"type": "stdio",
"command": "/path/to/aimdb-mcp",
"args": [],
"env": {
"RUST_LOG": "info"
}
}
}
}Note: VS Code will automatically detect and load MCP servers from .vscode/mcp.json.
Claude Desktop Configuration
Add to claude_desktop_config.json:
{
"mcpServers": {
"aimdb": {
"command": "/path/to/aimdb-mcp",
"args": []
}
}
}Choosing the Target Instance
Every tool that talks to an instance takes an optional endpoint argument — a
scheme:// URL that selects the transport at runtime:
Endpoint | Transport |
| Unix domain socket |
| Unix domain socket (the |
| Serial/UART (requires the |
When a tool's endpoint is omitted, the server resolves it in this order:
The tool's explicit
endpointargumentThe
--connect <ENDPOINT>startup flagThe
AIMDB_CONNECTenvironment variable
This lets you pin a single instance once at startup so the LLM never has to pass a path. Pass it as a flag:
{
"mcpServers": {
"aimdb": {
"command": "/path/to/aimdb-mcp",
"args": ["--connect", "unix:///tmp/aimdb-demo.sock"]
}
}
}…or via the environment:
{
"mcpServers": {
"aimdb": {
"command": "/path/to/aimdb-mcp",
"args": [],
"env": { "AIMDB_CONNECT": "unix:///tmp/aimdb-demo.sock" }
}
}
}In --public mode any client-supplied endpoint is stripped, so tools fall back
to the server-pinned --connect / AIMDB_CONNECT and clients cannot probe
arbitrary paths on the host.
Tool Modes
Mode | Offered tools |
default | All read-only tools; none that change a running instance |
| Also |
| Only |
The tool list a client sees reflects the mode. Calling a write tool without
--allow-writes is refused with a message naming the flag. Enable it only where
an agent should be able to change a live system:
{
"mcpServers": {
"aimdb": {
"command": "/path/to/aimdb-mcp",
"args": ["--connect", "unix:///tmp/aimdb-demo.sock", "--allow-writes"]
}
}
}The instance's own AimX security policy still applies: an instance running
SecurityPolicy::read_only() refuses writes even with --allow-writes.
The serial transport is off by default (it pulls tokio-serial → libudev on
Linux); build with cargo build -p aimdb-mcp --features transport-serial to dial
serial:// endpoints.
Test Server
Start the example server:
cd /aimdb/examples/remote-access-demo
cargo runThis creates an instance at /tmp/aimdb-demo.sock with sample records.
Demo
🎬 Demo video coming soon - showing natural language queries via GitHub Copilot
Available Tools
13 tools in total. The three tools that change a running instance
(set_record, reset_stage_profiling, reset_buffer_metrics) are offered only
with --allow-writes, so 10 tools are advertised by default. In --public mode only
discover_instances, list_records, and get_record are advertised (see
Tool Modes).
1. discover_instances
Find all running AimDB instances:
Query: "What AimDB instances are running?"
Result: Lists socket paths, versions, and record counts2. get_instance_info
Get detailed information about a specific instance:
Query: "Show me details about /tmp/aimdb-demo.sock"
Result: Server version, protocol, permissions, capabilities; from protocol 3.1
servers also the instance name and UID and the build it runs (application,
version, git revision, uncommitted changes, kind, config hash, target)3. list_records
List all records in an instance:
Query: "What records are in the demo instance?"
Result: Record names, types, buffer configs, producer/consumer counts, and the
declared schema (`schema_type`, `schema_version`) where the record has one4. get_record
Get current value of a record:
Query: "What's the current temperature?"
Result: JSON value of server::Temperature record5. set_record
Set value of a writable record (requires --allow-writes):
Query: "Set the config log_level to debug"
Action: Updates server::Config record6. drain_record
Drain all values accumulated since the last drain (a destructive batch read):
Query: "Drain the temperature buffer and analyze the trend"
Result: Values in chronological order; the first call is a cold start (empty)To wait for the next update after a prompt ("press B1, then check it
fired"), use the CLI's aimdb watch --new --timeout; see
Waiting for an event.
7. graph_nodes
List all nodes in the dependency graph:
Query: "Show me the record graph nodes"
Result: Per-record origin (source/link/transform/passive), schema name and version, buffer config, tap count, and outbound link addresses8. graph_edges
List the directed edges (data flow) between records:
Query: "How does data flow between records?"
Result: Directed edges from sources through transforms to consumers9. graph_topo_order
Show the topological (spawn/initialization) order of records:
Query: "What order are records initialized in?"
Result: Record keys ordered so dependencies precede their dependents10. get_stage_profiling
Show automatic per-stage timing — how long each .source() / .tap() / .link()
callback takes (wall-clock, including .await / I/O / sleeps) — for records
matching a key, and flag the slowest stage. Requires the target instance to be
built with the profiling feature; otherwise records carry no profiling data.
Query: "Which stage of my Temperature pipeline is the bottleneck?"
Result: Per-stage call_count / avg / min / max (ns) plus a "bottleneck" pointing
at the stage with the highest average time, with a recommendation string.Stage names come from .with_name("...") on the registrar; unnamed stages show as
source[0], tap[0], etc.
11. reset_stage_profiling
Reset stage profiling counters for every record on the target instance (requires
--allow-writes, write permission on the instance and the profiling feature).
Useful for windowed measurements.
Query: "Reset the stage profiling counters."
Result: { "reset": true }12. get_buffer_metrics
Return live buffer introspection counters
(produced_count / consumed_count / dropped_count / occupancy) for records
matching a key. Requires the target instance to be built with the metrics
feature; otherwise records carry no buffer metrics.
Query: "What's the producer/consumer lag on my Temperature buffer?"
Result: Per-record produced/consumed/dropped counts and current (used, capacity).13. reset_buffer_metrics
Reset buffer introspection counters for every record on the target instance
(requires --allow-writes, write permission on the instance and the metrics
feature). Useful for windowed measurements.
Query: "Reset the buffer metrics counters."
Result: { "reset": true }Record Contracts
The MCP server does not infer schemas. To learn what a record holds, use the contract the record declares and look at a real value:
list_recordsreturnsschema_typeandschema_versionfor each record configured with a data-contract schema. This is the versioned AimDB contract.get_recordreturns the current value as{value, ts}. Treat it as one observed sample: it shows the shape of this value, not which fields are optional or what an array may hold.
Schema metadata can be absent. A record configured without a schema has no
schema_type or schema_version; the fields are omitted, not null. In that
case get_record is the only view of the data, and the agent should ask the
user about units or semantics it cannot tell from the value.
// list_records (excerpt)
{ "record_key": "temp.berlin", "buffer_type": "single_latest",
"schema_type": "temperature", "schema_version": 2 }
// get_record
{ "value": { "celsius": 23.5, "sensor_id": "sensor-001" }, "ts": 81234000 }graph_nodes carries the same contract as schema: { name, version }.
Resources
Instance resources are discovered by scanning for Unix sockets, so their URIs are keyed by socket path:
aimdb://instances— list of all discovered instancesaimdb://instance/{socket_path}— details about a specific instanceaimdb://{socket_path}/records— all records in an instance
Prompts
The server provides one helper prompt (not available in --public mode):
troubleshooting— guided diagnostics for connection/record issues
Protocol Details
Transport
stdio: JSON-RPC 2.0 over standard input/output
Format: NDJSON (newline-delimited JSON)
Capabilities
Tools: ✓ (13 tools; 10 advertised by default, all 13 with
--allow-writes, 3 in--publicmode)Resources: ✓ (instances and their records)
Prompts: ✓ (1 prompt)
Sampling: ✗ (not supported)
Logging: ✓ (stderr)
Message Flow
Client → Server: initialize request
Client ← Server: initialize response
Client → Server: tools/list request
Client ← Server: tool definitions
Client → Server: tools/call (discover_instances)
Client ← Server: tool result
Client → Server: resources/read (aimdb://instances)
Client ← Server: resource contentUsage Examples
Health Check
User: "Check the health of all AimDB instances"
LLM:
1. discover_instances() → finds instances
2. For each: get_instance_info() → checks status
3. Reports: healthy/unhealthy with detailsRecord Exploration
User: "What data is available in the demo instance?"
LLM:
1. list_records(/tmp/aimdb-demo.sock) → gets record list
2. Reads schema_type / schema_version from that list → the declared contract
3. For interesting records: get_record() → an observed value
4. Summarizes available data, noting records without a declared schemaData Monitoring
User: "Monitor temperature and analyze the trend"
LLM:
1. drain_record(server::Temperature) # cold start — creates the reader, returns empty
2. drain_record(server::Temperature) # later: returns values accumulated since last drain
3. Analyzes: min, max, avg, trends, anomalies
4. Generates reportConfiguration Update
Requires --allow-writes:
User: "Set the log level to debug"
LLM:
1. list_records() → finds writable config record
2. get_record(server::Config) → sees current value
3. set_record(server::Config, {"log_level": "debug", ...})
4. Confirms changeError Handling
The MCP server provides clear error messages:
Error: Connection failed: /tmp/aimdb.sock
Reason: No such file or directory
Hint: Check if AimDB instance is runningError: Permission denied
Record 'server::Temperature' is not writable
Hint: Only records without producers can be setDevelopment
Building
cargo build -p aimdb-mcpTesting
# Unit tests
cargo test -p aimdb-mcp
# Integration test (requires running instance)
cargo run --example remote-access-demo # Terminal 1
cargo test -p aimdb-mcp --test integration # Terminal 2Debugging
Enable debug logging:
RUST_LOG=debug aimdb-mcpLogs go to stderr, keeping stdio clean for MCP protocol.
Adding Tools
Define tool in
tools.rs:
pub fn my_new_tool() -> Tool {
Tool {
name: "my_tool".to_string(),
description: "Does something useful".to_string(),
input_schema: json!({ /* ... */ }),
}
}Implement handler in
server.rs:
"my_tool" => {
let result = handle_my_tool(params).await?;
// Return result
}Add to tool list in
list_tools().
Security Considerations
Authentication
Currently no authentication required
Unix socket permissions control access
Future: Token-based auth planned
Permissions
Read-only by default (list, get, drain, graph): tools that change a running instance (
set_record,reset_stage_profiling,reset_buffer_metrics) are offered only with--allow-writesWrite operations (set) also require writable records on the instance
No shell access or arbitrary code execution
Data Privacy
No network communication
All data stays on local machine
Performance
Tool latency: < 10ms for local operations
Memory usage: ~5MB base
Concurrent connections: Single-threaded stdio
Troubleshooting
Server not responding
Check if MCP server is running:
ps aux | grep aimdb-mcpTest stdio manually:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | aimdb-mcpCan't find instances
Check socket paths:
ls /tmp/*.sock /var/run/aimdb/*.sockVerify permissions:
stat /tmp/aimdb-demo.sockReferences
MCP Specification: https://spec.modelcontextprotocol.io/
AimX Protocol:
docs/design/008-M3-remote-access.mdSchema Query (superseded, historical):
docs/design/011-M4-schema-query.md
License
See LICENSE file.
Available Tools
30 toolsdiscover_instancesA
Discover all running AimDB instances on the system. Scans /tmp/.sock and /var/run/aimdb/.sock for AimDB servers.
Inputs: no named parameters.
drain_recordA
Drain all pending values from a record since the last drain call. Returns values in chronological order. This is a destructive read — drained values won't be returned again. Use this for batch analysis of accumulated data (e.g., time-series analysis, trend detection). The first drain call creates a reader and returns empty (cold start). Subsequent calls return all values accumulated since the previous drain.
Inputs: record_name (required), limit, endpoint.
get_architectureA
Return the current architecture state from .aimdb/state.toml as structured JSON, including record count, validation summary, and decision log length. Run this first when entering an architecture session.
Inputs: state_path.
get_buffer_metricsB
Get live buffer metrics for records matching a key string from a running AimDB instance.
Inputs: record_key (required), endpoint.
get_instance_infoB
Get detailed information about a specific AimDB instance. Returns server version, protocol, permissions, and capabilities.
Inputs: endpoint.
get_recordB
Get the current value of a specific record from an AimDB instance. Returns the record's current JSON value.
Inputs: record_name (required), endpoint.
get_stage_profilingA
Get automatic stage profiling (per-.source()/.tap()/.link() callback wall-clock timing) for records matching a key from a running AimDB instance, including the slowest stage ('bottleneck'). Requires the instance to be built with the profiling feature.
Inputs: record_key (required), endpoint.
graph_edgesB
Get all edges in the dependency graph. Returns directed edges representing data flow between records. Shows how data flows from sources through transforms to consumers.
Inputs: endpoint.
graph_nodesB
Get all nodes in the dependency graph. Returns metadata for all records as graph nodes, including origin (source/link/transform/passive), buffer configuration, and connection counts. Useful for understanding database topology and data flow.
Inputs: endpoint.
graph_topo_orderA
Get the topological ordering of records in the dependency graph. Returns record keys ordered so all dependencies appear before their dependents. Reflects the spawn/initialization order used by AimDB.
Inputs: endpoint.
list_recordsB
List all records from a specific AimDB instance. Returns metadata including buffer type, capacity, producer/consumer counts, and timestamps.
Inputs: endpoint.
propose_add_binaryA
Propose adding a new binary definition. Binaries are deployable crates that group tasks together and optionally declare external broker connections. Present the proposal to the user before calling resolve_proposal.
Inputs: name (required), description (required), tasks, external_connectors.
propose_add_connectorA
Propose adding a connector (MQTT, KNX, etc.) to an existing record. Present the proposal to the user before calling resolve_proposal.
Inputs: url (required), protocol (required), direction (required), description (required), +1 more.
propose_add_recordA
Propose adding a new record to the architecture. All payload fields are explicit and typed — no guessing required. Present the proposal to the user before calling resolve_proposal.
Inputs: name (required), buffer (required), description (required), fields, +6 more.
propose_add_taskA
Propose adding a new task definition. Tasks are async functions that produce, transform, or consume record data. Present the proposal to the user before calling resolve_proposal.
Inputs: name (required), description (required), inputs, outputs, +1 more.
propose_modify_bufferA
Propose changing the buffer type (and optionally capacity) of an existing record. Present the proposal to the user before calling resolve_proposal.
Inputs: buffer (required), description (required), record_name (required), capacity.
propose_modify_fieldsA
Propose replacing the value struct fields of an existing record. This replaces ALL fields — include unchanged fields too. Present the proposal to the user before calling resolve_proposal.
Inputs: fields (required), description (required), record_name (required).
propose_modify_key_variantsA
Propose updating the key variants of an existing record. Use this when adding a record with no variants (e.g. ["Default"]) or expanding a fleet (e.g. adding a new device). Present the proposal to the user before calling resolve_proposal.
Inputs: description (required), record_name (required), key_variants (required), key_prefix.
query_schemaA
Get JSON schema and type information for a record.
Returns the data structure, field types, and metadata. Use this before setting record values to understand expected format.
Schema is inferred from current value + database metadata.
💡 TIP: Field names like 'celsius', 'timestamp', 'sensor_id' carry semantic meaning. If units or formats are unclear, ask the user for clarification.
Inputs: record_name (required), endpoint, include_example.
remove_binaryA
Propose removal of an existing binary. Creates a pending proposal — call resolve_proposal to confirm. Task definitions are preserved; only the binary grouping is removed.
Inputs: binary_name (required).
remove_recordA
Propose removal of an existing record. Creates a pending proposal — call resolve_proposal to confirm. Note: removing a record breaks generated type aliases.
Inputs: record_name (required).
remove_taskA
Propose removal of an existing task. Creates a pending proposal — call resolve_proposal to confirm. Note: removing a task affects binaries that reference it.
Inputs: task_name (required).
rename_recordA
Propose renaming a record. Creates a pending proposal — call resolve_proposal to confirm. Note: renames the generated key enum and value struct, breaking existing references.
Inputs: new_name (required), old_name (required).
reset_buffer_metricsA
Reset buffer introspection counters (produced/consumed/dropped/occupancy) for every record on a running AimDB instance (requires write permission and the metrics feature).
Inputs: endpoint.
reset_sessionA
Reset the architecture agent session, discarding any pending proposals. Use when the user wants to start over or abandon the current ideation cycle.
Inputs: no named parameters.
reset_stage_profilingA
Reset stage profiling counters for every record on a running AimDB instance (requires write permission and the profiling feature).
Inputs: endpoint.
resolve_proposalA
Resolve a pending proposal. On confirm: applies the change, writes state.toml, generates Mermaid and Rust artefacts. On reject: discards without changes. On revise: discards with a redirect message.
Inputs: resolution (required), proposal_id (required), redirect, rust_path, +2 more.
save_memoryA
Persist ideation context and design rationale to .aimdb/memory.md. Call this after every confirmed proposal with a narrative summary of what the user is building, the key question asked, the answer received, why the chosen buffer type fits, alternatives that were considered and rejected, and any future considerations noted. On session start, read aimdb://architecture/memory to restore this context.
Inputs: entry (required), mode, memory_path.
set_recordB
Set the value of a writable record in an AimDB instance. Only works for records with write permissions.
Inputs: value (required), record_name (required), endpoint.
validate_against_instanceA
Compare state.toml against a live AimDB instance and return a conflict report. Detects missing records, buffer type mismatches, capacity differences, and connector mismatches.
Inputs: endpoint, state_path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools target clearly distinct runtime or architecture actions, such as get_record vs. drain_record vs. set_record. The proposal tools are mostly well separated, though propose_add_record, propose_modify_fields, and propose_modify_key_variants can overlap for record-definition edits, requiring description-level reading to choose correctly.
The set is overwhelmingly snake_case and most names follow a verb_noun pattern like get_record, set_record, and propose_add_task. Minor deviations exist: graph_nodes/graph_edges/graph_topo_order are noun-first, and remove_task/rename_record behave like proposals but lack the propose_ prefix used elsewhere.
With 30 tools, the server is heavy for an agent tool surface and splits attention across runtime inspection, graph analysis, profiling, and architecture proposals. The tools are not redundant, but the count is high enough that selection pressure and prompt load become concerns.
The surface covers runtime discovery, reads/writes, schema, metrics, profiling, graph topology, validation, and a broad architecture proposal lifecycle. A few gaps remain, such as no explicit remove_connector or modify_task/binary operation, but agents can likely work around them through adjacent proposals.
Maintenance
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
An MCP server for search and retrieval over a local LanceDB database
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that provides LLMs access to other LLMs449 npm82MIT
- AlicenseNot gradedqualityAmaintenanceThe Multi DB MCP Server is a high-performance implementation of the Database Model Context Protocol designed to revolutionize how AI agents interact with databases. Currently supporting MySQL and PostgreSQL databases.485MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI applications to interact with DiceDB databases.5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for AI-assisted Python debugging using debugpy and Debug Adapter Protocol, enabling AI agents to run tests, set breakpoints, and inspect variables via natural language.8MIT