@memberjunction/server

The MemberJunction server package provides the complete API server infrastructure for MemberJunction applications. It delivers both GraphQL and REST APIs with a unified authentication layer, per-request transaction isolation, pluggable authentication providers, scope-based API key authorization, scheduled job orchestration, SQL logging, and built-in AI operation endpoints. This package is the primary integration point between client applications and the MemberJunction data layer.

Installation

npm install @memberjunction/server
Copy

Overview

MJServer acts as the central API gateway for MemberJunction, sitting between client applications (MJExplorer, external integrations, AI agents) and the SQL Server database via the @memberjunction/sqlserver-dataprovider. It initializes database connections, loads entity metadata, builds a GraphQL schema from dynamically discovered resolver modules, optionally exposes a REST API, and manages the full request lifecycle including authentication, per-request provider isolation, and transaction management.

flowchart TD
    subgraph Clients["Client Applications"]
        EX[MJ Explorer]
        EXT[External Apps]
        AI[AI Agents / MCP]
    end

    subgraph MJServer["@memberjunction/server"]
        direction TB
        AUTH[Authentication Layer]
        GQL[GraphQL API - Apollo Server]
        REST[REST API - Express Routes]
        CTX[Request Context & Provider Factory]
        RES[Resolver Layer]
        SCHED[Scheduled Jobs Service]
        SQLLOG[SQL Logging Manager]
    end

    subgraph Data["Data Layer"]
        SQLP[SQL Server Data Provider]
        DB[(SQL Server Database)]
    end

    Clients --> AUTH
    AUTH --> GQL
    AUTH --> REST
    GQL --> CTX
    REST --> CTX
    CTX --> RES
    RES --> SQLP
    SQLP --> DB
    SCHED --> SQLP

    style Clients fill:#2d6a9f,stroke:#1a4971,color:#fff
    style MJServer fill:#7c5295,stroke:#563a6b,color:#fff
    style Data fill:#2d8659,stroke:#1a5c3a,color:#fff
Copy

Key Features

• Dual API Support: GraphQL (Apollo Server) and REST APIs with consistent authentication and authorization
• Pluggable Authentication: Support for Azure AD/Entra ID (MSAL), Auth0, Okta, AWS Cognito, and Google via the IAuthProvider interface
• API Key Authorization: User-level (X-API-Key) and system-level (x-mj-api-key) API keys with scope-based access control
• Per-Request Provider Isolation: Each GraphQL request receives its own SQLServerDataProvider instance for transaction safety
• Multi-Database Support: Separate read-write and read-only database connection pools
• Transaction Management: Automatic transaction wrapping for GraphQL mutations with savepoint support
• Scheduled Jobs: Built-in job scheduler with configurable polling, concurrency limits, and lock management
• SQL Logging: Real-time SQL statement capture with session management, user filtering, and migration-format output
• AI Integration: Resolvers for AI prompt execution, agent orchestration, text embeddings, and Skip AI
• Real-time Support: WebSocket subscriptions via graphql-ws
• Response Compression: Built-in gzip compression with configurable thresholds
• Encryption Handling: Transparent field-level encryption/decryption with configurable API exposure policies
• CloudEvents: Optional CloudEvent emission for entity lifecycle events
• Telemetry: Configurable server-side telemetry with multiple verbosity levels
• Extensible Architecture: Custom resolvers, entity subclasses, and new user handling via @RegisterClass
• Server Extensions: Plugin architecture for auto-discovering and loading extension modules (webhooks, messaging adapters, custom integrations) via @RegisterClass + mj.config.cjs

Configuration

MJServer uses a layered configuration system with the following priority (highest to lowest):

1. Environment variables
2. mj.config.cjs file (discovered via cosmiconfig)
3. DEFAULT_SERVER_CONFIG hardcoded defaults

Environment Variables

Configuration File (mj.config.cjs)

