tana-mcp-codemode 0.2.2 → 0.3.0

package/package.json

@@ -1,33 +1,15 @@
 {
   "name": "tana-mcp-codemode",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Codemode MCP server for Tana — AI writes TypeScript that executes against Tana Local API",
   "type": "module",
-  "main": "src/index.ts",
+  "main": "dist/entry-node.js",
   "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",
-    "test": "bun test",
-    "typecheck": "bunx tsc --noEmit",
-    "prepublishOnly": "bun run typecheck",
-    "release:patch": "npm version patch && npm publish",
-    "release:minor": "npm version minor && npm publish",
-    "release:major": "npm version major && npm publish"
+    "tana-mcp-codemode": "dist/entry-node.js"
   },
   "files": [
-    "src/index.ts",
-    "src/prompts.ts",
-    "src/types.ts",
-    "src/api",
-    "src/sandbox",
-    "src/storage",
-    "src/generated",
+    "dist/",
+    "src/",
     "README.md"
   ],
   "keywords": [
@@ -43,16 +25,36 @@
     "url": "git+https://github.com/fabiogaliano/tana-mcp-codemode.git"
   },
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.0.0",
+    "node": ">=20"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.3",
     "zod": "^3"
   },
+  "optionalDependencies": {
+    "better-sqlite3": "^11",
+    "esbuild": "^0.24"
+  },
   "devDependencies": {
     "@types/bun": "^1.3.8",
     "openapi-typescript": "^7.10.1",
+    "tsup": "^8",
     "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/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"
+  }
+}

package/src/api/tana.ts

@@ -25,6 +25,115 @@ import type {
 } from "./types";
 import { format } from "./format";
 
