auth_login

Instructions

Implementation Reference

• src/actions/auth.ts:13-83 (handler)

  The 'auth.login' action definition containing the handler logic. It validates input via AuthLoginSchema, supports three auth methods (OAuth 1.0, integration bearer token, username/password), and creates a session via the SessionStore.

  name: 'auth.login',
  description: 'Authenticate with Magento Admin credentials and establish a session.',
  riskTier: RiskTier.Safe,
  requiresAuth: false,
  handler: async (params: Record<string, unknown>, context: ActionContext) => {
    const validated = AuthLoginSchema.parse(params);
  
    const base_url = validated.base_url || process.env.MAGENTO_BASE_URL;
    if (!base_url) {
      return { error: { code: 'VALIDATION_ERROR', message: 'base_url is required — pass it in params or set MAGENTO_BASE_URL env var' } };
    }
  
    // Check for OAuth 1.0 integration credentials first (bypasses 2FA)
    const oauthConsumerKey = (params['oauth_consumer_key'] as string) || process.env.MAGENTO_OAUTH_CONSUMER_KEY;
    const oauthConsumerSecret = (params['oauth_consumer_secret'] as string) || process.env.MAGENTO_OAUTH_CONSUMER_SECRET;
    const oauthToken = (params['oauth_token'] as string) || process.env.MAGENTO_OAUTH_TOKEN;
    const oauthTokenSecret = (params['oauth_token_secret'] as string) || process.env.MAGENTO_OAUTH_TOKEN_SECRET;
  
    if (oauthConsumerKey && oauthConsumerSecret && oauthToken && oauthTokenSecret) {
      const oauthCreds: OAuthCredentials = {
        consumerKey: oauthConsumerKey,
        consumerSecret: oauthConsumerSecret,
        token: oauthToken,
        tokenSecret: oauthTokenSecret,
      };
      const username = validated.username || process.env.MAGENTO_ADMIN_USERNAME || 'integration';
      sessionStore.createOAuth(context.sessionId, base_url, oauthCreds, username);
      return {
        message: 'Login successful (OAuth 1.0 integration)',
        username: username,
        base_url: base_url,
        auth_method: 'oauth',
      };
    }
  
    // Check for integration bearer token (bypasses 2FA)
    const integrationToken = (params['integration_token'] as string) || process.env.MAGENTO_INTEGRATION_TOKEN;
    if (integrationToken) {
      const username = validated.username || process.env.MAGENTO_ADMIN_USERNAME || 'integration';
      sessionStore.create(context.sessionId, base_url, integrationToken, username);
      return {
        message: 'Login successful (integration token)',
        username: username,
        base_url: base_url,
        auth_method: 'integration_token',
      };
    }
  
    // Fall back to username/password login
    const username = validated.username || process.env.MAGENTO_ADMIN_USERNAME;
    if (!username) {
      return { error: { code: 'VALIDATION_ERROR', message: 'username is required — pass it in params or set MAGENTO_ADMIN_USERNAME env var' } };
    }
  
    const password = validated.password || process.env.MAGENTO_ADMIN_PASSWORD;
    if (!password) {
      return { error: { code: 'VALIDATION_ERROR', message: 'password is required — pass it in params or set MAGENTO_ADMIN_PASSWORD env var' } };
    }
  
    const client = new MagentoRestClient(base_url);
    const token = await client.getAdminToken(username, password);
  
    sessionStore.create(context.sessionId, base_url, token, username);
  
    return {
      message: 'Login successful',
      username: username,
      base_url: base_url,
      auth_method: 'admin_token',
    };
  },

• src/validation/schemas.ts:35-39 (schema)

  Zod validation schema for auth_login input parameters: base_url (optional URL), username (optional string), password (optional string).

  export const AuthLoginSchema = z.object({
    base_url: z.string().url('base_url must be a valid URL').optional(),
    username: z.string().min(1).optional(),
    password: z.string().min(1).optional(),
  });

• src/index.ts:76-82 (registration)

  Registration of the tool: dots are converted to underscores (auth.login -> auth_login) when registering with the MCP SDK server via mcpServer.tool().

  for (const action of allActions) {
    // Convert dots to underscores for MCP tool names (e.g. "auth.login" -> "auth_login")
    const toolName = action.name.replace(/\./g, '_');
  
    mcpServer.tool(
      toolName,
      action.description,

• src/index.ts:51-53 (registration)

  Actions are collected from createAuthActions(sessionStore) into the allActions array, which is then iterated to register each tool.

  const allActions: ActionDefinition[] = [
    ...createAuthActions(sessionStore),
    ...createScopeActions(sessionStore),

• src/actions/auth.ts:10-39 (helper)

  Factory function createAuthActions that returns the action definition array including auth.login.

  export function createAuthActions(sessionStore: SessionStore): ActionDefinition[] {
    return [
      {
        name: 'auth.login',
        description: 'Authenticate with Magento Admin credentials and establish a session.',
        riskTier: RiskTier.Safe,
        requiresAuth: false,
        handler: async (params: Record<string, unknown>, context: ActionContext) => {
          const validated = AuthLoginSchema.parse(params);
  
          const base_url = validated.base_url || process.env.MAGENTO_BASE_URL;
          if (!base_url) {
            return { error: { code: 'VALIDATION_ERROR', message: 'base_url is required — pass it in params or set MAGENTO_BASE_URL env var' } };
          }
  
          // Check for OAuth 1.0 integration credentials first (bypasses 2FA)
          const oauthConsumerKey = (params['oauth_consumer_key'] as string) || process.env.MAGENTO_OAUTH_CONSUMER_KEY;
          const oauthConsumerSecret = (params['oauth_consumer_secret'] as string) || process.env.MAGENTO_OAUTH_CONSUMER_SECRET;
          const oauthToken = (params['oauth_token'] as string) || process.env.MAGENTO_OAUTH_TOKEN;
          const oauthTokenSecret = (params['oauth_token_secret'] as string) || process.env.MAGENTO_OAUTH_TOKEN_SECRET;
  
          if (oauthConsumerKey && oauthConsumerSecret && oauthToken && oauthTokenSecret) {
            const oauthCreds: OAuthCredentials = {
              consumerKey: oauthConsumerKey,
              consumerSecret: oauthConsumerSecret,
              token: oauthToken,
              tokenSecret: oauthTokenSecret,
            };
            const username = validated.username || process.env.MAGENTO_ADMIN_USERNAME || 'integration';
            sessionStore.createOAuth(context.sessionId, base_url, oauthCreds, username);