module.exports = {
  dbHost: 'myserver.database.windows.net',
  dbDatabase: 'MemberJunction',
  dbUsername: 'mj_user',
  dbPassword: 'secret',
  mjCoreSchema: '__mj',
  graphqlPort: 4000,

  userHandling: {
    autoCreateNewUsers: true,
    newUserLimitedToAuthorizedDomains: false,
    newUserRoles: ['UI', 'Developer'],
    contextUserForNewUserCreation: 'admin@example.com',
    CreateUserApplicationRecords: true,
  },

  databaseSettings: {
    connectionTimeout: 45000,
    requestTimeout: 30000,
    metadataCacheRefreshInterval: 180000,
    connectionPool: {
      max: 50,
      min: 5,
      idleTimeoutMillis: 30000,
      acquireTimeoutMillis: 30000,
    },
  },

  // Engine pre-warm during startup: 'full' (all @RegisterForStartup engines run at
  // boot — MJAPI's default) or 'task' (skip pre-warm; engines lazy-load on first
  // touch — the CLI/mj-sync/CodeGen default). MJ_STARTUP_MODE overrides per
  // invocation. See the root CLAUDE.md "Startup Mode" section for the full
  // precedence chain and trade-offs.
  startup: {
    mode: 'full',
  },

  restApiOptions: {
    enabled: true,
    includeEntities: ['User*', 'Entity*'],
    excludeEntities: ['Password', 'APIKey*'],
    includeSchemas: ['public'],
    excludeSchemas: ['internal'],
  },

  scheduledJobs: {
    enabled: true,
    systemUserEmail: 'system@example.com',
    maxConcurrentJobs: 5,
  },

  sqlLogging: {
    enabled: true,
    allowedLogDirectory: './logs/sql',
    maxActiveSessions: 5,
    sessionTimeout: 3600000,
  },

  telemetry: {
    enabled: true,
    level: 'standard',  // 'minimal' | 'standard' | 'verbose' | 'debug'
  },

  // Debugging — see "Debugging GraphQL requests" below
  loggingSettings: {
    graphql: {
      logVariables: false, // env override: MJ_LOG_GRAPHQL_VARIABLES
    },
  },
};
Copy

Debugging GraphQL requests

By default, MJServer logs only the GraphQL operationName for each incoming request. The variables payload is never logged in the default configuration — this protects credentials and other sensitive material from leaking into container logs, cloud log aggregators, or tail -f sessions.

For local debugging, you can enable a redacted verbose echo of variables via the loggingSettings.graphql.logVariables flag (or the MJ_LOG_GRAPHQL_VARIABLES=true environment variable). When enabled:

• A second log line is emitted per root resolver call: { operation: '<name>', args: { ... } }
• Fields on Create<X>Input / Update<X>Input that map to an entity column with EntityFieldInfo.Encrypt=true are redacted automatically (metadata-driven).
• Fields or parameters explicitly marked with the @NoLog decorator are redacted manually (for custom resolvers and non-metadata-bound args).
• A boot-time audit warns about every custom-resolver @Arg that is neither metadata-bound nor @NoLog-marked, so authors know which arguments will appear in plaintext while the flag is active.
• The first call into any such resolver also emits a one-time runtime warning naming the un-decorated args.

Security notes:

• This flag is opt-in and defaults to false in every environment regardless of NODE_ENV. Never set it to true in production.
• It does NOT re-enable the historical variables leak. The default-config log line emits operation name only; the verbose echo is a separate, redaction-aware path.
• Custom resolvers that accept sensitive arguments (e.g. credential-test mutations) should mark those parameters with @NoLog from @memberjunction/server so they remain redacted even when verbose logging is on.

Enabling for a single session:

MJ_LOG_GRAPHQL_VARIABLES=true npm run start
Copy

Enabling persistently via mj.config.cjs:

loggingSettings: {
  graphql: {
    logVariables: true,
  },
}
Copy

Applying @NoLog to a custom resolver:

import { NoLog } from '@memberjunction/server';

@Mutation(() => Boolean)
async TestCredential(
  @Arg('accessToken') @NoLog accessToken: string,
  @Ctx() ctx: AppContext,
): Promise<boolean> {
  // ...
}
Copy

import { InputType, Field } from 'type-graphql';
import { NoLog } from '@memberjunction/server';

@InputType()
export class MyInput {
  @Field(() => String) @NoLog Token: string;
  @Field(() => String) Description: string;
}
Copy

