@wonderwhy-er/desktop-commander 0.2.12 → 0.2.14

package/README.md

@@ -22,6 +22,7 @@ Work with code and text, run processes, and automate tasks, going far beyond oth
 ## Table of Contents
 - [Features](#features)
 - [How to install](#how-to-install)
+- [Getting Started](#getting-started)
 - [Usage](#usage)
 - [Handling Long-Running Commands](#handling-long-running-commands)
 - [Work in Progress and TODOs](#roadmap)
@@ -378,6 +379,28 @@ Close and restart Claude Desktop to complete the removal.
 **Need help?**
 - Join our Discord community: https://discord.com/invite/kQ27sNnZr7
 
+## Getting Started
+
+Once Desktop Commander is installed and Claude Desktop is restarted, you're ready to supercharge your Claude experience!
+
+### 🚀 New User Onboarding
+
+Desktop Commander includes intelligent onboarding to help you discover what's possible:
+
+**For New Users:** When you're just getting started (fewer than 10 successful commands), Claude will automatically offer helpful getting-started guidance and practical tutorials after you use Desktop Commander successfully.
+
+**Request Help Anytime:** You can ask for onboarding assistance at any time by simply saying:
+- *"Help me get started with Desktop Commander"*
+- *"Show me Desktop Commander examples"* 
+- *"What can I do with Desktop Commander?"*
+
+Claude will then show you beginner-friendly tutorials and examples, including:
+- 📁 Organizing your Downloads folder automatically
+- 📊 Analyzing CSV/Excel files with Python
+- ⚙️ Setting up GitHub Actions CI/CD
+- 🔍 Exploring and understanding codebases
+- 🤖 Running interactive development environments
+
 ## Usage
 
 The server provides a comprehensive set of tools organized into several categories:

package/dist/data/onboarding-prompts.json

@@ -6,8 +6,9 @@
       "id": "onb_001",
       "title": "Organize my Downloads folder",
       "description": "Clean up and organize your messy Downloads folder into relevant subfolders automatically.",
-      "prompt": "I want you to help me organize my Downloads folder. Let's do this step by step:\n\n**Phase 1: Analysis**\n1. First, analyze what's in my Downloads folder to understand the types of files\n2. Show me what file types and categories I have\n\n**Phase 2: Planning** \n3. Based on what you find, propose a logical folder structure\n4. Ask for my approval of the organization plan before proceeding\n\n**Phase 3: Organization**\n5. After I approve, create the necessary subfolders\n6. Move files into appropriate categories (documents, images, videos, software, etc.)\n7. Provide a summary of what was organized\n\n**Important**: Don't move any files until I approve your proposed organization structure.\n\nStart by exploring my Downloads folder and showing me what you find, then wait for my approval before organizing.",
+      "prompt": "Let's organize your Downloads folder! \n\nFirst, let me check what we're working with. I'll look at your Downloads folder to see how many files are there and what types.\n\nShould I start by analyzing your Downloads folder?",
       "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
       "votes": 0,
       "gaClicks": 0,
       "icon": "FolderOpen",
@@ -16,13 +17,14 @@
     },
     {
       "id": "onb_002",
-      "title": "Get my IP address and system info",
-      "description": "Quickly get your IP address and basic system information.",
-      "prompt": "Please help me get my system information:\n\n1. Get my current IP address (both local and public if possible)\n2. Show basic system information like:\n   - Operating system and version\n   - Available disk space\n   - Memory usage\n   - Current date and time\n   - Network connectivity status\n\nProvide this information in a clear, easy-to-read format.",
+      "title": "Set up GitHub Actions CI/CD",
+      "description": "Set up GitHub Actions for your project to automatically run tests on every push with proper CI/CD workflow.",
+      "prompt": "Let's set up GitHub Actions CI/CD for your project! 🚀\n\n**What's the path to your project folder?**\n\n*Try: `~/work/my-project` (replace with your path) or give me a different path.*\n\nI'll analyze your project type and set up automated testing and deployment in about 15 minutes!",
       "categories": ["onboarding"],
+      "secondaryTag": "Build & Deploy",
       "votes": 0,
       "gaClicks": 0,
-      "icon": "Monitor",
+      "icon": "GitBranch",
       "author": "DC team",
       "verified": true
     },
@@ -30,8 +32,9 @@
       "id": "onb_003",
       "title": "Create organized knowledge/documents folder",
       "description": "Set up a well-structured knowledge base or document organization system with templates and suggested categories.",
-      "prompt": "I want to help you create a well-organized knowledge base and document system. Let me understand your needs first:\n\n**Option 1: Create New Knowledge Base**\n- What type of work or projects do you typically do?\n- What subjects or topics would you like to organize knowledge about?\n- Do you prefer a general-purpose system or something specialized?\n\n**Option 2: Organize Existing Documents**\n- Do you have an existing folder with documents that needs organization?\n- What's the path to the folder you'd like me to analyze?\n\n**My Process:**\n1. **Assessment**: Understand your needs and existing content\n2. **Structure Design**: Propose a folder hierarchy tailored to your work\n3. **Template Creation**: Create useful template files (notes, project plans, etc.)\n4. **Organization**: Set up the complete system with guidelines\n\nWhich option sounds better - creating a new knowledge base from scratch, or organizing existing documents? And what type of work/subjects do you focus on?",
+      "prompt": "Let's create an organized knowledge base! 📚\n\n**Where should I set it up?**\n\n*I suggest: `~/Documents/Knowledge-Base` (replace with your path) or give me a different location.*\n\nI'll create a clean folder structure with templates and organize any existing documents you have!",
       "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
       "votes": 0,
       "gaClicks": 0,
       "icon": "BookOpen",
@@ -42,8 +45,9 @@
       "id": "onb_004",
       "title": "Explain codebase or repository to me",
       "description": "Analyze and explain any codebase - local project or GitHub repository - including architecture, dependencies, and how it works.",
-      "prompt": "I'll help you understand a codebase thoroughly. Let me know what you'd like to analyze:\n\n**Option 1: Local Project**\n- What's the folder path to your local project?\n\n**Option 2: GitHub Repository**\n- What's the GitHub repository URL you'd like me to analyze?\n- If you don't have git/gh installed, I'll help you set them up\n- If needed, I'll help you log in to GitHub\n\n**What I'll do:**\n1. **Setup**: Install git/gh CLI tools if needed and help with GitHub login\n2. **Code Retrieval**: Clone the repo or analyze your local folder\n3. **Initial Analysis**: Examine project structure, files, and technologies\n4. **Architecture Overview**: Explain the overall design and patterns\n5. **Key Components**: Break down main modules and features\n6. **Dependencies**: Document libraries and frameworks used\n7. **Setup Guide**: Provide step-by-step setup and running instructions\n8. **Code Flow**: Explain how the main functionality works\n9. **Summary Document**: Create comprehensive documentation\n\nPlease provide either:\n- Local folder path: `/path/to/your/project`\n- GitHub URL: `https://github.com/user/repo` or `git@github.com:user/repo.git`",
+      "prompt": "I'll analyze and explain any codebase for you! 🔍\n\n**What should I analyze?**\n\n*Local project:* `~/work/my-project` (replace with your path)\n*GitHub repo:* `https://github.com/user/repo`\n\nI'll break down the architecture, dependencies, and how everything works together!",
       "categories": ["onboarding"],
+      "secondaryTag": "Code Analysis",
       "votes": 0,
       "gaClicks": 0,
       "icon": "Code",
@@ -54,8 +58,9 @@
       "id": "onb_005",
       "title": "Clean up unused code in my project",
       "description": "Scan your codebase to find unused imports, dead functions, and redundant code that can be safely removed.",
-      "prompt": "I'll help you clean up unused and dead code in your project. Let's start safely:\n\n**First, I need to know:**\n- What's the folder path to your project?\n- What programming language/framework is it? (JavaScript, Python, Java, etc.)\n\n**My systematic approach:**\n\n**Phase 1: Analysis**\n1. **Project Understanding**: Analyze structure and main technologies\n2. **Dependency Mapping**: Understand how files reference each other\n3. **Code Scanning**: Identify potential unused code:\n   - Unused imports and dependencies\n   - Dead/unreferenced functions and variables\n   - Unreachable code blocks\n   - Unused configuration files\n\n**Phase 2: Safety & Backup**\n4. **Impact Assessment**: Explain what each finding does and removal safety\n5. **Backup Strategy**: Recommend backup before making changes\n6. **Show Before Remove**: Present everything I plan to remove\n\n**Phase 3: Cleanup (Only with your approval)**\n7. **Selective Removal**: Remove only what you approve\n8. **Testing**: Suggest running tests after cleanup\n9. **Summary Report**: Document what was cleaned and space saved\n\n**Safety Promise**: I will NEVER remove code without your explicit approval for each change.\n\nWhat's the path to your project folder?",
+      "prompt": "Let's clean up unused code in your project! 🧹\n\n**What's your project folder path?**\n\n*Try: `~/work/my-project` (replace with your path)*\n\nI'll safely scan for dead code and unused imports, then show you exactly what can be removed before making any changes!",
       "categories": ["onboarding"],
+      "secondaryTag": "Code Analysis",
       "votes": 0,
       "gaClicks": 0,
       "icon": "Trash2",
@@ -65,9 +70,10 @@
     {
       "id": "onb_006",
       "title": "Build shopping list app and deploy online",
-      "description": "Create a complete shopping list web application from scratch, run it locally, and deploy it to GitHub Pages.",
-      "prompt": "Let's build and deploy a complete shopping list web application! I'll guide you step-by-step:\n\n**Step 1: Project Setup**\nFirst, where would you like to work on this project? Please provide a folder path where I should create the shopping list app.\n\n**My Complete Process:**\n\n**Phase 1: Planning & Setup**\n1. Create project folder and basic structure\n2. Plan app features (add/remove items, mark as bought, categories)\n3. Set up HTML, CSS, and JavaScript foundation\n\n**Phase 2: Development**\n4. Build clean, modern user interface\n5. Implement core functionality (CRUD operations)\n6. Add local storage for persistence\n7. Create a simple local development server\n8. Open the app in your browser for testing\n\n**Phase 3: GitHub & Deployment** \n9. Check if you have git/gh CLI installed (install if needed)\n10. Help you log in to GitHub\n11. Create a new GitHub repository\n12. Commit and push your code\n13. Set up GitHub Pages hosting\n14. Deploy your app online with a live URL\n\n**App Features:**\n- Add/remove shopping items\n- Mark items as purchased with checkboxes\n- Organize items by categories\n- Persistent storage (survives browser refresh)\n- Responsive design (works on mobile)\n- Modern, clean interface\n\nReady to start? What folder should I use for your shopping list app project?",
+      "description": "Create a simple shopping list web app from scratch and deploy it online - perfect for learning web development basics.",
+      "prompt": "Let's build a simple shopping list web app and deploy it online! 🛒\n\n**Quick question:** Where should I create the project folder?\n\n*I suggest using `~/Downloads/shopping-app` for quick testing, or give me a different path if you prefer.*\n\nOnce I have the folder, I'll build a working app step-by-step and get it online in about 20 minutes!",
       "categories": ["onboarding"],
+      "secondaryTag": "Build & Deploy",
       "votes": 0,
       "gaClicks": 0,
       "icon": "ShoppingCart",
@@ -78,8 +84,9 @@
       "id": "onb_007",
       "title": "Analyze my data file",
       "description": "Upload or point to any data file (CSV, JSON, Excel, etc.) and get comprehensive analysis including patterns, insights, and summary reports.",
-      "prompt": "I have a data file that I'd like to understand better. Please help me analyze it:\n\n1. **File Examination**: First, let me know the path to your data file or describe what kind of data it contains\n2. **Data Overview**: Analyze the structure, size, and format of the data\n3. **Content Analysis**: Examine what columns/fields exist and their data types\n4. **Pattern Detection**: Look for interesting patterns, trends, or anomalies\n5. **Statistical Summary**: Provide key statistics (counts, averages, distributions, etc.)\n6. **Data Quality**: Identify any missing data, duplicates, or quality issues\n7. **Key Insights**: Highlight the most interesting findings\n8. **Summary Report**: Create a clear, non-technical summary of what the data shows\n\nWhat's the path to your data file, or would you like to tell me what kind of data you're working with first?",
+      "prompt": "I'll help you analyze your data file! \n\nWhat's the path to your data file? (e.g., `/Users/yourname/data.csv`)\n\nOnce you give me the path, I'll start by checking what type of file it is and show you a quick preview, then we can dive deeper step by step.",
       "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
       "votes": 0,
       "gaClicks": 0,
       "icon": "BarChart3",
@@ -90,8 +97,9 @@
       "id": "onb_008",
       "title": "Check system health and resources",
       "description": "Analyze your system's health, resource usage, running processes, and generate a comprehensive system status report.",
-      "prompt": "Let me perform a comprehensive system health check and resource analysis:\n\n**System Resource Analysis:**\n1. **CPU Usage**: Current and recent CPU utilization patterns\n2. **Memory Usage**: RAM usage, available memory, swap usage\n3. **Disk Space**: Storage usage across all drives/partitions\n4. **Network Status**: Network interfaces, connectivity, and usage\n\n**Process Analysis:**\n5. **Running Processes**: Top resource-consuming processes\n6. **System Services**: Critical service status\n7. **Port Usage**: Open ports and listening services\n\n**Health Indicators:**\n8. **System Load**: Overall system performance indicators\n9. **Uptime**: System uptime and stability\n10. **Temperature**: System temperature if available\n11. **Logs**: Recent system errors or warnings\n\n**Deliverable:**\n- Comprehensive system health report\n- Resource usage summary with recommendations\n- Identification of potential issues\n- Performance optimization suggestions\n\nI'll gather all this information using system commands and present it in a clear, actionable format.",
+      "prompt": "Let me check your system health and resources!\n\nI'll start by looking at your CPU, memory, and disk usage, then check for any performance issues.\n\nShould I begin the system analysis?",
       "categories": ["onboarding"],
+      "secondaryTag": "Quick Start",
       "votes": 0,
       "gaClicks": 0,
       "icon": "Activity",
@@ -102,8 +110,9 @@
       "id": "onb_009",
       "title": "Find Patterns and Errors in Log Files",
       "description": "Analyze log files to identify errors, patterns, performance issues, and security concerns with detailed insights and recommendations.",
-      "prompt": "I'll help you analyze log files to find patterns, errors, and insights. Let me know which approach you prefer:\n\n**Option 1: Analyze Specific Log File**\n- Do you have a specific log file you want me to analyze?\n- What's the full path to your log file?\n\n**Option 2: Find Log Files on Your System**\n- I can search your system for common log file locations\n- What type of application/service logs are you interested in? (web server, database, application, system logs, etc.)\n\n**What I'll analyze:**\n\n**Error Detection:**\n1. **Critical Errors**: Fatal errors, exceptions, crashes\n2. **Warning Patterns**: Recurring warnings that might indicate issues\n3. **Error Frequency**: How often specific errors occur\n4. **Error Trends**: Are errors increasing over time?\n\n**Performance Analysis:**\n5. **Response Times**: Slow queries, long-running operations\n6. **Resource Usage**: Memory, CPU, disk I/O patterns\n7. **Traffic Patterns**: Peak usage times, load distribution\n8. **Bottlenecks**: Identify performance constraints\n\n**Security & Anomalies:**\n9. **Failed Login Attempts**: Potential security threats\n10. **Unusual Access Patterns**: Suspicious activity\n11. **IP Analysis**: Frequent visitors, geographic patterns\n12. **Rate Limiting**: Abuse detection\n\n**Deliverables:**\n- **Error Summary Report**: Top errors with occurrence counts\n- **Timeline Analysis**: When issues happen most frequently\n- **Pattern Recognition**: Recurring themes and root causes\n- **Actionable Recommendations**: Specific steps to fix identified issues\n- **Monitoring Suggestions**: What to watch for in the future\n\nWhich option would you prefer? Please provide either:\n- **Specific file**: `/path/to/your/logfile.log`\n- **Search request**: \"Find web server logs\" or \"Look for application logs\"",
+      "prompt": "I'll analyze your log files to find errors and patterns! 🔍\n\n**What log file should I analyze?**\n\n*Try: `/var/log/system.log` (macOS/Linux) or `~/app.log`, or I can search for logs on your system.*\n\nI'll find errors, performance issues, and suspicious patterns with actionable recommendations!",
       "categories": ["onboarding"],
+      "secondaryTag": "Code Analysis",
       "votes": 0,
       "gaClicks": 0,
       "icon": "Search",

package/dist/handlers/search-handlers.js

@@ -24,6 +24,7 @@ export async function handleStartSearch(args) {
             contextLines: parsed.data.contextLines,
             timeout: parsed.data.timeout_ms,
             earlyTermination: parsed.data.earlyTermination,
+            literalSearch: parsed.data.literalSearch,
         });
         const searchTypeText = parsed.data.searchType === 'content' ? 'content search' : 'file search';
         let output = `Started ${searchTypeText} session: ${result.sessionId}\n`;

package/dist/index-oauth.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index-oauth.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+import { FilteredStdioServerTransport } from './custom-stdio.js';
+import { server } from './server.js';
+import { configManager } from './config-manager.js';
+import { runSetup } from './npm-scripts/setup.js';
+import { runUninstall } from './npm-scripts/uninstall.js';
+import { capture } from './utils/capture.js';
+import { logToStderr, logger } from './utils/logger.js';
+import { OAuthHttpServer } from './oauth/server.js';
+async function runServer() {
+    try {
+        // Check if first argument is "setup"
+        if (process.argv[2] === 'setup') {
+            await runSetup();
+            return;
+        }
+        // Check if first argument is "remove"
+        if (process.argv[2] === 'remove') {
+            await runUninstall();
+            return;
+        }
+        // Check for HTTP mode with OAuth
+        const httpMode = process.argv.includes('--http') || process.argv.includes('--oauth');
+        const port = getPortFromArgs() || 8000;
+        if (httpMode) {
+            await runHttpServer(port);
+        }
+        else {
+            await runStdioServer();
+        }
+    }
+    catch (error) {
+        logger.error('Failed to start server:', error);
+        process.exit(1);
+    }
+}
+async function runStdioServer() {
+    logger.info('Loading server.ts');
+    logger.info('Setting up request handlers...');
+    try {
+        logger.info('Loading configuration...');
+        await configManager.loadConfig();
+        logger.info('Configuration loaded successfully');
+        const transport = new FilteredStdioServerTransport();
+        logger.info('Enhanced FilteredStdioServerTransport initialized');
+        logger.info('Connecting server...');
+        await server.connect(transport);
+        logger.info('Server connected successfully');
+    }
+    catch (error) {
+        await capture('error_start_stdio_server', { error });
+        logToStderr('error', `Failed to start stdio server: ${error}`);
+        throw error;
+    }
+}
+async function runHttpServer(port) {
+    logger.info(`Starting HTTP server with OAuth on port ${port}`);
+    try {
+        logger.info('Loading configuration...');
+        await configManager.loadConfig();
+        logger.info('Configuration loaded successfully');
+        // OAuth configuration
+        const baseUrl = `http://localhost:${port}`;
+        const oauthConfig = {
+            enabled: true,
+            clientId: 'desktop-commander-mcp',
+            clientSecret: 'dc-secret-' + Math.random().toString(36).substring(7),
+            redirectUri: `${baseUrl}/callback`,
+            authorizationUrl: `${baseUrl}/authorize`,
+            tokenUrl: `${baseUrl}/token`,
+            scope: 'mcp:access mcp:tools mcp:resources',
+            issuer: baseUrl
+        };
+        // Create MCP handler for HTTP requests
+        const mcpHandler = createMcpHttpHandler();
+        // Create OAuth HTTP server
+        const oauthServer = new OAuthHttpServer(oauthConfig, mcpHandler);
+        oauthServer.listen(port, () => {
+            logger.info(`HTTP server running on port ${port}`);
+            logger.info(`Authorization Server Metadata: ${baseUrl}/.well-known/oauth-authorization-server`);
+            logger.info(`MCP Endpoint: ${baseUrl}/mcp`);
+            logger.info(`SSE Endpoint: ${baseUrl}/sse`);
+            console.log(`\n🚀 DesktopCommanderMCP HTTP Server Started!`);
+            console.log(`📍 Server URL: ${baseUrl}`);
+            console.log(`🔐 OAuth Metadata: ${baseUrl}/.well-known/oauth-authorization-server`);
+            console.log(`🔧 MCP Endpoint: ${baseUrl}/mcp`);
+            console.log(`⚡ SSE Endpoint: ${baseUrl}/sse`);
+            console.log(`\n📝 For Claude Custom Connectors:`);
+            console.log(`   URL: ${baseUrl}/sse`);
+            console.log(`   Authentication: OAuth`);
+        });
+        // Graceful shutdown
+        process.on('SIGINT', () => {
+            logger.info('Received SIGINT, shutting down gracefully...');
+            oauthServer.close(() => {
+                process.exit(0);
+            });
+        });
+    }
+    catch (error) {
+        await capture('error_start_http_server', { error });
+        logToStderr('error', `Failed to start HTTP server: ${error}`);
+        throw error;
+    }
+}
+function createMcpHttpHandler() {
+    return (req, res) => {
+        const url = new URL(req.url, `http://${req.headers.host}`);
+        // Handle SSE endpoint for MCP clients
+        if (url.pathname === '/sse') {
+            handleSSE(req, res);
+            return;
+        }
+        // Handle Streamable HTTP endpoint  
+        if (url.pathname === '/mcp') {
+            handleStreamableHttp(req, res);
+            return;
+        }
+        // Health check
+        if (url.pathname === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok', service: 'DesktopCommanderMCP' }));
+            return;
+        }
+        // 404 for other paths
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+    };
+}
+function handleSSE(req, res) {
+    // Set SSE headers
+    res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Headers': 'Cache-Control'
+    });
+    // SSE implementation would go here
+    // For now, just indicate that SSE is available
+    res.write('event: connected\n');
+    res.write('data: {"type":"connected","message":"DesktopCommanderMCP SSE endpoint"}\n\n');
+    // Keep connection alive
+    const heartbeat = setInterval(() => {
+        res.write('event: heartbeat\n');
+        res.write('data: {"type":"heartbeat","timestamp":' + Date.now() + '}\n\n');
+    }, 30000);
+    req.on('close', () => {
+        clearInterval(heartbeat);
+    });
+}
+function handleStreamableHttp(req, res) {
+    // Handle Streamable HTTP for MCP
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    if (req.method === 'GET') {
+        // Return server info
+        res.end(JSON.stringify({
+            name: 'DesktopCommanderMCP',
+            version: '0.2.13',
+            transport: 'streamable-http',
+            authenticated: !!req.user
+        }));
+        return;
+    }
+    // Handle MCP protocol messages
+    if (req.method === 'POST') {
+        let body = '';
+        req.on('data', chunk => body += chunk.toString());
+        req.on('end', () => {
+            try {
+                const message = JSON.parse(body);
+                // Process MCP message through the server
+                // This would need to be integrated with the existing MCP server
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    id: message.id,
+                    result: { message: 'MCP message received' }
+                }));
+            }
+            catch (error) {
+                res.writeHead(400, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ error: 'Invalid JSON' }));
+            }
+        });
+        return;
+    }
+    res.writeHead(405, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Method not allowed' }));
+}
+function getPortFromArgs() {
+    const portIndex = process.argv.findIndex(arg => arg === '--port');
+    if (portIndex !== -1 && process.argv[portIndex + 1]) {
+        return parseInt(process.argv[portIndex + 1], 10);
+    }
+    return null;
+}
+// Run the server
+runServer().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/oauth/provider.d.ts

@@ -0,0 +1,22 @@
+import type { OAuthConfig, AuthorizationServerMetadata, TokenResponse, AccessToken, AuthorizationRequest, TokenRequest } from './types.js';
+export declare class OAuthProvider {
+    private config;
+    private users;
+    private authCodes;
+    private accessTokens;
+    constructor(config: OAuthConfig);
+    static generatePKCE(): {
+        codeVerifier: string;
+        codeChallenge: string;
+    };
+    getAuthorizationServerMetadata(): AuthorizationServerMetadata;
+    handleAuthorizationRequest(params: AuthorizationRequest): {
+        authUrl: string;
+        authCode?: string;
+        error?: string;
+    };
+    handleTokenRequest(params: TokenRequest): Promise<TokenResponse | {
+        error: string;
+    }>;
+    validateAccessToken(token: string): AccessToken | null;
+}

package/dist/oauth/provider.js

@@ -0,0 +1,124 @@
+import crypto from 'crypto';
+export class OAuthProvider {
+    constructor(config) {
+        this.users = new Map();
+        this.authCodes = new Map();
+        this.accessTokens = new Map();
+        this.config = config;
+        // Add a default user for testing
+        this.users.set('admin', {
+            email: 'admin@localhost',
+            password: 'admin123' // In production, hash this!
+        });
+    }
+    // Generate PKCE code verifier and challenge
+    static generatePKCE() {
+        const codeVerifier = crypto.randomBytes(32).toString('base64url');
+        const codeChallenge = crypto
+            .createHash('sha256')
+            .update(codeVerifier)
+            .digest('base64url');
+        return { codeVerifier, codeChallenge };
+    }
+    // Get Authorization Server Metadata (required by MCP spec)
+    getAuthorizationServerMetadata() {
+        const baseUrl = this.config.issuer;
+        return {
+            issuer: baseUrl,
+            authorization_endpoint: `${baseUrl}/authorize`,
+            token_endpoint: `${baseUrl}/token`,
+            registration_endpoint: `${baseUrl}/register`,
+            revocation_endpoint: `${baseUrl}/revoke`,
+            jwks_uri: `${baseUrl}/.well-known/jwks.json`,
+            response_types_supported: ['code'],
+            grant_types_supported: ['authorization_code', 'refresh_token'],
+            token_endpoint_auth_methods_supported: ['none', 'client_secret_basic'],
+            code_challenge_methods_supported: ['S256'],
+            scopes_supported: ['mcp:access', 'mcp:tools', 'mcp:resources']
+        };
+    }
+    // Handle authorization request
+    handleAuthorizationRequest(params) {
+        if (!params.client_id || !params.redirect_uri || !params.code_challenge) {
+            return { authUrl: '', error: 'Missing required parameters' };
+        }
+        if (params.code_challenge_method !== 'S256') {
+            return { authUrl: '', error: 'Unsupported code_challenge_method' };
+        }
+        // Generate authorization code
+        const authCode = crypto.randomBytes(32).toString('hex');
+        const expiresAt = Date.now() + 10 * 60 * 1000; // 10 minutes
+        // Store authorization code
+        this.authCodes.set(authCode, {
+            userId: 'admin', // For simplicity, auto-approve for admin user
+            clientId: params.client_id,
+            redirectUri: params.redirect_uri,
+            scope: params.scope || 'mcp:access',
+            codeChallenge: params.code_challenge,
+            codeChallengeMethod: params.code_challenge_method,
+            expiresAt
+        });
+        // Build redirect URL with auth code
+        const redirectUrl = new URL(params.redirect_uri);
+        redirectUrl.searchParams.set('code', authCode);
+        if (params.state) {
+            redirectUrl.searchParams.set('state', params.state);
+        }
+        return { authUrl: redirectUrl.toString(), authCode };
+    }
+    // Exchange authorization code for access token
+    async handleTokenRequest(params) {
+        const authCodeData = this.authCodes.get(params.code);
+        if (!authCodeData) {
+            return { error: 'Invalid authorization code' };
+        }
+        if (Date.now() > authCodeData.expiresAt) {
+            this.authCodes.delete(params.code);
+            return { error: 'Authorization code expired' };
+        }
+        // Verify PKCE
+        const computedChallenge = crypto
+            .createHash('sha256')
+            .update(params.code_verifier)
+            .digest('base64url');
+        if (computedChallenge !== authCodeData.codeChallenge) {
+            return { error: 'Invalid code_verifier' };
+        }
+        // Verify client and redirect URI
+        if (params.client_id !== authCodeData.clientId ||
+            params.redirect_uri !== authCodeData.redirectUri) {
+            return { error: 'Invalid client_id or redirect_uri' };
+        }
+        // Generate access token
+        const accessToken = crypto.randomBytes(32).toString('hex');
+        const expiresIn = 3600; // 1 hour
+        const tokenData = {
+            sub: authCodeData.userId,
+            aud: params.client_id,
+            iss: this.config.issuer,
+            exp: Math.floor(Date.now() / 1000) + expiresIn,
+            iat: Math.floor(Date.now() / 1000),
+            scope: authCodeData.scope
+        };
+        this.accessTokens.set(accessToken, tokenData);
+        this.authCodes.delete(params.code);
+        return {
+            access_token: accessToken,
+            token_type: 'Bearer',
+            expires_in: expiresIn,
+            scope: authCodeData.scope
+        };
+    }
+    // Validate access token
+    validateAccessToken(token) {
+        const tokenData = this.accessTokens.get(token);
+        if (!tokenData) {
+            return null;
+        }
+        if (Date.now() / 1000 > tokenData.exp) {
+            this.accessTokens.delete(token);
+            return null;
+        }
+        return tokenData;
+    }
+}

package/dist/oauth/server.d.ts

@@ -0,0 +1,18 @@
+import http from 'http';
+import type { OAuthConfig } from './types.js';
+export declare class OAuthHttpServer {
+    private server;
+    private oauthProvider;
+    private mcpHandler;
+    constructor(config: OAuthConfig, mcpHandler: (req: http.IncomingMessage, res: http.ServerResponse) => void);
+    private handleRequest;
+    private setCorsHeaders;
+    private handleAuthServerMetadata;
+    private handleAuthorize;
+    private handleToken;
+    private handleCallback;
+    private sendUnauthorized;
+    private getRequestBody;
+    listen(port: number, callback?: () => void): void;
+    close(callback?: () => void): void;
+}