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.

Current Surface

Tool	Use
mcp.mcp	Inspect the live MCP tool catalog, categories, and surface roots.
mcp.help	Read full schema-owned help for one tool action.
mcp.arango	Search, describe, and execute raw ArangoDB OpenAPI operations.
mcp.tool.database	Work with ArangoDB database lifecycle operations.
mcp.tool.collection	Work with collections, documents, indexes, and CRUD schema gates.
mcp.tool.view	Work with ArangoSearch views and analyzers.
mcp.tool.graph	Work with ArangoDB graph operations.
mcp.tool.admin	Work with administration, AQL, monitoring, and task operations.
mcp.tool.template	List, search, validate, manage, and execute curated AQL templates.
mcp.tool.atlas	Read handbook-style projections over notes, edges, topology, and readiness hints.

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:

Variable	Default	Description
ARANGO_URL	http://127.0.0.1:8529	ArangoDB server URL.
ARANGO_DB	_system	Database name.
ARANGO_USERNAME	root	Basic auth username.
ARANGO_PASSWORD	empty	Basic auth password.
ARANGO_TOKEN	unset	Bearer token; overrides username and password.
ARANGO_LOG_LEVEL	info	silent, error, warn, info, debug, or trace.

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