Summary

Add a whoami action to manage_context tool that provides comprehensive information about the current authentication status, token capabilities, and available tools. This enables AI agents to understand access limitations and provide actionable guidance to users.

Key Feature: Dynamic Token Refresh - When called, whoami re-introspects the token to detect permission changes. If the user has updated their token scopes since startup, the tool registry is automatically refreshed and a tools/list_changed notification is sent. This enables hot-reloading of token permissions without server restart.

Problem Statement

Currently, when a user connects with a limited-scope token (e.g., only read_user without api), the MCP server:

1. Silently filters tools - Agent receives reduced tool list but doesn't understand why
2. No self-discovery mechanism - Agent cannot ask "what can I do?"
3. Shows irrelevant options - list_profiles/switch_profile appear even without OAuth
4. No guidance for users - Agent cannot explain how to fix access issues
5. Requires restart on token update - If user adds scopes to token, must restart server

Real-world scenario

User configures gitlab-mcp with a PAT that only has read_user scope:

AI Agent: "Let me check your merge requests..."
AI Agent: [ERROR] Tool 'browse_merge_requests' not found
User: "Why doesn't this work?"
AI Agent: "I don't know, the tool should exist but it's not available..."

Expected behavior with whoami:

AI Agent: "Let me check what I can access..."
AI Agent: [calls manage_context { action: "whoami" }]
AI Agent: "Your GitLab access is limited. Your token only has 'read_user' 
          scope, which allows browsing users and events. For full functionality,
          create a new token with 'api' scope: [link]"

After user updates token:

User: "I added the api scope to my token"
AI Agent: [calls manage_context { action: "whoami" }]
AI Agent: "Great! I detected that your token scopes have changed. You now 
          have full access to 45 tools including MR and issue management."

Proposed Solution

1. Add whoami action to manage_context

New action in the discriminated union schema:

const WhoamiSchema = z.object({
  action: z.literal("whoami").describe(
    "Get authentication status, token capabilities, and server configuration. " +
    "Re-introspects token to detect permission changes - if scopes changed, " +
    "automatically refreshes available tools (scopesRefreshed=true in response). " +
    "Use to diagnose access issues or verify new token permissions are active."
  ),
});

2. WhoamiResult response structure

interface WhoamiResult {
  user: WhoamiUserInfo | null;        // Current user identity
  token: WhoamiTokenInfo | null;       // Token info (scopes, expiry, validity)
  server: WhoamiServerInfo;            // Host, version, tier, edition
  capabilities: WhoamiCapabilities;    // Available/filtered tool counts
  context: WhoamiContextInfo;          // Active preset, profile, scope
  warnings: string[];                  // Issues (expiring token, limited scopes)
  recommendations: WhoamiRecommendation[]; // Actionable guidance with URLs
  scopesRefreshed: boolean;            // True if scopes changed & tools updated
}

3. Dynamic Token Refresh Flow

1. whoami calls ConnectionManager.refreshTokenScopes()
2. Token is re-introspected via GitLab API
3. If scopes changed:
   • Update internal token state
   • Call RegistryManager.refreshCache() to rebuild tool list
   • Send tools/list_changed notification to MCP clients
   • Set scopesRefreshed: true in response
4. Return fresh whoami data

4. Key capabilities info

interface WhoamiCapabilities {
  canBrowse: boolean;           // Has read access
  canManage: boolean;           // Has write access  
  canAccessGraphQL: boolean;    // Can use GraphQL operations
  availableToolCount: number;   // Tools after filtering
  totalToolCount: number;       // Total registered tools
  filteredByScopes: number;     // Filtered due to token scopes
  filteredByReadOnly: number;   // Filtered due to read-only mode
  filteredByTier: number;       // Filtered due to GitLab tier
  filteredByDeniedRegex: number; // Filtered by config regex
  filteredByActionDenial: number; // Filtered by action denial
}

5. Actionable recommendations

interface WhoamiRecommendation {
  action: "create_new_token" | "add_scope" | "renew_token" | "contact_admin";
  message: string;         // Human-readable guidance
  url?: string;           // Token creation page URL
  priority: "high" | "medium" | "low";
}

Implementation Tasks

• Add WhoamiSchema to discriminated union
• Add comprehensive types in types.ts
• Implement whoami.ts with main logic
• Add refreshTokenScopes() to ConnectionManager
• Add getFilterStats() to RegistryManager
• Integrate tools/list_changed notification
• Update tool description in registry
• Write unit tests (34 tests)
• Document the feature

Benefits

1. Self-discovery - Agent can understand its own capabilities
2. User guidance - Clear explanations and actionable links
3. Diagnostics - Detailed breakdown of why tools are filtered
4. Hot-reload - Token permission changes apply immediately
5. No restart - Update token scopes without server restart