@graypirate/tabula-mcp 1.0.0

package/README.md

@@ -0,0 +1,59 @@
+# Tabula MCP
+
+Local stdio MCP server for Tabula. This package is a transport adapter and uses Tabula exclusively through the public `@graypirate/tabula` package API.
+
+## Global Installation
+
+After the package is published, this installs the `tabula-mcp` executable and a compatible Tabula Core library from the npm registry. [Install Tabula Core globally](../core/README.md#global-installation) as well when you want its standalone CLI.
+
+```bash
+bun add --global @graypirate/tabula-mcp
+```
+
+Verify:
+```bash
+command -v tabula-mcp
+```
+
+Upgrade or remove the MCP package with Bun:
+```bash
+bun update --global @graypirate/tabula-mcp
+bun remove --global @graypirate/tabula-mcp
+```
+
+Tabula MCP uses stdio. The MCP client starts and owns the server process; do not run it as a background daemon.
+
+## Configure a Client
+
+```json
+{
+  "mcpServers": {
+    "tabula": {
+      "command": "tabula-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+The client launches the server over stdio. No daemon is required. For desktop
+clients that do not inherit the shell `PATH`, use the absolute path returned by
+`command -v tabula-mcp`.
+
+## Tools
+
+- `tabula_initialize_workspace`
+- `tabula_list_workspaces`
+- `tabula_read_workspace`
+- `tabula_list_workspace_entities`
+- `tabula_read_entity`
+- `tabula_list_entity_children`
+- `tabula_search_entities`
+- `tabula_create_object`
+- `tabula_create_block`
+- `tabula_write_entity`
+- `tabula_delete_entity`
+- `tabula_delete_workspace`
+
+Each tool accepts one JSON object. The server does not accept CLI arguments,
+stdin payloads, file payloads, SQLite paths, or hidden secondary inputs.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createTabulaMCPServer(): McpServer;

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import packageJSON from "../package.json" with { type: "json" };
+import { registerTabulaTools } from "./tools/tabula.js";
+export function createTabulaMCPServer() {
+    const server = new McpServer({
+        name: "tabula-mcp-server",
+        version: packageJSON.version,
+    });
+    registerTabulaTools(server);
+    return server;
+}
+async function main() {
+    const server = createTabulaMCPServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+if (import.meta.main) {
+    await main().catch((error) => {
+        console.error("Fatal MCP server error:", error);
+        process.exit(1);
+    });
+}

package/dist/tools/tabula.d.ts

@@ -0,0 +1,33 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+export declare class MCPInputError extends Error {
+    readonly code: string;
+    readonly details?: unknown | undefined;
+    readonly name = "MCPInputError";
+    constructor(code: string, message: string, details?: unknown | undefined);
+}
+type ToolAnnotations = {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+type ToolResult = {
+    content: [{
+        type: "text";
+        text: string;
+    }];
+    structuredContent: Record<string, unknown>;
+    isError?: true;
+};
+type TabulaTool = {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: z.ZodObject<z.ZodRawShape>;
+    annotations: ToolAnnotations;
+    execute: (input: unknown) => ToolResult;
+};
+export declare const tabulaTools: TabulaTool[];
+export declare function registerTabulaTools(server: McpServer): void;
+export {};

package/dist/tools/tabula.js

@@ -0,0 +1,388 @@
+import { z } from "zod";
+import { create, deleteEntity, deleteWorkspace, initializeWorkspace, InvalidWorkspaceNameError, listEntity, listWorkspaceNames, listWorkspace, openWorkspace, readEntity, readWorkspace, search, validateWriteInput, validateWorkspaceName, writeEntity, TabulaInputError, } from "@graypirate/tabula";
+export class MCPInputError extends Error {
+    code;
+    details;
+    name = "MCPInputError";
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+const workspaceSchema = z.object({
+    workspace: z.string().min(1),
+}).strict();
+const emptySchema = z.object({}).strict();
+const entityIDSchema = z.object({
+    workspace: z.string().min(1),
+    id: z.string().min(1),
+}).strict();
+const searchSchema = z.object({
+    workspace: z.string().min(1),
+    query: z.string(),
+    type: z.enum(["object", "block"]).optional(),
+}).strict();
+const propertiesSchema = z.record(z.unknown()).optional();
+const createObjectSchema = z.object({
+    workspace: z.string().min(1),
+    name: z.string(),
+    properties: propertiesSchema,
+    parentID: z.string().min(1).optional(),
+}).strict();
+const createBlockSchema = z.object({
+    workspace: z.string().min(1),
+    content: z.string(),
+    properties: propertiesSchema,
+    parentID: z.string().min(1),
+}).strict();
+const writeEntitySchema = z.object({
+    workspace: z.string().min(1),
+    parentID: z.string().min(1).optional(),
+    entity: z.unknown(),
+}).strict();
+export const tabulaTools = [
+    {
+        name: "tabula_initialize_workspace",
+        title: "Initialize Tabula Workspace",
+        description: "Create or open a managed Tabula workspace by workspace name.",
+        inputSchema: workspaceSchema,
+        annotations: mutation({ idempotentHint: true }),
+        execute(input) {
+            const { workspace } = parseWorkspaceInput(input);
+            return result(withInitializedWorkspace(workspace, readWorkspace));
+        },
+    },
+    {
+        name: "tabula_list_workspaces",
+        title: "List Tabula Workspaces",
+        description: "List managed Tabula workspace names.",
+        inputSchema: emptySchema,
+        annotations: readOnly(),
+        execute(input) {
+            emptySchema.parse(input);
+            return result({ workspaces: listWorkspaceNames() });
+        },
+    },
+    {
+        name: "tabula_read_workspace",
+        title: "Read Tabula Workspace",
+        description: "Read workspace metadata by workspace name.",
+        inputSchema: workspaceSchema,
+        annotations: readOnly(),
+        execute(input) {
+            const { workspace } = parseWorkspaceInput(input);
+            return result(withWorkspace(workspace, readWorkspace));
+        },
+    },
+    {
+        name: "tabula_list_workspace_entities",
+        title: "List Workspace Root Entities",
+        description: "List ordered root object IDs for a workspace name.",
+        inputSchema: workspaceSchema,
+        annotations: readOnly(),
+        execute(input) {
+            const { workspace } = parseWorkspaceInput(input);
+            return result(withWorkspace(workspace, (db) => ({ objectIDs: listWorkspace(db) })));
+        },
+    },
+    {
+        name: "tabula_read_entity",
+        title: "Read Tabula Entity",
+        description: "Read one object or block as a parent-aware recursive entity tree.",
+        inputSchema: entityIDSchema,
+        annotations: readOnly(),
+        execute(input) {
+            const { workspace, id } = parseEntityIDInput(input);
+            rejectWorkspaceID(id);
+            return result(withWorkspace(workspace, (db) => readEntity(db, id)));
+        },
+    },
+    {
+        name: "tabula_list_entity_children",
+        title: "List Entity Children",
+        description: "List ordered direct child IDs for one object or block.",
+        inputSchema: entityIDSchema,
+        annotations: readOnly(),
+        execute(input) {
+            const { workspace, id } = parseEntityIDInput(input);
+            rejectWorkspaceID(id);
+            return result(withWorkspace(workspace, (db) => ({ childIDs: listEntity(db, id) })));
+        },
+    },
+    {
+        name: "tabula_search_entities",
+        title: "Search Tabula Entities",
+        description: "Search object names/properties and block content/properties in a workspace.",
+        inputSchema: searchSchema,
+        annotations: readOnly(),
+        execute(input) {
+            const { workspace, query, type } = parseSearchInput(input);
+            return result(withWorkspace(workspace, (db) => ({ results: search(db, query, type) })));
+        },
+    },
+    {
+        name: "tabula_create_object",
+        title: "Create Tabula Object",
+        description: "Create one named object with optional properties and optional parent.",
+        inputSchema: createObjectSchema,
+        annotations: mutation({ idempotentHint: false }),
+        execute(input) {
+            const { workspace, createInput, parentID } = parseCreateObjectInput(input);
+            return result(withWorkspace(workspace, (db) => create(db, createInput, parentOptions(parentID))));
+        },
+    },
+    {
+        name: "tabula_create_block",
+        title: "Create Tabula Block",
+        description: "Create one content block with optional properties under an object or block parent.",
+        inputSchema: createBlockSchema,
+        annotations: mutation({ idempotentHint: false }),
+        execute(input) {
+            const { workspace, createInput, parentID } = parseCreateBlockInput(input);
+            return result(withWorkspace(workspace, (db) => create(db, createInput, parentOptions(parentID))));
+        },
+    },
+    {
+        name: "tabula_write_entity",
+        title: "Write Tabula Entity Tree",
+        description: "Create or replace one recursive public object or block entity tree.",
+        inputSchema: writeEntitySchema,
+        annotations: mutation({ idempotentHint: false }),
+        execute(input) {
+            const { workspace, entity, parentID } = parseWriteEntityInput(input);
+            return result(withWorkspace(workspace, (db) => writeEntity(db, entity, parentOptions(parentID))));
+        },
+    },
+    {
+        name: "tabula_delete_entity",
+        title: "Delete Tabula Entity",
+        description: "Delete one object or block and its descendants.",
+        inputSchema: entityIDSchema,
+        annotations: destructive(),
+        execute(input) {
+            const { workspace, id } = parseEntityIDInput(input);
+            rejectWorkspaceID(id);
+            return result(withWorkspace(workspace, (db) => ({ deleted: deleteEntity(db, id) })));
+        },
+    },
+    {
+        name: "tabula_delete_workspace",
+        title: "Delete Tabula Workspace",
+        description: "Delete one managed workspace by workspace name.",
+        inputSchema: workspaceSchema,
+        annotations: destructive(),
+        execute(input) {
+            const { workspace } = parseWorkspaceInput(input);
+            return result({ deleted: deleteWorkspace(workspace) });
+        },
+    },
+];
+export function registerTabulaTools(server) {
+    for (const tool of tabulaTools) {
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema.shape,
+            annotations: tool.annotations,
+        }, async (input) => {
+            try {
+                return tool.execute(input);
+            }
+            catch (error) {
+                return toolError(error);
+            }
+        });
+    }
+}
+function parseWorkspaceInput(input) {
+    const value = workspaceSchema.parse(input);
+    validateMCPWorkspaceName(value.workspace);
+    return value;
+}
+function parseEntityIDInput(input) {
+    const value = entityIDSchema.parse(input);
+    validateMCPWorkspaceName(value.workspace);
+    inferMCPIDType(value.id);
+    return value;
+}
+function parseSearchInput(input) {
+    const value = searchSchema.parse(input);
+    validateMCPWorkspaceName(value.workspace);
+    return value;
+}
+function parseCreateObjectInput(input) {
+    const value = createObjectSchema.parse(input);
+    validateMCPWorkspaceName(value.workspace);
+    if (value.parentID !== undefined) {
+        inferMCPIDType(value.parentID);
+    }
+    return {
+        workspace: value.workspace,
+        createInput: {
+            type: "object",
+            name: value.name,
+            properties: properties(value.properties),
+        },
+        ...(value.parentID === undefined ? {} : { parentID: value.parentID }),
+    };
+}
+function parseCreateBlockInput(input) {
+    const value = createBlockSchema.parse(input);
+    validateMCPWorkspaceName(value.workspace);
+    if (inferMCPIDType(value.parentID) === "workspace") {
+        throw new MCPInputError("INVALID_PARENT", `Workspace parents can only contain objects: ${value.parentID}`);
+    }
+    return {
+        workspace: value.workspace,
+        createInput: {
+            type: "block",
+            content: value.content,
+            properties: properties(value.properties),
+        },
+        parentID: value.parentID,
+    };
+}
+function parseWriteEntityInput(input) {
+    const value = writeEntitySchema.parse(input);
+    validateMCPWorkspaceName(value.workspace);
+    if (value.parentID !== undefined) {
+        inferMCPIDType(value.parentID);
+    }
+    return {
+        workspace: value.workspace,
+        entity: validateWriteInput(value.entity),
+        ...(value.parentID === undefined ? {} : { parentID: value.parentID }),
+    };
+}
+function withInitializedWorkspace(workspace, callback) {
+    const db = initializeWorkspace(workspace);
+    try {
+        return callback(db);
+    }
+    finally {
+        db.close();
+    }
+}
+function withWorkspace(workspace, callback) {
+    const db = openWorkspace(workspace);
+    try {
+        return callback(db);
+    }
+    finally {
+        db.close();
+    }
+}
+function validateMCPWorkspaceName(workspace) {
+    try {
+        validateWorkspaceName(workspace);
+    }
+    catch (error) {
+        if (error instanceof InvalidWorkspaceNameError) {
+            throw new MCPInputError("INVALID_WORKSPACE_NAME", error.message, error.details);
+        }
+        throw error;
+    }
+}
+function inferMCPIDType(id) {
+    switch (id.slice(0, 2)) {
+        case "d_":
+            return "workspace";
+        case "o_":
+            return "object";
+        case "b_":
+            return "block";
+        default:
+            throw new MCPInputError("INVALID_ID", `Unknown entity ID prefix: ${id}`);
+    }
+}
+function rejectWorkspaceID(id) {
+    if (inferMCPIDType(id) === "workspace") {
+        throw new MCPInputError("INVALID_ID", `Expected object or block ID: ${id}`);
+    }
+}
+function properties(value) {
+    if (value === undefined) {
+        return {};
+    }
+    if (!isJSONValue(value)) {
+        throw new MCPInputError("INVALID_FIELD", "Properties must contain only JSON values", {
+            field: "properties",
+        });
+    }
+    return value;
+}
+function isJSONValue(value) {
+    if (value === null
+        || typeof value === "string"
+        || typeof value === "number"
+        || typeof value === "boolean") {
+        return true;
+    }
+    if (Array.isArray(value)) {
+        return value.every(isJSONValue);
+    }
+    if (typeof value === "object") {
+        return Object.values(value).every(isJSONValue);
+    }
+    return false;
+}
+function parentOptions(parentID) {
+    return parentID === undefined ? {} : { parentID };
+}
+function result(output) {
+    const structuredContent = toRecord(output);
+    return {
+        content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+        structuredContent,
+    };
+}
+function toolError(error) {
+    const output = {
+        error: {
+            code: error instanceof MCPInputError || error instanceof TabulaInputError
+                ? error.code
+                : "OPERATION_FAILED",
+            message: error instanceof Error ? error.message : String(error),
+            ...((error instanceof MCPInputError || error instanceof TabulaInputError)
+                && error.details !== undefined
+                ? { details: error.details }
+                : {}),
+        },
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(output) }],
+        structuredContent: output,
+        isError: true,
+    };
+}
+function toRecord(output) {
+    if (output !== null && typeof output === "object" && !Array.isArray(output)) {
+        return output;
+    }
+    return { value: output };
+}
+function readOnly() {
+    return {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    };
+}
+function mutation(options) {
+    return {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: options.idempotentHint,
+        openWorldHint: false,
+    };
+}
+function destructive() {
+    return {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false,
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@graypirate/tabula-mcp",
+  "version": "1.0.0",
+  "description": "Local stdio MCP server for Tabula.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "tabula-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && chmod 755 dist/index.js",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build",
+    "start": "bun src/index.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "dependencies": {
+    "@graypirate/tabula": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.9.1",
+    "typescript": "^5"
+  }
+}