@tekmidian/devon 3.0.0

package/dist/shared/shell.d.ts

@@ -0,0 +1,15 @@
+/**
+ * shell.ts — Shell utilities shared across tools.
+ */
+/**
+ * Shell-quote a string by wrapping in single quotes and escaping embedded single quotes.
+ */
+export declare function shellQuote(s: string): string;
+/**
+ * Execute a shell command with timeout and encoding defaults.
+ * Returns trimmed stdout. Throws on non-zero exit.
+ */
+export declare function execSyncWithTimeout(command: string, opts?: {
+    timeout?: number;
+    maxBuffer?: number;
+}): string;

package/dist/shared/shell.js

@@ -0,0 +1,22 @@
+/**
+ * shell.ts — Shell utilities shared across tools.
+ */
+import { execSync } from "node:child_process";
+/**
+ * Shell-quote a string by wrapping in single quotes and escaping embedded single quotes.
+ */
+export function shellQuote(s) {
+    return `'${s.replace(/'/g, "'\\''")}'`;
+}
+/**
+ * Execute a shell command with timeout and encoding defaults.
+ * Returns trimmed stdout. Throws on non-zero exit.
+ */
+export function execSyncWithTimeout(command, opts) {
+    return execSync(command, {
+        encoding: "utf-8",
+        timeout: opts?.timeout ?? 10_000,
+        maxBuffer: opts?.maxBuffer ?? 50 * 1024 * 1024,
+    }).trim();
+}
+//# sourceMappingURL=shell.js.map

package/dist/shared/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/shared/shell.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE9C;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAS;IAClC,OAAO,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AACzC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAe,EACf,IAA+C;IAE/C,OAAO,QAAQ,CAAC,OAAO,EAAE;QACvB,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,IAAI,EAAE,OAAO,IAAI,MAAM;QAChC,SAAS,EAAE,IAAI,EAAE,SAAS,IAAI,EAAE,GAAG,IAAI,GAAG,IAAI;KAC/C,CAAC,CAAC,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/dist/tools/ai/ask-ai-about-documents.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ask-ai-about-documents.ts — Ask DEVONthink's AI a question about specific documents.
+ *
+ * Resolves each UUID to a DEVONthink record and passes them to DEVONthink's
+ * built-in AI feature along with the user's question. Supports optional engine,
+ * model, and temperature overrides. Returns the AI-generated answer string.
+ */
+export declare const askAiAboutDocumentsTool: import("../../jxa/types.js").McpTool;

package/dist/tools/ai/ask-ai-about-documents.js

