thingd-cli 0.5.0 → 0.6.0

package/README.md

@@ -20,6 +20,20 @@ Or run it on the fly using `npx`:
 npx thingd-cli
 ```
 
+## Quick Start: Zero-Config MCP Setup
+
+The easiest way to integrate `thingd` with your AI editors (Claude Desktop and Cursor) is to run the automated setup command:
+
+```bash
+thingd install
+```
+
+This command will:
+- Auto-detect the absolute path of your active `node` binary and global `thingd` script.
+- Automatically locate or create your persistent local database at `~/.thingd/data.db`.
+- **For Claude Desktop**: Automatically configure the stdio MCP server in your `claude_desktop_config.json` (macOS).
+- **For Cursor**: Print the exact, copy-pasteable JSON block to paste into your Cursor MCP settings.
+
 ## Two Modes of Operation
 
 The CLI is designed to support both human operators and automated scripts through two distinct modes:
@@ -71,7 +85,7 @@ You can configure the connection via environment variables or CLI flags:
 ```txt
 --url <url>          remote thingd URL. Defaults to THINGD_URL
 --auth-token <tok>   remote bearer token. Defaults to THINGD_AUTH_TOKEN
---path <path>        local database path. Defaults to THINGD_PATH or :memory:
+--path <path>        local database path. Defaults to THINGD_PATH or ~/.thingd/data.db
 --driver <driver>    memory, native, or cloud
 --pretty             pretty-print JSON output
 --limit <n>          result limit for search and list commands

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAKA,OAAO,EAOL,MAAM,EACN,KAAK,YAAY,EAClB,MAAM,QAAQ,CAAC;AAIhB,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjD,KAAK,YAAY,GAAG;IAClB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAyCF,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAiCjB;AAyUD,wBAAsB,MAAM,CAC1B,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAcf;AA4BD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,iBAAiB,CAYxE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAKA,OAAO,EAOL,MAAM,EACN,KAAK,YAAY,EAClB,MAAM,QAAQ,CAAC;AAKhB,KAAK,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjD,KAAK,YAAY,GAAG;IAClB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7B,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AA0CF,wBAAsB,MAAM,CAC1B,IAAI,WAAwB,EAC5B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAiCjB;AA+UD,wBAAsB,MAAM,CAC1B,OAAO,EAAE,UAAU,EACnB,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC,CAcf;AA4BD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,GAAG,iBAAiB,CAiBxE"}

package/dist/index.js

@@ -5,6 +5,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { ThingD, } from "thingd";
 import { runInteractiveCli } from "./interactive.js";
 import { runMcp } from "./mcp.js";
