list_smart_groups

Retrieve DEVONthink smart groups with names, UUIDs, and sync data for querying contents. Smart groups are only accessible through this method, not via standard AppleScript API.

Instructions

List all DEVONthink smart groups by parsing SmartGroups.plist. Returns name, UUID (from sync.UUID), sync date, and UseUUIDKey flag for each smart group. Smart groups are NOT accessible via the standard AppleScript API — this is the only way to enumerate them. Use the returned uuid with the search tool (groupUuid parameter) to query the contents of a smart group.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/tools/custom/list-smart-groups.ts:68-102 (handler)

The actual logic for listing and parsing DEVONthink smart groups from the SmartGroups.plist file.

const listSmartGroups = async (): Promise<SmartGroupsResult> => {
  if (!existsSync(PLIST_PATH)) {
    return {
      success: false,
      error: `SmartGroups.plist not found at: ${PLIST_PATH}. Ensure DEVONthink has been run at least once.`,
    };
  }

  let xml: string;
  try {
    xml = execSync(`plutil -convert xml1 -o - "${PLIST_PATH}"`, {
      encoding: "utf-8",
      timeout: 10000,
    });
  } catch (err) {
    return {
      success: false,
      error: `Failed to parse SmartGroups.plist: ${err instanceof Error ? err.message : String(err)}`,
    };
  }

  let smartGroups: SmartGroupEntry[];
  try {
    smartGroups = parsePlistXmlToSmartGroups(xml);
  } catch (err) {
    return {
      success: false,
      error: `Failed to parse XML output from plutil: ${err instanceof Error ? err.message : String(err)}`,
    };
  }

  smartGroups.sort((a, b) => a.name.localeCompare(b.name));

  return { success: true, smartGroups, totalCount: smartGroups.length };
};

src/tools/custom/list-smart-groups.ts:104-117 (registration)

The MCP tool definition for `list_smart_groups`, associating it with the `listSmartGroups` handler.

export const listSmartGroupsTool: McpTool = {
  name: "list_smart_groups",
  description:
    "List all DEVONthink smart groups by parsing SmartGroups.plist. " +
    "Returns name, UUID (from sync.UUID), sync date, and UseUUIDKey flag for each smart group. " +
    "Smart groups are NOT accessible via the standard AppleScript API — this is the only way to enumerate them. " +
    "Use the returned uuid with the search tool (groupUuid parameter) to query the contents of a smart group.",
  inputSchema: {
    type: "object" as const,
    properties: {},
    additionalProperties: false,
  },
  run: listSmartGroups,
};

Devon