+/**
+ * Build deep-object query params (style: deepObject, explode: true).
+ * Used by search and getFieldOptions.
+ */
+function addQueryParams(params: string[], obj: Record<string, unknown>, prefix: string) {
+  for (const [key, value] of Object.entries(obj)) {
+    const paramKey = prefix ? `${prefix}[${key}]` : key;
+    if (value === null || value === undefined) continue;
+    if (typeof value === "object" && !Array.isArray(value)) {
+      addQueryParams(params, value as Record<string, unknown>, paramKey);
+    } else if (Array.isArray(value)) {
+      value.forEach((item, i) => {
+        if (typeof item === "object") {
+          addQueryParams(params, item as Record<string, unknown>, `${paramKey}[${i}]`);
+        } else {
+          params.push(`${encodeURIComponent(`${paramKey}[${i}]`)}=${encodeURIComponent(String(item))}`);
+        }
+      });
+    } else {
+      params.push(`${encodeURIComponent(paramKey)}=${encodeURIComponent(String(value))}`);
+    }
+  }
+}
+
+/** Parse predetermined options: `  - Name <!-- node-id: ABC -->` */
+function parseOptionsFromMarkdown(md: string): { id: string; name: string }[] {
+  const results: { id: string; name: string }[] = [];
+  const lines = md.split("\n");
+  let inOptions = false;
+  for (const line of lines) {
+    if (line.includes("**Options**:")) { inOptions = true; continue; }
+    if (inOptions) {
+      const match = line.match(/^\s+- (.+?)\s*<!--\s*node-id:\s*(\S+)\s*-->/);
+      if (match) {
+        results.push({ id: match[2], name: match[1] });
+      } else if (line.trim() && !line.startsWith("  ")) {
+        break;
+      }
+    }
+  }
+  return results;
+}
+
+/** Parse `[name](tana:id)` references from markdown */
+function parseRefsFromMarkdown(md: string): { id: string; name: string }[] {
+  const results: { id: string; name: string }[] = [];
+  const re = /\[([^\]]+)\]\(tana:([^)]+)\)/g;
+  let match;
+  while ((match = re.exec(md)) !== null) {
+    results.push({ id: match[2], name: match[1] });
+  }
+  return results;
+}
+
+/**
+ * Extract option values for a specific field from node markdown.
+ * Scopes parsing to only the target field's section to avoid noise
+ * from other fields, tags, and node names.
+ */
+function parseFieldValues(md: string, fieldName: string): { id: string; name: string }[] {
+  const results: { id: string; name: string }[] = [];
+  const lines = md.split("\n");
+  let inField = false;
+  let fieldIndent = -1;
+
+  for (const line of lines) {
+    // Detect the field section: "  - **FieldName**:" or "  - **FieldName**: value <!-- node-id: xxx -->"
+    if (!inField && line.includes(`**${fieldName}**`)) {
+      inField = true;
+      fieldIndent = line.search(/\S/);
+
+      // Inline single-value: "  - **Type**: negotiation <!-- node-id: xxx -->"
+      const inlineMatch = line.match(
+        new RegExp(`\\*\\*${fieldName}\\*\\*:\\s*(.+?)\\s*<!--\\s*node-id:\\s*(\\S+)\\s*-->`)
+      );
+      if (inlineMatch) {
+        results.push({ id: inlineMatch[2], name: inlineMatch[1].trim() });
+      }
+      // Also check for tana-link format: "  - **Type**: [value](tana:id)"
+      const linkMatch = line.match(
+        new RegExp(`\\*\\*${fieldName}\\*\\*:\\s*\\[([^\\]]+)\\]\\(tana:([^)]+)\\)`)
+      );
+      if (linkMatch) {
+        results.push({ id: linkMatch[2], name: linkMatch[1] });
+      }
+      continue;
+    }
+
+    if (inField) {
+      const currentIndent = line.search(/\S/);
+      // Left the field's section (same or less indentation)
+      if (line.trim() && currentIndent <= fieldIndent) break;
+
+      // Child value: "    - value <!-- node-id: xxx -->"
+      const childMatch = line.match(/^\s+- (.+?)\s*<!--\s*node-id:\s*(\S+)\s*-->/);
+      if (childMatch) {
+        results.push({ id: childMatch[2], name: childMatch[1].trim() });
+        continue;
+      }
+      // Child value (tana-link): "    - [value](tana:id)"
+      const childLinkMatch = line.match(/^\s+- \[([^\]]+)\]\(tana:([^)]+)\)/);
+      if (childLinkMatch) {
+        results.push({ id: childLinkMatch[2], name: childLinkMatch[1] });
+      }
+    }
+  }
+  return results;
+}
+
 /**
  * TanaAPI Interface
  *
@@ -87,12 +196,11 @@ export interface TanaAPI {
   };
 
   fields: {
-    /** Set a field to an option value */
+    /** Set a field to option value(s). Pass string[] for multi-value fields. */
     setOption(
       nodeId: string,
       attributeId: string,
-      optionId: string,
-      mode?: "replace" | "append"
+      optionId: string | string[]
     ): Promise<{ success: boolean }>;
     /** Set a field to a string value, or null to clear it */
     setContent(
@@ -101,6 +209,11 @@ export interface TanaAPI {
       content: string | null,
       mode?: "replace" | "append"
     ): Promise<{ success: boolean }>;
+    /** Discover available options for an Options-type field */
+    getFieldOptions(
+      fieldId: string,
+      options?: { tagId?: string; workspaceId?: string; limit?: number }
+    ): Promise<{ id: string; name: string }[]>;
   };
 
   calendar: {
@@ -142,30 +255,8 @@ export function createTanaAPI(
         query: SearchQuery,
         options?: SearchOptions
       ): Promise<SearchResult[]> {
-        // Build deep object query params (style: deepObject, explode: true)
         const params: string[] = [];
-
-        function addQueryParams(obj: Record<string, unknown>, prefix: string) {
-          for (const [key, value] of Object.entries(obj)) {
-            const paramKey = prefix ? `${prefix}[${key}]` : key;
-            if (value === null || value === undefined) continue;
-            if (typeof value === "object" && !Array.isArray(value)) {
-              addQueryParams(value as Record<string, unknown>, paramKey);
-            } else if (Array.isArray(value)) {
-              value.forEach((item, i) => {
-                if (typeof item === "object") {
-                  addQueryParams(item as Record<string, unknown>, `${paramKey}[${i}]`);
-                } else {
-                  params.push(`${encodeURIComponent(`${paramKey}[${i}]`)}=${encodeURIComponent(String(item))}`);
-                }
-              });
-            } else {
-              params.push(`${encodeURIComponent(paramKey)}=${encodeURIComponent(String(value))}`);
-            }
-          }
-        }
-
-        addQueryParams(query as unknown as Record<string, unknown>, "query");
+        addQueryParams(params, query as unknown as Record<string, unknown>, "query");
         if (options?.limit) params.push(`limit=${options.limit}`);
         const effectiveWorkspaceIds = options?.workspaceIds
           ?? (defaultSearchWorkspaceIds?.length ? defaultSearchWorkspaceIds : undefined);
@@ -346,17 +437,48 @@ export function createTanaAPI(
     },
 
     fields: {
+      // Workaround: append mode is broken in Tana API (clears field instead of appending).
+      // For arrays, we set first value via API, then import remaining into the field tuple.
+      // See claudedocs/api-bugs.md
       async setOption(
         nodeId: string,
         attributeId: string,
-        optionId: string,
-        mode?: "replace" | "append"
+        optionId: string | string[],
+        _mode?: "replace" | "append"
       ): Promise<{ success: boolean }> {
-        const result = await client.post<{ nodeId: string; message: string }>(
+        const ids = Array.isArray(optionId) ? optionId : [optionId];
+        if (ids.length === 0) return { success: true };
+
+        // Step 1: set first value via API (creates the field tuple)
+        await client.post<{ nodeId: string; message: string }>(
           `/nodes/${nodeId}/fields/${attributeId}/option`,
-          { optionId, mode }
+          { optionId: ids[0], mode: "replace" }
         );
-        return { success: !!result.nodeId };
+
+        if (ids.length === 1) return { success: true };
+
+        // Step 2: find the field tuple via getChildren
+        const { children } = await client.get<Children>(
+          `/nodes/${nodeId}/children?limit=100`
+        );
+        let tupleId: string | null = null;
+        for (const child of children) {
+          if (child.docType === "tuple") {
+            const sub = await client.get<Children>(
+              `/nodes/${child.id}/children?limit=20`
+            );
+            if (sub.children.some(s => s.id === attributeId)) {
+              tupleId = child.id;
+              break;
+            }
+          }
+        }
+        if (!tupleId) return { success: false };
+
+        // Step 3: import remaining values into the tuple
+        const refs = ids.slice(1).map(id => `- [[^${id}]]`).join("\n");
+        await client.post<ImportResult>(`/nodes/${tupleId}/import`, { content: refs });
+        return { success: true };
       },
 
       async setContent(
@@ -371,6 +493,74 @@ export function createTanaAPI(
         );
         return { success: !!result.nodeId };
       },
+
+      async getFieldOptions(
+        fieldId: string,
+        options?: { tagId?: string; workspaceId?: string; limit?: number }
+      ): Promise<{ id: string; name: string }[]> {
+        const result = await client.get<{ markdown: string }>(
+          `/nodes/${fieldId}?maxDepth=2`
+        );
+        const md = result.markdown;
+
+        // Pattern A: Predetermined options (field definition lists them)
+        if (md.includes("**Options**:")) {
+          return parseOptionsFromMarkdown(md);
+        }
+
+        // Pattern B: Instance of supertag
+        if (md.includes("Options from supertag")) {
+          const sourceTagMatch = md.match(/\(tana:([^)]+)\)/);
+          if (sourceTagMatch) {
+            const params: string[] = [];
+            addQueryParams(params, { hasType: sourceTagMatch[1] } as Record<string, unknown>, "query");
+            if (options?.workspaceId) {
+              params.push(`workspaceIds[0]=${encodeURIComponent(options.workspaceId)}`);
+            }
+            if (options?.limit) params.push(`limit=${options.limit}`);
+            const results = await client.get<SearchResult[]>(`/nodes/search?${params.join("&")}`);
+            return results.map(r => ({ id: r.id, name: r.name }));
+          }
+        }
+
+        // Pattern C: Source search node
+        const searchNodeMatch = md.match(/\*\*Options List\*\*:.*?\(tana:([^)]+)\)/);
+        if (searchNodeMatch) {
+          const searchResult = await client.get<{ markdown: string }>(
+            `/nodes/${searchNodeMatch[1]}?maxDepth=1`
+          );
+          return parseRefsFromMarkdown(searchResult.markdown);
+        }
+
+        // Pattern D: Ad-hoc — sample from existing nodes that have this field set
+        // Extract field name from definition for scoped parsing
+        const fieldNameMatch = md.match(/^- (.+?) #field-definition/m);
+        if (!fieldNameMatch) return [];
+
+        const fieldName = fieldNameMatch[1];
+        const limit = options?.limit ?? 10;
+        const params: string[] = [];
+        const query: Record<string, unknown> = options?.tagId
+          ? { and: [{ hasType: options.tagId }, { field: { fieldId, state: "set" } }] }
+          : { field: { fieldId, state: "set" } };
+        addQueryParams(params, query, "query");
+        if (options?.workspaceId) {
+          params.push(`workspaceIds[0]=${encodeURIComponent(options.workspaceId)}`);
+        }
+        params.push(`limit=${limit}`);
+
+        const searchResults = await client.get<SearchResult[]>(`/nodes/search?${params.join("&")}`);
+        const seen = new Map<string, string>();
+        for (const node of searchResults) {
+          const nodeMd = await client.get<{ markdown: string }>(
+            `/nodes/${node.id}?maxDepth=1`
+          );
+          for (const { id, name } of parseFieldValues(nodeMd.markdown, fieldName)) {
+            if (!seen.has(id)) seen.set(id, name);
+          }
+        }
+        return Array.from(seen, ([id, name]) => ({ id, name }));
+      },
     },
 
     calendar: {
@@ -389,9 +579,15 @@ export function createTanaAPI(
     },
 
     async import(parentNodeId: string, content: string): Promise<ImportResult> {
-      return client.post<ImportResult>(`/nodes/${parentNodeId}/import`, {
-        content,
-      });
+      // API returns { createdNodes: [{id,name}], ... } — normalize to ImportResult
+      const raw = await client.post<{
+        createdNodes: { id: string; name: string }[];
+        message: string;
+      }>(`/nodes/${parentNodeId}/import`, { content });
+      return {
+        success: true,
+        nodeIds: raw.createdNodes.map(n => n.id),
+      };
     },
 
     format(data: unknown): string {

package/src/compat/bun.ts

@@ -0,0 +1,39 @@
+import { Database } from "bun:sqlite";
+import type { CompatDatabase, CompatOps, CompatStatement } from "./types";
+
+function wrapStatement(stmt: ReturnType<Database["prepare"]>): CompatStatement {
+  return {
+    run(...params: unknown[]) {
+      const result = stmt.run(...(params as Parameters<typeof stmt.run>));
+      return { changes: result.changes };
+    },
+    all(...params: unknown[]) {
+      return stmt.all(...(params as Parameters<typeof stmt.all>)) as unknown[];
+    },
+  };
+}
+
+function wrapDatabase(db: Database): CompatDatabase {
+  return {
+    exec(sql: string) {
+      db.run(sql);
+    },
+    prepare(sql: string) {
+      return wrapStatement(db.prepare(sql));
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+export const bunCompat: CompatOps = {
+  createDatabase(path: string): CompatDatabase {
+    return wrapDatabase(new Database(path, { create: true }));
+  },
+
+  transpileTS(code: string): string {
+    const transpiler = new Bun.Transpiler({ loader: "ts" });
+    return transpiler.transformSync(code);
+  },
+};

package/src/compat/index.ts

@@ -0,0 +1,29 @@
+import type { CompatDatabase, CompatOps } from "./types";
+
+export type { CompatDatabase, CompatStatement, CompatOps } from "./types";
+
+let ops: CompatOps | null = null;
+
+export function initCompat(compatOps: CompatOps): void {
+  if (ops) {
+    console.warn("initCompat called multiple times — overwriting previous compat ops");
+  }
+  ops = compatOps;
+}
+
+function getOps(): CompatOps {
+  if (!ops) {
+    throw new Error(
+      "compat not initialized — call initCompat() before using createDatabase or transpileTS"
+    );
+  }
+  return ops;
+}
+
+export function createDatabase(path: string): CompatDatabase {
+  return getOps().createDatabase(path);
+}
+
+export function transpileTS(code: string): string {
+  return getOps().transpileTS(code);
+}

package/src/compat/node.ts

@@ -0,0 +1,62 @@
+import { createRequire } from "node:module";
+import type { CompatDatabase, CompatOps, CompatStatement } from "./types";
+
+const require = createRequire(import.meta.url);
+
+function getBetterSqlite3(): any {
+  try {
+    return require("better-sqlite3");
+  } catch {
+    throw new Error(
+      "better-sqlite3 is required for Node.js. Install it: npm install better-sqlite3"
+    );
+  }
+}
+
+function getEsbuild(): any {
+  try {
+    return require("esbuild");
+  } catch {
+    throw new Error(
+      "esbuild is required for Node.js. Install it: npm install esbuild"
+    );
+  }
+}
+
+function wrapStatement(stmt: any): CompatStatement {
+  return {
+    run(...params: unknown[]) {
+      const result = stmt.run(...params);
+      return { changes: result.changes };
+    },
+    all(...params: unknown[]) {
+      return stmt.all(...params) as unknown[];
+    },
+  };
+}
+
+function wrapDatabase(db: any): CompatDatabase {
+  return {
+    exec(sql: string) {
+      db.exec(sql);
+    },
+    prepare(sql: string) {
+      return wrapStatement(db.prepare(sql));
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+export const nodeCompat: CompatOps = {
+  createDatabase(path: string): CompatDatabase {
+    const BetterSqlite3 = getBetterSqlite3();
+    return wrapDatabase(new BetterSqlite3(path));
+  },
+
+  transpileTS(code: string): string {
+    const esbuild = getEsbuild();
+    return esbuild.transformSync(code, { loader: "ts" }).code;
+  },
+};

package/src/compat/types.ts

@@ -0,0 +1,15 @@
+export interface CompatStatement {
+  run(...params: unknown[]): { changes: number };
+  all(...params: unknown[]): unknown[];
+}
+
+export interface CompatDatabase {
+  exec(sql: string): void;
+  prepare(sql: string): CompatStatement;
+  close(): void;
+}
+
+export interface CompatOps {
+  createDatabase(path: string): CompatDatabase;
+  transpileTS(code: string): string;
+}