tana-mcp-codemode 0.3.0 → 0.3.3

package/README.md

@@ -1,57 +1,37 @@
 # tana-mcp-codemode
 
-Codemode MCP server for [Tana](https://tana.inc). Instead of structured API calls, your AI writes TypeScript that executes directly against the Tana Local API.
+Codemode MCP server for [Tana](https://tana.inc). AI writes TypeScript that executes directly against the Tana Local API.
 
-## Install
-
-### Binary (no runtime required)
+**Requires:** Tana Desktop with Local API enabled + an API token (Settings → API).
 
-Download from [GitHub Releases](https://github.com/fabiogaliano/tana-mcp-codemode/releases) for your platform:
+## Install
 
-| Platform | File |
-|----------|------|
-| macOS ARM | `tana-mcp-codemode-darwin-arm64` |
-| macOS Intel | `tana-mcp-codemode-darwin-x64` |
-| Linux x64 | `tana-mcp-codemode-linux-x64` |
-| Linux ARM | `tana-mcp-codemode-linux-arm64` |
-| Windows | `tana-mcp-codemode-windows-x64.exe` |
+**Binary** — download from [GitHub Releases](https://github.com/fabiogaliano/tana-mcp-codemode/releases), `chmod +x`, run.
 
+**npm** (Node.js ≥ 20):
 ```bash
-chmod +x tana-mcp-codemode-darwin-arm64
-./tana-mcp-codemode-darwin-arm64
+npm install -g tana-mcp-codemode
 ```
 
-### npm (requires Node.js ≥ 20)
+**From source** (Bun): `git clone` → `bun install` → `bun run src/entry-bun.ts`
 
-```bash
-npm install -g tana-mcp-codemode
-# or run without installing:
-npx tana-mcp-codemode
-```
+## Setup
 
-### From source (requires Bun)
+Run the interactive setup script — detects your installation, prompts for credentials, and configures Claude Code and/or Claude Desktop automatically:
 
 ```bash
-git clone https://github.com/fabiogaliano/tana-mcp-codemode
-cd tana-mcp-codemode
-bun install
-bun run src/entry-bun.ts
+bun run setup
+# or for team-shared config:
+bun run setup --scope project
 ```
 
-## Prerequisites
-
-- [Tana Desktop](https://tana.inc) with **Local API enabled** (Settings → Local API → Enable)
-- An API token from Tana (Settings → API → Generate Token)
-
-## MCP Configuration
-
-Add to your MCP client config (e.g. `claude_desktop_config.json`):
+## Manual MCP Configuration
 
 ```json
 {
   "mcpServers": {
     "tana": {
-      "command": "/path/to/tana-mcp-codemode-darwin-arm64",
+      "command": "tana-mcp-codemode",
       "env": {
         "TANA_API_TOKEN": "your-token-here",
         "MAIN_TANA_WORKSPACE": "My Workspace"
@@ -61,39 +41,33 @@ Add to your MCP client config (e.g. `claude_desktop_config.json`):
 }
 ```
 
-For npm install, use `"command": "tana-mcp-codemode"`. For source, use `"command": "bun"` with `"args": ["run", "/path/to/src/entry-bun.ts"]`.
+For binary: set `command` to the binary path. For source: `"command": "bun", "args": ["run", "/path/to/src/entry-bun.ts"]`.
 
 ## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TANA_API_TOKEN` | (required) | Bearer token from Tana Desktop |
+| `TANA_API_TOKEN` | required | Bearer token from Tana Desktop |
 | `TANA_API_URL` | `http://127.0.0.1:8262` | Tana Local API URL |
-| `MAIN_TANA_WORKSPACE` | (none) | Default workspace name or ID |
-| `TANA_SEARCH_WORKSPACES` | (none) | Comma-separated workspaces for search scope |
+| `MAIN_TANA_WORKSPACE` | — | Default workspace name or ID |
+| `TANA_SEARCH_WORKSPACES` | — | Comma-separated workspaces for search scope |
 | `TANA_TIMEOUT` | `10000` | Request timeout in ms |
-| `TANA_HISTORY_PATH` | (platform default) | Custom SQLite history path |
+| `TANA_HISTORY_PATH` | platform default | Custom SQLite history path |
 
 ## Usage Examples
 
-Search for nodes:
-
 ```typescript
+// Search nodes
 const results = await tana.nodes.search("project ideas", {
   workspaceIds: [tana.workspace.id]
 });
-console.log(results.map(n => n.name));
-```
-
-Import content with tags and fields:
 
-```typescript
+// Import with tags and fields
 await tana.import(tana.workspace.id, `
 %%tana%%
 - Meeting notes #meeting
   - Date:: [[2024-01-15]]
   - Attendees:: Alice, Bob
-  - Summary:: Discussed Q1 roadmap
 `);
 ```
 
@@ -101,26 +75,24 @@ await tana.import(tana.workspace.id, `
 
 | Namespace | Methods |
 |-----------|---------|
-| `tana.workspace` | Pre-resolved default workspace |
+| `tana.workspace` | pre-resolved default workspace |
 | `tana.workspaces` | `list()` |
 | `tana.nodes` | `search()`, `read()`, `getChildren()`, `edit()`, `move()`, `trash()`, `check()`, `uncheck()`, `open()` |
 | `tana.tags` | `listAll()`, `getSchema()`, `create()`, `modify()`, `addField()`, `setCheckbox()` |
 | `tana.fields` | `setOption()`, `setContent()`, `getFieldOptions()` |
 | `tana.calendar` | `getOrCreate()` |
-| `tana.import()` | Import Tana Paste content |
+| `tana.import()` | import Tana Paste content |
 | `tana.health()` | API health check |
 
 ## Development
 
 ```bash
-bun install          # Install deps
-bun run start        # Start MCP server
-bun run dev          # Dev mode with watch
-bun run test         # Run tests
-bun run typecheck    # Type check
-bun run build        # Build Node.js dist (tsup)
-bun run build:binary # Build self-contained binary
-bun run debug        # Debug UI at localhost:3333
+bun run start        # MCP server
+bun run dev          # watch mode
+bun run test         # tests
+bun run build        # Node.js dist (tsup)
+bun run build:binary # self-contained binary
+bun run debug        # debug UI at :3333
 ```
 
 ## License

package/dist/entry-node.js

@@ -1215,6 +1215,7 @@ console.log() output becomes LLM context. Keep it compact:
 
 ## API Notes
 
+- **WARNING ON BULK UPDATES**: NEVER use tana.nodes.trash() followed by tana.import() to bulk-edit existing nodes. This destroys user data. Always update existing nodes individually using tana.fields.setContent or tana.nodes.edit.
 - search: no offset/pagination \u2014 use narrower queries, not repeated calls
 - getChildren: only endpoint with pagination (limit + offset)
 - Timeout is 10s. On timeout, try a different approach, not the same call.

package/package.json

@@ -1,12 +1,29 @@
 {
   "name": "tana-mcp-codemode",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "description": "Codemode MCP server for Tana — AI writes TypeScript that executes against Tana Local API",
   "type": "module",
   "main": "dist/entry-node.js",
   "bin": {
     "tana-mcp-codemode": "dist/entry-node.js"
   },
+  "scripts": {
+    "setup": "bun run scripts/setup.ts",
+    "generate": "bun run scripts/generate.ts",
+    "list-endpoints": "bun run scripts/list-endpoints.ts",
+    "check-api": "bun run scripts/check-api-version.ts",
+    "start": "bun run --env-file=.env src/entry-bun.ts",
+    "dev": "bun run --env-file=.env --watch src/entry-bun.ts",
+    "debug": "bun run --env-file=.env src/debug-server.ts",
+    "build": "tsup",
+    "build:binary": "bun build --compile src/entry-bun.ts --outfile dist/tana-mcp-codemode",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "prepublishOnly": "bun run typecheck && bun run build",
+    "release:patch": "npm version patch && git push && git push origin $(git describe --tags --abbrev=0)",
+    "release:minor": "npm version minor && git push && git push origin $(git describe --tags --abbrev=0)",
+    "release:major": "npm version major && git push && git push origin $(git describe --tags --abbrev=0)"
+  },
   "files": [
     "dist/",
     "src/",
@@ -42,19 +59,5 @@
     "tsup": "^8",
     "typescript": "^5.9.3"
   },
-  "license": "MIT",
-  "scripts": {
-    "generate": "bun run scripts/generate.ts",
-    "list-endpoints": "bun run scripts/list-endpoints.ts",
-    "start": "bun run --env-file=.env src/entry-bun.ts",
-    "dev": "bun run --env-file=.env --watch src/entry-bun.ts",
-    "debug": "bun run --env-file=.env src/debug-server.ts",
-    "build": "tsup",
-    "build:binary": "bun build --compile src/entry-bun.ts --outfile dist/tana-mcp-codemode",
-    "test": "bun test",
-    "typecheck": "bunx tsc --noEmit",
-    "release:patch": "npm version patch && npm publish",
-    "release:minor": "npm version minor && npm publish",
-    "release:major": "npm version major && npm publish"
-  }
-}
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env bun
+/**
+ * CLI entry point — pipe TypeScript to stdin or pass a file path as argument.
+ *
+ * Usage:
+ *   echo 'console.log(await tana.workspaces.list())' | bun run src/cli.ts
+ *   bun run src/cli.ts script.ts
+ */
+
+import { initCompat } from "./compat";
+import { bunCompat } from "./compat/bun";
+import { createClient } from "./api/client";
+import { createTanaAPI } from "./api/tana";
+import { executeSandbox } from "./sandbox/executor";
+import { initDb, cleanupOldRuns } from "./storage/history";
+import type { Workspace } from "./api/types";
+import type { TanaClient } from "./api/client";
+
+initCompat(bunCompat);
+
+async function resolveWorkspace(client: TanaClient): Promise<Workspace | null> {
+  const envValue = process.env.MAIN_TANA_WORKSPACE?.trim();
+  if (!envValue) return null;
+
+  let workspaces: Workspace[];
+  try {
+    workspaces = await client.get<Workspace[]>("/workspaces");
+  } catch {
+    return null;
+  }
+
+  const byId = workspaces.find((w) => w.id === envValue);
+  if (byId) return byId;
+
+  const lowerEnv = envValue.toLowerCase();
+  return workspaces.find((w) => w.name.toLowerCase() === lowerEnv) ?? null;
+}
+
+async function resolveSearchWorkspaces(client: TanaClient): Promise<string[]> {
+  const envValue = process.env.TANA_SEARCH_WORKSPACES?.trim();
+  if (!envValue) return [];
+
+  const values = envValue.split(",").map((v) => v.trim()).filter(Boolean);
+  if (values.length === 0) return [];
+
+  let workspaces: Workspace[];
+  try {
+    workspaces = await client.get<Workspace[]>("/workspaces");
+  } catch {
+    return [];
+  }
+
+  const resolvedIds: string[] = [];
+  for (const value of values) {
+    const byId = workspaces.find((w) => w.id === value);
+    if (byId) { resolvedIds.push(byId.id); continue; }
+    const byName = workspaces.find((w) => w.name.toLowerCase() === value.toLowerCase());
+    if (byName) resolvedIds.push(byName.id);
+  }
+  return resolvedIds;
+}
+
+async function readCode(): Promise<string> {
+  const filePath = process.argv[2];
+
+  if (filePath) {
+    const file = Bun.file(filePath);
+    const exists = await file.exists();
+    if (!exists) {
+      console.error(`Error: file not found: ${filePath}`);
+      process.exit(1);
+    }
+    return file.text();
+  }
+
+  // Read from stdin
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  const code = Buffer.concat(chunks).toString("utf8").trim();
+
+  if (!code) {
+    console.error("Usage: bun run src/cli.ts [file.ts]");
+    console.error("       echo '<code>' | bun run src/cli.ts");
+    process.exit(1);
+  }
+
+  return code;
+}
+
+async function main() {
+  initDb();
+  const cleaned = cleanupOldRuns(30);
+  if (cleaned > 0) {
+    process.stderr.write(`Cleaned up ${cleaned} old script runs\n`);
+  }
+
+  const code = await readCode();
+  const client = createClient();
+  const workspace = await resolveWorkspace(client);
+  const searchWorkspaceIds = await resolveSearchWorkspaces(client);
+  const tana = createTanaAPI(client, workspace, searchWorkspaceIds);
+
+  const result = await executeSandbox(code, tana);
+
+  if (result.output) {
+    process.stdout.write(result.output + "\n");
+  }
+
+  if (result.error) {
+    process.stderr.write(`Error: ${result.error}\n`);
+  }
+
+  process.stderr.write(`[${result.durationMs}ms]\n`);
+  process.exit(result.success ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/src/prompts.ts

@@ -74,6 +74,7 @@ console.log() output becomes LLM context. Keep it compact:
 
 ## API Notes
 
+- **WARNING ON BULK UPDATES**: NEVER use tana.nodes.trash() followed by tana.import() to bulk-edit existing nodes. This destroys user data. Always update existing nodes individually using tana.fields.setContent or tana.nodes.edit.
 - search: no offset/pagination — use narrower queries, not repeated calls
 - getChildren: only endpoint with pagination (limit + offset)
 - Timeout is 10s. On timeout, try a different approach, not the same call.