@xcitedbs/mcp

Model Context Protocol (MCP) server for XciteDB: exposes REST operations as MCP tools and ships static resources (xcitedb://conventions, xcitedb://api-overview) for assistants.

Implementation wraps the official @xcitedbs/client JavaScript SDK (stdio transport).

Requirements

• Node.js 18+
• A running XciteDB server and credentials (API key or platform Bearer token)

Install

From npm (when published):

npm install -g @xcitedbs/mcp

From this monorepo / local path:

cd sdks/mcp
npm ci
npm run build

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | XCITEDB_BASE_URL | Yes | API origin only, e.g. http://localhost:8080 (no /api/v1 suffix). | | XCITEDB_API_KEY | One of key/token | Developer API key (X-API-Key). | | XCITEDB_ACCESS_TOKEN | One of key/token | Platform JWT (Authorization: Bearer). | | XCITEDB_PROJECT_ID | Recommended with Bearer | Tenant/project id; with Bearer + this id, platform console mode sends X-Project-Id. Also set as default context.project_id. | | XCITEDB_BRANCH | No | Default X-Branch context. | | XCITEDB_SAFE_MODE | No | Default true. When true, mutating tools require confirm: true in tool arguments. | | XCITEDB_TEST_SESSION | No | If set, all tools run against the test session (X-Test-Session). The session may be a normal empty ephemeral session or an overlay session (provisioned with create_test_session and overlay: true); overlay is determined when the session is created, not by this env var. | | XCITEDB_TEST_AUTH_REQUIRED | No | When using a test session, set to 1/true to send X-Test-Auth: required. |

Cursor

Add to MCP settings (example):

{
  "mcpServers": {
    "xcitedb": {
      "command": "node",
      "args": ["/absolute/path/to/sdks/mcp/dist/index.js"],
      "env": {
        "XCITEDB_BASE_URL": "http://127.0.0.1:8080",
        "XCITEDB_API_KEY": "your-key",
        "XCITEDB_SAFE_MODE": "true"
      }
    }
  }
}

Or with npx after publish:

{
  "mcpServers": {
    "xcitedb": {
      "command": "npx",
      "args": ["-y", "@xcitedbs/mcp"],
      "env": {
        "XCITEDB_BASE_URL": "http://127.0.0.1:8080",
        "XCITEDB_ACCESS_TOKEN": "your-platform-jwt",
        "XCITEDB_PROJECT_ID": "t_your_tenant_id"
      }
    }
  }
}

Claude Desktop

Same pattern as Cursor: claude_desktop_config.json → mcpServers → command + args + env.

Tools (summary)

Document & query: list_documents, list_children, read_document, write_document, delete_document, list_json_documents, read_json_document, write_json_document, delete_json_document, run_unquery, search (optional at_date / date_from / date_to for temporal full-text search; use mode: "fts" for keyword-only temporal queries).

Versioning: list_workspaces, create_workspace, delete_workspace, publish_workspace, list_checkpoints, create_checkpoint, compare, list_bookmarks, create_bookmark, delete_bookmark, get_checkpoint, apply_checkpoint, revert_to_checkpoint.

Meta & locks: read_metadata, write_metadata, list_locks, acquire_lock, release_lock.

Project & security: server_health, list_projects, list_policies, create_policy.

Test DB: create_test_session (optional argument overlay: true to read production data through a writable server-side overlay—writes never hit production), destroy_test_session.

Resources

• xcitedb://conventions — short list of non-standard XciteDB behaviors (branches, identifiers, auth, Unquery).
• xcitedb://api-overview — compact REST surface overview.

Development

npm run build      # bundle to dist/index.js (esbuild)
npm run test:unit  # vitest unit tests (in-memory MCP + mocks)

Integration tests (real xcitedb-server binary under repo build/bin/):

XCITEDB_MCP_INTEGRATION=1 npm run test:integration

Optional: XCITEDB_WET_BUILD=1 to auto-run CMake if the binary is missing.

License

MIT (same as the parent project unless noted otherwise).