Usage

Basic Server Setup

Import the serve function and provide paths to your custom resolver modules. The server automatically includes its own built-in resolvers.

import { serve } from '@memberjunction/server';
import { resolve } from 'node:path';

const localPath = (p: string) => resolve(__dirname, p);

const resolverPaths = [
  'resolvers/**/*Resolver.{js,ts}',
  'generic/*Resolver.{js,ts}',
  'generated/generated.ts',
];

serve(resolverPaths.map(localPath));
Copy

Advanced Server Options

The serve function accepts an optional MJServerOptions object for lifecycle hooks and REST API overrides.

import { serve, createApp, MJServerOptions } from '@memberjunction/server';

const options: MJServerOptions = {
  onBeforeServe: async () => {
    // Custom initialization after schema is built, before HTTP listen
    console.log('Server is about to start...');
  },
  restApiOptions: {
    enabled: true,
    includeEntities: ['User*', 'Entity*'],
    excludeEntities: ['Password', 'APIKey*'],
  },
};

serve(resolverPaths.map(localPath), createApp(), options);
Copy

Custom New User Handling

Override the default new user creation behavior by subclassing NewUserBase and registering it with a higher priority.

import { RegisterClass } from '@memberjunction/global';
import { NewUserBase } from '@memberjunction/server';

@RegisterClass(NewUserBase, undefined, 1)
export class CustomNewUserHandler extends NewUserBase {
  public override async createNewUser(
    firstName: string,
    lastName: string,
    email: string
  ) {
    // Custom logic: create linked records, assign roles, etc.
    return super.createNewUser(firstName, lastName, email, 'Other');
  }
}
Copy

Import the file before calling serve to ensure registration:

import './auth/customNewUserHandler';
import { serve } from '@memberjunction/server';
// ...
serve(resolverPaths);
Copy

Architecture

Request Lifecycle

sequenceDiagram
    participant C as Client
    participant A as Auth Layer
    participant CF as Context Factory
    participant R as Resolver
    participant P as SQLServerDataProvider
    participant DB as SQL Server

    C->>A: Request (Bearer token / API key)
    A->>A: Validate JWT or API key
    A->>A: Resolve UserInfo from UserCache
    A->>CF: Create request context
    CF->>P: New per-request provider instance
    P->>P: Reuse cached metadata
    CF->>R: Pass AppContext with providers
    R->>P: Execute operations
    P->>DB: SQL queries within transaction
    DB-->>P: Results
    P-->>R: Entity objects / data
    R-->>C: GraphQL / REST response
    Note over P,DB: Transaction auto-committed on success, rolled back on error
Copy

Per-Request Provider Isolation

Each GraphQL request receives its own SQLServerDataProvider instance, ensuring complete transaction isolation between concurrent requests. Metadata is cached and reused across providers for efficiency.

// Automatically created per request in context.ts:
const provider = new SQLServerDataProvider();
await provider.Config({
  connectionPool: pool,
  MJCoreSchemaName: '__mj',
  ignoreExistingMetadata: false,  // Reuse cached metadata
});

// Included in AppContext for resolvers:
context.providers = [
  { provider: readWriteProvider, type: 'Read-Write' },
  { provider: readOnlyProvider, type: 'Read-Only' },  // if configured
];
Copy

Authentication Architecture

MJServer uses a pluggable authentication provider system built on the IAuthProvider interface and AuthProviderFactory.

flowchart LR
    subgraph Providers["Auth Providers"]
        MSAL[MSAL / Azure AD]
        A0[Auth0]
        OK[Okta]
        COG[AWS Cognito]
        GOOG[Google]
    end

    subgraph Factory["AuthProviderFactory"]
        REG[Provider Registry]
        CACHE[Issuer Cache]
    end

    subgraph Auth["Authentication Flow"]
        JWT[JWT Token]
        APIKEY[API Key]
        SYS[System API Key]
    end

    JWT --> REG
    REG --> Providers
    APIKEY --> VAL[API Key Engine]
    SYS --> SYSUSER[System User Lookup]

    style Providers fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Factory fill:#7c5295,stroke:#563a6b,color:#fff
    style Auth fill:#b8762f,stroke:#8a5722,color:#fff
