tana-mcp-codemode 0.1.0

package/src/index.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env bun
+/**
+ * Tana MCP Server - Entry Point
+ *
+ * Codemode MCP server for Tana knowledge management.
+ * AI writes TypeScript code that executes against the Tana Local API.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { createClient } from "./api/client";
+import { createTanaAPI } from "./api/tana";
+import { executeSandbox } from "./sandbox/executor";
+import { cleanupOldRuns, initDb } from "./storage/history";
+import { TOOL_DESCRIPTION } from "./prompts";
+
+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);
+
+  // 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",
+    {
+      description: TOOL_DESCRIPTION,
+      inputSchema: {
+        code: z.string().describe("TypeScript code to execute"),
+        sessionId: z
+          .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);
+
+      // Format response
+      let responseText = "";
+      if (result.output) {
+        responseText += result.output;
+      }
+      if (result.error) {
+        responseText += responseText ? "\n\n" : "";
+        responseText += `Error: ${result.error}`;
+      }
+      responseText += `\n\n[Executed in ${result.durationMs}ms]`;
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: responseText,
+          },
+        ],
+        isError: !result.success,
+      };
+    }
+  );
+
+  // Start server with stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  console.error("Tana MCP server started");
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/prompts.ts

@@ -0,0 +1,81 @@
+/**
+ * Tool Description - Markdown Documentation
+ */
+
+export const TOOL_DESCRIPTION = `Execute TypeScript code to interact with Tana.
+
+## APIs
+
+tana.health() → { status }
+tana.workspaces.list() → Workspace[] { id, name, homeNodeId }
+
+### Nodes
+tana.nodes.search(query, options?) → SearchResult[]
+tana.nodes.read(nodeId, maxDepth?) → string (markdown)
+tana.nodes.getChildren(nodeId, { limit?, offset? }) → { children, total, hasMore }
+tana.nodes.edit({ nodeId, name?, description? }) → { success }
+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.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", ... })
+tana.tags.setCheckbox({ tagId, showCheckbox, doneStateMapping? })
+
+### Fields
+tana.fields.setOption(nodeId, attributeId, optionId)
+tana.fields.setContent(nodeId, attributeId, content)
+
+### Calendar
+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\`
+
+### Helpers
+stdin().json<T>() | .lines() | .text() | .hasInput()
+workflow.start(msg) | .step(msg) | .progress(n, total, msg) | .complete(msg) | .abort(err)
+
+## Edit (search-and-replace)
+
+tana.nodes.edit({ nodeId, name: { old_string, new_string }, description: { old_string, new_string } })
+Empty old_string matches absent field.
+
+## Search Query Operators
+
+{ 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" }
+{ 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: {...} }
+
+## Examples
+
+Search: await tana.nodes.search({ and: [{ hasType: "tagId" }, { is: "todo" }] })
+
+Import:
+\`\`\`
+await tana.import(parentNodeId, \`
+- Node #[[^tagId]]
+  - [[^fieldId]]:: value
+- [ ] Todo item
+\`)
+\`\`\`
+
+## Output
+
+console.log() to return data.
+`;

package/src/sandbox/executor.ts

