DollhouseMCP

Instructions

Implementation Reference

• src/server/tools/AuthTools.ts:32-42 (registration)

  Registration of the 'clear_github_auth' MCP tool, including name, description, empty input schema, and handler that delegates to server.clearGitHubAuth()

  {
    tool: {
      name: "clear_github_auth",
      description: "Remove GitHub authentication and disconnect from GitHub. Use when users say 'disconnect from GitHub', 'remove my GitHub connection', 'clear authentication', or want to switch accounts.",
      inputSchema: {
        type: "object", 
        properties: {}
      }
    },
    handler: () => server.clearGitHubAuth()
  },

• src/auth/GitHubAuthManager.ts:571-605 (handler)

  Core implementation of clearing GitHub auth: retrieves token if present, clears API cache, logs security event, removes stored token via TokenManager, and handles errors

  async clearAuthentication(): Promise<void> {
    try {
      // Get the token before clearing it
      const token = await TokenManager.getGitHubTokenAsync();
      
      if (token) {
        // Attempt to revoke the token on GitHub
        // Note: GitHub OAuth tokens don't have a revocation endpoint for device flow tokens
        // But we'll clear the cache and remove from storage
        
        // Clear cached user info
        this.apiCache.clear();
        
        // Log security event for audit trail
        SecurityMonitor.logSecurityEvent({
          type: 'TOKEN_CACHE_CLEARED',
          severity: 'LOW',
          source: 'GitHubAuthManager.clearAuthentication',
          details: 'GitHub authentication cleared by user request',
          metadata: {
            hadToken: true,
            tokenPrefix: TokenManager.getTokenPrefix(token)
          }
        });
      }
      
      // Remove from secure storage
      await TokenManager.removeStoredToken();
      
      logger.info('GitHub authentication cleared successfully');
    } catch (error) {
      ErrorHandler.logError('GitHubAuthManager.clearAuthentication', error);
      throw ErrorHandler.createError('Failed to clear authentication', ErrorCategory.AUTH_ERROR, undefined, error);
    }
  }

• src/server/types.ts:50-50 (schema)

  TypeScript interface definition for the clearGitHubAuth method on IToolHandler

  clearGitHubAuth(): Promise<any>;

• src/server/tools/AuthTools.ts:8-75 (helper)

  getAuthTools function that returns the array of auth tools including clear_github_auth for registration in ServerSetup

  export function getAuthTools(server: IToolHandler): Array<{ tool: ToolDefinition; handler: any }> {
    return [
      {
        tool: {
          name: "setup_github_auth",
          description: "Set up GitHub authentication to access all DollhouseMCP features. This uses GitHub's secure device flow - no passwords needed! Use this when users say things like 'connect to GitHub', 'set up GitHub', 'I have a GitHub account now', or when they try to submit content without authentication.",
          inputSchema: {
            type: "object",
            properties: {}
          }
        },
        handler: () => server.setupGitHubAuth()
      },
      {
        tool: {
          name: "check_github_auth", 
          description: "Check current GitHub authentication status. Shows whether you're connected to GitHub, your username, and what actions are available. Use when users ask 'am I connected to GitHub?', 'what's my GitHub status?', or similar questions.",
          inputSchema: {
            type: "object",
            properties: {}
          }
        },
        handler: () => server.checkGitHubAuth()
      },
      {
        tool: {
          name: "clear_github_auth",
          description: "Remove GitHub authentication and disconnect from GitHub. Use when users say 'disconnect from GitHub', 'remove my GitHub connection', 'clear authentication', or want to switch accounts.",
          inputSchema: {
            type: "object", 
            properties: {}
          }
        },
        handler: () => server.clearGitHubAuth()
      },
      {
        tool: {
          name: "configure_oauth",
          description: "Configure GitHub OAuth client ID for authentication. If no client_id provided, shows current configuration status. If client_id provided, validates format and saves it to config. Use when users need to set up OAuth or check their configuration.",
          inputSchema: {
            type: "object",
            properties: {
              client_id: {
                type: "string",
                description: "GitHub OAuth client ID (starts with 'Ov23li' followed by at least 14 alphanumeric characters)"
              }
            }
          }
        },
        handler: (args: { client_id?: string }) => server.configureOAuth(args.client_id)
      },
      {
        tool: {
          name: "oauth_helper_status",
          description: "Get detailed diagnostic information about the OAuth helper process. Shows if authentication is in progress, process health, timing, and any errors. Use when troubleshooting authentication issues or checking if OAuth flow is working.",
          inputSchema: {
            type: "object",
            properties: {
              verbose: {
                type: "boolean",
                description: "Include detailed log output if available (default: false)"
              }
            }
          }
        },
        handler: (args: { verbose?: boolean }) => server.getOAuthHelperStatus(args.verbose)
      }
    ];