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

package/build/shared/src/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/build/shared/src/tools/revoke-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 = {
+    api_key_id: 'The numeric ID of the API key to revoke (the `id` field returned by `create_api_key`).',
+};
+const RevokeApiKeySchema = z.object({
+    api_key_id: z.number().int().positive().describe(PARAM_DESCRIPTIONS.api_key_id),
+});
+const TOOL_DESCRIPTION = `Revoke an API key by ID, immediately invalidating it.
+
+**This is a destructive operation.** Any clients still using the key will start receiving 401 Unauthorized. Revocation is idempotent — calling revoke on a non-existent or already-revoked key returns success without error.
+
+By default, the request requires explicit user approval via MCP elicitation before being sent to the admin API.
+
+**Use cases:**
+- Roll a tenant's keys after re-issuing credentials, so the old key stops working.
+- Revoke a leaked or compromised API key.
+- Remove a deprecated key during cleanup.
+
+**Parameters:**
+- \`api_key_id\` (required): Numeric ID of the API key (the \`id\` field returned by \`create_api_key\`).
+
+**Returns:**
+- \`success\`: Boolean indicating whether the request succeeded.
+- \`message\`: Human-readable confirmation message.`;
+export function revokeApiKey(server, clientFactory) {
+    return {
+        name: 'revoke_api_key',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                api_key_id: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.api_key_id,
+                },
+            },
+            required: ['api_key_id'],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = RevokeApiKeySchema.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.api_key_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': 'revoke_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.api_key_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/build/shared/src/tools/save-mcp-implementation.js

@@ -1,4 +1,29 @@
 import { z } from 'zod';