@@ -0,0 +1,270 @@
+/**
+ * Sandbox - Code Execution Engine
+ *
+ * Executes arbitrary TypeScript code with injected `tana` API object.
+ * Features:
+ * - AsyncFunction for top-level await support
+ * - 10s timeout via Promise.race
+ * - Duration tracking
+ * - Automatic history persistence with API call tracking
+ */
+
+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
+
+/**
+ * Wraps the tana API to track which methods are called
+ */
+function createTrackedTanaAPI(
+  tana: TanaAPI,
+  tracker: { calls: string[]; nodeIds: Set<string>; workspaceId: string | null }
+): TanaAPI {
+  const track = <T>(method: string, fn: () => Promise<T>): Promise<T> => {
+    tracker.calls.push(method);
+    return fn();
+  };
+
+  const trackNodeId = (id: string) => tracker.nodeIds.add(id);
+
+  return {
+    health: () => track("health", () => tana.health()),
+
+    workspaces: {
+      list: () => track("workspaces.list", () => tana.workspaces.list()),
+    },
+
+    nodes: {
+      search: (query, options) => {
+        if (options?.workspaceIds?.[0]) {
+          tracker.workspaceId = options.workspaceIds[0];
+        }
+        return track("nodes.search", () => tana.nodes.search(query, options));
+      },
+      read: (nodeId, maxDepth) => {
+        trackNodeId(nodeId);
+        return track("nodes.read", () => tana.nodes.read(nodeId, maxDepth));
+      },
+      getChildren: (nodeId, options) => {
+        trackNodeId(nodeId);
+        return track("nodes.getChildren", () => tana.nodes.getChildren(nodeId, options));
+      },
+      edit: (options) => {
+        trackNodeId(options.nodeId);
+        return track("nodes.edit", () => tana.nodes.edit(options));
+      },
+      trash: (nodeId) => {
+        trackNodeId(nodeId);
+        return track("nodes.trash", () => tana.nodes.trash(nodeId));
+      },
+      check: (nodeId) => {
+        trackNodeId(nodeId);
+        return track("nodes.check", () => tana.nodes.check(nodeId));
+      },
+      uncheck: (nodeId) => {
+        trackNodeId(nodeId);
+        return track("nodes.uncheck", () => tana.nodes.uncheck(nodeId));
+      },
+    },
+
+    tags: {
+      list: (workspaceId, limit) => {
+        tracker.workspaceId = workspaceId;
+        return track("tags.list", () => tana.tags.list(workspaceId, limit));
+      },
+      getSchema: (tagId, includeEditInstructions) =>
+        track("tags.getSchema", () => tana.tags.getSchema(tagId, includeEditInstructions)),
+      modify: (nodeId, action, tagIds) => {
+        trackNodeId(nodeId);
+        return track("tags.modify", () => tana.tags.modify(nodeId, action, tagIds));
+      },
+      create: (options) => {
+        tracker.workspaceId = options.workspaceId;
+        return track("tags.create", () => tana.tags.create(options));
+      },
+      addField: (options) =>
+        track("tags.addField", () => tana.tags.addField(options)),
+      setCheckbox: (options) =>
+        track("tags.setCheckbox", () => tana.tags.setCheckbox(options)),
+    },
+
+    fields: {
+      setOption: (nodeId, attributeId, optionId) => {
+        trackNodeId(nodeId);
+        return track("fields.setOption", () => tana.fields.setOption(nodeId, attributeId, optionId));
+      },
+      setContent: (nodeId, attributeId, content) => {
+        trackNodeId(nodeId);
+        return track("fields.setContent", () => tana.fields.setContent(nodeId, attributeId, content));
+      },
+    },
+
+    calendar: {
+      getOrCreate: (workspaceId, granularity, date) => {
+        tracker.workspaceId = workspaceId;
+        return track("calendar.getOrCreate", () =>
+          tana.calendar.getOrCreate(workspaceId, granularity, date)
+        );
+      },
+    },
+
+    import: (parentNodeId, content) => {
+      trackNodeId(parentNodeId);
+      return track("import", () => tana.import(parentNodeId, content));
+    },
+  };
+}
+
+export async function executeSandbox(
+  code: string,
+  tana: TanaAPI,
+  sessionId?: string,
+  input?: string
+): Promise<SandboxResult> {
+  const startTime = performance.now();
+  const logs: string[] = [];
+
+  // Track API usage
+  const tracker = {
+    calls: [] as string[],
+    nodeIds: new Set<string>(),
+    workspaceId: null as string | null,
+  };
+
+  // Custom console that captures output
+  const sandboxConsole = {
+    log: (...args: unknown[]) => {
+      logs.push(args.map(formatArg).join(" "));
+    },
+    error: (...args: unknown[]) => {
+      logs.push(`[ERROR] ${args.map(formatArg).join(" ")}`);
+    },
+    warn: (...args: unknown[]) => {
+      logs.push(`[WARN] ${args.map(formatArg).join(" ")}`);
+    },
+    info: (...args: unknown[]) => {
+      logs.push(args.map(formatArg).join(" "));
+    },
+  };
+
+  // Create helpers for script execution
+  const stdin = createStdinHelper(input);
+  const effectiveSessionId = sessionId ?? crypto.randomUUID();
+  const workflow = createWorkflowHelper(effectiveSessionId);
+
+  // Wrap tana to track API calls
+  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 () {}
+    ).constructor;
+
+    // Globals to shadow (will receive undefined to prevent accidental access)
+    // Note: This is defense-in-depth, not a security sandbox
+    const shadowedGlobals = [
+      "process",
+      "require",
+      "Bun",
+      "Deno",
+      "globalThis",
+      "global",
+      "eval",
+      "Function",
+      "__dirname",
+      "__filename",
+      "module",
+      "exports",
+    ];
+
+    const fn = new AsyncFunction(
+      "tana",
+      "console",
+      "stdin",
+      "workflow",
+      ...shadowedGlobals,
+      code
+    );
+
+    // 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),
+      timeoutPromise,
+    ]);
+
+    const durationMs = Math.round(performance.now() - startTime);
+    const output = logs.join("\n");
+
+    // Fire-and-forget save to history
+    saveScriptRun({
+      script: code,
+      success: true,
+      output,
+      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,
+    });
+
+    return {
+      success: true,
+      output,
+      durationMs,
+    };
+  } catch (error) {
+    const durationMs = Math.round(performance.now() - startTime);
+    const errorMessage =
+      error instanceof Error ? error.message : String(error);
+    const output = logs.join("\n");
+
+    // Fire-and-forget save to history
+    saveScriptRun({
+      script: code,
+      success: false,
+      output,
+      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,
+    });
+
+    return {
+      success: false,
+      output,
+      error: errorMessage,
+      durationMs,
+    };
+  }
+}
+
+function formatArg(arg: unknown): string {
+  if (arg === null) return "null";
+  if (arg === undefined) return "undefined";
+  if (typeof arg === "string") return arg;
+  if (typeof arg === "number" || typeof arg === "boolean") return String(arg);
+  try {
+    return JSON.stringify(arg, null, 2);
+  } catch {
+    return String(arg);
+  }
+}

