@mindstone-engineering/mcp-server-gamma 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Gamma authentication module.
+ *
+ * Simple API key management — stored via env var (GAMMA_API_KEY)
+ * or configured at runtime via the configure_gamma_api_key tool.
+ *
+ * Auth: x-api-key header on all API requests.
+ */
+/**
+ * Get the current API key.
+ */
+export declare function getApiKey(): string;
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export declare function setApiKey(key: string): void;
+/**
+ * Check if an API key is configured.
+ */
+export declare function hasApiKey(): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,29 @@
+/**
+ * Gamma authentication module.
+ *
+ * Simple API key management — stored via env var (GAMMA_API_KEY)
+ * or configured at runtime via the configure_gamma_api_key tool.
+ *
+ * Auth: x-api-key header on all API requests.
+ */
+/** Runtime API key — starts from env, can be updated via configure tool. */
+let apiKey = process.env.GAMMA_API_KEY ?? '';
+/**
+ * Get the current API key.
+ */
+export function getApiKey() {
+    return apiKey;
+}
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export function setApiKey(key) {
+    apiKey = key;
+}
+/**
+ * Check if an API key is configured.
+ */
+export function hasApiKey() {
+    return apiKey.trim().length > 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,46 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return {
+            success: false,
+            error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.`,
+        };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Gamma API HTTP client.
+ *
+ * Centralises x-api-key header injection, error handling, rate-limit
+ * messaging, and timeout handling for all Gamma API calls.
+ *
+ * Auth: x-api-key: {key}
+ * Base URL: https://public-api.gamma.app/v1.0
+ */
+import { type GenerationRequest, type CreateFromTemplateRequest, type GenerationResponse, type GenerationStatus, type Theme, type Folder, type PaginatedResponse } from './types.js';
+/**
+ * Create a new generation.
+ */
+export declare function createGeneration(apiKey: string, request: GenerationRequest): Promise<GenerationResponse>;
+/**
+ * Create from an existing template.
+ */
+export declare function createFromTemplate(apiKey: string, request: CreateFromTemplateRequest): Promise<GenerationResponse>;
+/**
+ * Get generation status (including export URLs when available).
+ */
+export declare function getGenerationStatus(apiKey: string, generationId: string): Promise<GenerationStatus>;
+/**
+ * List available themes.
+ */
+export declare function listThemes(apiKey: string, options?: {
+    query?: string;
+    limit?: number;
+    after?: string;
+}): Promise<PaginatedResponse<Theme>>;
+/**
+ * List workspace folders.
+ */
+export declare function listFolders(apiKey: string, options?: {
+    query?: string;
+    limit?: number;
+    after?: string;
+}): Promise<PaginatedResponse<Folder>>;
+/**
+ * Download an export file (PDF/PPTX) to the system tmpdir.
+ * Returns the absolute path of the downloaded file.
+ */
+export declare function downloadExportFile(url: string, generationId: string, format: 'pdf' | 'pptx'): Promise<string>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,177 @@
+/**
+ * Gamma API HTTP client.
+ *
+ * Centralises x-api-key header injection, error handling, rate-limit
+ * messaging, and timeout handling for all Gamma API calls.
+ *
+ * Auth: x-api-key: {key}
+ * Base URL: https://public-api.gamma.app/v1.0
+ */
+import { GammaError, REQUEST_TIMEOUT_MS, } from './types.js';
+const GAMMA_API_BASE = 'https://public-api.gamma.app/v1.0';
+/**
+ * Make an authenticated request to the Gamma API.
+ */
+async function gammaFetch(apiKey, endpoint, options = {}) {
+    const url = `${GAMMA_API_BASE}${endpoint}`;
+    console.error(`[Gamma API] ${options.method || 'GET'} ${url}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': apiKey,
+                ...options.headers,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new GammaError('Request to Gamma API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Gamma API is available.');
+        }
+        throw error;
+    }
+    // Handle rate limiting
+    if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        const waitTime = retryAfter ? `${retryAfter} seconds` : 'a moment';
+        throw new GammaError(`Rate limited. Please wait ${waitTime} before retrying.`, 'RATE_LIMITED', `Wait ${waitTime} and try again.`);
+    }
+    // Handle auth errors
+    if (response.status === 401) {
+        throw new GammaError('Authentication failed', 'AUTH_FAILED', 'API key is invalid or revoked. Check your Gamma API key at https://gamma.app/settings/developers.');
+    }
+    if (response.status === 403) {
+        throw new GammaError('Access forbidden', 'AUTH_FAILED', 'Your API key does not have permission for this operation.');
+    }
+    // Handle not found
+    if (response.status === 404) {
+        throw new GammaError('Resource not found', 'NOT_FOUND', 'The requested resource does not exist. Check the ID and try again.');
+    }
+    // Handle other errors
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => '');
+        console.error(`Gamma API error (${response.status}):`, errorText);
+        const statusMessage = response.status === 422
+            ? 'Validation error - check request parameters'
+            : response.status >= 500
+                ? 'Gamma server error - try again later'
+                : 'Request failed';
+        throw new GammaError(`Gamma API error (${response.status}): ${statusMessage}`, 'API_ERROR', 'Check the request parameters and try again.');
+    }
+    return response.json();
+}
+/**
+ * Create a new generation.
+ */
+export async function createGeneration(apiKey, request) {
+    const body = {
+        inputText: request.inputText,
+        textMode: request.textMode || 'generate',
+        format: request.format || 'presentation',
+    };
+    if (request.themeId)
+        body.themeId = request.themeId;
+    if (request.numCards)
+        body.numCards = request.numCards;
+    if (request.cardSplit)
+        body.cardSplit = request.cardSplit;
+    if (request.additionalInstructions)
+        body.additionalInstructions = request.additionalInstructions;
+    if (request.folderIds)
+        body.folderIds = request.folderIds;
+    if (request.exportAs)
+        body.exportAs = request.exportAs;
+    if (request.textOptions)
+        body.textOptions = request.textOptions;
+    if (request.imageOptions)
+        body.imageOptions = request.imageOptions;
+    if (request.cardOptions)
+        body.cardOptions = request.cardOptions;
+    if (request.sharingOptions)
+        body.sharingOptions = request.sharingOptions;
+    return gammaFetch(apiKey, '/generations', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+}
+/**
+ * Create from an existing template.
+ */
+export async function createFromTemplate(apiKey, request) {
+    const body = {
+        gammaId: request.gammaId,
+    };
+    if (request.prompt)
+        body.prompt = request.prompt;
+    if (request.themeId)
+        body.themeId = request.themeId;
+    if (request.folderIds)
+        body.folderIds = request.folderIds;
+    if (request.exportAs)
+        body.exportAs = request.exportAs;
+    if (request.imageOptions)
+        body.imageOptions = request.imageOptions;
+    if (request.sharingOptions)
+        body.sharingOptions = request.sharingOptions;
+    return gammaFetch(apiKey, '/generations/from-template', {
+        method: 'POST',
+        body: JSON.stringify(body),
+    });
+}
+/**
+ * Get generation status (including export URLs when available).
+ */
+export async function getGenerationStatus(apiKey, generationId) {
+    return gammaFetch(apiKey, `/generations/${generationId}`);
+}
+/**
+ * List available themes.
+ */
+export async function listThemes(apiKey, options) {
+    const params = new URLSearchParams();
+    if (options?.query)
+        params.set('query', options.query);
+    if (options?.limit)
+        params.set('limit', String(options.limit));
+    if (options?.after)
+        params.set('after', options.after);
+    const queryString = params.toString();
+    return gammaFetch(apiKey, `/themes${queryString ? `?${queryString}` : ''}`);
+}
+/**
+ * List workspace folders.
+ */
+export async function listFolders(apiKey, options) {
+    const params = new URLSearchParams();
+    if (options?.query)
+        params.set('query', options.query);
+    if (options?.limit)
+        params.set('limit', String(options.limit));
+    if (options?.after)
+        params.set('after', options.after);
+    const queryString = params.toString();
+    return gammaFetch(apiKey, `/folders${queryString ? `?${queryString}` : ''}`);
+}
+/**
+ * Download an export file (PDF/PPTX) to the system tmpdir.
+ * Returns the absolute path of the downloaded file.
+ */
+export async function downloadExportFile(url, generationId, format) {
+    const { writeFileSync } = await import('fs');
+    const { join } = await import('path');
+    const { tmpdir } = await import('os');
+    const safeId = generationId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const fileName = `gamma_export_${safeId}_${Date.now()}.${format}`;
+    const filePath = join(tmpdir(), fileName);
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Download failed: HTTP ${response.status}`);
+    }
+    const buffer = Buffer.from(await response.arrayBuffer());
+    writeFileSync(filePath, buffer);
+    return filePath;
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Gamma MCP Server
+ *
+ * Provides Gamma AI presentation generation via Model Context Protocol.
+ * Supports async generation workflow with export polling for PDF/PPTX.
+ *
+ * Environment variables:
+ * - GAMMA_API_KEY: Gamma API key (from https://gamma.app/settings/developers)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ * - GAMMA_EXPORT_POLL_INTERVAL_MS: Export poll interval in ms (default: 5000)
+ * - GAMMA_EXPORT_POLL_MAX_ATTEMPTS: Max export poll attempts (default: 12)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Gamma MCP Server
+ *
+ * Provides Gamma AI presentation generation via Model Context Protocol.
+ * Supports async generation workflow with export polling for PDF/PPTX.
+ *
+ * Environment variables:
+ * - GAMMA_API_KEY: Gamma API key (from https://gamma.app/settings/developers)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ * - GAMMA_EXPORT_POLL_INTERVAL_MS: Export poll interval in ms (default: 5000)
+ * - GAMMA_EXPORT_POLL_MAX_ATTEMPTS: Max export poll attempts (default: 12)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Gamma MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerGenerationTools, registerListingTools } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'gamma-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerGenerationTools(server);
+    registerListingTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { setApiKey } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { GammaError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_gamma_api_key', {
+        description: 'Configure the Gamma API key for this session. ' +
+            'Only call this if you get an error saying "Gamma API key not configured". ' +
+            'HOW USER GETS THEIR KEY: Go to https://gamma.app/settings/developers → Create API Key → Copy the key.',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('The Gamma API key'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const key = args.api_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/gamma/configure', { apiKey: key });
+                if (result.success) {
+                    setApiKey(key);
+                    const message = result.warning
+                        ? `Gamma API key configured successfully. Note: ${result.warning}`
+                        : 'Gamma API key configured successfully! You can now use gamma_generate to create presentations, documents, and webpages.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new GammaError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof GammaError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new GammaError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge — store in-memory
+        setApiKey(key);
+        return JSON.stringify({
+            ok: true,
+            message: 'Gamma API key configured successfully! You can now use gamma_generate to create presentations, documents, and webpages.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/generation.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerGenerationTools(server: McpServer): void;
+//# sourceMappingURL=generation.d.ts.map

package/dist/tools/generation.js

@@ -0,0 +1,298 @@
+import { z } from 'zod';
+import { getApiKey, hasApiKey } from '../auth.js';
+import { createGeneration, createFromTemplate, getGenerationStatus, downloadExportFile, } from '../client.js';
+import { GammaError, EXPORT_POLL_INTERVAL_MS, EXPORT_POLL_MAX_ATTEMPTS, } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * In-memory map of generation_id → requested export format.
+ * Used to trigger extended polling when checking status.
+ */
+const exportRequests = new Map();
+function requireApiKey() {
+    if (!hasApiKey()) {
+        throw new GammaError('Gamma API key not configured', 'AUTH_REQUIRED', 'Ask the user for their Gamma API key (get it from https://gamma.app/settings/developers), then call configure_gamma_api_key to set it up.');
+    }
+    return getApiKey();
+}
+export function registerGenerationTools(server) {
+    // ── gamma_generate ─────────────────────────────────────────────
+    server.registerTool('gamma_generate', {
+        description: 'Create AI-powered presentations, documents, webpages, or social posts with Gamma. ' +
+            'ASYNC WORKFLOW: 1) Call gamma_generate → returns generation_id. ' +
+            '2) Call gamma_get_status(generation_id) repeatedly every 3-5 seconds. ' +
+            '3) Continue polling until status is "completed" or "failed". ' +
+            'THEMES: First call gamma_list_themes, then pass theme_id. ' +
+            'EXPORT: Set export_as to "pdf" or "pptx" for auto-export on completion.',
+        inputSchema: z.object({
+            input_text: z.string().min(1).describe('The text content to generate from'),
+            format: z
+                .enum(['presentation', 'document', 'webpage', 'social'])
+                .optional()
+                .describe('Content type (default: presentation)'),
+            text_mode: z
+                .enum(['generate', 'condense', 'preserve'])
+                .optional()
+                .describe('generate: expand, condense: summarize, preserve: keep exact text'),
+            theme_id: z.string().optional().describe('Theme ID from gamma_list_themes'),
+            num_cards: z.number().optional().describe('Number of slides/cards (1-75)'),
+            card_split: z
+                .enum(['auto', 'inputTextBreaks'])
+                .optional()
+                .describe('How to divide cards'),
+            additional_instructions: z
+                .string()
+                .optional()
+                .describe('Extra instructions for generation (max 2000 chars)'),
+            folder_ids: z
+                .array(z.string())
+                .optional()
+                .describe('Folder IDs to save to'),
+            export_as: z
+                .enum(['pdf', 'pptx'])
+                .optional()
+                .describe('Auto-export format when generation completes'),
+            text_amount: z
+                .enum(['brief', 'medium', 'detailed', 'extensive'])
+                .optional()
+                .describe('How much text per card'),
+            text_tone: z.string().optional().describe('Tone/voice'),
+            text_audience: z.string().optional().describe('Target audience'),
+            text_language: z.string().optional().describe('Output language code'),
+            image_source: z
+                .enum([
+                'aiGenerated',
+                'pictographic',
+                'unsplash',
+                'giphy',
+                'webAllImages',
+                'webFreeToUse',
+                'webFreeToUseCommercially',
+                'placeholder',
+                'noImages',
+            ])
+                .optional()
+                .describe('Image source'),
+            image_model: z.string().optional().describe('AI image model'),
+            image_style: z.string().optional().describe('Image style'),
+            card_dimensions: z
+                .enum(['fluid', '16x9', '4x3', 'pageless', 'letter', 'a4', '1x1', '4x5', '9x16'])
+                .optional()
+                .describe('Card aspect ratio'),
+            workspace_access: z
+                .enum(['noAccess', 'view', 'comment', 'edit', 'fullAccess'])
+                .optional()
+                .describe('Access level for workspace members'),
+            external_access: z
+                .enum(['noAccess', 'view', 'comment', 'edit'])
+                .optional()
+                .describe('Access level for external viewers'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const apiKey = requireApiKey();
+        // Build text options
+        const textOptions = args.text_amount || args.text_tone || args.text_audience || args.text_language
+            ? {
+                amount: args.text_amount,
+                tone: args.text_tone,
+                audience: args.text_audience,
+                language: args.text_language,
+            }
+            : undefined;
+        // Build image options
+        const imageOptions = args.image_source || args.image_model || args.image_style
+            ? {
+                source: args.image_source,
+                model: args.image_model,
+                style: args.image_style,
+            }
+            : undefined;
+        // Build card options
+        const cardOptions = args.card_dimensions
+            ? { dimensions: args.card_dimensions }
+            : undefined;
+        // Build sharing options
+        const sharingOptions = args.workspace_access || args.external_access
+            ? {
+                workspaceAccess: args.workspace_access,
+                externalAccess: args.external_access,
+            }
+            : undefined;
+        const result = await createGeneration(apiKey, {
+            inputText: args.input_text,
+            format: args.format || 'presentation',
+            textMode: args.text_mode || 'generate',
+            themeId: args.theme_id,
+            numCards: args.num_cards,
+            cardSplit: args.card_split,
+            additionalInstructions: args.additional_instructions,
+            folderIds: args.folder_ids,
+            exportAs: args.export_as,
+            textOptions,
+            imageOptions,
+            cardOptions,
+            sharingOptions,
+        });
+        if (args.export_as) {
+            exportRequests.set(result.generationId, args.export_as);
+        }
+        return JSON.stringify({
+            success: true,
+            generation_id: result.generationId,
+            message: `Generation started. Use gamma_get_status with ID "${result.generationId}" to check progress.`,
+        });
+    }));
+    // ── gamma_create_from_template ──────────────────────────────────
+    server.registerTool('gamma_create_from_template', {
+        description: 'Clone and modify an existing Gamma presentation/document using AI. ' +
+            'Get the gamma_id from the URL (last part after title). ' +
+            'ASYNC: Same workflow as gamma_generate — poll gamma_get_status after calling.',
+        inputSchema: z.object({
+            gamma_id: z.string().min(1).describe('The ID of the existing gamma to use as template'),
+            prompt: z.string().optional().describe('Instructions for how to modify the template'),
+            theme_id: z.string().optional().describe('Theme ID to apply'),
+            folder_ids: z.array(z.string()).optional().describe('Folder IDs to save to'),
+            export_as: z
+                .enum(['pdf', 'pptx'])
+                .optional()
+                .describe('Auto-export format'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const apiKey = requireApiKey();
+        const result = await createFromTemplate(apiKey, {
+            gammaId: args.gamma_id,
+            prompt: args.prompt,
+            themeId: args.theme_id,
+            folderIds: args.folder_ids,
+            exportAs: args.export_as,
+        });
+        if (args.export_as) {
+            exportRequests.set(result.generationId, args.export_as);
+        }
+        return JSON.stringify({
+            success: true,
+            generation_id: result.generationId,
+            message: `Template generation started. Use gamma_get_status with ID "${result.generationId}" to check progress.`,
+        });
+    }));
+    // ── gamma_get_status ───────────────────────────────────────────
+    server.registerTool('gamma_get_status', {
+        description: 'Poll the status of a Gamma generation. REQUIRED after calling gamma_generate or gamma_create_from_template. ' +
+            'When export was requested, this tool automatically waits for the export URL. ' +
+            'Status values: "pending" (call again in 3-5s), "completed" (done), "failed" (check error).',
+        inputSchema: z.object({
+            generation_id: z
+                .string()
+                .min(1)
+                .describe('The generation_id returned by gamma_generate or gamma_create_from_template'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const apiKey = requireApiKey();
+        let status = await getGenerationStatus(apiKey, args.generation_id);
+        const response = {
+            generation_id: status.generationId,
+            status: status.status,
+        };
+        if (status.status === 'failed') {
+            exportRequests.delete(args.generation_id);
+            response.error = status.error;
+            response.message = 'Generation failed. Please try again.';
+        }
+        else if (status.status === 'completed') {
+            const exportFormat = exportRequests.get(args.generation_id);
+            const exportUrlKey = exportFormat === 'pdf' ? 'pdfUrl' : 'pptxUrl';
+            const hasExportUrl = exportFormat ? !!status[exportUrlKey] : false;
+            if (exportFormat && !hasExportUrl) {
+                // Delete Map entry before polling (concurrency guard)
+                exportRequests.delete(args.generation_id);
+                // Extended polling: export URL not yet available
+                for (let i = 1; i <= EXPORT_POLL_MAX_ATTEMPTS; i++) {
+                    console.error(`[gamma] Waiting for export URL (attempt ${i}/${EXPORT_POLL_MAX_ATTEMPTS})...`);
+                    await sleep(EXPORT_POLL_INTERVAL_MS);
+                    try {
+                        status = await getGenerationStatus(apiKey, args.generation_id);
+                    }
+                    catch (error) {
+                        const errMsg = error instanceof Error ? error.message : String(error);
+                        console.error(`[gamma] Polling error on attempt ${i}/${EXPORT_POLL_MAX_ATTEMPTS}: ${errMsg}`);
+                        continue;
+                    }
+                    if (status.status === 'failed') {
+                        response.status = 'failed';
+                        response.error = status.error;
+                        response.message = 'Generation failed. Please try again.';
+                        return JSON.stringify(response, null, 2);
+                    }
+                    if (status[exportUrlKey]) {
+                        break;
+                    }
+                }
+                // After polling: check if URL appeared
+                const exportUrl = status[exportUrlKey];
+                if (exportUrl) {
+                    response.gamma_url = status.gammaUrl;
+                    if (status.pdfUrl)
+                        response.pdf_url = status.pdfUrl;
+                    if (status.pptxUrl)
+                        response.pptx_url = status.pptxUrl;
+                    if (status.credits)
+                        response.credits = status.credits;
+                    try {
+                        const filePath = await downloadExportFile(exportUrl, args.generation_id, exportFormat);
+                        response.file_path = filePath;
+                        response.message = `Export file downloaded to ${filePath}. Use this local path — the URL will expire shortly.`;
+                    }
+                    catch (dlError) {
+                        const dlMsg = dlError instanceof Error ? dlError.message : String(dlError);
+                        console.error(`[gamma] Export download failed: ${dlMsg}`);
+                        response.message = `Export URL is available but download failed: ${dlMsg}. The URL expires soon — download it immediately if needed.`;
+                    }
+                }
+                else {
+                    // Timeout — URL never appeared
+                    response.gamma_url = status.gammaUrl;
+                    if (status.credits)
+                        response.credits = status.credits;
+                    response.message = `Export file (${exportFormat}) was requested but the URL was not available after polling. The presentation was created successfully — you can export manually at: ${status.gammaUrl}`;
+                }
+            }
+            else {
+                // No export requested, or export URL already present
+                if (exportFormat) {
+                    exportRequests.delete(args.generation_id);
+                }
+                response.gamma_url = status.gammaUrl;
+                if (status.pdfUrl)
+                    response.pdf_url = status.pdfUrl;
+                if (status.pptxUrl)
+                    response.pptx_url = status.pptxUrl;
+                if (status.credits)
+                    response.credits = status.credits;
+                // Auto-download if export URL is present
+                if (exportFormat && status[exportUrlKey]) {
+                    try {
+                        const filePath = await downloadExportFile(status[exportUrlKey], args.generation_id, exportFormat);
+                        response.file_path = filePath;
+                        response.message = `Export file downloaded to ${filePath}. Use this local path — the URL will expire shortly.`;
+                    }
+                    catch (dlError) {
+                        const dlMsg = dlError instanceof Error ? dlError.message : String(dlError);
+                        console.error(`[gamma] Export download failed: ${dlMsg}`);
+                        response.message = `Export URL is available but download failed: ${dlMsg}. The URL expires soon — download it immediately if needed.`;
+                    }
+                }
+                else {
+                    response.message = 'Generation complete! Access your content at the URL above.';
+                }
+            }
+        }
+        else {
+            response.message = 'Generation in progress...';
+        }
+        return JSON.stringify(response, null, 2);
+    }));
+}
+//# sourceMappingURL=generation.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerGenerationTools } from './generation.js';
+export { registerListingTools } from './listing.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerGenerationTools } from './generation.js';
+export { registerListingTools } from './listing.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/listing.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerListingTools(server: McpServer): void;
+//# sourceMappingURL=listing.d.ts.map

package/dist/tools/listing.js

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import { getApiKey, hasApiKey } from '../auth.js';
+import { listThemes, listFolders } from '../client.js';
+import { GammaError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+function requireApiKey() {
+    if (!hasApiKey()) {
+        throw new GammaError('Gamma API key not configured', 'AUTH_REQUIRED', 'Ask the user for their Gamma API key (get it from https://gamma.app/settings/developers), then call configure_gamma_api_key to set it up.');
+    }
+    return getApiKey();
+}
+export function registerListingTools(server) {
+    // ── gamma_list_themes ──────────────────────────────────────────
+    server.registerTool('gamma_list_themes', {
+        description: 'List available Gamma themes. Call this FIRST when user wants to apply corporate/custom branding. ' +
+            'type: "custom" = workspace themes (corporate branding), type: "standard" = global themes. ' +
+            'Use the "id" field when calling gamma_generate with theme_id parameter. ' +
+            'Pagination: if has_more is true, pass next_cursor as the "after" parameter.',
+        inputSchema: z.object({
+            query: z.string().optional().describe('Search themes by name'),
+            limit: z.number().optional().describe('Results per page (default 50, max 50)'),
+            after: z.string().optional().describe('Pagination cursor from previous response'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const apiKey = requireApiKey();
+        const result = await listThemes(apiKey, {
+            query: args.query,
+            limit: args.limit,
+            after: args.after,
+        });
+        return JSON.stringify({
+            themes: result.data,
+            has_more: result.hasMore,
+            next_cursor: result.nextCursor,
+        }, null, 2);
+    }));
+    // ── gamma_list_folders ─────────────────────────────────────────
+    server.registerTool('gamma_list_folders', {
+        description: 'List folders in the user\'s Gamma workspace for organizing presentations. ' +
+            'Use folder "id" in gamma_generate\'s folder_ids parameter. ' +
+            'Pagination: if has_more is true, pass next_cursor as the "after" parameter.',
+        inputSchema: z.object({
+            query: z.string().optional().describe('Search folders by name'),
+            limit: z.number().optional().describe('Results per page (default 50, max 50)'),
+            after: z.string().optional().describe('Pagination cursor from previous response'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const apiKey = requireApiKey();
+        const result = await listFolders(apiKey, {
+            query: args.query,
+            limit: args.limit,
+            after: args.after,
+        });
+        return JSON.stringify({
+            folders: result.data,
+            has_more: result.hasMore,
+            next_cursor: result.nextCursor,
+        }, null, 2);
+    }));
+}
+//# sourceMappingURL=listing.js.map

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/** Export polling interval in ms — overridable via GAMMA_EXPORT_POLL_INTERVAL_MS */
+export declare const EXPORT_POLL_INTERVAL_MS: number;
+/** Max export polling attempts — overridable via GAMMA_EXPORT_POLL_MAX_ATTEMPTS */
+export declare const EXPORT_POLL_MAX_ATTEMPTS: number;
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class GammaError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export type GenerationFormat = 'presentation' | 'document' | 'webpage' | 'social';
+export type TextMode = 'generate' | 'condense' | 'preserve';
+export type TextAmount = 'brief' | 'medium' | 'detailed' | 'extensive';
+export type ImageSource = 'aiGenerated' | 'pictographic' | 'unsplash' | 'giphy' | 'webAllImages' | 'webFreeToUse' | 'webFreeToUseCommercially' | 'placeholder' | 'noImages';
+export type CardDimensions = 'fluid' | '16x9' | '4x3' | 'pageless' | 'letter' | 'a4' | '1x1' | '4x5' | '9x16';
+export type CardSplit = 'auto' | 'inputTextBreaks';
+export type AccessLevel = 'noAccess' | 'view' | 'comment' | 'edit' | 'fullAccess';
+export interface HeaderFooterItem {
+    type: 'text' | 'image' | 'cardNumber';
+    value?: string;
+    source?: 'themeLogo' | 'custom';
+    src?: string;
+    size?: 'sm' | 'md' | 'lg' | 'xl';
+}
+export interface HeaderFooterOptions {
+    topLeft?: HeaderFooterItem;
+    topRight?: HeaderFooterItem;
+    topCenter?: HeaderFooterItem;
+    bottomLeft?: HeaderFooterItem;
+    bottomRight?: HeaderFooterItem;
+    bottomCenter?: HeaderFooterItem;
+    hideFromFirstCard?: boolean;
+    hideFromLastCard?: boolean;
+}
+export interface GenerationRequest {
+    inputText: string;
+    format?: GenerationFormat;
+    textMode?: TextMode;
+    themeId?: string;
+    numCards?: number;
+    cardSplit?: CardSplit;
+    additionalInstructions?: string;
+    folderIds?: string[];
+    exportAs?: 'pdf' | 'pptx';
+    textOptions?: {
+        amount?: TextAmount;
+        tone?: string;
+        audience?: string;
+        language?: string;
+    };
+    imageOptions?: {
+        source?: ImageSource;
+        model?: string;
+        style?: string;
+    };
+    cardOptions?: {
+        dimensions?: CardDimensions;
+        headerFooter?: HeaderFooterOptions;
+    };
+    sharingOptions?: {
+        workspaceAccess?: AccessLevel;
+        externalAccess?: Exclude<AccessLevel, 'fullAccess'>;
+        emailOptions?: {
+            recipients?: string[];
+            access?: AccessLevel;
+        };
+    };
+}
+export interface CreateFromTemplateRequest {
+    gammaId: string;
+    prompt?: string;
+    themeId?: string;
+    folderIds?: string[];
+    exportAs?: 'pdf' | 'pptx';
+    imageOptions?: {
+        source?: ImageSource;
+        model?: string;
+        style?: string;
+    };
+    sharingOptions?: {
+        workspaceAccess?: AccessLevel;
+        externalAccess?: Exclude<AccessLevel, 'fullAccess'>;
+        emailOptions?: {
+            recipients?: string[];
+            access?: AccessLevel;
+        };
+    };
+}
+export interface GenerationResponse {
+    generationId: string;
+}
+export interface GenerationStatus {
+    generationId: string;
+    status: 'pending' | 'completed' | 'failed';
+    gammaUrl?: string;
+    pdfUrl?: string;
+    pptxUrl?: string;
+    credits?: {
+        deducted: number;
+        remaining: number;
+    };
+    error?: string;
+}
+export interface Theme {
+    id: string;
+    name: string;
+    type: 'standard' | 'custom';
+    colorKeywords?: string[];
+    toneKeywords?: string[];
+}
+export interface Folder {
+    id: string;
+    name: string;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,16 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+/** Export polling interval in ms — overridable via GAMMA_EXPORT_POLL_INTERVAL_MS */
+export const EXPORT_POLL_INTERVAL_MS = parseInt(process.env.GAMMA_EXPORT_POLL_INTERVAL_MS ?? '5000', 10);
+/** Max export polling attempts — overridable via GAMMA_EXPORT_POLL_MAX_ATTEMPTS */
+export const EXPORT_POLL_MAX_ATTEMPTS = parseInt(process.env.GAMMA_EXPORT_POLL_MAX_ATTEMPTS ?? '12', 10);
+export class GammaError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'GammaError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On GammaError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { GammaError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On GammaError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof GammaError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-gamma",
+  "version": "0.1.0",
+  "description": "Gamma AI presentation generation MCP server for Model Context Protocol hosts",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-gamma": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/gamma"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/gamma",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}