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: Neo4j GraphRAG 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

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers