tana-mcp-codemode 0.1.0 → 0.2.0

package/LICENSE.MD

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 fábio galiano (fabiogaliano.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -5,7 +5,7 @@ A codemode MCP server for [Tana](https://tana.inc) knowledge management. AI writ
 ## Features
 
 - **Codemode Pattern** — AI writes executable TypeScript, not structured API calls
-- **Full Tana API** — Workspaces, nodes, tags, fields, calendar, import
+- **Tana Local API** — Workspaces, nodes, tags, fields, calendar, import
 - **Top-level Await** — `await tana.workspaces.list()` works directly
 - **Timeout Protection** — 10s max execution prevents infinite loops
 - **Script History** — SQLite persistence for debugging and replay
@@ -37,18 +37,18 @@ bun install
 
 ## Configuration
 
-| Variable            | Default                 | Description                             |
-| ------------------- | ----------------------- | --------------------------------------- |
-| `TANA_API_TOKEN`    | (required)              | Bearer token from Tana Desktop          |
-| `TANA_API_URL`      | `http://127.0.0.1:8262` | Tana Local API URL                      |
-| `TANA_TIMEOUT`      | `10000`                 | Request timeout in ms                   |
-| `TANA_HISTORY_PATH` | (platform default)      | Custom path for SQLite history database |
+| Variable                | Default                 | Description                                                    |
+| ----------------------- | ----------------------- | -------------------------------------------------------------- |
+| `TANA_API_TOKEN`        | (required)              | Bearer token from Tana Desktop                                 |
+| `TANA_API_URL`          | `http://127.0.0.1:8262` | Tana Local API URL                                             |
+| `TANA_TIMEOUT`          | `10000`                 | Request timeout in ms                                          |
+| `TANA_HISTORY_PATH`     | (platform default)      | Custom path for SQLite history database                        |
+| `MAIN_TANA_WORKSPACE`   | (none)                  | Default workspace name or ID, resolved at startup              |
+| `TANA_SEARCH_WORKSPACES`| (none)                  | Comma-separated workspace names or IDs for default search scoping |
 
 ## MCP Integration
 
-Add to your Claude Desktop config (`claude_desktop_config.json`):
-
-### If installed globally via bun:
+Add to your MCP client's configuration:
 
 ```json
 {
@@ -56,14 +56,25 @@ Add to your Claude Desktop config (`claude_desktop_config.json`):
     "tana": {
       "command": "tana-mcp-codemode",
       "env": {
-        "TANA_API_TOKEN": "your_token_here"
+        "TANA_API_TOKEN": "your_token_here",
+        // Optional
+        "MAIN_TANA_WORKSPACE": "My Workspace",
+        "TANA_SEARCH_WORKSPACES": "My Workspace",
+        // Optional: customize where the SQLite history database is stored
+        "TANA_HISTORY_PATH": "/path/to/history.db"
       }
     }
   }
 }
 ```
 
-### If installed from source:
+| Client            | Config Location                                             |
+| ----------------- | ----------------------------------------------------------- |
+| Claude Desktop    | `claude_desktop_config.json`                                |
+| Claude Code       | `.mcp.json` (project) or `~/.claude/settings.json` (global) |
+| Cursor / Windsurf | IDE MCP settings                                            |
+
+**If installed from source**, use `bun` as the command:
 
 ```json
 {
@@ -72,108 +83,18 @@ Add to your Claude Desktop config (`claude_desktop_config.json`):
       "command": "bun",
       "args": ["run", "/path/to/tana-mcp-codemode/src/index.ts"],
       "env": {
-        "TANA_API_TOKEN": "your_token_here"
+        "TANA_API_TOKEN": "your_token_here",
+        // Optional
+        "MAIN_TANA_WORKSPACE": "My Workspace",
+        "TANA_SEARCH_WORKSPACES": "My Workspace",
+        // Optional: customize where the SQLite history database is stored
+        "TANA_HISTORY_PATH": "/path/to/history.db"
       }
     }
   }
 }
 ```
 
-## API Reference
-
-The server exposes a single `execute` tool. AI writes TypeScript code with access to the `tana` object:
-
-### Workspaces
-
-```typescript
-const workspaces = await tana.workspaces.list();
-// → Workspace[] (id, name, homeNodeId)
-```
-
-### Nodes
-
-```typescript
-await tana.nodes.search(query, options?)     // → SearchResult[]
-await tana.nodes.read(nodeId, maxDepth?)     // → string (markdown)
-await tana.nodes.getChildren(nodeId, opts?)  // → { children, total, hasMore }
-await tana.nodes.edit({ nodeId, name?, description? })
-await tana.nodes.trash(nodeId)
-await tana.nodes.check(nodeId)               // mark done
-await tana.nodes.uncheck(nodeId)             // mark undone
-```
-
-### Tags (Supertags)
-
-```typescript
-await tana.tags.list(workspaceId, limit?)
-await tana.tags.getSchema(tagId, includeEditInstructions?)
-await tana.tags.modify(nodeId, action, tagIds)  // action: "add" | "remove"
-await tana.tags.create({ workspaceId, name, description?, extendsTagIds?, showCheckbox? })
-await tana.tags.addField({ tagId, name, dataType, ... })
-await tana.tags.setCheckbox({ tagId, showCheckbox, doneStateMapping? })
-```
-
-### Fields
-
-```typescript
-await tana.fields.setOption(nodeId, attributeId, optionId)   // dropdown fields
-await tana.fields.setContent(nodeId, attributeId, content)   // text/date/url fields
-```
-
-### Calendar
-
-```typescript
-await tana.calendar.getOrCreate(workspaceId, granularity, date?)
-// granularity: "day" | "week" | "month" | "year"
-```
-
-### Import (Tana Paste)
-
-```typescript
-await tana.import(parentNodeId, tanaPasteContent)
-// → { success, nodeIds?, error? }
-```
-
-### Utility
-
-```typescript
-await tana.health()  // → { status: "ok" }
-```
-
-## Script Helpers
-
-### stdin() — Input Data
-
-Pass data to scripts via the `input` parameter:
-
-```typescript
-// Parse JSON input
-const data = stdin().json<{ ids: string[] }>();
-
-// Split into lines
-const lines = stdin().lines();
-
-// Raw text
-const text = stdin().text();
-
-// Check if input exists
-if (stdin().hasInput()) {
-  // process input
-}
-```
-
-### workflow — Progress Tracking
-
-Track multi-step operations:
-
-```typescript
-workflow.start("Processing nodes");
-workflow.step("Fetching workspaces");
-workflow.progress(5, 100, "Processing");
-workflow.complete("Done!");
-// Or: workflow.abort("Error message");
-```
-
 ## Examples
 
 ### Search for nodes
@@ -208,16 +129,6 @@ await tana.import(parentNodeId, `
 `);
 ```
 
-### Process input data
-
-```typescript
-const { nodeIds } = stdin().json<{ nodeIds: string[] }>();
-for (const id of nodeIds) {
-  const content = await tana.nodes.read(id);
-  console.log(content);
-}
-```
-
 ## Debug UI
 
 A WebSocket-based dashboard for testing scripts:
@@ -229,11 +140,29 @@ bun run src/debug-server.ts
 # Open http://localhost:3333
 ```
 
-Features:
+**Routes:**
+- `http://localhost:3333/#debug` — Script execution console
+- `http://localhost:3333/#benchmark` — Codemode vs tana-local performance comparison
+
+**Features:**
 - Real-time script execution
 - Workflow event timeline
-- Input data testing
 - Error display with suggestions
+- Benchmark results visualization (cost, speed, token usage)
+
+### workflow Helper (Debug UI only)
+
+Track multi-step operations with a timeline view:
+
+```typescript
+workflow.start("Processing nodes");
+workflow.step("Fetching workspaces");
+workflow.progress(5, 100, "Processing");
+workflow.complete("Done!");
+// Or: workflow.abort("Error message");
+```
+
+> **Note**: `workflow` is only available in the Debug UI. It's not exposed in the production MCP prompt.
 
 ### Building the React UI (optional)
 
@@ -259,7 +188,6 @@ src/
 │   └── types.ts          # API type definitions
 ├── sandbox/
 │   ├── executor.ts       # Code execution engine
-│   ├── stdin.ts          # Input data helper
 │   └── workflow.ts       # Progress tracking
 ├── storage/
 │   └── history.ts        # SQLite script history
@@ -272,8 +200,8 @@ ui/                       # React debug dashboard
 ### How It Works
 
 1. AI sends TypeScript code to the `execute` tool
-2. `sandbox.ts` creates an AsyncFunction for top-level await
-3. Code runs with injected `tana`, `console`, `stdin`, `workflow` objects
+2. `executor.ts` creates an AsyncFunction for top-level await
+3. Code runs with injected `tana` and `console` objects
 4. 10s timeout via Promise.race prevents hangs
 5. `console.log()` output is captured and returned
 6. Script run is saved to SQLite history
@@ -290,38 +218,19 @@ Runs are persisted to SQLite:
 
 Old runs (>30 days) are automatically cleaned up on startup.
 
-### Custom History Location
-
-Set `TANA_HISTORY_PATH` to use a custom database path:
-
-```json
-{
-  "mcpServers": {
-    "tana": {
-      "command": "tana-mcp-codemode",
-      "env": {
-        "TANA_API_TOKEN": "your_token_here",
-        "TANA_HISTORY_PATH": "/path/to/custom/tana-history.db"
-      }
-    }
-  }
-}
-```
-
 ### What Gets Saved
 
 Each script run records:
 
-| Field | Description |
-|-------|-------------|
-| `script` | The TypeScript code that was executed |
-| `input` | Data passed via `stdin()` helper |
-| `output` | Captured `console.log()` output |
-| `error` | Error message if execution failed |
-| `api_calls` | Which Tana API methods were called |
-| `node_ids_affected` | Node IDs that were read/modified |
-| `workspace_id` | Workspace used (if detected) |
-| `duration_ms` | Execution time |
+| Field               | Description                           |
+| ------------------- | ------------------------------------- |
+| `script`            | The TypeScript code that was executed |
+| `output`            | Captured `console.log()` output       |
+| `error`             | Error message if execution failed     |
+| `api_calls`         | Which Tana API methods were called    |
+| `node_ids_affected` | Node IDs that were read/modified      |
+| `workspace_id`      | Workspace used (if detected)          |
+| `duration_ms`       | Execution time                        |
 
 ## Development
 
@@ -339,6 +248,69 @@ bun run generate
 bun run debug
 ```
 
+## API Reference
+
+The server exposes a single `execute` tool. AI writes TypeScript code with access to the `tana` object:
+
+### Workspaces
+
+```typescript
+const workspaces = await tana.workspaces.list();
+// → Workspace[] (id, name, homeNodeId)
+```
+
+### Nodes
+
+```typescript
+await tana.nodes.search(query, options?)     // → SearchResult[]
+await tana.nodes.read(nodeId, maxDepth?)     // → string (markdown)
+await tana.nodes.getChildren(nodeId, opts?)  // → { children, total, hasMore }
+await tana.nodes.edit({ nodeId, name?, description? })
+await tana.nodes.trash(nodeId)
+await tana.nodes.check(nodeId)               // mark done
+await tana.nodes.uncheck(nodeId)             // mark undone
+```
+
+### Tags (Supertags)
+
+```typescript
+await tana.tags.listAll(workspaceId)              // All workspace supertags (paginated)
+await tana.tags.getSchema(tagId, opts?)            // opts: { includeInheritedFields? }
+await tana.tags.modify(nodeId, action, tagIds)     // action: "add" | "remove"
+await tana.tags.create({ workspaceId, name, description?, extendsTagIds?, showCheckbox? })
+await tana.tags.addField({ tagId, name, dataType, ... })
+await tana.tags.setCheckbox({ tagId, showCheckbox, doneStateMapping? })
+```
+
+### Fields
+
+```typescript
+await tana.fields.setOption(nodeId, attributeId, optionId)   // dropdown fields
+await tana.fields.setContent(nodeId, attributeId, content)   // text/date/url fields
+```
+
+### Calendar
+
+```typescript
+await tana.calendar.getOrCreate(workspaceId, granularity, date?)
+// granularity: "day" | "week" | "month" | "year"
+```
+
+### Import (Tana Paste)
+
+```typescript
+await tana.import(parentNodeId, tanaPasteContent)
+// → { success, nodeIds?, error? }
+```
+
+### Utility
+
+```typescript
+tana.workspace                // Pre-resolved default workspace (from MAIN_TANA_WORKSPACE) or null
+tana.format(data)             // Compact display of any API response
+await tana.health()           // → { status: "ok" }
+```
+
 ## License
 
 MIT

package/package.json

@@ -1,21 +1,12 @@
 {
   "name": "tana-mcp-codemode",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Codemode MCP server for Tana — AI writes TypeScript that executes against Tana Local API",
   "type": "module",
   "main": "src/index.ts",
   "bin": {
     "tana-mcp-codemode": "src/index.ts"
   },
-  "scripts": {
-    "generate": "bun run scripts/generate.ts",
-    "list-endpoints": "bun run scripts/list-endpoints.ts",
-    "start": "bun run --env-file=.env src/index.ts",
-    "dev": "bun run --env-file=.env --watch src/index.ts",
-    "debug": "bun run --env-file=.env src/debug-server.ts",
-    "typecheck": "bunx tsc --noEmit",
-    "prepublishOnly": "bun run typecheck"
-  },
   "files": [
     "src/index.ts",
     "src/prompts.ts",
@@ -36,7 +27,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/fabiogaliano/tana-mcp-codemode"
+    "url": "git+https://github.com/fabiogaliano/tana-mcp-codemode.git"
   },
   "engines": {
     "bun": ">=1.0.0"
@@ -50,5 +41,14 @@
     "openapi-typescript": "^7.10.1",
     "typescript": "^5.9.3"
   },
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "generate": "bun run scripts/generate.ts",
+    "list-endpoints": "bun run scripts/list-endpoints.ts",
+    "start": "bun run --env-file=.env src/index.ts",
+    "dev": "bun run --env-file=.env --watch src/index.ts",
+    "debug": "bun run --env-file=.env src/debug-server.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  }
+}

package/src/api/client.ts

@@ -18,8 +18,8 @@ export class TanaAPIError extends Error {
 }
 
 const RETRY_CONFIG = {
-  maxRetries: 3,
-  baseDelayMs: 1000,
+  maxRetries: 2,
+  baseDelayMs: 500,
   retryableCodes: new Set([408, 429, 500, 502, 503, 504]),
 };
 
@@ -230,7 +230,7 @@ export class TanaClient {
 export function createClient(): TanaClient {
   const baseUrl = process.env.TANA_API_URL || "http://127.0.0.1:8262";
   const token = process.env.TANA_API_TOKEN;
-  const timeout = parseInt(process.env.TANA_TIMEOUT || "10000", 10);
+  const timeout = parseInt(process.env.TANA_TIMEOUT || "3000", 10);
 
   if (!token) {
     throw new Error(

package/src/api/format.ts

@@ -0,0 +1,125 @@
+/**
+ * Compact Formatter for Tana API Responses
+ *
+ * Pure function — detects response shape and returns a compact string representation.
+ * Designed to reduce token waste when AI logs API results via console.log(tana.format(data)).
+ *
+ * Shape detection uses discriminating fields from the OpenAPI spec:
+ * - SearchResult[]: has `breadcrumb`
+ * - Children: has `children` + `total` + `hasMore`
+ * - ChildNode[]: has `childCount`
+ * - Tag[]: has `id` + `name`, no `breadcrumb`/`childCount`/`homeNodeId`
+ * - Workspace[]: has `homeNodeId`
+ * - ImportResult: has `success` + (`nodeIds` or `error`)
+ * - string: passthrough (read/getSchema already return markdown)
+ */
+
+function hasKey(obj: unknown, key: string): boolean {
+  return typeof obj === "object" && obj !== null && key in obj;
+}
+
+function formatTags(tags: { id: string; name: string }[]): string {
+  if (!tags || tags.length === 0) return "";
+  return " " + tags.map((t) => `#${t.name}`).join(" ");
+}
+
+function formatSearchResults(data: unknown[]): string {
+  const lines = data.map((r: any) => {
+    const tags = formatTags(r.tags);
+    const breadcrumb = r.breadcrumb?.length ? ` — ${r.breadcrumb.join(" > ")}` : "";
+    return `  [${r.id}] ${r.name}${tags}${breadcrumb}`;
+  });
+  return `${data.length} results:\n${lines.join("\n")}`;
+}
+
+function formatChildren(data: any): string {
+  const showing = data.children.length;
+  const header = `${data.total} children (showing ${showing}${data.hasMore ? ", has more" : ""}):`;
+  const lines = data.children.map((c: any) => {
+    const tags = formatTags(c.tags);
+    const kids = c.childCount > 0 ? ` (${c.childCount} children)` : "";
+    return `  [${c.id}] ${c.name}${tags}${kids}`;
+  });
+  return `${header}\n${lines.join("\n")}`;
+}
+
+function formatChildNodes(data: unknown[]): string {
+  const lines = data.map((c: any) => {
+    const tags = formatTags(c.tags);
+    const kids = c.childCount > 0 ? ` (${c.childCount} children)` : "";
+    return `  [${c.id}] ${c.name}${tags}${kids}`;
+  });
+  return `${data.length} nodes:\n${lines.join("\n")}`;
+}
+
+function formatTags_(data: unknown[]): string {
+  const lines = data.map((t: any) => `  [${t.id}] ${t.name}`);
+  return `${data.length} tags:\n${lines.join("\n")}`;
+}
+
+function formatWorkspaces(data: unknown[]): string {
+  const lines = data.map((w: any) => `  [${w.id}] ${w.name} (home: ${w.homeNodeId})`);
+  return `${data.length} workspaces:\n${lines.join("\n")}`;
+}
+
+function formatImportResult(data: any): string {
+  if (data.success) {
+    const ids = data.nodeIds?.length ? ` (${data.nodeIds.join(", ")})` : "";
+    return `Import success: ${data.nodeIds?.length ?? 0} nodes${ids}`;
+  }
+  return `Import failed: ${data.error ?? "unknown error"}`;
+}
+
+/**
+ * Compact formatter for any Tana API response.
+ *
+ * Detects the shape of the data and returns a human-readable, token-efficient string.
+ * Falls back to JSON.stringify for unrecognized shapes.
+ */
+export function format(data: unknown): string {
+  if (typeof data === "string") return data;
+  if (data === null || data === undefined) return String(data);
+
+  // ImportResult: { success, nodeIds?, error? }
+  if (hasKey(data, "success") && (hasKey(data, "nodeIds") || hasKey(data, "error"))) {
+    return formatImportResult(data);
+  }
+
+  // Children: { children, total, hasMore }
+  if (hasKey(data, "children") && hasKey(data, "total") && hasKey(data, "hasMore")) {
+    return formatChildren(data);
+  }
+
+  if (Array.isArray(data)) {
+    if (data.length === 0) return "0 results";
+
+    const first = data[0];
+
+    // SearchResult[]: has `breadcrumb`
+    if (hasKey(first, "breadcrumb")) {
+      return formatSearchResults(data);
+    }
+
+    // ChildNode[]: has `childCount`
+    if (hasKey(first, "childCount")) {
+      return formatChildNodes(data);
+    }
+
+    // Workspace[]: has `homeNodeId`
+    if (hasKey(first, "homeNodeId")) {
+      return formatWorkspaces(data);
+    }
+
+    // Tag[]: has `id` + `name`, no discriminators for other types
+    if (hasKey(first, "id") && hasKey(first, "name") && !hasKey(first, "breadcrumb") && !hasKey(first, "childCount") && !hasKey(first, "homeNodeId")) {
+      return formatTags_(data);
+    }
+  }
+
+  // Fallback: pretty JSON
+  try {
+    return JSON.stringify(data, null, 2);
+  } catch {
+    return String(data);
+  }
+}

package/src/api/tana.ts

@@ -22,6 +22,7 @@ import type {
   SetCheckboxOptions,
   ImportResult,
 } from "./types";
+import { format } from "./format";
 
 /**
  * TanaAPI Interface
@@ -30,6 +31,9 @@ import type {
  * Provides high-level methods organized by domain (workspaces, nodes, tags, etc.)
  */
 export interface TanaAPI {
+  /** Pre-resolved default workspace (from MAIN_TANA_WORKSPACE env var), or null */
+  workspace: Workspace | null;
+
   /** Check API health */
   health(): Promise<{ status: string; timestamp: string; nodeSpaceReady: boolean }>;
 
@@ -59,10 +63,10 @@ export interface TanaAPI {
   };
 
   tags: {
-    /** List tags in a workspace */
-    list(workspaceId: string, limit?: number): Promise<Tag[]>;
+    /** List all tags in a workspace */
+    listAll(workspaceId: string): Promise<Tag[]>;
     /** Get tag schema */
-    getSchema(tagId: string, includeEditInstructions?: boolean): Promise<string>;
+    getSchema(tagId: string, includeEditInstructions?: boolean, includeInheritedFields?: boolean): Promise<string>;
     /** Add/remove tags from a node */
     modify(
       nodeId: string,
@@ -103,10 +107,19 @@ export interface TanaAPI {
 
   /** Import Tana Paste formatted content */
   import(parentNodeId: string, content: string): Promise<ImportResult>;
+
+  /** Compact formatter for any API response */
+  format(data: unknown): string;
 }
 
-export function createTanaAPI(client: TanaClient): TanaAPI {
+export function createTanaAPI(
+  client: TanaClient,
+  workspace?: Workspace | null,
+  defaultSearchWorkspaceIds?: string[]
+): TanaAPI {
   return {
+    workspace: workspace ?? null,
+
     async health() {
       return client.get<{ status: string; timestamp: string; nodeSpaceReady: boolean }>("/health");
     },
@@ -147,8 +160,10 @@ export function createTanaAPI(client: TanaClient): TanaAPI {
 
         addQueryParams(query as unknown as Record<string, unknown>, "query");
         if (options?.limit) params.push(`limit=${options.limit}`);
-        if (options?.workspaceIds) {
-          options.workspaceIds.forEach((id, i) => {
+        const effectiveWorkspaceIds = options?.workspaceIds
+          ?? (defaultSearchWorkspaceIds?.length ? defaultSearchWorkspaceIds : undefined);
+        if (effectiveWorkspaceIds) {
+          effectiveWorkspaceIds.forEach((id, i) => {
             params.push(`workspaceIds[${i}]=${encodeURIComponent(id)}`);
           });
         }
@@ -213,20 +228,36 @@ export function createTanaAPI(client: TanaClient): TanaAPI {
     },
 
     tags: {
-      async list(workspaceId: string, limit = 50): Promise<Tag[]> {
-        return client.get<Tag[]>(
-          `/workspaces/${workspaceId}/tags?limit=${limit}`
-        );
+      async listAll(workspaceId: string): Promise<Tag[]> {
+        const schemaNodeId = `${workspaceId}_SCHEMA`;
+        const tags: Tag[] = [];
+        let offset = 0;
+
+        while (true) {
+          const page = await client.get<Children>(
+            `/nodes/${schemaNodeId}/children?limit=200&offset=${offset}`
+          );
+          for (const child of page.children) {
+            if (child.docType === "tagDef") {
+              tags.push({ id: child.id, name: child.name });
+            }
+          }
+          if (!page.hasMore) break;
+          offset += 200;
+        }
+
+        return tags;
       },
 
       async getSchema(
         tagId: string,
-        includeEditInstructions = false
+        includeEditInstructions = false,
+        includeInheritedFields = true
       ): Promise<string> {
         const result = await client.get<{ markdown: string }>(
-          `/tags/${tagId}/schema?includeEditInstructions=${includeEditInstructions}`
+          `/tags/${tagId}/schema?includeEditInstructions=${includeEditInstructions}&includeInheritedFields=${includeInheritedFields}`
         );
-        return result.markdown;
+        return truncateOptionLists(result.markdown);
       },
 
       async modify(
@@ -328,5 +359,45 @@ export function createTanaAPI(client: TanaClient): TanaAPI {
         content,
       });
     },
+
+    format(data: unknown): string {
+      return format(data);
+    },
   };
 }
+
+const MAX_OPTIONS_SHOWN = 5;
+const OPTION_LINE_RE = /^  - .+ \(id:/;
+
+function truncateOptionLists(markdown: string): string {
+  const lines = markdown.split("\n");
+  const result: string[] = [];
+  let optionCount = 0;
+  let inOptions = false;
+
+  for (const line of lines) {
+    if (OPTION_LINE_RE.test(line)) {
+      if (!inOptions) {
+        inOptions = true;
+        optionCount = 0;
+      }
+      optionCount++;
+      if (optionCount <= MAX_OPTIONS_SHOWN) {
+        result.push(line);
+      }
+    } else {
+      if (inOptions && optionCount > MAX_OPTIONS_SHOWN) {
+        result.push(`  - ... (${optionCount - MAX_OPTIONS_SHOWN} more, ${optionCount} total)`);
+      }
+      inOptions = false;
+      optionCount = 0;
+      result.push(line);
+    }
+  }
+
+  if (inOptions && optionCount > MAX_OPTIONS_SHOWN) {
+    result.push(`  - ... (${optionCount - MAX_OPTIONS_SHOWN} more, ${optionCount} total)`);
+  }
+
+  return result.join("\n");
+}

package/src/api/types.ts

@@ -8,10 +8,6 @@
  */
 import type { operations } from "../generated/api";
 
-// ============================================================================
-// Response Types (extracted from operation responses)
-// ============================================================================
-
 /** Health check response */
 export type HealthResponse =
   operations["health.ping"]["responses"]["200"]["content"]["application/json"];
@@ -87,10 +83,6 @@ export type SetFieldOptionResponse =
 export type SetFieldContentResponse =
   operations["nodes.setFieldContent"]["responses"]["200"]["content"]["application/json"];
 
-// ============================================================================
-// Request/Query Types (extracted from operation parameters)
-// ============================================================================
-
 /** Search query structure */
 export type SearchQuery = NonNullable<
   operations["nodes.search"]["parameters"]["query"]
@@ -106,10 +98,6 @@ export type FieldDataType = NonNullable<
   operations["tags.addField"]["requestBody"]
 >["content"]["application/json"]["dataType"];
 
-// ============================================================================
-// Request Body Types
-// ============================================================================
-
 /** Create tag request body */
 export type CreateTagBody = NonNullable<
   operations["tags.create"]["requestBody"]
@@ -135,10 +123,6 @@ export type NodeUpdateBody = NonNullable<
   operations["nodes.update"]["requestBody"]
 >["content"]["application/json"];
 
-// ============================================================================
-// Derived Helper Types (for ergonomic API usage)
-// ============================================================================
-
 /** Options for search */
 export interface SearchOptions {
   limit?: number;
@@ -199,9 +183,5 @@ export interface ImportResult {
   error?: string;
 }
 
-// ============================================================================
-// Re-export full generated types for escape hatch
-// ============================================================================
-
 export type { operations } from "../generated/api";
 export type { paths } from "../generated/api";

package/src/index.ts

@@ -12,29 +12,114 @@ import { z } from "zod";
 
 import { createClient } from "./api/client";
 import { createTanaAPI } from "./api/tana";
+import type { TanaClient } from "./api/client";
+import type { Workspace } from "./api/types";
 import { executeSandbox } from "./sandbox/executor";
 import { cleanupOldRuns, initDb } from "./storage/history";
 import { TOOL_DESCRIPTION } from "./prompts";
 
+/**
+ * Resolves the default workspace from MAIN_TANA_WORKSPACE env var.
+ * Matches by ID first, then case-insensitive name.
+ * Returns null if unset, unmatched, or API unreachable.
+ */
+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 (err) {
+    console.error(
+      `[workspace] Failed to fetch workspaces: ${err instanceof Error ? err.message : err}`
+    );
+    return null;
+  }
+
+  const byId = workspaces.find((w) => w.id === envValue);
+  if (byId) {
+    console.error(`[workspace] Resolved "${envValue}" → ${byId.name} (${byId.id})`);
+    return byId;
+  }
+
+  const lowerEnv = envValue.toLowerCase();
+  const byName = workspaces.find((w) => w.name.toLowerCase() === lowerEnv);
+  if (byName) {
+    console.error(`[workspace] Resolved "${envValue}" → ${byName.name} (${byName.id})`);
+    return byName;
+  }
+
+  const available = workspaces.map((w) => `${w.name} (${w.id})`).join(", ");
+  console.error(
+    `[workspace] No match for "${envValue}". Available: ${available || "none"}`
+  );
+  return null;
+}
+
+/**
+ * Resolves TANA_SEARCH_WORKSPACES env var to an array of workspace IDs.
+ * Each value can be an ID or case-insensitive name.
+ * Unresolved values are logged and skipped.
+ */
+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 (err) {
+    console.error(
+      `[search-workspaces] Failed to fetch workspaces: ${err instanceof Error ? err.message : err}`
+    );
+    return [];
+  }
+
+  const resolvedIds: string[] = [];
+  for (const value of values) {
+    const byId = workspaces.find((w) => w.id === value);
+    if (byId) {
+      resolvedIds.push(byId.id);
+      console.error(`[search-workspaces] Resolved "${value}" → ${byId.name} (${byId.id})`);
+      continue;
+    }
+    const lowerValue = value.toLowerCase();
+    const byName = workspaces.find((w) => w.name.toLowerCase() === lowerValue);
+    if (byName) {
+      resolvedIds.push(byName.id);
+      console.error(`[search-workspaces] Resolved "${value}" → ${byName.name} (${byName.id})`);
+      continue;
+    }
+    const available = workspaces.map((w) => `${w.name} (${w.id})`).join(", ");
+    console.error(
+      `[search-workspaces] No match for "${value}". Available: ${available || "none"}`
+    );
+  }
+
+  return resolvedIds;
+}
+
 async function main() {
-  // Initialize database and cleanup old runs
   initDb();
   const cleaned = cleanupOldRuns(30);
   if (cleaned > 0) {
     console.error(`Cleaned up ${cleaned} old script runs`);
   }
 
-  // Create Tana client and API
   const client = createClient();
-  const tana = createTanaAPI(client);
+  const workspace = await resolveWorkspace(client);
+  const searchWorkspaceIds = await resolveSearchWorkspaces(client);
+  const tana = createTanaAPI(client, workspace, searchWorkspaceIds);
 
-  // Create MCP server using the modern McpServer API
   const server = new McpServer({
     name: "tana-mcp-codemode",
     version: "0.1.0",
   });
 
-  // Register the execute tool using registerTool (non-deprecated API)
   server.registerTool(
     "execute",
     {
@@ -45,16 +130,11 @@ async function main() {
           .string()
           .optional()
           .describe("Optional session ID for grouping script runs"),
-        input: z
-          .string()
-          .optional()
-          .describe("Data to pass to script via stdin() helper"),
       },
     },
-    async ({ code, sessionId, input }) => {
-      const result = await executeSandbox(code, tana, sessionId, input);
+    async ({ code, sessionId }) => {
+      const result = await executeSandbox(code, tana, sessionId);
 
-      // Format response
       let responseText = "";
       if (result.output) {
         responseText += result.output;
@@ -77,7 +157,6 @@ async function main() {
     }
   );
 
-  // Start server with stdio transport
   const transport = new StdioServerTransport();
   await server.connect(transport);
 

package/src/prompts.ts

@@ -6,7 +6,7 @@ export const TOOL_DESCRIPTION = `Execute TypeScript code to interact with Tana.
 
 ## APIs
 
-tana.health() → { status }
+tana.workspace → Workspace | null (pre-resolved default workspace)
 tana.workspaces.list() → Workspace[] { id, name, homeNodeId }
 
 ### Nodes
@@ -18,8 +18,8 @@ tana.nodes.trash(nodeId) → { success }
 tana.nodes.check(nodeId) / uncheck(nodeId) → { success }
 
 ### Tags
-tana.tags.list(workspaceId, limit?) → Tag[]
-tana.tags.getSchema(tagId, includeEditInstructions?) → string
+tana.tags.listAll(workspaceId) → Tag[] (workspace supertags only — for schema analysis)
+tana.tags.getSchema(tagId) → string
 tana.tags.modify(nodeId, "add"|"remove", tagIds[])
 tana.tags.create({ workspaceId, name, description?, extendsTagIds?, showCheckbox? })
 tana.tags.addField({ tagId, name, dataType: "plain"|"number"|"date"|"url"|"email"|"checkbox"|"user"|"instance"|"options", ... })
@@ -35,13 +35,10 @@ tana.calendar.getOrCreate(workspaceId, "day"|"week"|"month"|"year", date?)
 ### Import
 tana.import(parentNodeId, tanaPasteContent) → { success, nodeIds? }
 
-### Entry Points
-inbox: \`\${workspaceId}_CAPTURE_INBOX\`
-library: \`\${workspaceId}_STASH\`
+### Formatting
+tana.format(data) → string (compact display of any API response)
 
-### Helpers
-stdin().json<T>() | .lines() | .text() | .hasInput()
-workflow.start(msg) | .step(msg) | .progress(n, total, msg) | .complete(msg) | .abort(err)
+Entry points: \`\${workspaceId}_CAPTURE_INBOX\` (inbox), \`\${workspaceId}_STASH\` (library)
 
 ## Edit (search-and-replace)
 
@@ -53,15 +50,35 @@ Empty old_string matches absent field.
 { textContains: string } | { textMatches: "/regex/i" }
 { hasType: tagId } | { field: { fieldId, stringValue?, numberValue?, nodeId?, state? } }
 { compare: { fieldId, operator: "gt"|"lt"|"eq", value, type } }
-{ childOf: { nodeIds[], recursive?, includeRefs? } } | { ownedBy: { nodeId, recursive?, includeSelf? } }
 { linksTo: nodeIds[] }
-{ is: "done"|"todo"|"template"|"entity"|"calendarNode"|"search"|"inLibrary" }
+{ is: "done"|"todo"|"template"|"field"|"published"|"entity"|"calendarNode"|"onDayNode"|"chat"|"search"|"command"|"inLibrary" }
 { has: "tag"|"field"|"media"|"audio"|"video"|"image" }
 { created: { last: N } } | { edited: { last?, by?, since? } } | { done: { last: N } }
 { onDate: "YYYY-MM-DD" | { date, fieldId?, overlaps? } }
 { overdue: true } | { inLibrary: true }
 { and: [...] } | { or: [...] } | { not: {...} }
 
+## Default Workspace
+
+tana.workspace is pre-resolved if MAIN_TANA_WORKSPACE is set. Prefer over workspaces.list(): \`const ws = tana.workspace ?? (await tana.workspaces.list())[0];\`
+
+## Output
+
+console.log() output becomes LLM context. Keep it compact:
+- Use tana.format(data) for any API response, or .map() for task-specific fields
+- search returns metadata only (name, id, tags); use .read() for content and field values
+- Never JSON.stringify API responses
+
+## API Notes
+
+- 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.
+- childOf/ownedBy/inWorkspace operators broken. Scope by workspace: search(query, { workspaceIds: ["id"] })
+- Tag names are not unique. Find a tag by name: search({ and: [{ hasType: "SYS_T01" }, { textContains: "name" }] })
+- search results: { id, name, breadcrumb[], tags[{id,name}], tagIds[], workspaceId, docType, description, created, inTrash }
+- getSchema output: line 1 is \`# Tag definition: name (id:xxx)\`. Line 2 is \`Extends #parent (id:xxx)\` when tag has inheritance, or \`Extends #parent (base type) (id:xxx)\` for Tana built-in types. Parse "Extends" to find relationships.
+
 ## Examples
 
 Search: await tana.nodes.search({ and: [{ hasType: "tagId" }, { is: "todo" }] })
@@ -75,7 +92,4 @@ await tana.import(parentNodeId, \`
 \`)
 \`\`\`
 
-## Output
-
-console.log() to return data.
 `;

package/src/sandbox/executor.ts

@@ -12,7 +12,6 @@
 import type { SandboxResult } from "../types";
 import type { TanaAPI } from "../api/tana";
 import { saveScriptRun } from "../storage/history";
-import { createStdinHelper } from "./stdin";
 import { createWorkflowHelper } from "./workflow";
 
 const EXECUTION_TIMEOUT = 10_000; // 10 seconds
@@ -32,6 +31,8 @@ function createTrackedTanaAPI(
   const trackNodeId = (id: string) => tracker.nodeIds.add(id);
 
   return {
+    workspace: tana.workspace,
+
     health: () => track("health", () => tana.health()),
 
     workspaces: {
@@ -72,9 +73,9 @@ function createTrackedTanaAPI(
     },
 
     tags: {
-      list: (workspaceId, limit) => {
+      listAll: (workspaceId: string) => {
         tracker.workspaceId = workspaceId;
-        return track("tags.list", () => tana.tags.list(workspaceId, limit));
+        return track("tags.listAll", () => tana.tags.listAll(workspaceId));
       },
       getSchema: (tagId, includeEditInstructions) =>
         track("tags.getSchema", () => tana.tags.getSchema(tagId, includeEditInstructions)),
@@ -116,14 +117,15 @@ function createTrackedTanaAPI(
       trackNodeId(parentNodeId);
       return track("import", () => tana.import(parentNodeId, content));
     },
+
+    format: (data) => tana.format(data),
   };
 }
 
 export async function executeSandbox(
   code: string,
   tana: TanaAPI,
-  sessionId?: string,
-  input?: string
+  sessionId?: string
 ): Promise<SandboxResult> {
   const startTime = performance.now();
   const logs: string[] = [];
@@ -132,7 +134,7 @@ export async function executeSandbox(
   const tracker = {
     calls: [] as string[],
     nodeIds: new Set<string>(),
-    workspaceId: null as string | null,
+    workspaceId: tana.workspace?.id ?? null,
   };
 
   // Custom console that captures output
@@ -151,8 +153,6 @@ export async function executeSandbox(
     },
   };
 
-  // Create helpers for script execution
-  const stdin = createStdinHelper(input);
   const effectiveSessionId = sessionId ?? crypto.randomUUID();
   const workflow = createWorkflowHelper(effectiveSessionId);
 
@@ -160,7 +160,6 @@ export async function executeSandbox(
   const trackedTana = createTrackedTanaAPI(tana, tracker);
 
   try {
-    // Create async function to support top-level await
     // eslint-disable-next-line @typescript-eslint/no-implied-eval
     const AsyncFunction = Object.getPrototypeOf(
       async function () {}
@@ -183,26 +182,26 @@ export async function executeSandbox(
       "exports",
     ];
 
+    const transpiler = new Bun.Transpiler({ loader: "ts" });
+    const jsCode = transpiler.transformSync(code);
+
     const fn = new AsyncFunction(
       "tana",
       "console",
-      "stdin",
       "workflow",
       ...shadowedGlobals,
-      code
+      jsCode
     );
 
-    // Race between execution and timeout
     const timeoutPromise = new Promise<never>((_, reject) => {
       setTimeout(() => {
         reject(new Error(`Execution timed out after ${EXECUTION_TIMEOUT}ms`));
       }, EXECUTION_TIMEOUT);
     });
 
-    // Pass undefined for all shadowed globals
     const undefinedArgs = shadowedGlobals.map(() => undefined);
     await Promise.race([
-      fn(trackedTana, sandboxConsole, stdin, workflow, ...undefinedArgs),
+      fn(trackedTana, sandboxConsole, workflow, ...undefinedArgs),
       timeoutPromise,
     ]);
 
@@ -217,7 +216,6 @@ export async function executeSandbox(
       error: null,
       durationMs,
       sessionId: effectiveSessionId,
-      input: input ?? null,
       apiCalls: tracker.calls.length > 0 ? tracker.calls : null,
       nodeIdsAffected: tracker.nodeIds.size > 0 ? Array.from(tracker.nodeIds) : null,
       workspaceId: tracker.workspaceId,
@@ -242,7 +240,6 @@ export async function executeSandbox(
       error: errorMessage,
       durationMs,
       sessionId: effectiveSessionId,
-      input: input ?? null,
       apiCalls: tracker.calls.length > 0 ? tracker.calls : null,
       nodeIdsAffected: tracker.nodeIds.size > 0 ? Array.from(tracker.nodeIds) : null,
       workspaceId: tracker.workspaceId,

package/src/sandbox/stdin.ts

@@ -1,69 +0,0 @@
-/**
- * stdin() Helper
- *
- * Provides convenient methods for handling input data passed to scripts.
- * In MCP context, this handles data passed via the `input` parameter.
- *
- * Usage in scripts:
- *   const data = stdin().json();   // Parse as JSON
- *   const lines = stdin().lines(); // Split into lines
- *   const text = stdin().text();   // Raw trimmed text
- */
-
-export interface StdinHelper {
-  /** Get raw input as trimmed string */
-  text(): string;
-  /** Split input into array of lines (empty lines filtered) */
-  lines(): string[];
-  /** Parse input as JSON (throws if invalid) */
-  json<T = unknown>(): T;
-  /** Parse input as JSON, return null if invalid */
-  jsonSafe<T = unknown>(): T | null;
-  /** Check if any input was provided */
-  hasInput(): boolean;
-}
-
-export function createStdinHelper(input: string | undefined): () => StdinHelper {
-  const rawInput = input ?? "";
-
-  return () => ({
-    text(): string {
-      return rawInput.trim();
-    },
-
-    lines(): string[] {
-      return rawInput
-        .split("\n")
-        .map((line) => line.trim())
-        .filter((line) => line.length > 0);
-    },
-
-    json<T = unknown>(): T {
-      const text = rawInput.trim();
-      if (!text) {
-        throw new Error("stdin is empty - no JSON to parse");
-      }
-      try {
-        return JSON.parse(text) as T;
-      } catch (e) {
-        throw new Error(
-          `Failed to parse stdin as JSON: ${e instanceof Error ? e.message : String(e)}`
-        );
-      }
-    },
-
-    jsonSafe<T = unknown>(): T | null {
-      const text = rawInput.trim();
-      if (!text) return null;
-      try {
-        return JSON.parse(text) as T;
-      } catch {
-        return null;
-      }
-    },
-
-    hasInput(): boolean {
-      return rawInput.trim().length > 0;
-    },
-  });
-}