+import { defaultThingdDbPath, ensureThingdDir } from "./paths.js";
 const HELP_TEXT = `thingd
 
 Admin and operator CLI for thingd.
@@ -12,6 +13,7 @@ Admin and operator CLI for thingd.
 Usage:
   thingd status [--url <url>]
   thingd tools --url <url>
+  thingd install
   thingd mcp [--path <path>] [--driver <driver>]
   thingd mcp-http [--path <path>] [--driver <driver>] [--host <host>] [--port <port>] [--auth-token <tok>] [--allow-unauthenticated]
   thingd search <query> [--collection <name>] [--limit <n>]
@@ -35,7 +37,7 @@ Usage:
 Options:
   --url <url>          remote thingd URL. Defaults to THINGD_URL
   --auth-token <tok>  remote bearer token. Defaults to THINGD_AUTH_TOKEN
-  --path <path>       local database path. Defaults to THINGD_PATH or :memory:
+  --path <path>       local database path. Defaults to THINGD_PATH or ~/.thingd/data.db
   --driver <driver>   memory, native, or cloud
   --pretty            pretty-print JSON output
   --limit <n>         result limit for search and list commands
@@ -93,6 +95,11 @@ async function runCommand(context) {
         await runMcpHttp(context);
         return;
     }
+    if (command === "install") {
+        const { runInstall } = await import("./install.js");
+        await runInstall(context);
+        return;
+    }
     if (command === "objects") {
         await runObjects(context);
         return;
@@ -350,9 +357,12 @@ function buildMemoryEvent(parsed, type) {
 }
 export function resolveConnection(context) {
     const url = stringFlag(context.parsed, "url") ?? context.env.THINGD_URL;
-    const path = url ?? stringFlag(context.parsed, "path") ?? context.env.THINGD_PATH ?? ":memory:";
+    const path = url ?? stringFlag(context.parsed, "path") ?? context.env.THINGD_PATH ?? defaultThingdDbPath();
     const cloud = isCloudPath(path);
     const driver = parseDriver(stringFlag(context.parsed, "driver") ?? context.env.THINGD_DRIVER);
+    if (!cloud && path === defaultThingdDbPath()) {
+        ensureThingdDir();
+    }
     return {
         path,
         driver: driver ?? (cloud ? "cloud" : undefined),

package/dist/install.d.ts

@@ -0,0 +1,3 @@
+import type { CliContext } from "./index.js";
+export declare function runInstall(context: CliContext): Promise<void>;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAY7C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCnE"}

package/dist/install.js

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join, resolve } from "node:path";
+import pc from "picocolors";
+import { defaultThingdDbPath, ensureThingdDir } from "./paths.js";
+export async function runInstall(context) {
+    const nodePath = process.execPath;
+    const cliPath = resolveCliPath();
+    const dbPath = defaultThingdDbPath();
+    const driver = detectDriver();
+    ensureThingdDir();
+    const config = generateMcpConfig(nodePath, cliPath, dbPath, driver);
+    context.stderr.write(`\n${pc.bold("thingd install")}\n\n`);
+    context.stderr.write(`  ${pc.green("✓")} Database path: ${pc.cyan(dbPath)}\n`);
+    context.stderr.write(`  ${pc.green("✓")} Driver: ${pc.cyan(driver)}\n`);
+    context.stderr.write(`  ${pc.green("✓")} Node: ${pc.cyan(nodePath)}\n`);
+    context.stderr.write(`  ${pc.green("✓")} CLI:   ${pc.cyan(cliPath)}\n\n`);
+    const claudeResult = updateClaudeDesktopConfig(config);
+    if (claudeResult.updated) {
+        context.stderr.write(`  ${pc.bold("Claude Desktop:")}\n`);
+        context.stderr.write(`    ${pc.green("✓")} Updated ${pc.cyan(claudeResult.path)}\n\n`);
+    }
+    else if (claudeResult.skipped) {
+        context.stderr.write(`  ${pc.bold("Claude Desktop:")}\n`);
+        context.stderr.write(`    ${pc.yellow("⊘")} Skipped: ${claudeResult.reason}\n\n`);
+    }
+    context.stderr.write(`  ${pc.bold("Cursor:")}\n`);
+    context.stderr.write(`    Paste this into Cursor Settings → Features → MCP → Add New MCP Server:\n\n`);
+    const fullConfig = {
+        mcpServers: {
+            thingd: config,
+        },
+    };
+    context.stdout.write(`${JSON.stringify(fullConfig, null, 2)}\n`);
+    context.stderr.write(`\n  Restart Claude Desktop to activate. Cursor activates immediately after pasting.\n\n`);
+}
+function resolveCliPath() {
+    const scriptPath = process.argv[1];
+    if (!scriptPath) {
+        throw new Error("Could not detect thingd CLI path from process.argv[1].");
+    }
+    return resolve(scriptPath);
+}
+function detectDriver() {
+    try {
+        // Check if the native .node binary exists relative to the CLI entry point.
+        // When installed globally via npm, thingd-native is typically a sibling package.
+        const cliDir = join(resolveCliPath(), "..", "..");
+        const nativePaths = [
+            join(cliDir, "node_modules", "thingd-native", "dist", "thingd_native.node"),
+            join(cliDir, "..", "thingd-native", "dist", "thingd_native.node"),
+        ];
+        for (const candidate of nativePaths) {
+            if (existsSync(candidate)) {
+                return "native";
+            }
+        }
+    }
+    catch {
+        // Ignore detection errors.
+    }
+    // Default to native since most global installs will have it.
+    // If it's not available, the SDK will produce a clear error at open time.
+    return "native";
+}
+function generateMcpConfig(nodePath, cliPath, dbPath, driver) {
+    return {
+        command: nodePath,
+        args: [cliPath, "mcp", "--path", dbPath, "--driver", driver],
+    };
+}
+function updateClaudeDesktopConfig(config) {
+    if (platform() !== "darwin") {
+        return { skipped: true, reason: "Claude Desktop auto-config is only supported on macOS." };
+    }
+    const configPath = join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    if (!existsSync(configPath)) {
+        return {
+            skipped: true,
+            reason: `Config file not found at ${configPath}. Is Claude Desktop installed?`,
+        };
+    }
+    try {
+        const raw = readFileSync(configPath, "utf-8");
+        const existing = JSON.parse(raw);
+        const mcpServers = (existing.mcpServers ?? {});
+        mcpServers.thingd = config;
+        existing.mcpServers = mcpServers;
+        writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`, "utf-8");
+        return { updated: true, path: configPath };
+    }
+    catch (error) {
+        return {
+            skipped: true,
+            reason: `Failed to update config: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}

package/dist/mcp/tools.js

@@ -10,7 +10,7 @@ const auditInputSchema = {
 };
 export function registerThingdTools(server, db, options = {}) {
     const audit = resolveThingdMcpAuditOptions(options.audit);
-    server.registerTool("thing.search", {
+    server.registerTool("thing_search", {
         title: "Search Memory",
         description: "Search thingd objects and events by text.",
         inputSchema: {
@@ -25,7 +25,7 @@ export function registerThingdTools(server, db, options = {}) {
             openWorldHint: false,
         },
     }, async ({ query, collections, limit }) => jsonResult(await db.search(query, { collections, limit })));
-    server.registerTool("thing.get", {
+    server.registerTool("thing_get", {
         title: "Get Object",
         description: "Read one thingd object by collection and id.",
         inputSchema: {
@@ -39,7 +39,7 @@ export function registerThingdTools(server, db, options = {}) {
             openWorldHint: false,
         },
     }, async ({ collection, id }) => jsonResult(await db.get(collection, id)));
-    server.registerTool("thing.put", {
+    server.registerTool("thing_put", {
         title: "Put Object",
         description: "Create or replace one object-shaped memory record.",
         inputSchema: {
@@ -70,7 +70,7 @@ export function registerThingdTools(server, db, options = {}) {
         });
         return jsonResult(stored);
     });
-    server.registerTool("thing.delete", {
+    server.registerTool("thing_delete", {
         title: "Delete Object",
         description: "Delete one thingd object by collection and id.",
         inputSchema: {
@@ -97,7 +97,7 @@ export function registerThingdTools(server, db, options = {}) {
         });
         return jsonResult(result);
     });
-    server.registerTool("thing.events.append", {
+    server.registerTool("thing_events_append", {
         title: "Append Event",
         description: "Append an event to a thingd stream.",
         inputSchema: {
@@ -128,7 +128,7 @@ export function registerThingdTools(server, db, options = {}) {
         });
         return jsonResult(stored);
     });
-    server.registerTool("thing.events.list", {
+    server.registerTool("thing_events_list", {
         title: "List Events",
         description: "List thingd events, optionally filtered by stream.",
         inputSchema: {
@@ -141,7 +141,7 @@ export function registerThingdTools(server, db, options = {}) {
             openWorldHint: false,
         },
     }, async ({ stream }) => jsonResult(await db.events.list(stream)));
-    server.registerTool("thing.queue.push", {
+    server.registerTool("thing_queue_push", {
         title: "Push Queue Job",
         description: "Push a durable job onto a thingd queue.",
         inputSchema: {
@@ -179,7 +179,7 @@ export function registerThingdTools(server, db, options = {}) {
         });
         return jsonResult(job);
     });
-    server.registerTool("thing.queue.claim", {
+    server.registerTool("thing_queue_claim", {
         title: "Claim Queue Job",
         description: "Claim the next ready job from a thingd queue.",
         inputSchema: {
@@ -213,7 +213,7 @@ export function registerThingdTools(server, db, options = {}) {
         }
         return jsonResult(job);
     });
-    server.registerTool("thing.queue.ack", {
+    server.registerTool("thing_queue_ack", {
         title: "Acknowledge Queue Job",
         description: "Mark one leased queue job as completed.",
         inputSchema: {
@@ -245,7 +245,7 @@ export function registerThingdTools(server, db, options = {}) {
         }
         return jsonResult(result);
     });
-    server.registerTool("thing.queue.nack", {
+    server.registerTool("thing_queue_nack", {
         title: "Reject Queue Job",
         description: "Reject a leased queue job for retry or dead-letter routing.",
         inputSchema: {
@@ -279,7 +279,7 @@ export function registerThingdTools(server, db, options = {}) {
         }
         return jsonResult(result);
     });
-    server.registerTool("thing.queue.list", {
+    server.registerTool("thing_queue_list", {
         title: "List Queue Jobs",
         description: "List jobs in a thingd queue.",
         inputSchema: {
@@ -292,7 +292,7 @@ export function registerThingdTools(server, db, options = {}) {
             openWorldHint: false,
         },
     }, async ({ queue }) => jsonResult(await db.queue(queue).list()));
-    server.registerTool("thing.queue.dead", {
+    server.registerTool("thing_queue_dead", {
         title: "List Dead Queue Jobs",
         description: "List dead-letter jobs in a thingd queue.",
         inputSchema: {

package/dist/mcp-http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-http.d.ts","sourceRoot":"","sources":["../src/mcp-http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAwCnE"}
+{"version":3,"file":"mcp-http.d.ts","sourceRoot":"","sources":["../src/mcp-http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAM7C,wBAAsB,UAAU,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CA4CnE"}

package/dist/mcp-http.js

@@ -1,17 +1,21 @@
 import { readClusterOptionsFromEnv } from "./mcp/cluster.js";
 import { parsePort, parseThingdDriver, readMcpAuditOptionsFromEnv } from "./mcp/config.js";
 import { startThingdHttpServer } from "./mcp/http.js";
+import { defaultThingdDbPath, ensureThingdDir } from "./paths.js";
 export async function runMcpHttp(context) {
     const parsed = context.parsed;
     // Resolve port, host, allowUnauthenticated, etc. from flags or env
     const portStr = parsed.flags.get("port")?.at(-1) ?? context.env.THINGD_PORT;
     const host = parsed.flags.get("host")?.at(-1) ?? context.env.THINGD_HOST ?? "127.0.0.1";
-    const path = parsed.flags.get("path")?.at(-1) ?? context.env.THINGD_PATH ?? ":memory:";
+    const path = parsed.flags.get("path")?.at(-1) ?? context.env.THINGD_PATH ?? defaultThingdDbPath();
     const driverStr = parsed.flags.get("driver")?.at(-1) ?? context.env.THINGD_DRIVER;
     const authToken = parsed.flags.get("auth-token")?.at(-1) ?? context.env.THINGD_AUTH_TOKEN;
     const allowUnauthenticated = parsed.booleans.has("allow-unauthenticated") || parsed.flags.has("allow-unauthenticated");
     const port = parsePort(portStr, 8757);
     const driver = parseThingdDriver(driverStr);
+    if (path === defaultThingdDbPath()) {
+        ensureThingdDir();
+    }
     if (!authToken) {
         console.error("thingd-mcp HTTP runtime is starting without THINGD_AUTH_TOKEN.");
     }

package/dist/paths.d.ts

@@ -0,0 +1,4 @@
+export declare function defaultThingdDir(): string;
+export declare function defaultThingdDbPath(): string;
+export declare function ensureThingdDir(): void;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAOA,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/paths.js

@@ -0,0 +1,14 @@
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const THINGD_DIR_NAME = ".thingd";
+const THINGD_DB_NAME = "data.db";
+export function defaultThingdDir() {
+    return join(homedir(), THINGD_DIR_NAME);
+}
+export function defaultThingdDbPath() {
+    return join(defaultThingdDir(), THINGD_DB_NAME);
+}
+export function ensureThingdDir() {
+    mkdirSync(defaultThingdDir(), { recursive: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thingd-cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Admin and operator CLI for thingd.",
   "type": "module",
   "author": "Sayan Mohsin",
@@ -33,7 +33,7 @@
     "cli-table3": "^0.6.5",
     "picocolors": "^1.1.1",
     "zod": "^4.4.3",
-    "thingd": "0.5.0"
+    "thingd": "0.6.0"
   },
   "engines": {
     "node": ">=20"