Copy

Providers are registered via @RegisterClass(BaseAuthProvider, 'type-key') and automatically discovered at startup. Each provider implements:

• validateConfig() -- Validates required configuration
• getSigningKey() -- Retrieves JWKS signing keys with retry logic
• extractUserInfo() -- Extracts email, name from provider-specific JWT claims
• matchesIssuer() -- Matches JWT iss claim to the provider

Configure providers in mj.config.cjs under authProviders or via environment variables (see Configuration section).

API Key Authentication

The server supports two types of API key authentication:

User API Keys (X-API-Key header, mj_sk_* format):

• Authenticate as a specific user
• Support expiration dates and individual revocation
• Subject to scope-based authorization
• Usage is logged for audit

System API Key (x-mj-api-key header):

• Single shared key set via MJ_API_KEY environment variable
• Authenticates as the system user with elevated privileges
• Used for server-to-server communication

Scope-Based Authorization

API keys are subject to a two-level scope evaluation: the application ceiling (maximum allowed scopes for MJAPI, MCP Server, etc.) and the individual key's assigned scopes.

Add scope checks to custom resolvers:

import { ResolverBase } from '@memberjunction/server';

@Resolver()
export class MyResolver extends ResolverBase {
  @Mutation(() => MyResult)
  async myOperation(@Ctx() ctx: AppContext): Promise<MyResult> {
    // Checks scope for API key auth; no-op for JWT auth
    await this.CheckAPIKeyScopeAuthorization('my:scope', 'resource-name', ctx.userPayload);
    // Proceed with operation...
  }
}
Copy

Alternatively, use the standalone utility functions:

import { CheckAPIKeyScope, RequireScope } from '@memberjunction/server';

// Standalone function
await CheckAPIKeyScope(ctx.userPayload.apiKeyId, 'view:run', ctx.userPayload.userRecord, {
  resource: 'Users',
});

// Pre-built scope checker
const requireViewRun = RequireScope('view:run');
await requireViewRun(ctx);
Copy

GraphQL API

Custom Directives

• @RequireSystemUser: Restricts a field or mutation to system-user-only access. Applied at the schema level; non-system users receive an AuthorizationError.
• @Public: Marks a field as publicly accessible without authentication. All other fields require an active, authenticated user by default.

Built-in Resolvers

The server includes resolvers for the following domains:

Transaction Management

GraphQL mutations are automatically wrapped in transactions through the per-request provider:

mutation {
  CreateUser(input: { FirstName: "John", LastName: "Doe" }) { ID }
  CreateUserRole(input: { UserID: "...", RoleID: "..." }) { ID }
}
# Both operations execute within the same provider's transaction scope.
# Success: both committed together. Error: both rolled back.
Copy

WebSocket Subscriptions

Real-time updates are supported via WebSocket at the same path as the GraphQL endpoint:

// Server-side: already configured
const webSocketServer = new WebSocketServer({
  server: httpServer,
  path: graphqlRootPath,
});
Copy

ResolverBase

All built-in resolvers extend ResolverBase, which provides:

REST API

In addition to GraphQL, MJServer provides a REST API at /api/v1/. By default it is disabled and can be enabled via configuration.

For comprehensive REST API documentation including endpoints, security configuration, wildcard filtering, and examples, see REST_API.md.

Key endpoints:

SQL Logging

The server includes a runtime SQL logging system for debugging and migration generation. Requires Owner-level user privileges.

# Start a logging session
mutation {
  startSqlLogging(input: {
    fileName: "debug-session.sql"
    filterToCurrentUser: true
    options: {
      sessionName: "Debug Session"
      prettyPrint: true
      statementTypes: "both"
      formatAsMigration: false
    }
  }) {
    id
    filePath
    sessionName
  }
}

# Query active sessions
query {
  activeSqlLoggingSessions {
    id
    sessionName
    statementCount
  }
}

# Stop a session
mutation {
  stopSqlLogging(sessionId: "session-id")
}
Copy

Configuration in mj.config.cjs:

sqlLogging: {
  enabled: true,
  allowedLogDirectory: './logs/sql',
  maxActiveSessions: 5,
  sessionTimeout: 3600000,
  autoCleanupEmptyFiles: true,
  defaultOptions: {
    formatAsMigration: false,
    statementTypes: 'both',  // 'queries' | 'mutations' | 'both'
    prettyPrint: true,
    logRecordChangeMetadata: false,
  },
}
Copy

Scheduled Jobs

MJServer integrates with the @memberjunction/scheduling-engine to execute scheduled jobs defined in MemberJunction metadata.

flowchart LR
    subgraph Config["Configuration"]
        CFG[mj.config.cjs]
    end

    subgraph Service["ScheduledJobsService"]
        INIT[Initialize]
        POLL[Start Polling]
        STOP[Stop Polling]
    end

    subgraph Engine["SchedulingEngine"]
        JOBS[Active Jobs]
        EXEC[Job Execution]
        LOCK[Lock Management]
    end

    CFG --> INIT
    INIT --> POLL
    POLL --> JOBS
    JOBS --> EXEC
    EXEC --> LOCK

    style Config fill:#b8762f,stroke:#8a5722,color:#fff
    style Service fill:#2d6a9f,stroke:#1a4971,color:#fff
    style Engine fill:#2d8659,stroke:#1a5c3a,color:#fff
Copy

Configuration:

scheduledJobs: {
  enabled: true,
  systemUserEmail: 'system@example.com',
  maxConcurrentJobs: 5,
  defaultLockTimeout: 600000,    // 10 minutes
  staleLockCleanupInterval: 300000, // 5 minutes
}
Copy

The service starts automatically during server initialization and shuts down gracefully on SIGTERM/SIGINT.

AI Integration

AI Prompt Execution

mutation {
  RunAIPrompt(input: {
    PromptName: "Summarize Content"
    ModelID: "model-guid"
    Temperature: 0.7
    Messages: [{ role: "user", content: "Summarize this article..." }]
  }) {
    Success
    Result
    TokenUsage { InputTokens OutputTokens }
  }
}
Copy

Simple Prompt Execution

mutation {
  ExecuteSimplePrompt(input: {
    SystemPrompt: "You are a helpful assistant."
    UserMessage: "What is MemberJunction?"
    ModelPowerLevel: "Standard"
  }) {
    Success
    Result
  }
}
Copy

Text Embeddings

mutation {
  EmbedText(input: {
    Texts: ["Hello world", "MemberJunction framework"]
    ModelSize: "small"
  }) {
    Success
    Embeddings
    Dimensions
    Model
  }
}
Copy

AI Agent Execution

mutation {
  RunAIAgent(input: {
    AgentID: "agent-guid"
    SessionID: "session-guid"
    UserMessage: "Find all active users"
  }) {
    Success
    Result
    SessionID
  }
}
Copy

All AI operations have system-user variants (e.g., RunAIPromptSystemUser) that use the @RequireSystemUser directive for server-to-server operations.

API Reference

Core Exports

Server Functions

Types

Authentication

Scope Authorization

Resolver Base Classes

Utility Functions

GraphQL Inputs

Directives

Performance

Response Compression

Responses larger than 1KB are automatically compressed using gzip at compression level 6. Binary content types (images, video, audio) are excluded.

Connection Pooling

Database connections are managed via mssql connection pools. Configure pool size in databaseSettings.connectionPool:

connectionPool: {
  max: 50,      // Maximum connections
  min: 5,       // Minimum connections
  idleTimeoutMillis: 30000,
  acquireTimeoutMillis: 30000,
}
Copy

Recommended settings:

• Development: max: 10, min: 2
• Production: max: 50, min: 5
• High load: max: 100, min: 10

Metadata Caching

Entity metadata is loaded once at startup and shared across all per-request provider instances. The cache refresh interval is configurable:

databaseSettings: {
  metadataCacheRefreshInterval: 180000,  // 3 minutes
}
Copy

Authentication Token Caching

Validated JWT tokens are cached using an LRU cache, avoiding repeated cryptographic verification for the same token within its lifetime.

Server Extensions