package/src/sandbox/stdin.ts

@@ -0,0 +1,69 @@
+/**
+ * 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;
+    },
+  });
+}

package/src/sandbox/workflow.ts

@@ -0,0 +1,197 @@
+/**
+ * Workflow Event Logging
+ *
+ * Tracks execution progress through multi-step operations.
+ * Provides timeline view instead of flat pass/fail history.
+ *
+ * Usage in scripts:
+ *   workflow.start("Processing nodes");
+ *   workflow.step("Fetching workspaces");
+ *   workflow.step("Found 3 workspaces");
+ *   workflow.complete("Done!");
+ */
+
+import { Database } from "bun:sqlite";
+import { initDb } from "../storage/history";
+
+export type WorkflowEventType =
+  | "start"
+  | "step"
+  | "progress"
+  | "complete"
+  | "abort";
+
+export interface WorkflowEvent {
+  id: number;
+  sessionId: string;
+  timestamp: number;
+  eventType: WorkflowEventType;
+  message: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface WorkflowHelper {
+  /** Start a new workflow with description */
+  start(message: string): void;
+  /** Log an intermediate step */
+  step(message: string): void;
+  /** Log progress (e.g., "25/100 processed") */
+  progress(current: number, total: number, message?: string): void;
+  /** Mark workflow as successfully completed */
+  complete(message?: string): void;
+  /** Mark workflow as aborted/failed */
+  abort(reason: string): void;
+}
+
+let workflowTableInitialized = false;
+
+function ensureWorkflowTable(db: Database): void {
+  if (workflowTableInitialized) return;
+
+  db.run(`
+    CREATE TABLE IF NOT EXISTS workflow_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      session_id TEXT NOT NULL,
+      timestamp INTEGER NOT NULL,
+      event_type TEXT NOT NULL,
+      message TEXT NOT NULL,
+      metadata TEXT
+    )
+  `);
+
+  db.run(`
+    CREATE INDEX IF NOT EXISTS idx_workflow_session
+    ON workflow_events(session_id, timestamp)
+  `);
+
+  workflowTableInitialized = true;
+}
+
+function saveWorkflowEvent(
+  sessionId: string,
+  eventType: WorkflowEventType,
+  message: string,
+  metadata?: Record<string, unknown>
+): void {
+  try {
+    const db = initDb();
+    ensureWorkflowTable(db);
+
+    const stmt = db.prepare(`
+      INSERT INTO workflow_events (session_id, timestamp, event_type, message, metadata)
+      VALUES (?, ?, ?, ?, ?)
+    `);
+    stmt.run(
+      sessionId,
+      Date.now(),
+      eventType,
+      message,
+      metadata ? JSON.stringify(metadata) : null
+    );
+  } catch (e) {
+    // Fire-and-forget - don't disrupt execution
+    console.error("Failed to save workflow event:", e);
+  }
+}
+
+export function createWorkflowHelper(sessionId: string): WorkflowHelper {
+  return {
+    start(message: string): void {
+      saveWorkflowEvent(sessionId, "start", message);
+    },
+
+    step(message: string): void {
+      saveWorkflowEvent(sessionId, "step", message);
+    },
+
+    progress(current: number, total: number, message?: string): void {
+      const progressMsg = message
+        ? `${message} (${current}/${total})`
+        : `${current}/${total}`;
+      saveWorkflowEvent(sessionId, "progress", progressMsg, { current, total });
+    },
+
+    complete(message?: string): void {
+      saveWorkflowEvent(sessionId, "complete", message ?? "Completed");
+    },
+
+    abort(reason: string): void {
+      saveWorkflowEvent(sessionId, "abort", reason);
+    },
+  };
+}
+
+export function getWorkflowEvents(
+  sessionId: string,
+  limit = 100
+): WorkflowEvent[] {
+  try {
+    const db = initDb();
+    ensureWorkflowTable(db);
+
+    const stmt = db.prepare(`
+      SELECT
+        id,
+        session_id as sessionId,
+        timestamp,
+        event_type as eventType,
+        message,
+        metadata
+      FROM workflow_events
+      WHERE session_id = ?
+      ORDER BY timestamp ASC
+      LIMIT ?
+    `);
+
+    const rows = stmt.all(sessionId, limit) as Array<{
+      id: number;
+      sessionId: string;
+      timestamp: number;
+      eventType: WorkflowEventType;
+      message: string;
+      metadata: string | null;
+    }>;
+
+    return rows.map((row) => ({
+      ...row,
+      metadata: row.metadata ? JSON.parse(row.metadata) : undefined,
+    }));
+  } catch {
+    return [];
+  }
+}
+
+export function getRecentWorkflows(limit = 20): Array<{
+  sessionId: string;
+  startTime: number;
+  eventCount: number;
+  lastEvent: string;
+}> {
+  try {
+    const db = initDb();
+    ensureWorkflowTable(db);
+
+    const stmt = db.prepare(`
+      SELECT
+        session_id as sessionId,
+        MIN(timestamp) as startTime,
+        COUNT(*) as eventCount,
+        (SELECT message FROM workflow_events w2
+         WHERE w2.session_id = workflow_events.session_id
+         ORDER BY timestamp DESC LIMIT 1) as lastEvent
+      FROM workflow_events
+      GROUP BY session_id
+      ORDER BY startTime DESC
+      LIMIT ?
+    `);
+
+    return stmt.all(limit) as Array<{
+      sessionId: string;
+      startTime: number;
+      eventCount: number;
+      lastEvent: string;
+    }>;
+  } catch {
+    return [];
+  }
+}