@lithium-ai/mcp

MCP server for @lithium-ai/core. Give Claude, Cursor, Windsurf, and any MCP client tools to navigate, store, and retrieve structured data.

Install

npm install @lithium-ai/core @lithium-ai/postgres @lithium-ai/mcp

Quick Start

Create a server file:

// server.ts
import { Lithium } from "@lithium-ai/core";
import { postgresAdapter } from "@lithium-ai/postgres";
import { serveMcp } from "@lithium-ai/mcp";
import postgres from "postgres";

const sql = postgres(process.env.LITHIUM_DATABASE_URL!);

const lithium = new Lithium(postgresAdapter(sql), {
  read: async (versionIds) => {
    const rows = await sql`
      SELECT entry_version_id, data
      FROM content
      WHERE entry_version_id = ANY(${versionIds})
    `;
    return new Map(rows.map((r) => [r.entry_version_id, r.data]));
  },
  write: async (versionId, content) => {
    await sql`INSERT INTO content (entry_version_id, data) VALUES (${versionId}, ${sql.json(content)})`;
    return content;
  },
});

serveMcp(lithium);

Add to your Claude Code config:

{
  "mcpServers": {
    "lithium": {
      "command": "npx",
      "args": ["tsx", "server.ts"]
    }
  }
}

Tools

list_clusters

Lists all clusters in the hierarchy. No parameters.

Returns cluster paths, names, descriptions, and IDs as JSON.

get_context

Get all entries and content under a cluster path. Resolves the full subtree via ltree.

| Parameter | Type | Description | | --------- | -------- | --------------------------------------------------- | | path | string | Dot-separated cluster path, e.g. "infra.database" |

Returns descendant cluster IDs, entries with latest versions, and resolved content as JSON.

create_cluster

Create a knowledge domain. Optionally nest under a parent path.

| Parameter | Type | Description | |---|---|---| | name | string | Name of the cluster | | parentPath | string? | Dot-separated parent path | | description | string? | Description of the cluster |

create_entry

Create a versioned entry in a cluster. Returns the entry and its first version.

| Parameter | Type | Description | |---|---|---| | clusterId | string | ID of the cluster to add the entry to |

API

serveMcp(lithium)

Starts an MCP server with stdio transport. Registers all tools and connects.

import { serveMcp } from "@lithium-ai/mcp";
await serveMcp(lithium);

createMcpServer(lithium)

Creates and returns the MCP server without connecting. Use this if you need a custom transport.

import { createMcpServer } from "@lithium-ai/mcp";
const server = createMcpServer(lithium);
// Connect your own transport

Content

Content callbacks are optional and configured on the Lithium class, not the MCP package.

// Without content callbacks
const lithium = new Lithium(postgresAdapter(sql));
// get_context returns entries without content
// create_entry stores structure only

// With content callbacks
const lithium = new Lithium(postgresAdapter(sql), {
  read: async (versionIds) => new Map(...),
  write: async (versionId, content) => { /* insert */ return content; },
});
// get_context returns entries with content
// create_entry stores structure + content

Requirements

• Node.js >= 20
• PostgreSQL with ltree extension
• MCP-compatible client (Claude Code, etc.)

License

MIT