@@ -0,0 +1,88 @@
+/**
+ * ask-ai-about-documents.ts — Ask DEVONthink's AI a question about specific documents.
+ *
+ * Resolves each UUID to a DEVONthink record and passes them to DEVONthink's
+ * built-in AI feature along with the user's question. Supports optional engine,
+ * model, and temperature overrides. Returns the AI-generated answer string.
+ */
+import { z } from "zod";
+import { defineTool } from "../../jxa/types.js";
+import { jxaLiteral } from "../../jxa/escape.js";
+import { JXA_APP } from "../../jxa/helpers.js";
+const ENGINE_VALUES = [
+    "ChatGPT",
+    "Claude",
+    "Gemini",
+    "Mistral AI",
+    "GPT4All",
+    "LM Studio",
+    "Ollama",
+];
+export const askAiAboutDocumentsTool = defineTool({
+    name: "ask_ai_about_documents",
+    description: "Ask AI questions about specific DEVONthink documents for analysis, comparison, or extraction.",
+    schema: z.object({
+        documentUuids: z
+            .array(z.string())
+            .min(1)
+            .describe("One or more DEVONthink record UUIDs to use as context for the AI question"),
+        question: z
+            .string()
+            .min(1)
+            .max(10000)
+            .describe("The question or instruction to send to the AI about the documents"),
+        temperature: z
+            .number()
+            .min(0)
+            .max(2)
+            .default(0.7)
+            .optional()
+            .describe("Sampling temperature for the AI response (0 = deterministic, 2 = creative). Defaults to 0.7"),
+        model: z
+            .string()
+            .optional()
+            .describe("Optional AI model name to use (e.g. 'gpt-4o', 'claude-3-5-sonnet'). Uses DEVONthink default if omitted"),
+        engine: z
+            .enum(ENGINE_VALUES)
+            .optional()
+            .describe("Optional AI engine to use. Uses DEVONthink's configured default if omitted"),
+    }),
+    run: async (args, executor) => {
+        const { documentUuids, question, temperature, model, engine } = args;
+        const script = `
+      ${JXA_APP}
+      var uuids = ${jxaLiteral(documentUuids)};
+      var question = ${jxaLiteral(question)};
+      var temperature = ${jxaLiteral(temperature ?? 0.7)};
+      var modelName = ${jxaLiteral(model ?? null)};
+      var engineName = ${jxaLiteral(engine ?? null)};
+
+      // Resolve each UUID to a DEVONthink record
+      var records = [];
+      for (var i = 0; i < uuids.length; i++) {
+        var rec = app.getRecordWithUuid(uuids[i]);
+        if (!rec || !rec.uuid()) {
+          throw new Error("Record not found for UUID: " + uuids[i]);
+        }
+        records.push(rec);
+      }
+
+      // Build AI call options
+      var aiOpts = { record: records, temperature: temperature };
+      if (engineName) aiOpts["engine"] = engineName;
+      if (modelName) aiOpts["model"] = modelName;
+
+      // Call DEVONthink's AI
+      var answer = app.getChatResponseForMessage(question, aiOpts);
+
+      JSON.stringify({
+        answer: answer || null,
+        documentCount: records.length,
+        question: question
+      });
+    `;
+        const result = executor.run(script);
+        return JSON.parse(result.stdout);
+    },
+});
+//# sourceMappingURL=ask-ai-about-documents.js.map

package/dist/tools/ai/ask-ai-about-documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-ai-about-documents.js","sourceRoot":"","sources":["../../../src/tools/ai/ask-ai-about-documents.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,MAAM,aAAa,GAAG;IACpB,SAAS;IACT,QAAQ;IACR,QAAQ;IACR,YAAY;IACZ,SAAS;IACT,WAAW;IACX,QAAQ;CACA,CAAC;AAEX,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC;IAChD,IAAI,EAAE,wBAAwB;IAC9B,WAAW,EACT,+FAA+F;IACjG,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,aAAa,EAAE,CAAC;aACb,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,2EAA2E,CAAC;QACxF,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,KAAK,CAAC;aACV,QAAQ,CAAC,mEAAmE,CAAC;QAChF,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,GAAG,CAAC,CAAC,CAAC;aACN,OAAO,CAAC,GAAG,CAAC;aACZ,QAAQ,EAAE;aACV,QAAQ,CAAC,6FAA6F,CAAC;QAC1G,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,wGAAwG,CAAC;QACrH,MAAM,EAAE,CAAC;aACN,IAAI,CAAC,aAAa,CAAC;aACnB,QAAQ,EAAE;aACV,QAAQ,CAAC,4EAA4E,CAAC;KAC1F,CAAC;IACF,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAC5B,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QAErE,MAAM,MAAM,GAAG;QACX,OAAO;oBACK,UAAU,CAAC,aAAa,CAAC;uBACtB,UAAU,CAAC,QAAQ,CAAC;0BACjB,UAAU,CAAC,WAAW,IAAI,GAAG,CAAC;wBAChC,UAAU,CAAC,KAAK,IAAI,IAAI,CAAC;yBACxB,UAAU,CAAC,MAAM,IAAI,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;KAyB9C,CAAC;QAEF,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAI9B,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/ai/check-ai-health.d.ts

@@ -0,0 +1,8 @@
+/**
+ * check-ai-health.ts — Check if DEVONthink's AI services are available.
+ *
+ * Probes DEVONthink AI by attempting a lightweight operation. Returns a
+ * structured availability report with a human-readable message so callers
+ * can decide whether to proceed with more expensive AI tool calls.
+ */
+export declare const checkAiHealthTool: import("../../jxa/types.js").McpTool;

