@dollhousemcp/mcp-server 1.4.4 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to DollhouseMCP will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2025-08-05
+
+### Added
+- **GitHub OAuth Device Flow Authentication** - Secure authentication without manual token management
+  - New tools: `authenticate_github`, `get_auth_status`, `clear_authentication`
+  - AES-256-GCM encrypted token storage with machine-specific keys
+  - Natural language OAuth flow with user-friendly instructions
+  - Built-in rate limiting and Unicode security validation
+  - Automatic token persistence across sessions
+- **Comprehensive test coverage** for OAuth implementation (420+ lines of tests)
+- **ES module mocking support** using `jest.unstable_mockModule` for better test reliability
+
+### Security
+- **Token encryption**: GitHub tokens are now encrypted at rest using AES-256-GCM
+- **Machine-specific encryption keys**: Tokens are encrypted with keys derived from machine ID
+- **Secure file permissions**: Token storage uses 0o600 file and 0o700 directory permissions
+- **Rate limiting**: Built-in protection against brute force token validation attacks
+
+## [1.4.5] - 2025-08-05
+
+### Fixed
+- **Critical**: Fixed server startup with npx and CLI commands in Claude Desktop
+  - Server now properly detects and handles all execution methods (direct, npx, CLI)
+  - No more "Server disconnected" errors when using standard npm installation
+  - Added 50ms delay for npx/CLI execution to ensure proper module initialization
+  - Better error logging with execution context details
+
+### Changed
+- Improved startup detection logic to handle various execution scenarios
+- Added global error handlers for better debugging of startup issues
+
 ## [1.4.4] - 2025-08-04
 
 ### 🚨 Emergency Hotfix

package/README.md

@@ -23,7 +23,7 @@ A comprehensive Model Context Protocol (MCP) server that enables dynamic AI pers
 **🏪 Collection**: https://github.com/DollhouseMCP/collection  
 **📦 NPM Package**: https://www.npmjs.com/package/@dollhousemcp/mcp-server  
 **🌍 Website**: https://dollhousemcp.com (planned)  
-**📦 Version**: v1.4.4
+**📦 Version**: v1.5.0
 
 > **⚠️ Breaking Change Notice**: Tool names have changed from "marketplace" to "collection" terminology. Old names still work but are deprecated. See [Migration Guide](docs/MIGRATION_GUIDE_COLLECTION_RENAME.md) for details.
 
@@ -33,7 +33,8 @@ A comprehensive Model Context Protocol (MCP) server that enables dynamic AI pers
 # Install globally
 npm install -g @dollhousemcp/mcp-server
 
-# ⚠️ IMPORTANT: If you have v1.4.2 or v1.4.3, upgrade immediately:
+# ✅ v1.5.0 introduces GitHub OAuth authentication!
+# New secure authentication without manual token management:
 # npm install -g @dollhousemcp/mcp-server@latest
 
 # Add to Claude Desktop config (see path below for your OS)
@@ -59,7 +60,7 @@ Restart Claude Desktop and you're ready to use DollhouseMCP! Try `list_personas`
 
 | Feature | Description |
 |---------|-------------|
-| 🎭 **40 MCP Tools** | Complete portfolio element management through chat interface |
+| 🎭 **43 MCP Tools** | Complete portfolio element management through chat interface |
 | 🏪 **GitHub Collection** | Browse, search, install, and submit personas to community collection |
 | 👤 **User Identity System** | Environment-based attribution for persona creators |
 | 🆔 **Unique ID System** | Advanced ID generation: `{type}_{name}_{author}_{YYYYMMDD}-{HHMMSS}` |
@@ -149,7 +150,7 @@ DollhouseMCP implements comprehensive security measures to protect your personas
 ### Security Features
 - **🛡️ Content Sanitization**: DOMPurify integration prevents XSS attacks in persona content
 - **📝 YAML Injection Prevention**: Secure parsing with schema validation and size limits
-- **🔐 Token Security**: GitHub tokens are validated, encrypted at rest, with rotation support
+- **🔐 Token Security**: GitHub OAuth device flow authentication with AES-256-GCM encrypted storage
 - **🐳 Container Hardening**: Non-root execution, read-only filesystem, resource limits
 - **🚦 Rate Limiting**: Token bucket algorithm prevents API abuse (10 checks/hour default)
 - **✅ Signature Verification**: GPG verification ensures release authenticity
