claude-session-share 1.0.0

package/dist/gist/client.js

@@ -0,0 +1,199 @@
+/**
+ * GitHub Gist client for creating and managing secret gists
+ *
+ * Uses Octokit v5 with automatic rate limiting and retry handling.
+ * Requires GITHUB_TOKEN environment variable for authentication.
+ */
+import { Octokit } from 'octokit';
+/**
+ * Error thrown when GITHUB_TOKEN is missing or invalid
+ */
+export class GistAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GistAuthError';
+    }
+}
+/**
+ * Error thrown when Gist API operations fail
+ */
+export class GistApiError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'GistApiError';
+    }
+}
+/**
+ * Authenticated GitHub Gist client
+ *
+ * Handles authentication, rate limiting, and error handling for GitHub Gist operations.
+ */
+export class GistClient {
+    octokit;
+    constructor() {
+        const token = process.env.GITHUB_TOKEN;
+        if (!token) {
+            throw new GistAuthError('GITHUB_TOKEN environment variable is required. ' +
+                'Create a personal access token at https://github.com/settings/tokens with "gist" scope.');
+        }
+        // Initialize Octokit with authentication and throttling
+        this.octokit = new Octokit({
+            auth: token,
+            throttle: {
+                onRateLimit: (retryAfter, options, octokit, retryCount) => {
+                    // Retry up to 3 times on primary rate limits
+                    console.warn(`Rate limit hit for ${options.method} ${options.url}. ` +
+                        `Retrying after ${retryAfter} seconds (attempt ${retryCount + 1}/3)`);
+                    return retryCount < 3;
+                },
+                onSecondaryRateLimit: (retryAfter, options, octokit) => {
+                    // Always retry secondary rate limits (abuse detection)
+                    console.warn(`Secondary rate limit hit for ${options.method} ${options.url}. ` +
+                        `Retrying after ${retryAfter} seconds`);
+                    return true;
+                },
+            },
+        });
+    }
+    /**
+     * Get the authenticated Octokit instance
+     * @internal Used for testing
+     */
+    getOctokit() {
+        return this.octokit;
+    }
+    /**
+     * Extract gist ID from a GitHub gist URL or return the ID if already in ID format
+     *
+     * @param gistIdOrUrl - Either a full gist URL (https://gist.github.com/username/abc123) or just the gist ID
+     * @returns The extracted gist ID
+     *
+     * @example
+     * extractGistId('https://gist.github.com/user/abc123def456') // Returns 'abc123def456'
+     * extractGistId('abc123def456') // Returns 'abc123def456'
+     */
+    extractGistId(gistIdOrUrl) {
+        // Remove trailing slash if present
+        const normalized = gistIdOrUrl.replace(/\/$/, '');
+        // If it's already just an ID (no slashes), return it
+        if (!normalized.includes('/')) {
+            return normalized;
+        }
+        // Extract ID from URL format: https://gist.github.com/username/abc123def456
+        // The ID is the last segment after the username
+        const segments = normalized.split('/');
+        const lastSegment = segments[segments.length - 1];
+        // Return the last segment (which should be the gist ID)
+        return lastSegment;
+    }
+    /**
+     * Fetch a gist by ID or URL
+     *
+     * @param gistIdOrUrl - Either a full gist URL or just the gist ID
+     * @returns Promise resolving to GistResponse with gist content
+     * @throws {GistAuthError} If token is invalid (401)
+     * @throws {GistApiError} If gist not found (404), private/deleted (403), or other errors
+     *
+     * @example
+     * const gist = await client.fetchGist('https://gist.github.com/user/abc123');
+     * const gist = await client.fetchGist('abc123');
+     */
+    async fetchGist(gistIdOrUrl) {
+        const gistId = this.extractGistId(gistIdOrUrl);
+        try {
+            const response = await this.octokit.rest.gists.get({
+                gist_id: gistId,
+            });
+            // Map response to our GistResponse type
+            return {
+                id: response.data.id,
+                url: response.data.url,
+                html_url: response.data.html_url,
+                files: response.data.files,
+                public: response.data.public,
+                created_at: response.data.created_at,
+                updated_at: response.data.updated_at,
+                description: response.data.description || '',
+            };
+        }
+        catch (error) {
+            // Handle authentication errors
+            if (error.status === 401) {
+                throw new GistAuthError('Invalid GITHUB_TOKEN. Please check that your token is valid and has the "gist" scope. ' +
+                    'Create a new token at https://github.com/settings/tokens');
+            }
+            // Handle not found errors
+            if (error.status === 404) {
+                throw new GistApiError(`Gist not found: ${gistId}. The gist may not exist or you may not have access to it.`, 404);
+            }
+            // Handle permission/private gist errors
+            if (error.status === 403) {
+                const message = error.message || 'Forbidden';
+                if (message.toLowerCase().includes('rate limit')) {
+                    throw new GistApiError('GitHub API rate limit exceeded. Please wait and try again later.', 403);
+                }
+                throw new GistApiError(`Access denied to gist ${gistId}. The gist may be private or deleted. Ensure your GITHUB_TOKEN has the "gist" scope.`, 403);
+            }
+            // Handle other errors
+            throw new GistApiError(`Failed to fetch gist: ${error.message || 'Unknown error'}`, error.status);
+        }
+    }
+    /**
+     * Create a secret (unlisted) gist with the provided files
+     *
+     * @param description - Description of the gist
+     * @param files - Object mapping filenames to file content
+     * @returns Promise resolving to GistResponse with gist URL, ID, and files
+     * @throws {GistAuthError} If token is invalid (401)
+     * @throws {GistApiError} If API request fails (403, 422, or other errors)
+     */
+    async createGist(description, files) {
+        try {
+            // Convert files object to Gist API format
+            const gistFiles = {};
+            for (const [filename, content] of Object.entries(files)) {
+                gistFiles[filename] = { content };
+            }
+            // Create secret gist (public: false makes it unlisted)
+            const response = await this.octokit.rest.gists.create({
+                description,
+                public: false,
+                files: gistFiles,
+            });
+            // Map response to our GistResponse type
+            return {
+                id: response.data.id,
+                url: response.data.url,
+                html_url: response.data.html_url,
+                files: response.data.files,
+                public: response.data.public,
+                created_at: response.data.created_at,
+                updated_at: response.data.updated_at,
+                description: response.data.description || '',
+            };
+        }
+        catch (error) {
+            // Handle authentication errors
+            if (error.status === 401) {
+                throw new GistAuthError('Invalid GITHUB_TOKEN. Please check that your token is valid and has the "gist" scope. ' +
+                    'Create a new token at https://github.com/settings/tokens');
+            }
+            // Handle permission/rate limit errors
+            if (error.status === 403) {
+                const message = error.message || 'Forbidden';
+                if (message.toLowerCase().includes('rate limit')) {
+                    throw new GistApiError('GitHub API rate limit exceeded. Please wait and try again later.', 403);
+                }
+                throw new GistApiError('Permission denied. Ensure your GITHUB_TOKEN has the "gist" scope.', 403);
+            }
+            // Handle validation errors
+            if (error.status === 422) {
+                throw new GistApiError(`Invalid gist data: ${error.message || 'Validation failed'}`, 422);
+            }
+            // Handle other errors
+            throw new GistApiError(`Failed to create gist: ${error.message || 'Unknown error'}`, error.status);
+        }
+    }
+}