MJServer supports a plugin architecture that enables auto-discovery and lifecycle management of extension modules. Extensions register Express routes, handle their own authentication, and participate in health checks and graceful shutdown — all without modifying MJServer source code.

How It Works

1. Extensions implement BaseServerExtension from @memberjunction/server-extensions-core
2. Extensions register via @RegisterClass(BaseServerExtension, 'DriverClassName')
3. Configuration in mj.config.cjs defines which extensions to load
4. MJServer's ServerExtensionLoader discovers and initializes all enabled extensions at startup

Configuration

// mj.config.cjs
module.exports = {
    serverExtensions: [
        {
            Enabled: true,
            DriverClass: 'SlackMessagingExtension',
            RootPath: '/webhook/slack',
            Settings: {
                AgentID: 'your-agent-guid',
                BotToken: process.env.SLACK_BOT_TOKEN,
                SigningSecret: process.env.SLACK_SIGNING_SECRET,
            }
        },
        {
            Enabled: true,
            DriverClass: 'TeamsMessagingExtension',
            RootPath: '/webhook/teams',
            Settings: {
                AgentID: 'your-agent-guid',
                MicrosoftAppId: process.env.MICROSOFT_APP_ID,
                MicrosoftAppPassword: process.env.MICROSOFT_APP_PASSWORD,
            }
        }
    ]
};
Copy

Health Monitoring

MJServer exposes an aggregate health check endpoint for all loaded extensions:

GET /health/extensions
Copy

Returns 200 when all extensions are healthy, 503 when any extension reports unhealthy.

Available Extensions

Creating Custom Extensions

See @memberjunction/server-extensions-core for documentation on building custom extensions.

Graceful Shutdown

The server registers handlers for SIGTERM and SIGINT to:

1. Shut down all server extensions (in reverse order of loading)
2. Stop the scheduled jobs service
3. Close the HTTP server
4. Force-exit after a 10-second timeout if graceful shutdown stalls

Unhandled promise rejections are caught and logged without crashing the server.

Dependencies

Core MemberJunction Packages

AI Packages

Infrastructure Packages

Third-Party Dependencies

Related Packages

• @memberjunction/server-bootstrap -- Pre-built class registration manifest for tree-shaking prevention
• MJAPI -- Reference server application that consumes this package
• @memberjunction/core -- Core framework that MJServer exposes via API
• Caching & Pub/Sub Guide -- Comprehensive guide to caching architecture, Redis cross-server sync, and GraphQL cache invalidation subscriptions

Troubleshooting

Enable verbose logging:

DEBUG=mj:*
NODE_ENV=development
Copy

Knowledge Hub Resolvers

This package includes GraphQL resolvers for the Knowledge Hub:

• SearchKnowledgeResolver — Unified search combining vector similarity (Pinecone) with full-text search via Metadata.FullTextSearch() and RRF fusion
• VectorizeEntityResolver — Triggers entity vectorization via EntityVectorSyncer
• PipelineProgressResolver — GraphQL subscription for real-time pipeline progress
• FetchEntityVectorsResolver — Retrieves vectors and metadata from the vector database for a given entity document

See the Full-Text Search Guide for the complete FTS architecture.

FetchEntityVectorsResolver

Fetches vectors and their associated metadata from a vector database (e.g., Pinecone) for a specific entity document. Used by the clustering dashboard to obtain raw vectors for visualization.

How it works: The resolver performs a zero-vector query against the vector index with an entity metadata filter (Entity: { $eq: entityName }). Since the query vector is all zeros, similarity scores are meaningless -- the purpose is purely to retrieve vectors matching the entity filter. This approach is used because Pinecone's list API does not support metadata filtering, but the query API does.

query {
  FetchEntityVectors(
    entityDocumentID: "doc-uuid"
    maxRecords: 500
    filter: ""
  ) {
    Success
    Results {
      ID
      Values
      Metadata
    }
    TotalCount
    ElapsedMs
    ErrorMessage
  }
}
Copy

The resolver resolves the vector index for the entity document using a fallback chain: explicit VectorIndexID on the document, then matching by VectorDatabaseID + EmbeddingModelID.

Contributing

See the MemberJunction Contributing Guide for development setup and guidelines.