aiquila-mcp 0.3.23 → 0.3.25

package/dist/client/passman.js

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+import { getNextcloudConfig } from '../tools/types.js';
+import { logger } from '../logger.js';
+import { ApiError } from './aiquila.js';
+/**
+ * Make an authenticated request to the Nextcloud Passman REST API v2.
+ *
+ * Base path: /index.php/apps/passman/api/v2
+ */
+export async function fetchPassmanAPI(endpoint, options = {}) {
+    const config = getNextcloudConfig();
+    const auth = Buffer.from(`${config.user}:${config.password}`).toString('base64');
+    let url = `${config.url}/index.php/apps/passman/api/v2${endpoint}`;
+    if (options.queryParams) {
+        const params = new URLSearchParams(options.queryParams);
+        url += `?${params.toString()}`;
+    }
+    const headers = {
+        Authorization: `Basic ${auth}`,
+        'OCS-APIRequest': 'true',
+        Accept: 'application/json',
+    };
+    let body;
+    if (options.body !== undefined) {
+        body = JSON.stringify(options.body);
+        headers['Content-Type'] = 'application/json';
+    }
+    const method = options.method ?? 'GET';
+    const t0 = Date.now();
+    const response = await fetch(url, { method, headers, body });
+    logger.trace({ method, url, status: response.status, ms: Date.now() - t0 }, '[passman] HTTP');
+    if (!response.ok) {
+        const text = await response.text();
+        throw new ApiError(response.status, response.statusText, text);
+    }
+    if (response.status === 200 &&
+        response.headers.get('content-type')?.includes('application/json')) {
+        return (await response.json());
+    }
+    return undefined;
+}

package/dist/tool-registry.js

@@ -43,6 +43,9 @@ import { projectsTools } from './tools/apps/projects.js';
 import { pollsTools } from './tools/apps/polls.js';
 import { formsTools } from './tools/apps/forms.js';
 import { textTools } from './tools/apps/text.js';