package/dist/gist/types.js

@@ -0,0 +1,7 @@
+/**
+ * TypeScript types for GitHub Gist operations
+ *
+ * These types represent the structure of Gist API responses
+ * and request payloads for creating and reading gists.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { uploadSession } from "./services/session-uploader.js";
+import { importSession } from "./services/session-importer.js";
+import { homedir } from 'os';
+import { join } from 'path';
+import { readdir, stat } from 'fs/promises';
+/**
+ * MCP Server for Claude Code session sharing
+ *
+ * This server provides tools for exporting and importing Claude Code sessions,
+ * enabling collaboration through shareable links.
+ */
+// Create the MCP server instance
+const server = new Server({
+    name: "claude-session-share",
+    version: "0.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+/**
+ * Find the most recent session file
+ * Searches ~/.claude/projects/ for all session files and returns the most recently modified one
+ */
+async function findMostRecentSession() {
+    const projectsDir = join(homedir(), '.claude', 'projects');
+    try {
+        // Get all subdirectories in ~/.claude/projects/
+        const entries = await readdir(projectsDir, { withFileTypes: true });
+        const dirs = entries.filter(e => e.isDirectory()).map(e => e.name);
+        let mostRecentFile = null;
+        let mostRecentTime = 0;
+        // Search each project directory for session files
+        for (const dir of dirs) {
+            const dirPath = join(projectsDir, dir);
+            try {
+                const files = await readdir(dirPath);
+                for (const file of files) {
+                    if (file.endsWith('.jsonl')) {
+                        const filePath = join(dirPath, file);
+                        const stats = await stat(filePath);
+                        if (stats.mtimeMs > mostRecentTime) {
+                            mostRecentTime = stats.mtimeMs;
+                            mostRecentFile = filePath;
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                // Skip directories we can't read
+                continue;
+            }
+        }
+        return mostRecentFile;
+    }
+    catch (err) {
+        throw new Error(`Failed to find sessions: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * List available tools
+ */
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "share_session",
+                description: "Share a Claude Code session via GitHub Gist. Creates a sanitized, shareable link to the conversation.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        sessionPath: {
+                            type: "string",
+                            description: "Optional path to session file. If not provided, shares the most recent session.",
+                        },
+                    },
+                },
+            },
+            {
+                name: "import_session",
+                description: "Import a shared Claude Code session from GitHub Gist URL or ID. Creates local resumable session in ~/.claude/projects/",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        gistUrl: {
+                            type: "string",
+                            description: "GitHub Gist URL (https://gist.github.com/user/id) or bare gist ID",
+                        },
+                        projectPath: {
+                            type: "string",
+                            description: "Local project directory path where session will be imported (e.g., /Users/name/project)",
+                        },
+                    },
+                    required: ["gistUrl", "projectPath"],
+                },
+            },
+        ],
+    };
+});
+/**
+ * Handle tool execution
+ */
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name === "share_session") {
+        try {
+            const sessionPath = request.params.arguments?.sessionPath;
+            // If no sessionPath provided, find most recent session
+            const pathToShare = sessionPath || await findMostRecentSession();
+            if (!pathToShare) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: No session files found. Please provide a session path or ensure you have Claude Code sessions in ~/.claude/projects/",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Upload session and get gist URL
+            const gistUrl = await uploadSession(pathToShare);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Successfully shared session!\n\nGist URL: ${gistUrl}\n\nYou can share this URL with others to give them access to this conversation.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Failed to share session: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    if (request.params.name === "import_session") {
+        try {
+            const gistUrl = request.params.arguments?.gistUrl;
+            const projectPath = request.params.arguments?.projectPath;
+            // Validate inputs
+            if (!gistUrl || typeof gistUrl !== 'string' || gistUrl.trim() === '') {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: gistUrl is required and must be a non-empty string",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            if (!projectPath || typeof projectPath !== 'string' || projectPath.trim() === '') {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: projectPath is required and must be a non-empty string",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Import session
+            const result = await importSession(gistUrl, projectPath);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Session imported successfully!\n\nSession ID: ${result.sessionId}\nMessages: ${result.messageCount}\nLocation: ${result.sessionPath}\n\nUse 'claude --resume' to see imported session.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Import failed: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
+    throw new Error(`Unknown tool: ${request.params.name}`);
+});
+/**
+ * Start the server with stdio transport
+ * This allows the MCP server to communicate via standard input/output
+ */
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Server is now running and ready to handle MCP protocol messages
+    console.error("Claude Session Share MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error in main():", error);
+    process.exit(1);
+});

package/dist/sanitization/pipeline.js

@@ -0,0 +1,48 @@
+/**
+ * Session sanitization pipeline
+ *
+ * Orchestrates full session sanitization:
+ * - Maps over all messages in session
+ * - Applies appropriate sanitization based on message type
+ * - Preserves message order and structure
+ */
+import { sanitizeAssistantMessage, sanitizeUserMessage, sanitizeFileHistorySnapshot, } from './sanitizer.js';
+/**
+ * Sanitize entire session by processing all messages
+ *
+ * Uses discriminated union type guards to apply correct sanitization
+ * Returns new array (immutable transformation)
+ */
+export function sanitizeSession(messages, basePath) {
+    return messages.map((msg) => {
+        switch (msg.type) {
+            case 'assistant':
+                return sanitizeAssistantMessage(msg, basePath);
+            case 'user':
+                return sanitizeUserMessage(msg, basePath);
+            case 'file-history-snapshot':
+                return sanitizeFileHistorySnapshot(msg, basePath);
+            default:
+                // Exhaustiveness check - TypeScript ensures all cases covered
+                const _exhaustive = msg;
+                return _exhaustive;
+        }
+    });
+}
+/**
+ * Infer base path from session messages
+ *
+ * Extracts the working directory from first user message with cwd
+ * Returns empty string if no cwd found
+ */
+export function inferBasePath(messages) {
+    for (const msg of messages) {
+        if (msg.type === 'user') {
+            const userMsg = msg;
+            if (userMsg.cwd) {
+                return userMsg.cwd;
+            }
+        }
+    }
+    return '';
+}

package/dist/sanitization/redactor.js

@@ -0,0 +1,48 @@
+/**
+ * Secret redaction utilities for tool results
+ *
+ * Detects and redacts common secret patterns:
+ * - API keys, tokens, access keys
+ * - Environment variable values
+ * - GitHub tokens
+ * - AWS credentials
+ * - Long base64/hex strings
+ */
+/**
+ * Pattern-based secret detection and redaction
+ *
+ * Philosophy: Better to redact too much (false positive) than leak secrets (false negative)
+ */
+export function redactSecrets(content) {
+    if (!content) {
+        return content;
+    }
+    let redacted = content;
+    // Pattern 1: API keys in JSON/object notation
+    // Matches: "api_key": "value", "apiKey": "value", "API_KEY": "value"
+    redacted = redacted.replace(/(["']?(?:api[_-]?key|apikey|access[_-]?key|secret[_-]?key|token|access[_-]?token|auth[_-]?token|bearer[_-]?token)["']?\s*[=:]\s*)["']([^"'\s]{8,})["']/gi, '$1"[REDACTED]"');
+    // Pattern 2: Environment variable format (KEY=value)
+    // Matches: API_KEY=abc123, SECRET_TOKEN=xyz789
+    redacted = redacted.replace(/\b([A-Z_]+(?:KEY|TOKEN|SECRET|PASSWORD|AUTH)[A-Z_]*)\s*=\s*([^\s"']{8,})/g, '$1=[REDACTED]');
+    // Pattern 3: GitHub tokens
+    // Matches: ghp_, ghs_, github_pat_
+    redacted = redacted.replace(/\b(ghp_|ghs_|github_pat_)[a-zA-Z0-9]{30,}/g, '[REDACTED]');
+    // Pattern 4: AWS access keys
+    // Matches: AKIA..., aws_secret_access_key with long value
+    redacted = redacted.replace(/\bAKIA[A-Z0-9]{16}\b/g, '[REDACTED]');
+    redacted = redacted.replace(/(aws[_-]?secret[_-]?access[_-]?key\s*[=:]\s*)["']?([^\s"']{20,})["']?/gi, '$1[REDACTED]');
+    // Pattern 5: Generic long strings that look like secrets
+    // Base64-like strings (alphanumeric + / + =, 32+ chars)
+    // Hex strings (32+ hex chars)
+    // Only in value positions (after = or :)
+    redacted = redacted.replace(/([=:]\s*)["']?([A-Za-z0-9+/]{32,}={0,2})["']?/g, (match, prefix, value) => {
+        // Avoid redacting things that look like file paths or normal text
+        if (value.includes('/') && value.split('/').length > 2) {
+            return match; // Likely a file path
+        }
+        return prefix + '[REDACTED]';
+    });
+    // Pattern 6: Private keys (BEGIN PRIVATE KEY)
+    redacted = redacted.replace(/-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g, '[REDACTED PRIVATE KEY]');
+    return redacted;
+}

package/dist/sanitization/sanitizer.js

@@ -0,0 +1,87 @@
+/**
+ * Session sanitization utilities for privacy protection
+ *
+ * Removes sensitive data before sharing:
+ * - Strips thinking blocks from assistant messages
+ * - Sanitizes absolute paths to relative paths
+ * - Immutable transformations (returns new objects)
+ */
+import * as path from 'node:path';
+import { redactSecrets } from './redactor.js';
+/**
+ * Sanitize assistant message by stripping thinking and sanitizing paths in tool results
+ */
+export function sanitizeAssistantMessage(msg, basePath) {
+    return {
+        ...msg,
+        snapshot: {
+            thinking: null, // Strip thinking block
+            messages: msg.snapshot.messages.map((m) => ({
+                ...m,
+                content: redactSecrets(sanitizePathsInContent(m.content, basePath)),
+            })),
+        },
+    };
+}
+/**
+ * Sanitize user message by converting absolute cwd to relative path
+ */
+export function sanitizeUserMessage(msg, basePath) {
+    return {
+        ...msg,
+        cwd: sanitizePath(msg.cwd, basePath),
+    };
+}
+/**
+ * Sanitize file history snapshot by converting absolute paths to relative
+ */
+export function sanitizeFileHistorySnapshot(msg, basePath) {
+    return {
+        ...msg,
+        snapshot: {
+            ...msg.snapshot,
+            files: msg.snapshot.files.map((file) => ({
+                ...file,
+                path: sanitizePath(file.path, basePath),
+            })),
+        },
+    };
+}
+/**
+ * Sanitize a single path: convert absolute to relative if within basePath
+ */
+function sanitizePath(absolutePath, basePath) {
+    if (!basePath || !absolutePath) {
+        return absolutePath;
+    }
+    // Normalize paths for comparison
+    const normalizedBase = path.resolve(basePath);
+    const normalizedPath = path.resolve(absolutePath);
+    // Check if path is within basePath
+    if (normalizedPath.startsWith(normalizedBase)) {
+        const relativePath = path.relative(normalizedBase, normalizedPath);
+        // Avoid returning empty string for basePath itself
+        return relativePath || '.';
+    }
+    // External path - return as-is
+    return absolutePath;
+}
+/**
+ * Sanitize paths found in text content (tool results, etc.)
+ */
+function sanitizePathsInContent(content, basePath) {
+    if (!basePath || !content) {
+        return content;
+    }
+    // Replace absolute paths with relative ones
+    // Match file paths (must be platform-aware)
+    const normalizedBase = path.resolve(basePath);
+    // Create regex that matches the base path
+    // Escape special regex characters in path
+    const escapedBase = normalizedBase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Match absolute paths starting with base (both forward and backslashes)
+    const pathRegex = new RegExp(escapedBase.replace(/\\/g, '[\\\\/]') + '[\\\\/][^\\s"\'<>|]*', 'g');
+    return content.replace(pathRegex, (match) => {
+        return sanitizePath(match, basePath);
+    });
+}