addTaskManager MCP Server

Instructions

Implementation Reference

• src/index.ts:834-878 (handler)

  Primary handler function for the 'authenticate_user' tool. Manages both production (delegates to UserAuthService) and mock authentication modes, sets user session/token.

  private async authenticateUser(webAuthToken: string) {
    if (this.productionMode && this.authService) {
      // Production CloudKit authentication
      try {
        const authResult = await this.authService.authenticateUser(webAuthToken);
        
        if (authResult.success) {
          this.currentSession = await this.authService.validateSession(authResult.sessionId!);
          this.userToken = {
            cloudKitWebAuthToken: webAuthToken,
            userIdentity: { 
              userRecordName: authResult.userRecordName, 
              lookupInfo: { sessionId: authResult.sessionId } 
            }
          };
          
          return { 
            content: [{ 
              type: 'text', 
              text: `✅ Successfully authenticated with iCloud as ${authResult.userRecordName}. Session expires: ${authResult.expiresAt?.toLocaleString()}` 
            }] 
          };
        } else if (authResult.redirectToSignIn) {
          return { 
            content: [{ 
              type: 'text', 
              text: `🔐 Please authenticate with your Apple ID: ${authResult.authUrl}\n\nAfter signing in, provide your web auth token to complete authentication.` 
            }] 
          };
        } else {
          throw new Error(authResult.message || 'Authentication failed');
        }
      } catch (error) {
        console.error('Production CloudKit authentication failed:', error);
        throw new McpError(ErrorCode.InvalidParams, `CloudKit authentication failed: ${error instanceof Error ? error.message : String(error)}`);
      }
    } else {
      // Mock authentication for development
      this.userToken = {
        cloudKitWebAuthToken: webAuthToken,
        userIdentity: { userRecordName: `mock_user_${uuidv4()}`, lookupInfo: {} }
      };
      return { content: [{ type: 'text', text: '🧪 Mock authentication successful. You can now access addTaskManager data (development mode).' }] };
    }
  }

• src/index.ts:241-251 (schema)

  Input schema definition for the 'authenticate_user' tool, specifying required webAuthToken.

  {
    name: 'authenticate_user',
    description: 'Authenticate user with Apple ID to access their addTaskManager data',
    inputSchema: {
      type: 'object',
      properties: {
        webAuthToken: { type: 'string', description: 'CloudKit web auth token from Apple Sign-In' }
      },
      required: ['webAuthToken']
    }
  },

• src/index.ts:652-657 (registration)

  Tool dispatch/registration in the CallToolRequestSchema handler switch statement.

  case 'authenticate_user':
    if (!args || typeof args.webAuthToken !== 'string') {
      throw new McpError(ErrorCode.InvalidRequest, 'Invalid or missing webAuthToken.');
    }
    return await this.authenticateUser(args.webAuthToken);

• src/services/UserAuthService.ts:25-93 (helper)

  Core production authentication logic in UserAuthService. Validates token via CloudKitService, creates and manages user sessions with rate limiting.

  async authenticateUser(webAuthToken?: string): Promise<AuthResult> {
    try {
      // Check rate limiting
      if (this.securityConfig?.rateLimiting && !this.checkRateLimit('auth')) {
        return {
          success: false,
          message: 'Rate limit exceeded. Please try again later.'
        };
      }
  
      // If no token provided, initiate authentication flow
      if (!webAuthToken) {
        return {
          success: false,
          authUrl: this.generateAuthUrl(),
          message: 'User authentication required. Please visit the provided URL to sign in with your Apple ID.',
          redirectToSignIn: true
        };
      }
  
      // Validate the provided token with CloudKit
      const isValid = await this.validateWebAuthToken(webAuthToken);
      if (!isValid) {
        return {
          success: false,
          message: 'Invalid or expired authentication token. Please authenticate again.'
        };
      }
  
      // Get user identity from CloudKit
      const userIdentity = await this.getUserIdentityFromToken(webAuthToken);
      if (!userIdentity) {
        return {
          success: false,
          message: 'Failed to retrieve user identity from token'
        };
      }
  
      // Create user session
      const sessionId = this.generateSessionId();
      const session: UserSession = {
        sessionId,
        webAuthToken,
        userId: this.generateUserId(userIdentity.userRecordName),
        userRecordName: userIdentity.userRecordName,
        createdAt: new Date(),
        expiresAt: new Date(Date.now() + (this.securityConfig?.sessionTimeout || 24 * 60 * 60 * 1000)), // Default 24 hours
        containerID: userIdentity.containerID || 'unknown'
      };
  
      this.sessions.set(sessionId, session);
  
      console.log(`User authenticated: ${session.userRecordName} (session: ${sessionId})`);
  
      return {
        success: true,
        sessionId,
        userId: session.userId,
        userRecordName: session.userRecordName,
        expiresAt: session.expiresAt
      };
    } catch (error) {
      console.error('Authentication failed:', error);
      return {
        success: false,
        message: `Authentication failed: ${error instanceof Error ? error.message : String(error)}`
      };
    }
  }

• src/services/CloudKitService.ts:73-99 (helper)

  Low-level CloudKit authentication using CloudKit JS SDK's setUpAuth with webAuthToken.

  async authenticateUser(webAuthToken?: string): Promise<boolean> {
    if (this.config.authMethod !== 'user') {
      throw new Error('User authentication not available in server-to-server mode');
    }
  
    try {
      if (webAuthToken) {
        // Use provided web auth token
        this.userIdentity = await this.ck.setUpAuth(webAuthToken);
      } else {
        // Request user authentication flow
        this.userIdentity = await this.ck.setUpAuth();
      }
  
      if (this.userIdentity) {
        this.authenticated = true;
        console.log('User authenticated:', this.userIdentity.userRecordName);
        return true;
      } else {
        this.authenticated = false;
        return false;
      }
    } catch (error) {
      console.error('User authentication failed:', error);
      this.authenticated = false;
      return false;
    }