Summary

Add new whoami action to manage_context tool that provides comprehensive information about 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 scopes have changed since startup, the tool registry is automatically refreshed and clients receive a tools/list_changed notification. No server restart required.

Problem

When a user connects with a limited-scope token, the MCP server silently filters tools and the agent has no way to understand why operations fail or how to help the user fix access issues. Additionally, if the user updates their token permissions, they previously had to restart the server.

Solution

The whoami action returns detailed introspection data:

• User identity — fetched via REST API (works with any token scope)
• Token info — name, scopes, expiry, validity status
• Server config — host, version, tier (free/premium/ultimate)
• Capabilities summary — available/filtered tools with breakdown by filter reason
• Current context — active preset, profile, scope
• Warnings — expiring token, limited scopes, read-only mode, tier restrictions
• Recommendations — actionable guidance with URLs for token creation
• scopesRefreshed — indicates if token permissions changed and tools were updated

Dynamic Token Refresh Flow

User: "I added the api scope to my token"
Agent: [calls manage_context { action: "whoami" }]

→ whoami re-introspects token via GitLab API
→ Detects scopes changed from ["read_user"] to ["api", "read_user"]  
→ Refreshes RegistryManager tool cache
→ Sends tools/list_changed notification to clients
→ Returns { scopesRefreshed: true, ... }

Agent: "Your token scopes have been updated! You now have access to 45 tools."

Changes

• Added WhoamiSchema to discriminated union in schema.ts
• Added comprehensive types in types.ts (WhoamiResult, WhoamiUserInfo, WhoamiTokenInfo, etc.)
• New src/entities/context/whoami.ts with main implementation
• Added refreshTokenScopes() to ConnectionManager for hot-reload
• Added getFilterStats() to RegistryManager for tool filtering statistics
• Updated handlers.ts with handleWhoami() dispatcher
• Integrated sendToolsListChangedNotification() for client updates
• 34 unit tests covering various token scenarios

Example Response

{
  "user": {
    "id": 123,
    "username": "developer",
    "name": "John Developer",
    "state": "active"
  },
  "token": {
    "type": "personal_access_token",
    "name": "gitlab-mcp",
    "scopes": ["api", "read_user"],
    "expiresAt": "2025-12-31",
    "daysUntilExpiry": 340,
    "isValid": true,
    "hasGraphQLAccess": true,
    "hasWriteAccess": true
  },
  "server": {
    "host": "gitlab.example.com",
    "version": "17.5.2",
    "tier": "ultimate",
    "readOnlyMode": false
  },
  "capabilities": {
    "canBrowse": true,
    "canManage": true,
    "canAccessGraphQL": true,
    "availableToolCount": 45,
    "totalToolCount": 45,
    "filteredByScopes": 0
  },
  "warnings": [],
  "recommendations": [],
  "scopesRefreshed": false
}

Test plan

• yarn lint passes (0 errors)
• yarn test passes (4005 tests)
• yarn build succeeds
• Manual testing with limited-scope token
• Manual testing with expired token
• Manual testing: add scope to token, verify hot-reload works

Closes #203