@@ -271,9 +272,9 @@ Add DollhouseMCP to your Claude Desktop configuration:
 **🔄 After configuration:**
 1. Save the file
 2. Restart Claude Desktop completely
-3. All 46 DollhouseMCP tools will be available
+3. All 49 DollhouseMCP tools will be available
 
-## 🛠️ Available Tools (46 Total)
+## 🛠️ Available Tools (49 Total)
 
 ### Portfolio Element Management (NEW!)
 - **`list_elements`** - List all elements of a specific type
@@ -322,6 +323,11 @@ Add DollhouseMCP to your Claude Desktop configuration:
 - **`configure_indicator`** - Configure how persona indicators appear in AI responses
 - **`get_indicator_config`** - View current indicator configuration settings
 
+### GitHub Authentication (NEW!)
+- **`authenticate_github`** - Start GitHub OAuth device flow authentication
+- **`get_auth_status`** - Check current authentication status
+- **`clear_authentication`** - Remove stored authentication credentials
+
 ## 📖 Usage Examples
 
 ### Collection Operations
@@ -401,6 +407,46 @@ export DOLLHOUSE_INDICATOR_STYLE=minimal
 export DOLLHOUSE_INDICATOR_EMOJI=🎨
 ```
 
+### GitHub Authentication (NEW! v1.5.0)
+
+DollhouseMCP now supports GitHub OAuth device flow authentication for secure access to GitHub features without exposing tokens:
+
+```
+authenticate_github                        # Start OAuth device flow
+get_auth_status                           # Check authentication status
+clear_authentication                      # Remove stored credentials
+```
+
+**Features:**
+- 🔐 **Secure Token Storage**: Tokens encrypted with AES-256-GCM
+- 📱 **Device Flow**: No need to manually create or paste tokens
+- 🔄 **Automatic Token Management**: Secure storage and retrieval
+- 🛡️ **Rate Limiting**: Built-in protection against API abuse
+- ✅ **Unicode Security**: Prevents homograph attacks
+
+**How It Works:**
+1. Run `authenticate_github` to start the OAuth flow
+2. Visit the provided URL and enter the user code
+3. Authorize DollhouseMCP in your browser
+4. Authentication completes automatically
+5. Token is securely stored for future use
+
+**Example Usage:**
+```
+# First-time setup
+authenticate_github
+# Copy the user code: XXXX-XXXX
+# Visit: https://github.com/login/device
+# Enter the code and authorize
+
+# Check status
+get_auth_status
+# ✅ Authenticated as: your-username
+
+# Later sessions automatically use stored token
+browse_collection  # Works with authenticated access
+```
+
 ## 🖥️ Cross-Platform Installation
 
 ### 🐧 Linux Installation
@@ -1154,7 +1200,22 @@ This project is licensed under the **AGPL-3.0** License with Platform Stability
 
 ## 🏷️ Version History
 
-### v1.4.4 - August 4, 2025 (Current)
+### v1.5.0 - August 5, 2025 (Current)
+**GitHub OAuth Authentication**:
+- 🔐 **OAuth Device Flow** - Secure authentication without manual token management
+- 🔒 **AES-256-GCM Encryption** - Tokens encrypted at rest with machine-specific keys
+- 🛡️ **Rate Limiting** - Built-in protection against brute force attacks
+- ✅ **Natural Language Flow** - User-friendly authentication instructions
+- 🧪 **Comprehensive Tests** - 420+ lines of OAuth implementation tests
+
+### v1.4.5 - August 5, 2025
+**Claude Desktop Integration Fix**:
+- ✅ **Fixed "Server disconnected" errors** when using `npx` or `dollhousemcp` CLI
+- 🔄 **Progressive retry mechanism** for better compatibility across different machine speeds
+- 🔒 **Security improvements** - removed detailed error logging to prevent information disclosure
+- 🧪 **Added comprehensive tests** for execution detection logic
+
+### v1.4.4 - August 4, 2025
 **Emergency Hotfix**:
 - 🚨 **Fixed v1.4.3 total failure** - initialization crashes fixed
 - 🔧 **Fixed jsdom crash** - heavy dependencies now load lazily

package/dist/auth/GitHubAuthManager.d.ts

@@ -0,0 +1,93 @@
+/**
+ * GitHub authentication manager using OAuth device flow
+ * Handles authentication for MCP servers without requiring client secrets
+ */
+import { APICache } from '../cache/APICache.js';
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    expires_in: number;
+    interval: number;
+}
+export interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    scope: string;
+}
+export interface AuthStatus {
+    isAuthenticated: boolean;
+    hasToken: boolean;
+    username?: string;
+    scopes?: string[];
+    expiresAt?: Date;
+}
+/**
+ * Manages GitHub authentication using the OAuth device flow
+ * This is the recommended approach for CLI/desktop applications
+ */
+export declare class GitHubAuthManager {
+    private static readonly CLIENT_ID;
+    private static readonly DEVICE_CODE_URL;
+    private static readonly TOKEN_URL;
+    private static readonly USER_URL;
+    private static readonly DEFAULT_POLL_INTERVAL;
+    private static readonly MAX_POLL_ATTEMPTS;
+    private apiCache;
+    private activePolling;
+    constructor(apiCache: APICache);
+    /**
+     * Execute a network request with retry logic
+     */
+    private fetchWithRetry;
+    /**
+     * Check current authentication status
+     */
+    getAuthStatus(): Promise<AuthStatus>;
+    /**
+     * Initiate the device flow authentication process
+     */
+    initiateDeviceFlow(): Promise<DeviceCodeResponse>;
+    /**
+     * Poll for token after user has authorized the device
+     */
+    pollForToken(deviceCode: string, interval?: number): Promise<TokenResponse>;
+    /**
+     * Complete the authentication flow and store the token
+     */
+    completeAuthentication(tokenResponse: TokenResponse): Promise<AuthStatus>;
+    /**
+     * Clear stored authentication and revoke token
+     */
+    clearAuthentication(): Promise<void>;
+    /**
+     * Store token securely using encrypted file storage
+     */
+    private storeToken;
+    /**
+     * Fetch user information from GitHub
+     */
+    private fetchUserInfo;
+    /**
+     * Format authentication instructions for users
+     */
+    formatAuthInstructions(deviceResponse: DeviceCodeResponse): string;
+    /**
+     * Check if user needs to authenticate for a specific action
+     */
+    needsAuthForAction(action: string): boolean;
+    /**
+     * Wait with abort signal support
+     */
+    private waitWithAbort;
+    /**
+     * Clean up any active operations (called on server shutdown)
+     */
+    cleanup(): Promise<void>;
+    /**
+     * Get user-friendly error message based on HTTP status code
+     * Avoids exposing sensitive information while providing helpful guidance
+     */
+    private getErrorMessageForStatus;
+}
+//# sourceMappingURL=GitHubAuthManager.d.ts.map

package/dist/auth/GitHubAuthManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitHubAuthManager.d.ts","sourceRoot":"","sources":["../../src/auth/GitHubAuthManager.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIhD,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAG5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAA0C;IAG3E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAA0C;IACjF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAClF,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAGjE,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAQ;IACrD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,iBAAiB,CAAO;IAEhD,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,aAAa,CAAgC;gBAEzC,QAAQ,EAAE,QAAQ;IAI9B;;OAEG;YACW,cAAc;IA0C5B;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IA8B1C;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,kBAAkB,CAAC;IA0DvD;;OAEG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAgD,GAAG,OAAO,CAAC,aAAa,CAAC;IAkF1H;;OAEG;IACG,sBAAsB,CAAC,aAAa,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,CAAC;IA4B/E;;OAEG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;IAoC1C;;OAEG;YACW,UAAU;IAYxB;;OAEG;YACW,aAAa;IA6E3B;;OAEG;IACH,sBAAsB,CAAC,cAAc,EAAE,kBAAkB,GAAG,MAAM;IAmBlE;;OAEG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAK3C;;OAEG;YACW,aAAa;IAmB3B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB9B;;;OAGG;IACH,OAAO,CAAC,wBAAwB;CAyBjC"}