+// Hosts that must never appear as canonical URLs. Source-code hosts belong in
+// `source_code_location`; aggregators are not authoritative. Mirrors the rule
+// in agents/skills/server-discovery/identify-remote-canonical-url/SKILL.md.
+export const BLOCKLISTED_CANONICAL_HOSTS = [
+    'github.com',
+    'gitlab.com',
+    'bitbucket.org',
+    'smithery.ai',
+    'glama.ai',
+];
+export function findBlocklistedCanonicalHost(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+    for (const blocked of BLOCKLISTED_CANONICAL_HOSTS) {
+        if (host === blocked || host.endsWith(`.${blocked}`)) {
+            return host;
+        }
+    }
+    return null;
+}
 // Parameter descriptions - single source of truth
 const PARAM_DESCRIPTIONS = {
     id: 'The ID of the MCP implementation to update. Omit this field to CREATE a new implementation instead of updating an existing one.',
@@ -26,11 +51,12 @@ const PARAM_DESCRIPTIONS = {
     // Remote endpoints
     remote: 'Array of remote endpoint configurations for MCP servers. Providing this replaces ALL existing remotes. Omitting leaves them unchanged. Pass an empty array to delete all. Each remote can have: id (existing remote ID or blank for new), url_direct, url_setup, transport (e.g., "sse"), host_platform (e.g., "smithery"), host_infrastructure (e.g., "cloudflare"), authentication_method (e.g., "open"), cost (e.g., "free"), status (defaults to "live"), display_name, and internal_notes.',
     // Canonical URLs
-    canonical: 'Array of canonical URL configurations. Providing this replaces ALL existing canonical URLs. Omitting leaves them unchanged. Pass an empty array to delete all. Each entry must have: url (the canonical URL), scope (one of "domain", "subdomain", or "url"), and optional note for additional context.',
+    canonical: 'Array of canonical URL configurations. Providing this replaces ALL existing canonical URLs. Omitting leaves them unchanged. Pass an empty array to delete all. Each entry must have: url (the canonical URL), scope (one of "domain", "subdomain", or "url"), and optional note for additional context. The host must NOT be one of: github.com, gitlab.com, bitbucket.org, smithery.ai, glama.ai (or any subdomain of those) — source-code repos belong in `source_code_location`, and aggregator listings are not authoritative. Calls with blocklisted canonical hosts are rejected with `CANONICAL_BLOCKLISTED_HOST`.',
     // Flags
     verified_no_remote_canonicals: 'Mark that this server has been verified to have no remote canonical URLs (true = verified no remote canonicals exist, false = reset/canonicals found)',
     // Other fields
     internal_notes: 'Admin-only notes. Not displayed publicly. Used for tracking submission sources, reviewer comments, etc.',
+    owner_tenant: 'Owner tenant of this server. Pass a tenant slug (e.g. "gram-recommended") or numeric tenant ID to link, or null to clear the link. Omit to leave unchanged. Slugs are preferred for readability; the Rails backend resolves them to a tenant ID. An unknown slug returns a validation error.',
 };
 const SaveMCPImplementationSchema = z.object({
     id: z.number().optional().describe(PARAM_DESCRIPTIONS.id),
@@ -97,6 +123,10 @@ const SaveMCPImplementationSchema = z.object({
         .describe(PARAM_DESCRIPTIONS.verified_no_remote_canonicals),
     // Other fields
     internal_notes: z.string().optional().describe(PARAM_DESCRIPTIONS.internal_notes),
+    owner_tenant: z
+        .union([z.string(), z.number(), z.null()])
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.owner_tenant),
 });
 export function saveMCPImplementation(_server, clientFactory) {
     return {
@@ -314,13 +344,48 @@ Important notes:
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.internal_notes,
                 },
+                // Owner tenant
+                owner_tenant: {
+                    oneOf: [{ type: 'string' }, { type: 'number' }, { type: 'null' }],
+                    description: PARAM_DESCRIPTIONS.owner_tenant,
+                },
             },
         },
         handler: async (args) => {
             const validatedArgs = SaveMCPImplementationSchema.parse(args);
+            if (validatedArgs.canonical) {
+                for (const entry of validatedArgs.canonical) {
+                    const blockedHost = findBlocklistedCanonicalHost(entry.url);
+                    if (blockedHost) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `CANONICAL_BLOCKLISTED_HOST: ${blockedHost} is not a valid canonical URL host. Use the actual project homepage instead.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+            }
             const client = clientFactory();
             try {
-                const { id, type, ...restParams } = validatedArgs;
+                const { id, type, owner_tenant, ...restParams } = validatedArgs;
+                // Translate owner_tenant (string slug | number id | null clear) into the
+                // explicit owner_tenant_slug / owner_tenant_id fields the admin client
+                // forwards to Rails.
+                if (owner_tenant !== undefined) {
+                    if (typeof owner_tenant === 'string') {
+                        restParams.owner_tenant_slug = owner_tenant;
+                    }
+                    else if (typeof owner_tenant === 'number') {
+                        restParams.owner_tenant_id = owner_tenant;
+                    }
+                    else {
+                        restParams.owner_tenant_id = null;
+                    }
+                }
                 // Determine if this is a create or update operation
                 const isCreate = id === undefined;
                 if (isCreate) {
@@ -386,6 +451,15 @@ Important notes:
                             content += `  - ${r.display_name || r.url_direct || `ID ${r.id}`}\n`;
                         });
                     }
+                    const createOwnerSlug = implementation.mcp_server?.owner_tenant_slug;
+                    const createOwnerId = implementation.mcp_server?.owner_tenant_id;
+                    if (createOwnerSlug || createOwnerId) {
+                        content += `**Owner Tenant:** ${createOwnerSlug ?? '(no slug)'}`;
+                        if (createOwnerId) {
+                            content += ` (id: ${createOwnerId})`;
+                        }
+                        content += '\n';
+                    }
                     if (implementation.created_at) {
                         content += `**Created:** ${new Date(implementation.created_at).toLocaleDateString()}\n`;
                     }
@@ -459,6 +533,19 @@ Important notes:
                             content += `  - ${r.display_name || r.url_direct || `ID ${r.id}`}\n`;
                         });
                     }
+                    const updateOwnerSlug = implementation.mcp_server?.owner_tenant_slug;
+                    const updateOwnerId = implementation.mcp_server?.owner_tenant_id;
+                    if (updateOwnerSlug || updateOwnerId) {
+                        content += `**Owner Tenant:** ${updateOwnerSlug ?? '(no slug)'}`;
+                        if (updateOwnerId) {
+                            content += ` (id: ${updateOwnerId})`;
+                        }
+                        content += '\n';
+                    }
+                    else if (implementation.mcp_server?.owner_tenant_id === null &&
+                        implementation.mcp_server?.owner_tenant_slug === null) {
+                        content += `**Owner Tenant:** (none)\n`;
+                    }
                     if (implementation.updated_at) {
                         content += `**Updated:** ${new Date(implementation.updated_at).toLocaleDateString()}\n`;
                     }

package/build/shared/src/tools/update-mcp-server.js

@@ -22,6 +22,7 @@ const PARAM_DESCRIPTIONS = {
     canonical_urls: 'Authoritative URLs for the server. Providing this replaces ALL existing canonical URLs. Omitting leaves them unchanged. Pass an empty array to delete all.',
     remotes: 'Remote endpoints for the server. Providing this replaces ALL existing remotes. Omitting leaves them unchanged. Pass an empty array to delete all.',
     internal_notes: 'Admin-only internal notes',
+    owner_tenant: 'Owner tenant of this server. Pass a tenant slug (e.g. "gram-recommended") or numeric tenant ID to link, or null to clear the link. Omit to leave unchanged. Slugs are preferred for readability; the Rails backend resolves them to a tenant ID. An unknown slug returns a validation error.',
 };
 const CanonicalUrlSchema = z.object({
     url: z.string().describe('The canonical URL'),
@@ -95,6 +96,10 @@ const UpdateMCPServerSchema = z.object({
         .describe(PARAM_DESCRIPTIONS.canonical_urls),
     remotes: z.array(RemoteEndpointSchema).optional().describe(PARAM_DESCRIPTIONS.remotes),
     internal_notes: z.string().optional().describe(PARAM_DESCRIPTIONS.internal_notes),
+    owner_tenant: z
+        .union([z.string(), z.number(), z.null()])
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.owner_tenant),
 });
 export function updateMCPServer(_server, clientFactory) {
     return {
@@ -284,6 +289,10 @@ Create new provider:
                     description: PARAM_DESCRIPTIONS.remotes,
                 },
                 internal_notes: { type: 'string', description: PARAM_DESCRIPTIONS.internal_notes },
+                owner_tenant: {
+                    oneOf: [{ type: 'string' }, { type: 'number' }, { type: 'null' }],
+                    description: PARAM_DESCRIPTIONS.owner_tenant,
+                },
             },
             required: ['implementation_id'],
         },
@@ -335,6 +344,16 @@ Create new provider:
                 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 if (server.owner_tenant_id === null && server.owner_tenant_slug === null) {
+                    content += `**Owner Tenant:** (none)\n`;
+                }
                 if (server.updated_at) {
                     content += `**Updated:** ${server.updated_at}\n`;
                 }

package/build/shared/src/tools.js

@@ -31,6 +31,12 @@ import { getTenants } from './tools/get-tenants.js';
 import { getTenant } from './tools/get-tenant.js';
 import { createTenant } from './tools/create-tenant.js';
 import { createApiKey } from './tools/create-api-key.js';
+import { revokeApiKey } from './tools/revoke-api-key.js';
+import { deleteTenant } from './tools/delete-tenant.js';
+import { deleteApiKey } from './tools/delete-api-key.js';
+import { listTenantServers } from './tools/list-tenant-servers.js';
+import { addServersToTenant } from './tools/add-servers-to-tenant.js';
+import { removeServersFromTenant } from './tools/remove-servers-from-tenant.js';
 // MCP JSON tools
 import { getMcpJsons } from './tools/get-mcp-jsons.js';
 import { getMcpJson } from './tools/get-mcp-json.js';
@@ -178,6 +184,19 @@ const ALL_TOOLS = [
     { factory: getTenant, groups: ['tenants'], isWriteOperation: false },
     { factory: createTenant, groups: ['tenants'], isWriteOperation: true },
     { factory: createApiKey, groups: ['tenants'], isWriteOperation: true },
+    // revoke_api_key lives in the regular `tenants` group (not `tenants_destructive`) so
+    // it's exposed to read-write tenant management workflows like sub-registry credential
+    // re-issuance. The tool gates each call with MCP elicitation; if the connected client
+    // supports neither native elicitation nor an HTTP fallback, the elicitation library
+    // throws at runtime rather than silently destroying the key.
+    { factory: revokeApiKey, groups: ['tenants'], isWriteOperation: true },
+    // Destructive tenant tools — opt-in only, NOT in BASE_TOOL_GROUPS
+    { factory: deleteTenant, groups: ['tenants_destructive'], isWriteOperation: true },
+    { factory: deleteApiKey, groups: ['tenants_destructive'], isWriteOperation: true },
+    // Tenant -> recommended MCP server association tools
+    { factory: listTenantServers, groups: ['tenants'], isWriteOperation: false },
+    { factory: addServersToTenant, groups: ['tenants'], isWriteOperation: true },
+    { factory: removeServersFromTenant, groups: ['tenants'], isWriteOperation: true },
     // MCP JSON tools (CRUD) (also in server_directory)
     {
         factory: getMcpJsons,
@@ -277,6 +296,7 @@ const VALID_TOOL_GROUPS = [
     'official_mirrors_readonly',
     'tenants',
     'tenants_readonly',
+    'tenants_destructive',
     'mcp_jsons',
     'mcp_jsons_readonly',
     'mcp_servers',
@@ -382,8 +402,9 @@ function shouldIncludeTool(toolDef, enabledGroups) {
  * - unofficial_mirrors: Unofficial mirror CRUD tools (read + write)
  * - unofficial_mirrors_readonly: Unofficial mirror tools (read only)
  * - official_mirrors_readonly: Official mirrors REST API tools (read only)
- * - tenants: Tenant management tools including API key provisioning (read + write)
+ * - tenants: Tenant management tools including API key provisioning + revoke_api_key (read + write). revoke_api_key is gated by MCP elicitation user approval before execution.
  * - tenants_readonly: Tenant tools (read only)
+ * - tenants_destructive: Destructive tenant tools (delete_tenant, delete_api_key). NOT enabled by default; operators must opt in via TOOL_GROUPS. Each tool requires MCP elicitation user approval before execution.
  * - mcp_jsons: MCP JSON configuration tools (read + write)
  * - mcp_jsons_readonly: MCP JSON tools (read only)
  * - mcp_servers: Unified MCP server tools with abstracted interface (read + write)

package/node_modules/@pulsemcp/mcp-elicitation/build/config.d.ts

@@ -0,0 +1,15 @@
+import type { ElicitationConfig } from './types.js';
+/**
+ * Reads elicitation configuration from environment variables.
+ *
+ * Environment variables:
+ *   ELICITATION_ENABLED              - "true" (default) or "false"
+ *   ELICITATION_REQUEST_URL          - POST endpoint for HTTP fallback
+ *   ELICITATION_POLL_URL             - GET endpoint for HTTP fallback polling
+ *   ELICITATION_TTL_MS               - Request TTL in milliseconds (default: 300000)
+ *   ELICITATION_POLL_INTERVAL_MS     - Poll interval in milliseconds (default: 5000, min: 1000)
+ *   ELICITATION_SESSION_ID           - Session identifier for HTTP fallback `_meta`
+ *   ELICITATION_PREFER_HTTP_FALLBACK - "true" forces HTTP fallback over native elicitation
+ *                                      when both are available. Default: "false".
+ */
+export declare function readElicitationConfig(env?: Record<string, string | undefined>): ElicitationConfig;

package/node_modules/@pulsemcp/mcp-elicitation/build/config.js

@@ -0,0 +1,41 @@
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_POLL_INTERVAL_MS = 5 * 1000; // 5 seconds
+const MIN_POLL_INTERVAL_MS = 1000; // 1 second minimum to prevent tight loops
+/**
+ * Parses a positive integer from a string, returning the default if invalid.
+ */
+function parsePositiveInt(value, defaultValue) {
+    if (!value)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    return Number.isNaN(parsed) || parsed < 0 ? defaultValue : parsed;
+}
+/**
+ * Reads elicitation configuration from environment variables.
+ *
+ * Environment variables:
+ *   ELICITATION_ENABLED              - "true" (default) or "false"
+ *   ELICITATION_REQUEST_URL          - POST endpoint for HTTP fallback
+ *   ELICITATION_POLL_URL             - GET endpoint for HTTP fallback polling
+ *   ELICITATION_TTL_MS               - Request TTL in milliseconds (default: 300000)
+ *   ELICITATION_POLL_INTERVAL_MS     - Poll interval in milliseconds (default: 5000, min: 1000)
+ *   ELICITATION_SESSION_ID           - Session identifier for HTTP fallback `_meta`
+ *   ELICITATION_PREFER_HTTP_FALLBACK - "true" forces HTTP fallback over native elicitation
+ *                                      when both are available. Default: "false".
+ */
+export function readElicitationConfig(env = process.env) {
+    const enabledRaw = env.ELICITATION_ENABLED;
+    const enabled = enabledRaw === undefined ? true : enabledRaw.toLowerCase() !== 'false';
+    const preferHttpFallbackRaw = env.ELICITATION_PREFER_HTTP_FALLBACK;
+    const preferHttpFallback = preferHttpFallbackRaw !== undefined && preferHttpFallbackRaw.toLowerCase() === 'true';
+    const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, parsePositiveInt(env.ELICITATION_POLL_INTERVAL_MS, DEFAULT_POLL_INTERVAL_MS));
+    return {
+        enabled,
+        requestUrl: env.ELICITATION_REQUEST_URL,
+        pollUrl: env.ELICITATION_POLL_URL,
+        ttlMs: parsePositiveInt(env.ELICITATION_TTL_MS, DEFAULT_TTL_MS),
+        pollIntervalMs,
+        sessionId: env.ELICITATION_SESSION_ID,
+        preferHttpFallback,
+    };
+}

package/node_modules/@pulsemcp/mcp-elicitation/build/elicitation.d.ts

@@ -0,0 +1,24 @@
+import type { ElicitationConfig, ElicitationRequestedSchema, ElicitationResult, RequestConfirmationOptions } from './types.js';
+/**
+ * Requests user confirmation through the best available mechanism.
+ *
+ * Decision tree (default):
+ * 1. If elicitation is disabled (`ELICITATION_ENABLED=false`), returns `accept` immediately.
+ * 2. If the client supports native elicitation, uses `server.elicitInput()`.
+ * 3. If HTTP fallback URLs are configured, posts to the external endpoint and polls.
+ * 4. Otherwise, throws an error indicating no elicitation mechanism is available.
+ *
+ * When `cfg.preferHttpFallback` is true (set via `ELICITATION_PREFER_HTTP_FALLBACK=true`)
+ * AND both fallback URLs are configured, tier 3 runs before tier 2. This is intended for
+ * headless agent runtimes that falsely advertise elicitation capability but cannot actually
+ * surface the prompt to a user.
+ *
+ * @param options - Configuration for the confirmation request.
+ * @param config - Elicitation config (defaults to reading from env vars).
+ * @returns The user's response.
+ */
+export declare function requestConfirmation(options: RequestConfirmationOptions, config?: ElicitationConfig): Promise<ElicitationResult>;
+/**
+ * Creates a simple boolean confirmation schema for common "are you sure?" prompts.
+ */
+export declare function createConfirmationSchema(title?: string, description?: string): ElicitationRequestedSchema;