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
Schema Inference: Infers JSON schemas from record values
Live Subscriptions: Subscribe to record updates with automatic data capture
Rich Toolset: 11 tools covering all AimDB operations
VS Code Integration: Works seamlessly with GitHub Copilot

Architecture

┌──────────────────────────────┐
│  LLM Host (VS Code/Claude)   │
│  - Natural language queries  │
│  - Tool invocations          │
└──────────────┬───────────────┘
               │ stdio (JSON-RPC 2.0)
               ▼
┌──────────────────────────────┐
│     aimdb-mcp Server         │
│  - Protocol translation      │
│  - Tool implementations      │
│  - Schema inference          │
└──────────────┬───────────────┘
               │ aimdb-client
               ▼
┌──────────────────────────────┐
│  AimDB Instances             │
│  (Unix domain sockets)       │
└──────────────────────────────┘

Quick Start

Installation

Build from source:

cd /aimdb
cargo build --release -p aimdb-mcp

Binary 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": []
    }
  }
}

Test Server

Start the example server:

cd /aimdb/examples/remote-access-demo
cargo run

This 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

1. discover_instances

Find all running AimDB instances:

Query: "What AimDB instances are running?"

Result: Lists socket paths, versions, and record counts

2. 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

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

4. get_record

Get current value of a record:

Query: "What's the current temperature?"

Result: JSON value of server::Temperature record

5. set_record

Set value of a writable record:

Query: "Set the config log_level to debug"

Action: Updates server::Config record

6. query_schema

Infer JSON schema from record values:

Query: "What's the schema of the Temperature record?"

Result: JSON Schema with types, required fields, and example

7. subscribe_record

Subscribe to live record updates:

Query: "Subscribe to temperature for 50 samples"

Action: Creates subscription, auto-saves updates to JSONL file

8. unsubscribe_record

Stop an active subscription:

Query: "Stop subscription sub-abc123"

Action: Unsubscribes and stops data collection

9. list_subscriptions

Show active subscriptions:

Query: "What subscriptions are active?"

Result: Subscription IDs, records, sample counts, file paths

10. get_notification_directory

Get directory where subscription data is saved:

Query: "Where is subscription data saved?"

Result: Path to notification directory

Schema Inference

The MCP server can infer JSON schemas from record values:

// Record value
{
  "celsius": 23.5,
  "sensor_id": "sensor-001",
  "timestamp": 1730379296
}

// Inferred schema
{
  "type": "object",
  "properties": {
    "celsius": { "type": "number" },
    "sensor_id": { "type": "string" },
    "timestamp": { "type": "integer" }
  },
  "required": ["celsius", "sensor_id", "timestamp"]
}

Limitations:

Best-effort inference from current value
May not capture full type constraints
Nullable fields require multiple samples
Ask user for clarification on ambiguous cases

Subscriptions

How It Works

LLM requests subscription with sample limit
Server creates subscription and JSONL file
Updates automatically saved as they arrive
Auto-unsubscribes when limit reached
File path returned for analysis

File Format

Subscription data saved as JSONL (one JSON object per line):

{"timestamp":"2025-11-06T10:30:45.123Z","sequence_number":1,"value":{"celsius":23.5,"sensor_id":"sensor-001"}}
{"timestamp":"2025-11-06T10:30:47.456Z","sequence_number":2,"value":{"celsius":23.6,"sensor_id":"sensor-001"}}
{"timestamp":"2025-11-06T10:30:49.789Z","sequence_number":3,"value":{"celsius":23.7,"sensor_id":"sensor-001"}}

Sample Limits

IMPORTANT: Always ask user for sample limit before subscribing.

Suggested limits:

10-30 samples: Quick check (~20-60 seconds)
50-100 samples: Short monitoring (~2-3 minutes)
200-500 samples: Extended analysis (~7-17 minutes)
null: Unlimited (requires explicit user confirmation)

File Location

Default: ~/.local/share/aimdb-mcp/notifications/

Files named: {subscription_id}.jsonl

Resources

MCP server provides 5 resources:

1. `aimdb://instances`

List of all discovered instances

2. `aimdb://instance/{socket_path}`

Details about specific instance

3. `aimdb://records/{socket_path}`

All records in an instance

4. `aimdb://record/{socket_path}/{record_name}`

Specific record value

5. `aimdb://schema/{socket_path}/{record_name}`

Inferred schema for record

Prompts

MCP server provides 3 helper prompts:

1. `aimdb-quickstart`

Introduction and common usage patterns

2. `notification-directory`

Information about subscription data storage

3. `subscription-help`

Guide to subscriptions and data analysis

Protocol Details

Transport

stdio: JSON-RPC 2.0 over standard input/output
Format: NDJSON (newline-delimited JSON)

Capabilities

Tools: ✓ (11 tools)
Resources: ✓ (5 resources)
Prompts: ✓ (3 prompts)
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 content

Usage 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 details

Record Exploration

User: "What data is available in the demo instance?"

LLM:
1. list_records(/tmp/aimdb-demo.sock) → gets record list
2. For interesting records: get_record() → shows values
3. query_schema() → explains structure
4. Summarizes available data types

Data Monitoring

User: "Monitor temperature for 100 samples and analyze"

LLM:
1. subscribe_record(server::Temperature, 100)
2. Waits for completion
3. Reads JSONL file
4. Analyzes: min, max, avg, trends, anomalies
5. Generates report

Configuration Update

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 change

Error 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 running

Error: Permission denied
  Record 'server::Temperature' is not writable
  Hint: Only records without producers can be set

Development

Building

cargo build -p aimdb-mcp

Testing

# 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 2

Debugging

Enable debug logging:

RUST_LOG=debug aimdb-mcp

Logs 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, subscribe)
Write operations (set) require writable records
No shell access or arbitrary code execution

Data Privacy

Subscription data stored locally
No network communication
All data stays on local machine

Performance

Tool latency: < 10ms for local operations
Subscription overhead: Minimal (async streaming)
Memory usage: ~5MB base + subscription buffers
Concurrent connections: Single-threaded stdio

Troubleshooting

Server not responding

Check if MCP server is running:

ps aux | grep aimdb-mcp

Test stdio manually:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | aimdb-mcp

Can't find instances

Check socket paths:

ls /tmp/*.sock /var/run/aimdb/*.sock

Verify permissions:

stat /tmp/aimdb-demo.sock

Subscription not working

Check notification directory:

ls -la ~/.local/share/aimdb-mcp/notifications/

Verify disk space:

df -h ~/.local/share/

References

MCP Specification: https://spec.modelcontextprotocol.io/
AimX Protocol: docs/design/008-M3-remote-access.md
Schema Design: docs/design/011-M4-schema-query.md

License

See LICENSE file.

aimdb-mcp 0.3.0