package/dist/tools/ai/check-ai-health.js

@@ -0,0 +1,40 @@
+/**
+ * check-ai-health.ts — Check if DEVONthink's AI services are available.
+ *
+ * Probes DEVONthink AI by attempting a lightweight operation. Returns a
+ * structured availability report with a human-readable message so callers
+ * can decide whether to proceed with more expensive AI tool calls.
+ */
+import { z } from "zod";
+import { defineTool } from "../../jxa/types.js";
+import { JXA_APP } from "../../jxa/helpers.js";
+export const checkAiHealthTool = defineTool({
+    name: "check_ai_health",
+    description: "Check if DEVONthink's AI services are available and working properly.",
+    schema: z.object({}),
+    run: async (_args, executor) => {
+        const script = `
+      ${JXA_APP}
+
+      var available = false;
+      var message = "";
+      var model = null;
+
+      try {
+        // Attempt a lightweight AI probe: ask a trivial question with no documents.
+        // DEVONthink will throw if the AI engine is unavailable or misconfigured.
+        var testAnswer = app.getChatResponseForMessage("Reply with the single word: OK", { temperature: 0 });
+        available = true;
+        message = "DEVONthink AI is available and responding.";
+      } catch (e) {
+        available = false;
+        message = e.message || String(e);
+      }
+
+      JSON.stringify({ available: available, message: message, model: model });
+    `;
+        const result = executor.run(script);
+        return JSON.parse(result.stdout);
+    },
+});
+//# sourceMappingURL=check-ai-health.js.map

package/dist/tools/ai/check-ai-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-ai-health.js","sourceRoot":"","sources":["../../../src/tools/ai/check-ai-health.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAG,UAAU,CAAC;IAC1C,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,uEAAuE;IACzE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACpB,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG;QACX,OAAO;;;;;;;;;;;;;;;;;;KAkBV,CAAC;QAEF,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAI9B,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/ai/create-summary-document.d.ts

@@ -0,0 +1,8 @@
+/**
+ * create-summary-document.ts — Create an AI-generated summary document in DEVONthink.
+ *
+ * Resolves source documents by UUID, invokes DEVONthink's AI summarization,
+ * and stores the result as a new record. The destination group and title are
+ * optional; sensible defaults are applied when they are omitted.
+ */
+export declare const createSummaryDocumentTool: import("../../jxa/types.js").McpTool;

package/dist/tools/ai/create-summary-document.js

