auth_whoami

Instructions

Implementation Reference

• src/actions/auth.ts:98-124 (handler)

  The auth.whoami tool handler: returns current admin user info for the active session. It calls Magento API endpoint /V1/users/me, falling back to returning username, base_url, and default_scope from session context if the API call fails.

    name: 'auth.whoami',
    description: 'Return current admin user info for the active session.',
    riskTier: RiskTier.Safe,
    requiresAuth: true,
    handler: async (_params: Record<string, unknown>, context: ActionContext) => {
      const token = context.getToken();
      const baseUrl = context.getBaseUrl();
  
      if (!token || !baseUrl) {
        return { error: { code: ErrorCodes.NOT_AUTHENTICATED, message: 'No active session' } };
      }
  
      // Try to get current admin user info from Magento
      try {
        const client = context.getClient();
        const userInfo = await client.get('/V1/users/me');
        return userInfo;
      } catch {
        // If the endpoint isn't available, return what we know
        return {
          username: context.username,
          base_url: baseUrl,
          default_scope: context.getDefaultScope(),
        };
      }
    },
  },

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

  The auth.whoami tool is registered via createAuthActions(sessionStore) which returns an array of ActionDefinitions including auth.whoami. In index.ts, all actions are iterated and registered as MCP tools using mcpServer.tool(), with dots replaced by underscores (auth.whoami -> auth_whoami).

  const allActions: ActionDefinition[] = [
    ...createAuthActions(sessionStore),
    ...createScopeActions(sessionStore),
    ...createPromotionsActions(planStore, guardrails, config),
    ...createCatalogActions(planStore, guardrails, idempotencyLedger, config),
    ...createPricingActions(planStore, guardrails, idempotencyLedger, config),
    ...createCmsActions(planStore, guardrails, config),
    ...createSeoActions(planStore, guardrails, config),
    ...createDiagnosticsActions(),
    ...createCacheActions(guardrails, config),
  ];

• src/index.ts:75-159 (registration)

  Each ActionDefinition is registered as an MCP tool with name conversion (dots to underscores), description, schema, and a wrapper handler that checks auth, builds ActionContext, executes the handler, and audits results.

  // Register each action as an MCP 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,
      { params: z.record(z.unknown()).optional().describe('Action parameters as a JSON object') },
      async (args) => {
        const params = (args.params || {}) as Record<string, unknown>;
  
        // Check authentication
        if (action.requiresAuth) {
          const token = sessionStore.getToken(sessionId);
          if (!token) {
            return {
              content: [{ type: 'text' as const, text: JSON.stringify({ error: { code: 'NOT_AUTHENTICATED', message: 'Not authenticated. Call auth_login first.' } }, null, 2) }],
              isError: true,
            };
          }
        }
  
        // Build action context
        const context: ActionContext = {
          sessionId,
          getToken: () => sessionStore.getToken(sessionId),
          getBaseUrl: () => sessionStore.getBaseUrl(sessionId),
          getDefaultScope: () => sessionStore.getDefaultScope(sessionId),
          getOAuthCredentials: () => sessionStore.getOAuthCredentials(sessionId),
          getClient: () => {
            const baseUrl = sessionStore.getBaseUrl(sessionId);
            const token = sessionStore.getToken(sessionId);
            if (!baseUrl) throw new Error('No active session');
            const client = new MagentoRestClient(baseUrl, token);
            const oauth = sessionStore.getOAuthCredentials(sessionId);
            if (oauth) client.setOAuth(oauth);
            return client;
          },
          username: sessionStore.getUsername(sessionId),
        };
  
        try {
          const result = await action.handler(params, context);
  
          // Audit log
          const auditRecord: AuditRecord = {
            timestamp: new Date().toISOString(),
            username: context.username,
            action: action.name,
            scope: context.getDefaultScope(),
            params,
            result_summary: summarizeResult(result),
            plan_id: (params['plan_id'] as string) || null,
            reason: (params['reason'] as string) || null,
          };
          auditLogger.log(auditRecord);
  
          return {
            content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
          };
        } catch (err) {
          const errorMessage = err instanceof Error ? err.message : String(err);
  
          // Audit the error
          const auditRecord: AuditRecord = {
            timestamp: new Date().toISOString(),
            username: context.username,
            action: action.name,
            scope: null,
            params,
            result_summary: `ERROR: ${errorMessage}`,
            plan_id: null,
            reason: null,
          };
          auditLogger.log(auditRecord);
  
          return {
            content: [{ type: 'text' as const, text: JSON.stringify({ error: errorMessage }, null, 2) }],
            isError: true,
          };
        }
      },
    );
  }

• src/protocol/types.ts:62-126 (helper)

  The ActionDefinition interface and ActionContext interface used by auth.whoami. ActionDefinition defines the shape of a tool handler, and ActionContext provides the methods (getToken, getBaseUrl, getClient, etc.) used by the whoami handler.

  export interface ActionDefinition {
    name: string;
    description: string;
    riskTier: RiskTier;
    requiresAuth: boolean;
    inputSchema?: Record<string, unknown>;
    handler: (params: Record<string, unknown>, context: ActionContext) => Promise<unknown>;
  }
  
  // ── Action Context (passed to every handler) ────────────────────────────────
  
  export interface ActionContext {
    sessionId: string;
    getToken: () => string | null;
    getBaseUrl: () => string | null;
    getDefaultScope: () => StoreScope | null;
    getOAuthCredentials: () => import('../client/magentoRest').OAuthCredentials | null;
    getClient: () => import('../client/magentoRest').MagentoRestClient;
    username: string | null;
  }
  
  // ── Store / Scope ───────────────────────────────────────────────────────────
  
  export interface StoreScope {
    website_code?: string;
    store_code?: string;
    store_view_code?: string;
    scope?: 'global';
  }
  
  // ── Audit Record ────────────────────────────────────────────────────────────
  
  export interface AuditRecord {
    timestamp: string;
    username: string | null;
    action: string;
    scope: StoreScope | null;
    params: Record<string, unknown>;
    result_summary: string;
    plan_id: string | null;
    reason: string | null;
  }
  
  // ── Plan (for two-phase commit) ─────────────────────────────────────────────
  
  export interface BulkPlan {
    plan_id: string;
    action: string;
    created_at: string;
    expires_at: string;
    payload: unknown;
    affected_count: number;
    sample_diffs?: unknown[];
    warnings?: string[];
  }
  
  // ── Idempotency ─────────────────────────────────────────────────────────────
  
  export interface IdempotencyEntry {
    key: string;
    action: string;
    created_at: string;
    result_summary: string;
  }

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

  AuthLoginSchema used by auth.login, but auth.whoami has no dedicated input schema since it takes no parameters (the handler uses only the context).

  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(),
  });