pulsemcp-cms-admin-mcp-server 0.9.17 → 0.9.26

package/shared/tools/delete-api-key.js

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import { requestConfirmation, createConfirmationSchema } from '@pulsemcp/mcp-elicitation';
+import { readCmsAdminElicitationConfig } from '../elicitation-config.js';
+const PARAM_DESCRIPTIONS = {
+    id: 'The numeric ID of the API key to revoke.',
+};
+const DeleteApiKeySchema = z.object({
+    id: z.number().int().positive().describe(PARAM_DESCRIPTIONS.id),
+});
+const TOOL_DESCRIPTION = `Permanently revoke (delete) an API key.
+
+**This is a destructive operation.** Revoking an API key immediately invalidates it; any clients still using the key will start receiving 401 Unauthorized. The deletion is idempotent — calling delete on a non-existent or already-deleted key returns success.
+
+By default, the request requires explicit user approval via MCP elicitation before being sent to the admin API.
+
+**Parameters:**
+- \`id\` (required): Numeric ID of the API key.
+
+**Returns:**
+- \`success\`: Boolean indicating whether the request succeeded.
+- \`message\`: Human-readable confirmation message.
+
+**Use cases:**
+- Revoke a leaked or compromised API key.
+- Roll a tenant's keys after a permission change.
+- Remove a deprecated key during cleanup.`;
+export function deleteApiKey(server, clientFactory) {
+    return {
+        name: 'delete_api_key',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.id,
+                },
+            },
+            required: ['id'],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = DeleteApiKeySchema.parse(args);
+                const elicitConfig = readCmsAdminElicitationConfig();
+                if (elicitConfig.destructiveElicitationEnabled) {
+                    const lines = [
+                        'About to PERMANENTLY REVOKE an API key via the PulseMCP admin API:',
+                        `  API key ID: ${validatedArgs.id}`,
+                        '',
+                        'Any clients still using this key will start receiving 401 Unauthorized.',
+                        'This action cannot be undone.',
+                    ];
+                    const confirmation = await requestConfirmation({
+                        server,
+                        message: lines.join('\n') + '\n',
+                        requestedSchema: createConfirmationSchema('Revoke this API key?', 'Confirm that you want to permanently revoke this API key.'),
+                        meta: {
+                            'com.pulsemcp/tool-name': 'delete_api_key',
+                        },
+                    }, elicitConfig.base);
+                    if (confirmation.action !== 'accept') {
+                        if (confirmation.action === 'expired') {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'API key revocation confirmation expired. Please try again.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'API key revocation was cancelled by the user.',
+                                },
+                            ],
+                        };
+                    }
+                    if (confirmation.content &&
+                        'confirm' in confirmation.content &&
+                        confirmation.content.confirm === false) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'API key revocation was not confirmed.',
+                                },
+                            ],
+                        };
+                    }
+                }
+                const client = clientFactory();
+                const result = await client.deleteApiKey(validatedArgs.id);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${result.success ? 'API key revoked.' : 'API key revocation failed.'} ${result.message}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error revoking API key: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/delete-tenant.d.ts