@@ -0,0 +1,102 @@
+/**
+ * create-summary-document.ts — Create an AI-generated summary document in DEVONthink.
+ *
+ * Resolves source documents by UUID, invokes DEVONthink's AI summarization,
+ * and stores the result as a new record. The destination group and title are
+ * optional; sensible defaults are applied when they are omitted.
+ */
+import { z } from "zod";
+import { defineTool } from "../../jxa/types.js";
+import { jxaLiteral } from "../../jxa/escape.js";
+import { JXA_APP, JXA_RECORD_PROPS } from "../../jxa/helpers.js";
+const SUMMARY_TYPE_VALUES = ["markdown", "rich", "sheet", "simple"];
+const SUMMARY_STYLE_VALUES = [
+    "text summary",
+    "key points summary",
+    "list summary",
+    "table summary",
+    "custom summary",
+];
+export const createSummaryDocumentTool = defineTool({
+    name: "create_summary_document",
+    description: "Create an AI-generated summary document from multiple DEVONthink documents.",
+    schema: z.object({
+        documentUuids: z
+            .array(z.string())
+            .min(1)
+            .describe("UUIDs of the source DEVONthink records to summarize"),
+        summaryType: z
+            .enum(SUMMARY_TYPE_VALUES)
+            .default("markdown")
+            .optional()
+            .describe("Output format for the summary document. " +
+            "One of: markdown, rich, sheet, simple. Defaults to markdown"),
+        summaryStyle: z
+            .enum(SUMMARY_STYLE_VALUES)
+            .optional()
+            .describe("Style of summary to generate. " +
+            "One of: text summary, key points summary, list summary, table summary, custom summary"),
+        parentGroupUuid: z
+            .string()
+            .optional()
+            .describe("UUID of the group where the summary document should be created. " +
+            "If omitted, the summary is placed in the same group as the first source record"),
+        customTitle: z
+            .string()
+            .optional()
+            .describe("Title for the new summary record. Defaults to 'Summary - <ISO date>' if omitted"),
+    }),
+    run: async (args, executor) => {
+        const { documentUuids, summaryType, summaryStyle, parentGroupUuid, customTitle } = args;
+        const script = `
+      ${JXA_APP}
+      var uuids = ${jxaLiteral(documentUuids)};
+      var summaryType = ${jxaLiteral(summaryType ?? "markdown")};
+      var summaryStyle = ${jxaLiteral(summaryStyle ?? null)};
+      var parentGroupUuid = ${jxaLiteral(parentGroupUuid ?? null)};
+      var customTitle = ${jxaLiteral(customTitle ?? null)};
+
+      // Resolve source records
+      var records = [];
+      for (var i = 0; i < uuids.length; i++) {
+        var rec = app.getRecordWithUuid(uuids[i]);
+        if (!rec || !rec.uuid()) {
+          throw new Error("Record not found for UUID: " + uuids[i]);
+        }
+        records.push(rec);
+      }
+
+      // Resolve destination group
+      var parentGroup = null;
+      if (parentGroupUuid) {
+        parentGroup = app.getRecordWithUuid(parentGroupUuid);
+        if (!parentGroup || !parentGroup.uuid()) {
+          throw new Error("Parent group not found for UUID: " + parentGroupUuid);
+        }
+      } else {
+        // Default: same group as the first source record
+        parentGroup = records[0].parent();
+      }
+
+      // Build summarization options
+      var summarizeOpts = {
+        records: records,
+        to: summaryType,
+        in: parentGroup
+      };
+      if (summaryStyle) summarizeOpts["as"] = summaryStyle;
+
+      // Call DEVONthink's AI summarization
+      var summaryRecord = app.summarizeContentsOf(summarizeOpts);
+      if (!summaryRecord || !summaryRecord.uuid()) {
+        throw new Error("DEVONthink did not return a summary record");
+      }
+
+      var record = summaryRecord;
+      JSON.stringify(${JXA_RECORD_PROPS});
+    `;
+        const result = executor.run(script);
+        return JSON.parse(result.stdout);
+    },
+});
+//# sourceMappingURL=create-summary-document.js.map

package/dist/tools/ai/create-summary-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-summary-document.js","sourceRoot":"","sources":["../../../src/tools/ai/create-summary-document.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,MAAM,mBAAmB,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAU,CAAC;AAE7E,MAAM,oBAAoB,GAAG;IAC3B,cAAc;IACd,oBAAoB;IACpB,cAAc;IACd,eAAe;IACf,gBAAgB;CACR,CAAC;AAEX,MAAM,CAAC,MAAM,yBAAyB,GAAG,UAAU,CAAC;IAClD,IAAI,EAAE,yBAAyB;IAC/B,WAAW,EACT,6EAA6E;IAC/E,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC;QACf,aAAa,EAAE,CAAC;aACb,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;aACjB,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,qDAAqD,CAAC;QAClE,WAAW,EAAE,CAAC;aACX,IAAI,CAAC,mBAAmB,CAAC;aACzB,OAAO,CAAC,UAAU,CAAC;aACnB,QAAQ,EAAE;aACV,QAAQ,CACP,0CAA0C;YAC1C,6DAA6D,CAC9D;QACH,YAAY,EAAE,CAAC;aACZ,IAAI,CAAC,oBAAoB,CAAC;aAC1B,QAAQ,EAAE;aACV,QAAQ,CACP,gCAAgC;YAChC,uFAAuF,CACxF;QACH,eAAe,EAAE,CAAC;aACf,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,kEAAkE;YAClE,gFAAgF,CACjF;QACH,WAAW,EAAE,CAAC;aACX,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,iFAAiF,CAClF;KACJ,CAAC;IACF,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;QAC5B,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;QAExF,MAAM,MAAM,GAAG;QACX,OAAO;oBACK,UAAU,CAAC,aAAa,CAAC;0BACnB,UAAU,CAAC,WAAW,IAAI,UAAU,CAAC;2BACpC,UAAU,CAAC,YAAY,IAAI,IAAI,CAAC;8BAC7B,UAAU,CAAC,eAAe,IAAI,IAAI,CAAC;0BACvC,UAAU,CAAC,WAAW,IAAI,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;uBAuClC,gBAAgB;KAClC,CAAC;QAEF,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACnC,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/ai/get-ai-tool-documentation.d.ts

