mcp-arango-mind

An ArangoDB MCP server for agents that need more than a database wrapper.

mcp-arango-mind turns ArangoDB into a schema-driven tool surface: discover the operation you need, inspect the contract, execute it with structured parameters, and keep higher-level knowledge workflows in templates and atlas projections instead of oversized tool lists.

The project is built for three jobs:

• use ArangoDB as a document, graph, and search substrate from MCP clients

• keep the MCP surface small with search -> describe -> exec instead of hundreds of exposed tools

• turn notes, edges, templates, views, and graph topology into handbook-style knowledge coordinates

It has zero npm dependencies and runs on Node.js built-ins.

Why It Exists

Agent database tooling has two common failure modes: every database operation becomes a separate MCP tool, or the agent has to hand-write queries without enough local context. Both scale badly.

This server uses a layered surface:

MCP client
  -> small MCP tool surface
  -> schema-owned tool owners
  -> ArangoDB OpenAPI operation catalog
  -> ArangoDB

Large catalogs stay searchable. Stable workflows become templates. Knowledge structure becomes atlas projections. The agent keeps a coordinate system instead of guessing through a giant action menu.

Related MCP server: MySQL MCP Server

Current Surface

The generic ArangoDB flow is:

mcp.arango search -> mcp.arango describe -> mcp.arango exec

Category tools expose direct owner actions. The tools/list description keeps one compact line per action in the same shape as the real call:

mcp.tool.collection(action=insert, payload={"collection":"notes","document":{}})
mcp.tool.admin(action=aql_query, payload={"query":"RETURN 1"})

Use mcp.help for the full schema-owned action page:

mcp.help(action=get, payload={"target":"mcp.tool.collection","action":"insert"})

Unmigrated actions are not advertised as normal callable actions. If an older action name is known but not implemented in master, mcp.help get returns an explicit unavailable page instead of a normal payload contract.

Raw OpenAPI, template, and atlas profile selection still use payload.target because those actions select a nested catalog entry.

Quick Start

git clone https://github.com/woolkingx/mcp-arango-mind.git
cd mcp-arango-mind

cp .env.example .env
# Edit .env with your ArangoDB connection details.

node server.mjs

No npm install is required.

For HTTP transport:

node server.mjs --sse --port 8000

Configuration

The connection cascade is:

CLI flags
  -> environment variables
  -> .env
  -> config/profiles.json
  -> config/arango-connection.json schema defaults

Common environment variables:

Useful CLI flags:

--profile <name>    Select profile from config/profiles.json
--debug             Force debug logging
--sse               Use HTTP JSON transport
--port <number>     HTTP port, default 8000
--host <address>    HTTP bind address, default 127.0.0.1
--audit <file>      Write structured JSON audit events

Example Calls

Search the ArangoDB OpenAPI catalog:

{
  "action": "search",
  "payload": {
    "query": "collection create"
  }
}

Execute a known operation:

{
  "action": "exec",
  "payload": {
    "target": "createCollection",
    "params": {
      "name": "notes",
      "type": 2
    }
  }
}

Run a curated template:

{
  "action": "call",
  "payload": {
    "target": "memory.view",
    "params": {
      "query": "handbook",
      "tags": ["knowledge-organization"],
      "limit": 10
    }
  }
}

Insert a document through the collection owner:

{
  "action": "insert",
  "payload": {
    "collection": "notes",
    "document": {
      "title": "Example",
      "content": "Schema-owned write."
    }
  }
}

Read an atlas projection:

{
  "action": "call",
  "payload": {
    "target": "atlas.index",
    "params": {
      "root": "notes/root",
      "depth": 2
    }
  }
}

MCP clients send these payloads through tools/call with the corresponding tool name, such as mcp.arango, mcp.tool.template, or mcp.tool.atlas.

Handbook

The public README is the quickstart and product entry. Architecture truth lives in the handbook:

• Handbook index

• Tool surfaces

• Tool categories

• Known risks

• Roadmap

• Changelog

The handbook records owner boundaries, schema roots, topology, acceptance gates, migration rationale, and the atlas design.

Verification

npm test
node scripts/handbook-link-check.mjs docs/handbook
node scripts/handbook-parse.mjs docs/handbook/index.html

Live ArangoDB checks use the connection from .env or environment variables. Tests that require ArangoDB skip when no live connection is configured.

Project Status

Current release line: 0.3.0.

Runtime boundary:

• Node.js 22+

• zero npm dependencies

• MCP stdio transport by default

• HTTP JSON transport via --sse

• ArangoDB operation contracts projected from arango/schema/arango.openapi.schema.json

• tool activation projected from tools/schema/tools.schema.json

File-size discipline:

• project-owned .mjs files stay under 500 lines

• 200 lines is the recommended split checkpoint

• vendored src/lib/schema2object.mjs follows its sync gate

License

MIT