+import { recommendationsTools } from './tools/apps/recommendations.js';
+import { socialSharingTools } from './tools/apps/social-sharing.js';
+import { passmanTools } from './tools/apps/passman.js';
 /**
  * Single source of truth for tool-to-Nextcloud-app mapping.
  *
@@ -77,6 +80,7 @@ export const TOOL_REGISTRY = [
     { category: 'news', appIds: ['news'], tools: newsTools },
     { category: 'mail', appIds: ['mail'], tools: mailTools },
     { category: 'deck', appIds: ['deck'], tools: deckTools },
+    { category: 'passman', appIds: ['passman'], tools: passmanTools },
     { category: 'cookbook', appIds: ['cookbook'], tools: cookbookTools },
     { category: 'maps', appIds: ['maps'], tools: mapsTools },
     { category: 'photos', appIds: ['photos'], tools: photosTools },
@@ -98,6 +102,20 @@ export const TOOL_REGISTRY = [
         appIds: ['terms_of_service'],
         tools: termsOfServiceTools,
     },
+    { category: 'recommendations', appIds: ['recommendations'], tools: recommendationsTools },
+    {
+        category: 'social_sharing',
+        appIds: [
+            'socialsharing_email',
+            'socialsharing_twitter',
+            'socialsharing_facebook',
+            'socialsharing_telegram',
+            'socialsharing_whatsapp',
+            'socialsharing_bluesky',
+            'socialsharing_diaspora',
+        ],
+        tools: socialSharingTools,
+    },
 ];
 const ALL_CATEGORIES = new Set(TOOL_REGISTRY.map((e) => e.category));
 /**

package/dist/tools/apps/passman.js

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: MIT
+import { z } from 'zod';
+import { fetchPassmanAPI, } from '../../client/passman.js';
+import { handleAppError } from '../error-utils.js';
+/**
+ * Nextcloud Passman App Tools (password manager)
+ * Uses the Passman REST API v2 (/index.php/apps/passman/api/v2).
+ *
+ * IMPORTANT: Passman is zero-knowledge / end-to-end encrypted. Credential
+ * secrets (password, username, url, email, description, custom fields, OTP,
+ * tags, files) are encrypted client-side (SJCL AES-256) with a vault password
+ * that never reaches the server. This integration therefore exposes vault and
+ * credential *metadata only* (notably the plaintext `label`) and cannot decrypt
+ * or return any secret value.
+ */
+const passmanStatusMap = {
+    404: 'Not found.',
+    403: 'Permission denied.',
+    400: (e) => `Bad request: ${e.responseBody}`,
+};
+const E2E_NOTE = 'Note: secret values (password, username, url, etc.) are end-to-end encrypted and cannot be retrieved by this server.';
+function formatVault(vault) {
+    const count = vault.credentials?.length ?? undefined;
+    const parts = [`guid: ${vault.guid}`];
+    if (count !== undefined)
+        parts.push(`${count} credentials`);
+    parts.push(`created: ${new Date(vault.created * 1000).toISOString()}`);
+    if (vault.last_access) {
+        parts.push(`last access: ${new Date(vault.last_access * 1000).toISOString()}`);
+    }
+    return `${vault.name} (${parts.join(', ')})`;
+}
+function hasValue(v) {
+    if (v === undefined || v === null || v === '')
+        return false;
+    if (Array.isArray(v))
+        return v.length > 0;
+    return true;
+}
+function formatCredential(cred) {
+    const flags = [];
+    if (hasValue(cred.url))
+        flags.push('has url');
+    if (hasValue(cred.tags))
+        flags.push('tagged');
+    if (cred.hidden)
+        flags.push('hidden');
+    if (cred.compromised)
+        flags.push('compromised');
+    if (cred.expire_time) {
+        flags.push(`expires: ${new Date(cred.expire_time * 1000).toISOString()}`);
+    }
+    const meta = [`guid: ${cred.guid}`, ...flags].join(', ');
+    return `[${cred.credential_id}] ${cred.label} (${meta})`;
+}
+export const listVaultsTool = {
+    name: 'passman_list_vaults',
+    description: `List all Passman password vaults. Returns name, guid, creation/last-access time and credential count. ${E2E_NOTE}`,
+    inputSchema: z.object({}),
+    handler: async () => {
+        try {
+            const vaults = await fetchPassmanAPI('/vaults');
+            if (!vaults || vaults.length === 0) {
+                return { content: [{ type: 'text', text: 'No vaults found.' }] };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Vaults (${vaults.length}):\n\n${vaults.map(formatVault).join('\n')}\n\n${E2E_NOTE}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error listing vaults', passmanStatusMap);
+        }
+    },
+};
+export const listCredentialsTool = {
+    name: 'passman_list_credentials',
+    description: `List credentials (metadata only) in a Passman vault. Returns each credential's label, id, guid and non-secret flags. ${E2E_NOTE}`,
+    inputSchema: z.object({
+        vault_guid: z.string().describe('Vault GUID (from passman_list_vaults)'),
+    }),
+    handler: async (args) => {
+        try {
+            const vault = await fetchPassmanAPI(`/vaults/${encodeURIComponent(args.vault_guid)}`);
+            const creds = vault.credentials ?? [];
+            if (creds.length === 0) {
+                return { content: [{ type: 'text', text: 'No credentials in this vault.' }] };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Credentials in "${vault.name}" (${creds.length}):\n\n${creds
+                            .map(formatCredential)
+                            .join('\n')}\n\n${E2E_NOTE}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error listing credentials', passmanStatusMap);
+        }
+    },
+};
+export const getCredentialInfoTool = {
+    name: 'passman_get_credential_info',
+    description: `Get non-secret metadata for a single Passman credential (label, id, timestamps, flags). ${E2E_NOTE}`,
+    inputSchema: z.object({
+        vault_guid: z.string().describe('Vault GUID (from passman_list_vaults)'),
+        credential_guid: z.string().describe('Credential GUID (from passman_list_credentials)'),
+    }),
+    handler: async (args) => {
+        try {
+            const vault = await fetchPassmanAPI(`/vaults/${encodeURIComponent(args.vault_guid)}`);
+            const cred = (vault.credentials ?? []).find((c) => c.guid === args.credential_guid);
+            if (!cred) {
+                return {
+                    content: [{ type: 'text', text: 'Credential not found in this vault.' }],
+                    isError: true,
+                };
+            }
+            const lines = [
+                `# ${cred.label}`,
+                '',
+                `ID: ${cred.credential_id}`,
+                `GUID: ${cred.guid}`,
+                `Vault: ${vault.name}`,
+                `Created: ${new Date(cred.created * 1000).toISOString()}`,
+                `Changed: ${new Date(cred.changed * 1000).toISOString()}`,
+                `Has URL: ${hasValue(cred.url)}`,
+                `Tagged: ${hasValue(cred.tags)}`,
+                `Hidden: ${Boolean(cred.hidden)}`,
+                `Compromised: ${Boolean(cred.compromised)}`,
+            ];
+            if (cred.expire_time) {
+                lines.push(`Expires: ${new Date(cred.expire_time * 1000).toISOString()}`);
+            }
+            lines.push('', E2E_NOTE);
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error getting credential info', passmanStatusMap);
+        }
+    },
+};
+export const passmanTools = [listVaultsTool, listCredentialsTool, getCredentialInfoTool];

package/dist/tools/apps/recommendations.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: MIT
+import { z } from 'zod';
+import { fetchOCS } from '../../client/ocs.js';
+function formatTime(ts) {
+    if (!ts)
+        return '';
+    return new Date(ts * 1000).toISOString();
+}
+function formatRecommendations(items) {
+    return items
+        .map((f) => {
+        const dir = f.directory && f.directory !== '/' ? f.directory.replace(/\/$/, '') : '';
+        const path = `${dir}/${f.name}`;
+        const time = f.timestamp ? ` (${formatTime(f.timestamp)})` : '';
+        const reason = f.reason ? `\n  reason: ${f.reason}` : '';
+        return `- ${path}${time}${reason}`;
+    })
+        .join('\n');
+}
+// ---------------------------------------------------------------------------
+// list_recommendations
+// ---------------------------------------------------------------------------
+export const listRecommendationsTool = {
+    name: 'list_recommendations',
+    description: 'List files Nextcloud recommends for the configured user (e.g. recently or frequently ' +
+        'accessed, recently shared, or files in active folders), including the reason each file ' +
+        "is recommended. Respects the user's recommendations setting.",
+    inputSchema: z.object({}),
+    handler: async () => {
+        try {
+            const result = await fetchOCS('/ocs/v2.php/apps/recommendations/api/v1/recommendations');
+            const data = result.ocs.data;
+            const items = data.recommendations ?? [];
+            if (!data.enabled && items.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Recommendations are disabled for this user.',
+                        },
+                    ],
+                };
+            }
+            if (items.length === 0) {
+                return {
+                    content: [{ type: 'text', text: 'No recommended files.' }],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Recommended files (${items.length}):\n${formatRecommendations(items)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error listing recommendations: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    },
+};
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+export const recommendationsTools = [listRecommendationsTool];

package/dist/tools/apps/social-sharing.js

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: MIT
+import { z } from 'zod';
+import { fetchOCS } from '../../client/ocs.js';
+import { getNextcloudConfig } from '../types.js';
+import { handleAppError } from '../error-utils.js';
+const SHARE_TYPE_PUBLIC_LINK = 3;
+/** Default share message used by the upstream apps. */
+const DEFAULT_MESSAGE = 'I shared a file with you';
+const NETWORKS = [
+    {
+        key: 'email',
+        appId: 'socialsharing_email',
+        build: (link, msg) => `mailto:?subject=${msg}&body=${encodeURIComponent(link)}`,
+    },
+    {
+        key: 'twitter',
+        appId: 'socialsharing_twitter',
+        build: (link) => `https://twitter.com/intent/tweet?url=${encodeURIComponent(link)}`,
+    },
+    {
+        key: 'facebook',
+        appId: 'socialsharing_facebook',
+        build: (link) => `https://www.facebook.com/sharer/sharer.php?u=${encodeURIComponent(link)}`,
+    },
+    {
+        key: 'telegram',
+        appId: 'socialsharing_telegram',
+        build: (link, msg) => `https://telegram.me/share/url?url=${encodeURIComponent(link)}&text=${msg}`,
+    },
+    {
+        key: 'whatsapp',
+        appId: 'socialsharing_whatsapp',
+        build: (link, msg) => `whatsapp://send?text=${msg}:%0A%0A${encodeURIComponent(link)}`,
+    },
+    {
+        key: 'bluesky',
+        appId: 'socialsharing_bluesky',
+        build: (link, msg) => `https://bsky.app/intent/compose?text=${msg}:%0A%0A${encodeURIComponent(link)}`,
+    },
+    {
+        key: 'diaspora',
+        appId: 'socialsharing_diaspora',
+        build: (link) => `https://share.diasporafoundation.org/?url=${encodeURIComponent(link)}`,
+    },
+];
+/** Fetch the set of enabled Nextcloud app ids. */
+async function getEnabledApps() {
+    const result = await fetchOCS('/ocs/v2.php/cloud/apps', {
+        queryParams: { filter: 'enabled' },
+    });
+    return new Set(result.ocs.data.apps);
+}
+/** Resolve a public-link share by id or path. */
+async function resolvePublicShare(args) {
+    if (args.share_id !== undefined) {
+        const result = await fetchOCS(`/ocs/v2.php/apps/files_sharing/api/v1/shares/${args.share_id}`);
+        // The single-share endpoint returns an array with one entry.
+        const data = result.ocs.data;
+        const share = Array.isArray(data) ? data[0] : data;
+        if (!share)
+            throw new Error(`Share ${args.share_id} not found`);
+        return share;
+    }
+    const result = await fetchOCS('/ocs/v2.php/apps/files_sharing/api/v1/shares', {
+        queryParams: { path: args.path },
+    });
+    const link = result.ocs.data.find((s) => s.share_type === SHARE_TYPE_PUBLIC_LINK && s.token);
+    if (!link) {
+        throw new Error(`No public link share found for path "${args.path}". Create one first.`);
+    }
+    return link;
+}
+export const generateSocialShareLinksTool = {
+    name: 'generate_social_share_links',
+    description: 'Generate social-network share URLs (email, X/Twitter, Facebook, Telegram, WhatsApp, ' +
+        'Bluesky, Diaspora) for an existing Nextcloud public-link share. Only networks whose ' +
+        'socialsharing_<network> app is enabled are returned. Provide either share_id or path.',
+    inputSchema: z.object({
+        share_id: z.number().optional().describe('ID of an existing public-link share'),
+        path: z
+            .string()
+            .optional()
+            .describe('File/folder path; its public-link share is used (must already exist)'),
+        networks: z
+            .array(z.string())
+            .optional()
+            .describe('Optional filter, e.g. ["twitter","email"]. Defaults to all enabled networks.'),
+    }),
+    handler: async (args) => {
+        if (args.share_id === undefined && !args.path) {
+            return {
+                content: [{ type: 'text', text: 'Provide either share_id or path.' }],
+                isError: true,
+            };
+        }
+        try {
+            const share = await resolvePublicShare(args);
+            if (share.share_type !== SHARE_TYPE_PUBLIC_LINK || !share.token) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'The referenced share is not a public link (no shareable token).',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const { url } = getNextcloudConfig();
+            const link = share.url || `${url}/s/${share.token}`;
+            const message = encodeURIComponent(DEFAULT_MESSAGE);
+            const filter = args.networks ? new Set(args.networks.map((n) => n.toLowerCase())) : null;
+            const enabledApps = await getEnabledApps();
+            const lines = NETWORKS.filter((n) => enabledApps.has(n.appId))
+                .filter((n) => !filter || filter.has(n.key))
+                .map((n) => `${n.key}: ${n.build(link, message)}`);
+            if (lines.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'No matching social sharing networks are available. Install/enable a ' +
+                                'socialsharing_<network> app (or adjust the networks filter).',
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Social share links for ${link}:\n${lines.join('\n')}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            return handleAppError(error, 'Error generating social share links');
+        }
+    },
+};
+export const socialSharingTools = [generateSocialShareLinksTool];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiquila-mcp",
-  "version": "0.3.23",
+  "version": "0.3.25",
   "description": "Nextcloud MCP server — files, calendar, contacts, mail, maps, notes, tasks & 120+ more tools",
   "type": "module",
   "main": "dist/index.js",