@@ -0,0 +1,8 @@
+/**
+ * get-ai-tool-documentation.ts — Return documentation for DEVONthink AI tools.
+ *
+ * This is a pure TypeScript tool with no JXA execution. It serves embedded
+ * documentation for the four AI tools so that the AI assistant can understand
+ * how to use them effectively before making calls.
+ */
+export declare const getAiToolDocumentationTool: import("../../jxa/types.js").McpTool;

package/dist/tools/ai/get-ai-tool-documentation.js

@@ -0,0 +1,220 @@
+/**
+ * get-ai-tool-documentation.ts — Return documentation for DEVONthink AI tools.
+ *
+ * This is a pure TypeScript tool with no JXA execution. It serves embedded
+ * documentation for the four AI tools so that the AI assistant can understand
+ * how to use them effectively before making calls.
+ */
+import { z } from "zod";
+import { defineTool } from "../../jxa/types.js";
+const AI_TOOL_DOCS = {
+    get_ai_tool_documentation: {
+        name: "get_ai_tool_documentation",
+        description: "Returns detailed documentation, parameter descriptions, usage examples, and " +
+            "notes for any of the four DEVONthink AI tools. Call this tool first if you are " +
+            "unsure how to use ask_ai_about_documents, check_ai_health, or create_summary_document.",
+        parameters: [
+            {
+                name: "toolName",
+                type: "string (enum)",
+                required: false,
+                description: "Optional. One of: get_ai_tool_documentation, check_ai_health, " +
+                    "ask_ai_about_documents, create_summary_document. " +
+                    "If omitted, documentation for all four tools is returned.",
+            },
+        ],
+        returns: "A documentation object (or array of documentation objects) describing " +
+            "each requested AI tool — including its parameters, return shape, usage examples, and tips.",
+        examples: [
+            {
+                description: "Get documentation for all AI tools",
+                input: {},
+            },
+            {
+                description: "Get documentation for a specific tool",
+                input: { toolName: "ask_ai_about_documents" },
+            },
+        ],
+        notes: [
+            "This tool itself has no side-effects and does not call DEVONthink.",
+            "Use this before calling AI tools for the first time in a session.",
+        ],
+    },
+    check_ai_health: {
+        name: "check_ai_health",
+        description: "Verifies that DEVONthink's built-in AI features are available and responding. " +
+            "Call this before any AI-intensive operations to confirm the AI engine is ready.",
+        parameters: [],
+        returns: "An object with fields: { available: boolean, model?: string, error?: string }. " +
+            "`available` is true when DEVONthink AI is ready to process requests. " +
+            "`model` reports the active AI model name when available.",
+        examples: [
+            {
+                description: "Check if AI is available before summarising a document",
+                input: {},
+            },
+        ],
+        notes: [
+            "DEVONthink AI requires an active network connection and a valid subscription.",
+            "If `available` is false, inspect the `error` field for the reason.",
+            "The check adds minimal latency and is safe to call frequently.",
+        ],
+    },
+    ask_ai_about_documents: {
+        name: "ask_ai_about_documents",
+        description: "Sends a natural-language question to DEVONthink AI with one or more documents " +
+            "as context. The AI reads the document content and returns an answer grounded in " +
+            "those documents. Ideal for summarisation, extraction, comparison, and Q&A tasks.",
+        parameters: [
+            {
+                name: "question",
+                type: "string",
+                required: true,
+                description: "The question or instruction to send to the AI. Be specific: " +
+                    "'Summarise the key findings' or 'List all action items mentioned'.",
+            },
+            {
+                name: "uuids",
+                type: "string[]",
+                required: true,
+                description: "Array of DEVONthink record UUIDs to include as context. " +
+                    "Use search or get_record_properties to obtain UUIDs first.",
+            },
+            {
+                name: "database",
+                type: "string",
+                required: false,
+                description: "Optional database name to scope the lookup. If omitted, all open databases are searched.",
+            },
+        ],
+        returns: "An object with fields: { answer: string, tokensUsed?: number, error?: string }. " +
+            "`answer` contains the AI-generated response. `tokensUsed` is the approximate " +
+            "token count consumed by the request.",
+        examples: [
+            {
+                description: "Summarise a single document",
+                input: {
+                    question: "Summarise this document in three bullet points.",
+                    uuids: ["A1B2C3D4-..."],
+                },
+            },
+            {
+                description: "Compare two contracts",
+                input: {
+                    question: "What are the key differences between these two contracts?",
+                    uuids: ["UUID-contract-a", "UUID-contract-b"],
+                    database: "Legal",
+                },
+            },
+            {
+                description: "Extract action items",
+                input: {
+                    question: "List every action item and its owner from these meeting notes.",
+                    uuids: ["UUID-meeting-2026-01", "UUID-meeting-2026-02"],
+                },
+            },
+        ],
+        notes: [
+            "Each UUID must refer to a record in an open database.",
+            "Very large documents may be truncated to fit the AI context window.",
+            "Token limits apply — avoid including more than 5-10 large documents at once.",
+            "check_ai_health first if you encounter repeated failures.",
+        ],
+    },
+    create_summary_document: {
+        name: "create_summary_document",
+        description: "Generates a new DEVONthink document containing an AI-written summary of one or " +
+            "more source records. The summary is saved as a new Markdown or plain-text record " +
+            "in the specified group or database, leaving the originals untouched.",
+        parameters: [
+            {
+                name: "uuids",
+                type: "string[]",
+                required: true,
+                description: "Array of DEVONthink record UUIDs to summarise. " +
+                    "Use search or get_record_properties to obtain UUIDs first.",
+            },
+            {
+                name: "prompt",
+                type: "string",
+                required: false,
+                description: "Optional custom instruction for the AI, e.g. 'Focus on the financial data only'. " +
+                    "If omitted, a standard summarisation prompt is used.",
+            },
+            {
+                name: "destinationUuid",
+                type: "string",
+                required: false,
+                description: "UUID of the DEVONthink group where the summary document should be created. " +
+                    "If omitted, the summary is created in the same group as the first source record.",
+            },
+            {
+                name: "title",
+                type: "string",
+                required: false,
+                description: "Title for the new summary record. Defaults to 'Summary - <date>'.",
+            },
+        ],
+        returns: "An object with fields: { success: boolean, uuid?: string, name?: string, error?: string }. " +
+            "`uuid` and `name` identify the newly created summary record.",
+        examples: [
+            {
+                description: "Summarise a single report",
+                input: {
+                    uuids: ["UUID-annual-report-2025"],
+                    title: "Annual Report 2025 - Summary",
+                },
+            },
+            {
+                description: "Create a focused summary in a specific group",
+                input: {
+                    uuids: ["UUID-doc-a", "UUID-doc-b", "UUID-doc-c"],
+                    prompt: "Extract only the risk factors and mitigation strategies.",
+                    destinationUuid: "UUID-risk-analysis-group",
+                    title: "Risk Factor Summary",
+                },
+            },
+        ],
+        notes: [
+            "The new summary record is created immediately; the AI generation is synchronous.",
+            "For very long source documents, the AI may only see a truncated excerpt.",
+            "The summary is saved as Markdown by default.",
+            "Use check_ai_health if the call fails without a clear error.",
+        ],
+    },
+};
+// ---------------------------------------------------------------------------
+// Tool definition
+// ---------------------------------------------------------------------------
+const AI_TOOL_NAMES = [
+    "get_ai_tool_documentation",
+    "check_ai_health",
+    "ask_ai_about_documents",
+    "create_summary_document",
+];
+export const getAiToolDocumentationTool = defineTool({
+    name: "get_ai_tool_documentation",
+    description: "Get detailed documentation for DEVONthink AI tools including examples and use cases. " +
+        "Optionally specify a toolName to get docs for a single tool; omit to get docs for all four.",
+    schema: z.object({
+        toolName: z
+            .enum(AI_TOOL_NAMES)
+            .optional()
+            .describe("Optional name of the specific AI tool to document. " +
+            "One of: get_ai_tool_documentation, check_ai_health, " +
+            "ask_ai_about_documents, create_summary_document."),
+    }),
+    run: async (args, _executor) => {
+        const { toolName } = args;
+        if (toolName) {
+            const doc = AI_TOOL_DOCS[toolName];
+            if (!doc) {
+                return { error: `No documentation found for tool: ${toolName}` };
+            }
+            return doc;
+        }
+        // Return all tool docs as an array
+        return AI_TOOL_NAMES.map((name) => AI_TOOL_DOCS[name]);
+    },
+});
+//# sourceMappingURL=get-ai-tool-documentation.js.map

