fa-mcp-sdk 0.2.146 → 0.2.182

package/cli-template/{fa-mcp-sdk-spec.md → FA-MCP-SDK.md}

@@ -79,7 +79,6 @@ const customAuthValidator: CustomAuthValidator = async (req): Promise<AuthResult
     return {
       success: true,
       authType: 'basic',
-      tokenType: 'custom',
       username: userID || 'unknown',
     };
   } else {
@@ -451,7 +450,7 @@ consul:
       description: <description> # <description> will be replaced by <package.json>.description at initialization
       tags: [] # If null or empty array - Will be pulled up from package.keywords at initialization
       meta:
-         # "About" page link template
+         # "Home" page link template
          who: 'http://{address}:{port}/'
    envCode: # Used to generate the service ID
       prod: {{consul.envCode.prod}} # Production environment code
@@ -497,7 +496,7 @@ swagger:
         description: "PROD server"
 
 uiColor:
-   # Font color of the header and a number of interface elements on the ABOUT page
+   # Font color of the header and a number of interface elements on the HOME page
    primary: '#0f65dc'
 
 webServer:
@@ -870,13 +869,12 @@ addErrorMessage(originalError, 'Database operation failed');
 ```typescript
 import {
   ICheckTokenResult,
-  checkToken,
+  checkJwtToken,
   generateToken
 } from 'fa-mcp-sdk';
 
 // Types used:
 export interface ICheckTokenResult {
-  inTokenType?: TTokenType          // 'permanent' | 'JWT'
   payload?: ITokenPayload,          // Token payload with user data
   errorReason?: string,             // Error message if validation failed
   isTokenDecrypted?: boolean,       // Whether token was successfully decrypted
@@ -888,16 +886,16 @@ export interface ITokenPayload {
   [key: string]: any,               // Additional payload data
 }
 
-// checkToken - validate token and return detailed result
+// checkJwtToken - validate token and return detailed result
 // Function Signature:
-const checkToken = (arg: {
+const checkJwtToken = (arg: {
   token: string,
   expectedUser?: string,
   expectedService?: string,
 }): ICheckTokenResult {...}
 
 // Example:
-const tokenResult = checkToken({
+const tokenResult = checkJwtToken({
   token: 'user_provided_token',
   expectedUser: 'john_doe',
   expectedService: 'my-mcp-server'
@@ -966,6 +964,193 @@ await generateTokenApp(); // Uses default configuration from appConfig
 //   domainController: 'dc.domain.com'
 ```
 
+#### Test Authentication Headers
+
+```typescript
+import { getAuthHeadersForTests } from 'fa-mcp-sdk';
+
+// getAuthHeadersForTests - automatically generate authentication headers for testing
+// Function Signature:
+function getAuthHeadersForTests(): object {...}
+
+// Determines authentication headers based on appConfig.webServer.auth configuration.
+// Returns Authorization header using the first valid auth method found.
+//
+// Priority order (CPU-optimized, fastest first):
+// 1. permanentServerTokens - if at least one token is defined
+// 2. basic auth - if username AND password are both set
+// 3. JWT token - if jwtToken.encryptKey is set, generates token on the fly
+//
+// Returns empty object if auth is not enabled or no valid method configured.
+
+// Examples:
+const headers = getAuthHeadersForTests();
+
+// Use in fetch requests
+const response = await fetch('http://localhost:3000/mcp', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    ...headers  // Automatically adds Authorization header if auth is enabled
+  },
+  body: JSON.stringify(requestBody)
+});
+
+// Use with test clients
+import { McpHttpClient } from 'fa-mcp-sdk';
+
+const client = new McpHttpClient('http://localhost:3000');
+const authHeaders = getAuthHeadersForTests();
+const result = await client.callTool('my_tool', { query: 'test' }, authHeaders);
+
+// Return value examples based on configuration:
+
+// If permanentServerTokens configured:
+// { Authorization: 'Bearer server-token-1' }
+
+// If basic auth configured:
+// { Authorization: 'Basic YWRtaW46cGFzc3dvcmQ=' }  // base64 of 'admin:password'
+
+// If JWT encryptKey configured:
+// { Authorization: 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...' }
+
+// If auth.enabled = false or no valid method:
+// {}
+
+// Typical test setup:
+import { getAuthHeadersForTests, appConfig } from 'fa-mcp-sdk';
+
+describe('MCP Server Tests', () => {
+  const baseUrl = `http://localhost:${appConfig.webServer.port}`;
+  const authHeaders = getAuthHeadersForTests();
+
+  it('should call tool with authentication', async () => {
+    const response = await fetch(`${baseUrl}/mcp`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...authHeaders
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'tools/call',
+        params: { name: 'my_tool', arguments: { query: 'test' } },
+        id: 1
+      })
+    });
+
+    expect(response.ok).toBe(true);
+  });
+});
+```
+
+#### Token Generator Authorization Handler
+
+The Token Generator admin page (`/admin/`) can be protected with an additional 
+custom authorization layer beyond the standard authentication. This allows you 
+to implement fine-grained access control, such as restricting access to specific 
+AD groups or roles.
+
+##### Types
+
+```typescript
+import { TokenGenAuthHandler, TokenGenAuthInput, AuthResult } from 'fa-mcp-sdk';
+
+// Input data passed to the authorization handler
+interface TokenGenAuthInput {
+  user: string;                    // Username from authentication
+  domain?: string;                 // Domain (only for NTLM auth)
+  payload?: Record<string, any>;   // JWT payload (only for jwtToken auth)
+  authType: 'jwtToken' | 'basic' | 'ntlm' | 'permanentServerTokens';
+}
+
+// Authorization handler function type
+type TokenGenAuthHandler = (input: TokenGenAuthInput) => Promise<AuthResult> | AuthResult;
+```
+
+##### Configuration
+
+Add `tokenGenAuthHandler` to your `McpServerData` in `src/start.ts`:
+
+```typescript
+import { initMcpServer, McpServerData, TokenGenAuthHandler, initADGroupChecker } from 'fa-mcp-sdk';
+
+// Example 1: Restrict to specific AD groups (NTLM authentication)
+const { isUserInGroup } = initADGroupChecker();
+
+const tokenGenAuthHandler: TokenGenAuthHandler = async (input) => {
+  // Only check for NTLM-authenticated users
+  if (input.authType === 'ntlm') {
+    const isAdmin = await isUserInGroup(input.user, 'TokenGeneratorAdmins');
+    if (!isAdmin) {
+      return {
+        success: false,
+        error: `User ${input.user} is not authorized to access Token Generator`,
+      };
+    }
+  }
+  return { success: true, username: input.user };
+};
+
+// Example 2: Check JWT payload for specific claims
+const tokenGenAuthHandler: TokenGenAuthHandler = async (input) => {
+  if (input.authType === 'jwtToken') {
+    const roles = input.payload?.roles || [];
+    if (!roles.includes('token-admin')) {
+      return {
+        success: false,
+        error: 'Missing required role: token-admin',
+      };
+    }
+  }
+  return { success: true, username: input.user };
+};
+
+// Example 3: Simple whitelist check
+const allowedUsers = ['admin', 'john.doe', 'jane.smith'];
+
+const tokenGenAuthHandler: TokenGenAuthHandler = (input) => {
+  if (!allowedUsers.includes(input.user.toLowerCase())) {
+    return {
+      success: false,
+      error: `User ${input.user} is not in the allowed users list`,
+    };
+  }
+  return { success: true, username: input.user };
+};
+
+// Use in McpServerData
+const serverData: McpServerData = {
+  tools,
+  toolHandler: handleToolCall,
+  agentBrief: AGENT_BRIEF,
+  agentPrompt: AGENT_PROMPT,
+
+  // Add custom authorization for Token Generator
+  tokenGenAuthHandler,
+
+  // ... other configuration
+};
+
+await initMcpServer(serverData);
+```
+
+##### Behavior
+
+- **If `tokenGenAuthHandler` is not provided**: All authenticated users can access Token Generator
+- **If handler returns `{ success: true }`**: User is authorized
+- **If handler returns `{ success: false, error: '...' }`**: User receives 403 Forbidden with error message
+- **Handler errors**: Caught and returned as 403 with error message
+
+##### Auth Type Input Details
+
+| Auth Type | `user` | `domain` | `payload` |
+|-----------|--------|----------|-----------|
+| `ntlm` | NTLM username | NTLM domain | - |
+| `basic` | Basic auth username | - | - |
+| `jwtToken` | JWT `user` claim | - | Full JWT payload |
+| `permanentServerTokens` | "Unknown" | - | - |
+
 #### Multi-Authentication System
 
 The FA-MCP-SDK supports a comprehensive multi-authentication system that allows multiple authentication methods to work together with CPU-optimized performance ordering.
@@ -979,7 +1164,6 @@ import {
   AuthDetectionResult,
   CustomAuthValidator,
   checkMultiAuth,
-  checkCombinedAuth,
   detectAuthConfiguration,
   logAuthConfiguration,
   createAuthMW,         // Universal authentication middleware
@@ -987,19 +1171,19 @@ import {
 } from 'fa-mcp-sdk';
 
 // Authentication types in CPU priority order (low to high cost)
-export type AuthType = 'permanentServerTokens' | 'basic' | 'jwtToken';
+export type AuthType = 'permanentServerTokens' | 'jwtToken' | 'basic' | 'custom';
 
 // Custom Authentication validator function (black box - receives full request)
 export type CustomAuthValidator = (req: any) => Promise<AuthResult> | AuthResult;
 
 // Authentication result interface
 export interface AuthResult {
-  success: boolean;
-  error?: string;
-  authType?: AuthType;
-  tokenType?: string;
-  username?: string;
-  payload?: any;
+   success: boolean;
+   error?: string;
+   authType?: AuthType;
+   username?: string;
+   isTokenDecrypted?: boolean; // only for JWT
+   payload?: any;
 }
 
 // Authentication detection result
@@ -1026,24 +1210,6 @@ if (result.success) {
   console.log('Authentication failed:', result.error);
 }
 
-// checkCombinedAuth - validate using configured auth + custom validator
-// Function Signature:
-async function checkCombinedAuth( req: any ): Promise<AuthResult> {...}
-
-// This is the enhanced function that:
-// 1. Runs standard MCP auth methods (if configured)
-// 2. Additionally runs custom validator (if configured)
-// 3. Can use custom validator as fallback if standard auth fails
-
-// Example:
-const authResult = await checkCombinedAuth(req);
-
-if (authResult.success) {
-  console.log(`Authentication successful via ${authResult.authType}`);
-} else {
-  console.log('Combined authentication failed:', authResult.error);
-}
-
 // detectAuthConfiguration - analyze auth configuration
 // Function Signature:
 function detectAuthConfiguration(): AuthDetectionResult {...}
@@ -1088,7 +1254,6 @@ app.get('/api/protected', (req, res) => {
     message: 'Access granted',
     authType: authInfo?.authType,
     username: authInfo?.username,
-    tokenType: authInfo?.tokenType
   });
 });
 
@@ -1119,7 +1284,7 @@ function createAuthMW(options?: {
 async function getMultiAuthError(req: Request): Promise<{ code: number, message: string } | undefined>
 
 // Returns error object if authentication failed, undefined if successful
-// Uses checkCombinedAuth internally - supports all authentication methods
+// Uses checkMultiAuth internally - supports all authentication methods
 
 // Example - Custom middleware with different auth levels
 app.use('/api/custom', async (req, res, next) => {
@@ -1174,7 +1339,6 @@ const databaseAuthValidator: CustomAuthValidator = async (req): Promise<AuthResu
         return {
           success: true,
           authType: 'basic',
-          tokenType: 'basic',
           username: dbUser.username,
           payload: { userId: dbUser.id, roles: dbUser.roles }
         };
@@ -1187,7 +1351,6 @@ const databaseAuthValidator: CustomAuthValidator = async (req): Promise<AuthResu
         return {
           success: true,
           authType: 'basic',
-          tokenType: 'apiKey',
           username: username,
           payload: { apiKey: apiKey.substring(0, 8) + '...' }
         };
@@ -1226,7 +1389,6 @@ const ipBasedAuthValidator: CustomAuthValidator = async (req): Promise<AuthResul
     return {
       success: true,
       authType: 'basic',
-      tokenType: 'ipBased',
       username: `ip-${clientIP}`,
       payload: { clientIP, userAgent, accessTime: new Date().toISOString() }
     };
@@ -1261,7 +1423,6 @@ const externalServiceAuthValidator: CustomAuthValidator = async (req): Promise<A
       return {
         success: true,
         authType: 'basic',
-        tokenType: 'external',
         username: result.username || clientId,
         payload: {
           clientId,
@@ -1303,7 +1464,6 @@ const mfaAuthValidator: CustomAuthValidator = async (req): Promise<AuthResult> =
       return {
         success: true,
         authType: 'basic',
-        tokenType: 'mfa',
         username: username,
         payload: {
           userId: user.id,
@@ -1351,7 +1511,6 @@ app.post('/test-token', async (req, res) => {
     res.json({
       valid: result.success,
       authType: result.authType,
-      tokenType: result.tokenType,
       error: result.error,
       username: result.username,
       hasPayload: !!result.payload
@@ -1412,6 +1571,504 @@ curl -H "Authorization: Bearer token123" \
 
 The multi-authentication system automatically tries authentication methods in CPU-optimized order (fastest first) and returns on the first successful match, providing both performance and flexibility.
 
+### Check if a user belongs to an AD group
+
+#### Configuration (`config/local.yaml`)
+
+```yaml
+ad:
+  domains:
+    MYDOMAIN:
+      default: true
+      controllers: ['ldap://dc1.corp.com']
+      username: 'svc_account@corp.com'
+      password: '***'
+      # baseDn: 'DC=corp,DC=com'  # Optional, auto-derived from controller URL
+```
+
+#### Usage
+
+```typescript
+import { initADGroupChecker } from 'fa-mcp-sdk';
+
+const { isUserInGroup, groupChecker } = initADGroupChecker();
+
+const isAdmin = await isUserInGroup('john.doe', 'Admins');
+const isDeveloper = await isUserInGroup('john.doe', 'Developers');
+
+groupChecker.clearCache();  // Clear cache if needed
+```
+
+### Advanced Authorization with AD Group Membership
+
+This section demonstrates how to implement additional authorization based on Active Directory (AD)
+group membership. These examples assume JWT token authentication (`jwtToken`) is configured,
+and the user information is extracted from the JWT payload.
+
+#### Configuration for AD Group Authorization
+
+First, extend your configuration to include the required AD group:
+
+**`src/_types_/custom-config.ts`:**
+```typescript
+import { AppConfig } from 'fa-mcp-sdk';
+
+export interface IGroupAccessConfig {
+  groupAccess: {
+    /** AD group required for access */
+    requiredGroup: string;
+    /** Bypass group check for debugging (default: false) */
+    bypassGroupCheck?: boolean;
+    /** Cache TTL in seconds (default: 300) */
+    cacheTtlSeconds?: number;
+  };
+}
+
+export interface CustomAppConfig extends AppConfig, IGroupAccessConfig {}
+```
+
+**`config/default.yaml`:**
+```yaml
+groupAccess:
+  requiredGroup: "DOMAIN\\MCP-Users"
+  bypassGroupCheck: false
+  cacheTtlSeconds: 300
+```
+
+#### Example 1: HTTP Server Level Access Restriction
+
+This example uses `customAuthValidator` to check AD group membership at the HTTP server level.
+If the user is not in the required group, a 403 Forbidden error is returned before any
+MCP request processing.
+
+**`src/start.ts`:**
+```typescript
+import {
+  appConfig,
+  initMcpServer,
+  McpServerData,
+  CustomAuthValidator,
+  AuthResult,
+  initADGroupChecker,
+  checkJwtToken,
+} from 'fa-mcp-sdk';
+import { tools } from './tools/tools.js';
+import { handleToolCall } from './tools/handle-tool-call.js';
+import { AGENT_BRIEF } from './prompts/agent-brief.js';
+import { AGENT_PROMPT } from './prompts/agent-prompt.js';
+import { CustomAppConfig } from './_types_/custom-config.js';
+
+// Get typed config
+const config = appConfig as CustomAppConfig;
+
+// Initialize AD group checker
+const { isUserInGroup } = initADGroupChecker();
+
+/**
+ * Custom authentication validator with AD group membership check
+ * Returns 403 Forbidden if user is not in the required AD group
+ */
+const customAuthValidator: CustomAuthValidator = async (req): Promise<AuthResult> => {
+  const authHeader = req.headers.authorization;
+
+  if (!authHeader?.startsWith('Bearer ')) {
+    return { success: false, error: 'Missing or invalid Authorization header' };
+  }
+
+  const token = authHeader.slice(7);
+
+  // Validate JWT token
+  const tokenResult = checkJwtToken({ token });
+  if (tokenResult.errorReason) {
+    return { success: false, error: tokenResult.errorReason };
+  }
+
+  const payload = tokenResult.payload;
+  if (!payload?.user) {
+    return { success: false, error: 'Invalid token: missing user' };
+  }
+
+  const username = payload.user;
+
+  // Bypass group check if configured (for debugging)
+  if (config.groupAccess.bypassGroupCheck) {
+    return {
+      success: true,
+      authType: 'jwtToken',
+      username,
+      payload,
+      isTokenDecrypted: tokenResult.isTokenDecrypted,
+    };
+  }
+
+  // Check AD group membership
+  const requiredGroup = config.groupAccess.requiredGroup;
+  try {
+    const isInGroup = await isUserInGroup(username, requiredGroup);
+
+    if (!isInGroup) {
+      return {
+        success: false,
+        error: `Forbidden: User '${username}' is not a member of group '${requiredGroup}'`,
+      };
+    }
+
+    return {
+      success: true,
+      authType: 'jwtToken',
+      username,
+      payload,
+      isTokenDecrypted: tokenResult.isTokenDecrypted,
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      error: `AD group check failed: ${errorMessage}`,
+    };
+  }
+};
+
+const startProject = async (): Promise<void> => {
+  const serverData: McpServerData = {
+    tools,
+    toolHandler: handleToolCall,
+    agentBrief: AGENT_BRIEF,
+    agentPrompt: AGENT_PROMPT,
+
+    // Enable custom authentication with AD group check
+    customAuthValidator,
+
+    // ... other configuration
+  };
+
+  await initMcpServer(serverData);
+};
+
+startProject().catch(console.error);
+```
+
+**Result**: If the user is not in the required AD group, they receive HTTP 403 Forbidden
+response before any MCP processing occurs.
+
+#### Example 2: Access Restriction to ALL MCP Tools
+
+This example restricts access to all MCP tools by checking AD group membership in the
+`toolHandler` function. If the user is not in the required group, the tool call returns
+an MCP error with "Forbidden" message.
+
+**`src/tools/handle-tool-call.ts`:**
+```typescript
+import {
+  formatToolResult,
+  ToolExecutionError,
+  logger,
+  appConfig,
+  initADGroupChecker,
+} from 'fa-mcp-sdk';
+import { CustomAppConfig } from '../_types_/custom-config.js';
+
+// Get typed config
+const config = appConfig as CustomAppConfig;
+
+// Initialize AD group checker
+const { isUserInGroup } = initADGroupChecker();
+
+/**
+ * Check if user has access to MCP tools based on AD group membership
+ */
+async function checkToolAccess(payload: { user: string; [key: string]: any } | undefined): Promise<void> {
+  // Skip check if bypass is enabled
+  if (config.groupAccess.bypassGroupCheck) {
+    return;
+  }
+
+  if (!payload?.user) {
+    throw new ToolExecutionError('authorization', 'Forbidden: User information not available');
+  }
+
+  const username = payload.user;
+  const requiredGroup = config.groupAccess.requiredGroup;
+
+  try {
+    const isInGroup = await isUserInGroup(username, requiredGroup);
+
+    if (!isInGroup) {
+      throw new ToolExecutionError(
+        'authorization',
+        `Forbidden: User '${username}' is not authorized to use MCP tools. ` +
+        `Required group: '${requiredGroup}'`
+      );
+    }
+  } catch (error) {
+    if (error instanceof ToolExecutionError) {
+      throw error;
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new ToolExecutionError('authorization', `Forbidden: AD group check failed - ${errorMessage}`);
+  }
+}
+
+export const handleToolCall = async (params: {
+  name: string;
+  arguments?: any;
+  headers?: Record<string, string>;
+  payload?: { user: string; [key: string]: any };
+}): Promise<any> => {
+  const { name, arguments: args, headers, payload } = params;
+
+  logger.info(`Tool called: ${name} by user: ${payload?.user || 'unknown'}`);
+
+  // Check AD group membership for ALL tools
+  await checkToolAccess(payload);
+
+  try {
+    switch (name) {
+      case 'my_tool':
+        return await handleMyTool(args);
+      case 'another_tool':
+        return await handleAnotherTool(args);
+      default:
+        throw new ToolExecutionError(name, `Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    logger.error(`Tool execution failed for ${name}:`, error);
+    throw error;
+  }
+};
+
+async function handleMyTool(args: any): Promise<any> {
+  // Tool implementation
+  return formatToolResult({ message: 'Tool executed successfully', args });
+}
+
+async function handleAnotherTool(args: any): Promise<any> {
+  // Tool implementation
+  return formatToolResult({ message: 'Another tool executed', args });
+}
+```
+
+**Result**: If the user is not in the required AD group, any tool call returns an MCP error:
+```json
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32603,
+    "message": "Forbidden: User 'john.doe' is not authorized to use MCP tools. Required group: 'DOMAIN\\MCP-Users'"
+  },
+  "id": 1
+}
+```
+
+#### Example 3: Access Restriction to a SPECIFIC MCP Tool
+
+This example restricts access to specific MCP tools based on AD group membership.
+Different tools can require different AD groups.
+
+**`src/_types_/custom-config.ts`:**
+```typescript
+import { AppConfig } from 'fa-mcp-sdk';
+
+export interface IToolGroupAccessConfig {
+  toolGroupAccess: {
+    /** Default group required for tools without specific configuration */
+    defaultGroup?: string;
+    /** Specific group requirements per tool */
+    tools: Record<string, {
+      /** AD group required for this tool */
+      requiredGroup: string;
+      /** Allow access without group check (default: false) */
+      public?: boolean;
+    }>;
+    /** Bypass all group checks (for debugging) */
+    bypassGroupCheck?: boolean;
+  };
+}
+
+export interface CustomAppConfig extends AppConfig, IToolGroupAccessConfig {}
+```
+
+**`config/default.yaml`:**
+```yaml
+toolGroupAccess:
+  defaultGroup: "DOMAIN\\MCP-Users"
+  bypassGroupCheck: false
+  tools:
+    get_public_data:
+      public: true  # No group check required
+    get_user_data:
+      requiredGroup: "DOMAIN\\MCP-Users"
+    modify_data:
+      requiredGroup: "DOMAIN\\MCP-DataModifiers"
+    admin_operation:
+      requiredGroup: "DOMAIN\\MCP-Admins"
+```
+
+**`src/tools/handle-tool-call.ts`:**
+```typescript
+import {
+  formatToolResult,
+  ToolExecutionError,
+  logger,
+  appConfig,
+  initADGroupChecker,
+} from 'fa-mcp-sdk';
+import { CustomAppConfig } from '../_types_/custom-config.js';
+
+// Get typed config
+const config = appConfig as CustomAppConfig;
+
+// Initialize AD group checker
+const { isUserInGroup } = initADGroupChecker();
+
+/**
+ * Check if user has access to a specific tool based on AD group membership
+ */
+async function checkToolAccess(
+  toolName: string,
+  payload: { user: string; [key: string]: any } | undefined
+): Promise<void> {
+  const toolAccess = config.toolGroupAccess;
+
+  // Skip check if bypass is enabled
+  if (toolAccess.bypassGroupCheck) {
+    return;
+  }
+
+  const toolConfig = toolAccess.tools[toolName];
+
+  // If tool is marked as public, allow access
+  if (toolConfig?.public) {
+    return;
+  }
+
+  // Check user availability
+  if (!payload?.user) {
+    throw new ToolExecutionError(
+      toolName,
+      `Forbidden: User information not available for tool '${toolName}'`
+    );
+  }
+
+  const username = payload.user;
+
+  // Determine required group: tool-specific or default
+  const requiredGroup = toolConfig?.requiredGroup || toolAccess.defaultGroup;
+
+  if (!requiredGroup) {
+    // No group configured - allow access
+    return;
+  }
+
+  try {
+    const isInGroup = await isUserInGroup(username, requiredGroup);
+
+    if (!isInGroup) {
+      throw new ToolExecutionError(
+        toolName,
+        `Forbidden: User '${username}' is not authorized to use tool '${toolName}'. ` +
+        `Required group: '${requiredGroup}'`
+      );
+    }
+
+    logger.info(`User '${username}' authorized for tool '${toolName}' via group '${requiredGroup}'`);
+  } catch (error) {
+    if (error instanceof ToolExecutionError) {
+      throw error;
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    throw new ToolExecutionError(
+      toolName,
+      `Forbidden: AD group check failed for tool '${toolName}' - ${errorMessage}`
+    );
+  }
+}
+
+export const handleToolCall = async (params: {
+  name: string;
+  arguments?: any;
+  headers?: Record<string, string>;
+  payload?: { user: string; [key: string]: any };
+}): Promise<any> => {
+  const { name, arguments: args, headers, payload } = params;
+
+  logger.info(`Tool called: ${name} by user: ${payload?.user || 'unknown'}`);
+
+  // Check AD group membership for the specific tool
+  await checkToolAccess(name, payload);
+
+  try {
+    switch (name) {
+      case 'get_public_data':
+        // Public tool - no group check was performed
+        return await handleGetPublicData(args);
+
+      case 'get_user_data':
+        // Requires MCP-Users group
+        return await handleGetUserData(args);
+
+      case 'modify_data':
+        // Requires MCP-DataModifiers group
+        return await handleModifyData(args);
+
+      case 'admin_operation':
+        // Requires MCP-Admins group
+        return await handleAdminOperation(args);
+
+      default:
+        // Unknown tools use defaultGroup if configured
+        throw new ToolExecutionError(name, `Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    logger.error(`Tool execution failed for ${name}:`, error);
+    throw error;
+  }
+};
+
+async function handleGetPublicData(args: any): Promise<any> {
+  return formatToolResult({ message: 'Public data retrieved', data: { public: true } });
+}
+
+async function handleGetUserData(args: any): Promise<any> {
+  return formatToolResult({ message: 'User data retrieved', data: args });
+}
+
+async function handleModifyData(args: any): Promise<any> {
+  return formatToolResult({ message: 'Data modified', modified: args });
+}
+
+async function handleAdminOperation(args: any): Promise<any> {
+  return formatToolResult({ message: 'Admin operation completed', operation: args });
+}
+```
+
+**Result**: Each tool enforces its own AD group requirements:
+- `get_public_data` - accessible to everyone (public)
+- `get_user_data` - requires `DOMAIN\MCP-Users` group
+- `modify_data` - requires `DOMAIN\MCP-DataModifiers` group
+- `admin_operation` - requires `DOMAIN\MCP-Admins` group
+
+If a user tries to call a tool without being in the required group:
+```json
+{
+  "jsonrpc": "2.0",
+  "error": {
+    "code": -32603,
+    "message": "Forbidden: User 'john.doe' is not authorized to use tool 'admin_operation'. Required group: 'DOMAIN\\MCP-Admins'"
+  },
+  "id": 1
+}
+```
+
+#### Summary: Authorization Levels
+
+| Level | Location | Error Type | Use Case |
+|-------|----------|------------|----------|
+| HTTP Server | `customAuthValidator` | HTTP 403 Forbidden | Block unauthorized users completely |
+| All Tools | `toolHandler` (global check) | MCP Tool Error | Allow HTTP access, restrict all tool usage |
+| Specific Tool | `toolHandler` (per-tool check) | MCP Tool Error | Fine-grained tool-level permissions |
+
+
 ### Utility Functions
 
 #### General Utilities