@@ -0,0 +1,36 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function deleteTenant(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            id_or_slug: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: "The ID (number) or slug (string) of the tenant to delete.";
+            };
+            force: {
+                type: string;
+                description: "When true, deletes the tenant and cascades to dependent records (API keys, enrichments, etc.). When false (default), the deletion will fail with a 422 if dependents exist.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+};
+//# sourceMappingURL=delete-tenant.d.ts.map

package/shared/tools/delete-tenant.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { requestConfirmation, createConfirmationSchema } from '@pulsemcp/mcp-elicitation';
+import { readCmsAdminElicitationConfig } from '../elicitation-config.js';
+const PARAM_DESCRIPTIONS = {
+    id_or_slug: 'The ID (number) or slug (string) of the tenant to delete.',
+    force: 'When true, deletes the tenant and cascades to dependent records (API keys, enrichments, etc.). When false (default), the deletion will fail with a 422 if dependents exist.',
+};
+const DeleteTenantSchema = z.object({
+    id_or_slug: z.union([z.number(), z.string()]).describe(PARAM_DESCRIPTIONS.id_or_slug),
+    force: z.boolean().optional().describe(PARAM_DESCRIPTIONS.force),
+});
+const TOOL_DESCRIPTION = `Permanently delete a tenant from the PulseMCP admin API.
+
+**This is a destructive operation.** Deleting a tenant removes the tenant record and (with \`force: true\`) cascades to dependent records such as API keys and enrichments. By default, the request requires explicit user approval via MCP elicitation before being sent to the admin API.
+
+**Parameters:**
+- \`id_or_slug\` (required): Numeric ID or slug of the tenant.
+- \`force\` (optional, default false): Cascade-delete dependents. Without this, deleting a tenant that owns API keys or other resources returns 422.
+
+**Returns:**
+- \`success\`: Boolean indicating whether the tenant was deleted.
+- \`message\`: Human-readable confirmation message.
+
+**Use cases:**
+- Permanently remove a deprovisioned tenant.
+- Delete a test tenant created during onboarding/QA.
+- Cascading cleanup of a tenant and all of its API keys (\`force: true\`).`;
+export function deleteTenant(server, clientFactory) {
+    return {
+        name: 'delete_tenant',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id_or_slug: {
+                    oneOf: [{ type: 'number' }, { type: 'string' }],
+                    description: PARAM_DESCRIPTIONS.id_or_slug,
+                },
+                force: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.force,
+                },
+            },
+            required: ['id_or_slug'],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = DeleteTenantSchema.parse(args);
+                const elicitConfig = readCmsAdminElicitationConfig();
+                if (elicitConfig.destructiveElicitationEnabled) {
+                    const lines = [
+                        'About to PERMANENTLY DELETE a tenant via the PulseMCP admin API:',
+                        `  Tenant: ${validatedArgs.id_or_slug}`,
+                        `  Cascade dependents (force): ${validatedArgs.force ? 'yes' : 'no'}`,
+                        '',
+                        'This action cannot be undone.',
+                    ];
+                    const confirmation = await requestConfirmation({
+                        server,
+                        message: lines.join('\n') + '\n',
+                        requestedSchema: createConfirmationSchema('Delete this tenant?', 'Confirm that you want to permanently delete this tenant.'),
+                        meta: {
+                            'com.pulsemcp/tool-name': 'delete_tenant',
+                        },
+                    }, elicitConfig.base);
+                    if (confirmation.action !== 'accept') {
+                        if (confirmation.action === 'expired') {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Tenant deletion confirmation expired. Please try again.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Tenant deletion was cancelled by the user.',
+                                },
+                            ],
+                        };
+                    }
+                    // Defense-in-depth: some MCP clients may return action='accept' without the
+                    // user actually checking the confirmation checkbox.
+                    if (confirmation.content &&
+                        'confirm' in confirmation.content &&
+                        confirmation.content.confirm === false) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Tenant deletion was not confirmed.',
+                                },
+                            ],
+                        };
+                    }
+                }
+                const client = clientFactory();
+                const result = await client.deleteTenant({
+                    id_or_slug: validatedArgs.id_or_slug,
+                    force: validatedArgs.force,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `${result.success ? 'Tenant deleted.' : 'Tenant deletion failed.'} ${result.message}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error deleting tenant: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/get-mcp-server.js

@@ -105,6 +105,16 @@ Example response:
                 if (server.verified_no_remote_canonicals !== undefined) {
                     content += `**Verified No Remote Canonicals:** ${server.verified_no_remote_canonicals ? 'Yes' : 'No'}\n`;
                 }
+                if (server.owner_tenant_slug || server.owner_tenant_id) {
+                    content += `**Owner Tenant:** ${server.owner_tenant_slug ?? '(no slug)'}`;
+                    if (server.owner_tenant_id) {
+                        content += ` (id: ${server.owner_tenant_id})`;
+                    }
+                    content += '\n';
+                }
+                else {
+                    content += `**Owner Tenant:** (none)\n`;
+                }
                 if (server.short_description) {
                     content += `\n**Short Description:**\n${server.short_description}\n`;
                 }
@@ -152,10 +162,11 @@ Example response:
                         content += `- **Status:** ${server.source_code.github_status}\n`;
                     }
                 }
-                // Canonical URLs
-                if (server.canonical_urls && server.canonical_urls.length > 0) {
-                    content += `\n## Canonical URLs\n`;
-                    for (const canonical of server.canonical_urls) {
+                // Canonical URLs — always rendered so callers can see the field is empty vs. missing
+                const canonicalUrls = server.canonical_urls ?? [];
+                if (canonicalUrls.length > 0) {
+                    content += `\n## Canonical URLs (${canonicalUrls.length})\n`;
+                    for (const canonical of canonicalUrls) {
                         content += `- **${canonical.scope}:** ${canonical.url}`;
                         if (canonical.note) {
                             content += ` (${canonical.note})`;
@@ -163,10 +174,14 @@ Example response:
                         content += '\n';
                     }
                 }
-                // Remote endpoints
-                if (server.remotes && server.remotes.length > 0) {
-                    content += `\n## Remote Endpoints (${server.remotes.length})\n`;
-                    for (const [idx, remote] of server.remotes.entries()) {
+                else {
+                    content += `\n## Canonical URLs\n(none)\n`;
+                }
+                // Remote endpoints — always rendered so callers can see the field is empty vs. missing
+                const remotes = server.remotes ?? [];
+                if (remotes.length > 0) {
+                    content += `\n## Remote Endpoints (${remotes.length})\n`;
+                    for (const [idx, remote] of remotes.entries()) {
                         content += `\n### ${idx + 1}. ${remote.display_name || 'Endpoint'}`;
                         if (remote.id) {
                             content += ` (ID: ${remote.id})`;
@@ -198,6 +213,9 @@ Example response:
                         }
                     }
                 }
+                else {
+                    content += `\n## Remote Endpoints\n(none)\n`;
+                }
                 // Tags
                 if (server.tags && server.tags.length > 0) {
                     content += `\n## Tags\n`;

package/shared/tools/list-mcp-servers.js

@@ -123,6 +123,9 @@ Use cases:
                     if (server.remotes && server.remotes.length > 0) {
                         content += `   Remote endpoints: ${server.remotes.length}\n`;
                     }
+                    if (server.owner_tenant_slug || server.owner_tenant_id) {
+                        content += `   Owner Tenant: ${server.owner_tenant_slug ?? `id ${server.owner_tenant_id}`}\n`;
+                    }
                     if (server.downloads_estimate_total) {
                         content += `   Downloads (total): ${server.downloads_estimate_total.toLocaleString()}\n`;
                     }

package/shared/tools/list-tenant-servers.d.ts

@@ -0,0 +1,45 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function listTenantServers(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            tenant: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: "Tenant ID (number) or slug (string)";
+            };
+            status: {
+                type: string;
+                enum: string[];
+                description: "Association status filter: \"active\" (default), \"deleted\" (soft-deleted only), or \"all\"";
+            };
+            limit: {
+                type: string;
+                description: "Results per page, range 1-100 (default 30)";
+            };
+            offset: {
+                type: string;
+                description: "Pagination offset (default 0)";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=list-tenant-servers.d.ts.map

package/shared/tools/list-tenant-servers.js

@@ -0,0 +1,89 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    tenant: 'Tenant ID (number) or slug (string)',
+    status: 'Association status filter: "active" (default), "deleted" (soft-deleted only), or "all"',
+    limit: 'Results per page, range 1-100 (default 30)',
+    offset: 'Pagination offset (default 0)',
+};
+const ListTenantServersSchema = z.object({
+    tenant: z.union([z.number(), z.string()]).describe(PARAM_DESCRIPTIONS.tenant),
+    status: z.enum(['active', 'deleted', 'all']).optional().describe(PARAM_DESCRIPTIONS.status),
+    limit: z.number().int().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.limit),
+    offset: z.number().int().min(0).optional().describe(PARAM_DESCRIPTIONS.offset),
+});
+export function listTenantServers(_server, clientFactory) {
+    return {
+        name: 'list_tenant_servers',
+        description: `List a tenant's recommended MCP server associations (TenantsMcpServer rows).
+
+Use this to inspect which public MCP servers are currently part of a tenant's recommendation list, before/after calling add_servers_to_tenant or remove_servers_from_tenant.
+
+Each association row includes:
+- id: TenantsMcpServer association ID (use this for restore_association_ids in add_servers_to_tenant)
+- mcp_server_id / mcp_server_slug: the underlying public MCP server
+- status: "active" or "deleted" (soft-deleted)
+- server_json_selection: which server.json variant the tenant pins (always "unofficial" for entries created via these tools)
+- touched / first_touched_at: whether the tenant's customization touched this association
+
+Use cases:
+- Audit a tenant's recommendation list
+- Find soft-deleted associations to restore
+- Verify the result of a recent add/remove call`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tenant: {
+                    oneOf: [{ type: 'number' }, { type: 'string' }],
+                    description: PARAM_DESCRIPTIONS.tenant,
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'deleted', 'all'],
+                    description: PARAM_DESCRIPTIONS.status,
+                },
+                limit: { type: 'number', description: PARAM_DESCRIPTIONS.limit },
+                offset: { type: 'number', description: PARAM_DESCRIPTIONS.offset },
+            },
+            required: ['tenant'],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = ListTenantServersSchema.parse(args);
+                const client = clientFactory();
+                const response = await client.listTenantServers(validatedArgs.tenant, {
+                    status: validatedArgs.status,
+                    limit: validatedArgs.limit,
+                    offset: validatedArgs.offset,
+                });
+                const { data, pagination } = response;
+                const statusLabel = validatedArgs.status || 'active';
+                let content = `**Tenant Server Associations** (status=${statusLabel})\n\n`;
+                content += `Showing ${data.length} of ${pagination.total_count} associations (page ${pagination.current_page} of ${pagination.total_pages}).\n\n`;
+                if (data.length === 0) {
+                    content += `_No associations matching this filter._\n`;
+                }
+                else {
+                    for (const row of data) {
+                        content += `- **${row.mcp_server_slug}** (server_id=${row.mcp_server_id}, association_id=${row.id})\n`;
+                        content += `  status=${row.status}, server_json_selection=${row.server_json_selection}, touched=${row.touched}\n`;
+                        if (row.first_touched_at) {
+                            content += `  first_touched_at=${row.first_touched_at}\n`;
+                        }
+                    }
+                }
+                return { content: [{ type: 'text', text: content }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error listing tenant servers: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/remove-servers-from-tenant.d.ts

@@ -0,0 +1,42 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function removeServersFromTenant(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            tenant: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: "Tenant ID (number) or slug (string) to remove servers from.";
+            };
+            mcp_servers: {
+                type: string;
+                items: {
+                    oneOf: {
+                        type: string;
+                    }[];
+                };
+                description: "Array of MCP server IDs (numbers) or slugs (strings) to remove from the tenant's recommendation list. Touched associations are soft-deleted (preserving the customization history); untouched associations are hard-deleted.";
+                minItems: number;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=remove-servers-from-tenant.d.ts.map

package/shared/tools/remove-servers-from-tenant.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    tenant: 'Tenant ID (number) or slug (string) to remove servers from.',
+    mcp_servers: "Array of MCP server IDs (numbers) or slugs (strings) to remove from the tenant's recommendation list. Touched associations are soft-deleted (preserving the customization history); untouched associations are hard-deleted.",
+};
+const RemoveServersFromTenantSchema = z.object({
+    tenant: z.union([z.number(), z.string()]).describe(PARAM_DESCRIPTIONS.tenant),
+    mcp_servers: z
+        .array(z.union([z.number(), z.string()]))
+        .min(1)
+        .describe(PARAM_DESCRIPTIONS.mcp_servers),
+});
+export function removeServersFromTenant(_server, clientFactory) {
+    return {
+        name: 'remove_servers_from_tenant',
+        description: `Remove MCP servers from a tenant's recommendation list.
+
+This is a convenience inverse of add_servers_to_tenant — it accepts only the tenant and a list of servers to remove. For combined add/remove/restore in a single transactional call, use add_servers_to_tenant.
+
+This tool only changes the tenant's recommendation list (TenantsMcpServer rows). The underlying MCP server's public listing is NOT affected.
+
+Outcome behavior:
+- Untouched associations: hard-deleted (row removed entirely; outcome "hard_deleted")
+- Touched associations: soft-deleted (status set to "deleted", row preserved; outcome "soft_deleted")
+
+The response includes:
+- removed: servers detached, with outcome
+- skipped/unresolved_identifiers: as for add_servers_to_tenant
+
+Use cases:
+- Curate a tenant's recommendation list by trimming servers
+- Cleanly remove servers from a tenant without affecting public listings`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                tenant: {
+                    oneOf: [{ type: 'number' }, { type: 'string' }],
+                    description: PARAM_DESCRIPTIONS.tenant,
+                },
+                mcp_servers: {
+                    type: 'array',
+                    items: { oneOf: [{ type: 'number' }, { type: 'string' }] },
+                    description: PARAM_DESCRIPTIONS.mcp_servers,
+                    minItems: 1,
+                },
+            },
+            required: ['tenant', 'mcp_servers'],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = RemoveServersFromTenantSchema.parse(args);
+                const client = clientFactory();
+                const result = await client.bulkUpdateTenantServers(validatedArgs.tenant, {
+                    remove_server_identifiers: validatedArgs.mcp_servers,
+                });
+                let content = `**Tenant servers updated** (tenant=${result.tenant.slug}, id=${result.tenant.id})\n\n`;
+                content += `- Removed: ${result.removed.length}\n`;
+                content += `- Skipped: ${result.skipped.length}\n`;
+                content += `- Unresolved identifiers: ${result.unresolved_identifiers.length}\n`;
+                if (result.removed.length > 0) {
+                    content += `\n**Removed:**\n`;
+                    for (const item of result.removed) {
+                        const assocPart = item.association_id != null ? `, association_id=${item.association_id}` : '';
+                        content += `- ${item.mcp_server_slug} (server_id=${item.mcp_server_id}${assocPart}, outcome=${item.outcome})\n`;
+                    }
+                }
+                if (result.skipped.length > 0) {
+                    content += `\n**Skipped:**\n`;
+                    for (const item of result.skipped) {
+                        const label = item.mcp_server_slug || item.mcp_server_id || item.association_id;
+                        content += `- ${label} — reason: ${item.reason}\n`;
+                    }
+                }
+                if (result.unresolved_identifiers.length > 0) {
+                    content += `\n**Unresolved identifiers:** ${result.unresolved_identifiers.join(', ')}\n`;
+                }
+                return { content: [{ type: 'text', text: content }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error removing tenant servers: ${error instanceof Error ? error.message : String(error)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/revoke-api-key.d.ts

@@ -0,0 +1,30 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ClientFactory } from '../server.js';
+export declare function revokeApiKey(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            api_key_id: {
+                type: string;
+                description: "The numeric ID of the API key to revoke (the `id` field returned by `create_api_key`).";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+};
+//# sourceMappingURL=revoke-api-key.d.ts.map