Magento MCP Server

Instructions

Implementation Reference

• src/actions/auth.ts:102-123 (handler)

  Handler function for auth.whoami tool that retrieves current admin user info. It checks for an active session using context.getToken() and context.getBaseUrl(), then calls Magento API endpoint /V1/users/me to get user information. Falls back to returning session metadata if the API endpoint is unavailable.

  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:76-159 (registration)

  Registration of auth.whoami as an MCP tool. Converts action name 'auth.whoami' to 'auth_whoami' (line 78), registers it via mcpServer.tool(), builds ActionContext with session utilities, and handles authentication checks for actions requiring auth.

  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/actions/auth.ts:98-124 (schema)

  Action definition for auth.whoami including metadata: name ('auth.whoami'), description, riskTier (Safe), requiresAuth (true), and the handler function. No inputSchema is defined since the tool takes no parameters.

    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/protocol/types.ts:73-81 (helper)

  ActionContext interface definition providing utilities used by auth.whoami handler: getToken(), getBaseUrl(), getDefaultScope(), getOAuthCredentials(), getClient(), and username property.

  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;
  }