package/dist/tools/ai/get-ai-tool-documentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-ai-tool-documentation.js","sourceRoot":"","sources":["../../../src/tools/ai/get-ai-tool-documentation.ts"],"names":[],"mappings":"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"}

package/dist/tools/application/is-running.d.ts

@@ -0,0 +1,7 @@
+/**
+ * is-running.ts — Check whether the DEVONthink application is currently running.
+ *
+ * Uses System Events to query the process list, which avoids launching DEVONthink
+ * as a side-effect. Checks for both "DEVONthink 3" (v3.x) and "DEVONthink" (v4.x).
+ */
+export declare const isRunningTool: import("../../jxa/types.js").McpTool;

package/dist/tools/application/is-running.js

@@ -0,0 +1,24 @@
+/**
+ * is-running.ts — Check whether the DEVONthink application is currently running.
+ *
+ * Uses System Events to query the process list, which avoids launching DEVONthink
+ * as a side-effect. Checks for both "DEVONthink 3" (v3.x) and "DEVONthink" (v4.x).
+ */
+import { z } from "zod";
+import { defineTool } from "../../jxa/types.js";
+export const isRunningTool = defineTool({
+    name: "is_running",
+    description: "Check if the DEVONthink application is currently running.",
+    schema: z.object({}),
+    run: async (_args, executor) => {
+        const script = `
+var se = Application("System Events");
+var v3 = se.processes.whose({ name: "DEVONthink 3" }).length > 0;
+var v4 = se.processes.whose({ name: "DEVONthink" }).length > 0;
+JSON.stringify({ running: v3 || v4 });
+`.trim();
+        const { stdout } = executor.run(script);
+        return JSON.parse(stdout);
+    },
+});
+//# sourceMappingURL=is-running.js.map

package/dist/tools/application/is-running.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"is-running.js","sourceRoot":"","sources":["../../../src/tools/application/is-running.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAEhD,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;IACtC,IAAI,EAAE,YAAY;IAClB,WAAW,EAAE,2DAA2D;IACxE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACpB,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG;;;;;CAKlB,CAAC,IAAI,EAAE,CAAC;QAEL,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACxC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAyB,CAAC;IACpD,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/custom/column-layout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * column-layout.ts — Read and copy DEVONthink column layouts for smart groups/rules.
+ *
+ * Column layouts are stored in ~/Library/Preferences/com.devon-technologies.think.plist
+ * under three related keys per smart group or rule.
+ */
+import type { McpTool } from "../../jxa/types.js";
+export declare const getColumnLayoutTool: McpTool;
+export declare const copyColumnLayoutTool: McpTool;