fa-mcp-sdk 0.4.3 → 0.4.6

package/src/template/_types_/custom-config.ts

@@ -1,83 +1,83 @@
-/**
- * An example of extending the fa-mcp-sdk configuration with a custom settings block.
- *
- * This file demonstrates how to add your own settings
- * (for example, to check the user's membership in an AEC group).
- */
-
-import { AppConfig } from '../../core/index.js';
-
-/**
- * AD Group Membership Verification Settings
- */
-export interface IGroupAccessConfig {
-  groupAccess: {
-    /** AD Group whose membership is required for access */
-    requiredGroup: string;
-
-    /** Optional: Allow access without checking the group (for debugging) */
-    bypassGroupCheck?: boolean;
-
-    /** Optional: cache the result of the check (seconds) */
-    cacheTtlSeconds?: number;
-
-    /** Optional: List of groups with different access levels */
-    accessLevels?: {
-      /** Full access group (read/write) */
-      fullAccess?: string;
-      /** Read-only group */
-      readOnly?: string;
-      /** Administrators group */
-      admin?: string;
-    };
-  };
-}
-
-/**
- * Extended app config with group checking settings
- */
-export interface CustomAppConfig extends AppConfig, IGroupAccessConfig {}
-
-// ========================================================================
-// YAML CONFIGURATION EXAMPLE (config/default.yaml)
-// ========================================================================
-/*
-groupAccess:
-  requiredGroup: "DOMAIN\\MCP-Users"
-  bypassGroupCheck: false
-  cacheTtlSeconds: 300
-  accessLevels:
-    fullAccess: "DOMAIN\\MCP-FullAccess"
-    readOnly: "DOMAIN\\MCP-ReadOnly"
-    admin: "DOMAIN\\MCP-Admins"
-*/
-
-// ========================================================================
-// EXAMPLE OF USE IN CODE
-// ========================================================================
-/*
-import { appConfig } from '../core/index.js';
-
-// TYPED ACCESS TO CUSTOM SETTINGS
-const config = appConfig as CustomAppConfig;
-
-const requiredGroup = config.groupAccess.requiredGroup;
-const shouldBypass = config.groupAccess.bypassGroupCheck;
-
-// Checking the Access Level from Payload
-function getUserAccessLevel(payload: { user: string; groups?: string[] }): 'admin' | 'full' | 'readonly' | 'none' {
-  const { accessLevels } = config.groupAccess;
-  const userGroups = payload.groups || [];
-
-  if (accessLevels?.admin && userGroups.includes(accessLevels.admin)) {
-    return 'admin';
-  }
-  if (accessLevels?.fullAccess && userGroups.includes(accessLevels.fullAccess)) {
-    return 'full';
-  }
-  if (accessLevels?.readOnly && userGroups.includes(accessLevels.readOnly)) {
-    return 'readonly';
-  }
-  return 'none';
-}
-*/
+/**
+ * An example of extending the fa-mcp-sdk configuration with a custom settings block.
+ *
+ * This file demonstrates how to add your own settings
+ * (for example, to check the user's membership in an AEC group).
+ */
+
+import { AppConfig } from '../../core/index.js';
+
+/**
+ * AD Group Membership Verification Settings
+ */
+export interface IGroupAccessConfig {
+  groupAccess: {
+    /** AD Group whose membership is required for access */
+    requiredGroup: string;
+
+    /** Optional: Allow access without checking the group (for debugging) */
+    bypassGroupCheck?: boolean;
+
+    /** Optional: cache the result of the check (seconds) */
+    cacheTtlSeconds?: number;
+
+    /** Optional: List of groups with different access levels */
+    accessLevels?: {
+      /** Full access group (read/write) */
+      fullAccess?: string;
+      /** Read-only group */
+      readOnly?: string;
+      /** Administrators group */
+      admin?: string;
+    };
+  };
+}
+
+/**
+ * Extended app config with group checking settings
+ */
+export interface CustomAppConfig extends AppConfig, IGroupAccessConfig {}
+
+// ========================================================================
+// YAML CONFIGURATION EXAMPLE (config/default.yaml)
+// ========================================================================
+/*
+groupAccess:
+  requiredGroup: "DOMAIN\\MCP-Users"
+  bypassGroupCheck: false
+  cacheTtlSeconds: 300
+  accessLevels:
+    fullAccess: "DOMAIN\\MCP-FullAccess"
+    readOnly: "DOMAIN\\MCP-ReadOnly"
+    admin: "DOMAIN\\MCP-Admins"
+*/
+
+// ========================================================================
+// EXAMPLE OF USE IN CODE
+// ========================================================================
+/*
+import { appConfig } from '../core/index.js';
+
+// TYPED ACCESS TO CUSTOM SETTINGS
+const config = appConfig as CustomAppConfig;
+
+const requiredGroup = config.groupAccess.requiredGroup;
+const shouldBypass = config.groupAccess.bypassGroupCheck;
+
+// Checking the Access Level from Payload
+function getUserAccessLevel(payload: { user: string; groups?: string[] }): 'admin' | 'full' | 'readonly' | 'none' {
+  const { accessLevels } = config.groupAccess;
+  const userGroups = payload.groups || [];
+
+  if (accessLevels?.admin && userGroups.includes(accessLevels.admin)) {
+    return 'admin';
+  }
+  if (accessLevels?.fullAccess && userGroups.includes(accessLevels.fullAccess)) {
+    return 'full';
+  }
+  if (accessLevels?.readOnly && userGroups.includes(accessLevels.readOnly)) {
+    return 'readonly';
+  }
+  return 'none';
+}
+*/

package/src/template/api/router.ts

@@ -1,89 +1,86 @@
-import { Router, Request, Response } from 'express';
-import { Route, Get, Tags } from 'tsoa';
-import { logger, createAuthMW } from '../../core/index.js';
-
-export const apiRouter: Router | null = Router();
-
-// Create universal auth middleware
-const authMW = createAuthMW();
-
-// Example response interfaces for tsoa
-export interface ExampleResponse {
-  success: boolean;
-  message: string;
-  data: {
-    timestamp: string;
-  };
-}
-
-/**
- * Example TSOA Controller
- * This demonstrates how to use tsoa decorators for automatic OpenAPI generation
- */
-@Route('api')
-export class ExampleController {
-  /**
-   * Example protected endpoint
-   * Template endpoint - customize as needed
-   */
-  @Get('example')
-  @Tags('Example')
-  public async getExample (): Promise<ExampleResponse> {
-    try {
-      logger.info('Example endpoint called');
-
-      return {
-        success: true,
-        message: 'This is a template endpoint',
-        data: {
-          timestamp: new Date().toISOString(),
-        },
-      };
-    } catch (error) {
-      logger.error('Error in example endpoint:', error);
-      throw new Error(error instanceof Error ? error.message : 'Unknown error');
-    }
-  }
-
-  /**
-   * Health check endpoint
-   * Simple health check for monitoring
-   */
-  @Get('health')
-  @Tags('Server')
-  public async getHealth (): Promise<{
-    status: string;
-    timestamp: string;
-    version: string;
-  }> {
-    const { appConfig } = await import('../../core/index.js');
-
-    return {
-      status: 'ok',
-      timestamp: new Date().toISOString(),
-      version: appConfig.version || '1.0.0',
-    };
-  }
-}
-
-// Manual Express routes for backward compatibility and custom endpoints
-// Example protected endpoint using auth middleware
-apiRouter.get('/example', authMW, async (req: Request, res: Response) => {
-  try {
-    logger.info('Example endpoint called');
-
-    res.json({
-      success: true,
-      message: 'This is a template endpoint',
-      data: {
-        timestamp: new Date().toISOString(),
-      },
-    });
-  } catch (error) {
-    logger.error('Error in example endpoint:', error);
-    res.status(500).json({
-      success: false,
-      error: error instanceof Error ? error.message : 'Unknown error',
-    });
-  }
-});
+import { Router, Request, Response } from 'express';
+import { Route, Get, Tags } from 'tsoa';
+
+import { logger, createAuthMW } from '../../core/index.js';
+
+export const apiRouter: Router | null = Router();
+
+// Create universal auth middleware
+const authMW = createAuthMW();
+
+// Example response interfaces for tsoa
+export interface ExampleResponse {
+  success: boolean;
+  message: string;
+  data: {
+    timestamp: string;
+  };
+}
+
+/**
+ * Example TSOA Controller
+ * This demonstrates how to use tsoa decorators for automatic OpenAPI generation
+ */
+@Route('api')
+export class ExampleController {
+  /**
+   * Example protected endpoint
+   * Template endpoint - customize as needed
+   */
+  @Get('example')
+  @Tags('Example')
+  public async getExample (): Promise<ExampleResponse> {
+    try {
+      logger.info('Example endpoint called');
+
+      return {
+        success: true,
+        message: 'This is a template endpoint',
+        data: { timestamp: new Date().toISOString() },
+      };
+    } catch (error) {
+      logger.error('Error in example endpoint:', error);
+      throw new Error(error instanceof Error ? error.message : 'Unknown error');
+    }
+  }
+
+  /**
+   * Health check endpoint
+   * Simple health check for monitoring
+   */
+  @Get('health')
+  @Tags('Server')
+  public async getHealth (): Promise<{
+    status: string;
+    timestamp: string;
+    version: string;
+  }> {
+    const { appConfig } = await import('../../core/index.js');
+
+    return {
+      status: 'ok',
+      timestamp: new Date().toISOString(),
+      version: appConfig.version || '1.0.0',
+    };
+  }
+}
+
+// Manual Express routes for backward compatibility and custom endpoints
+// Example protected endpoint using auth middleware
+apiRouter.get('/example', authMW, async (req: Request, res: Response) => {
+  try {
+    logger.info('Example endpoint called');
+
+    res.json({
+      success: true,
+      message: 'This is a template endpoint',
+      data: { timestamp: new Date().toISOString() },
+    });
+  } catch (error) {
+    logger.error('Error in example endpoint:', error);
+    res.status(500).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error',
+    });
+  }
+});

package/src/template/custom-resources.ts

@@ -1,11 +1,11 @@
-import { IResourceData } from '../core/index.js';
-
-export const customResources: IResourceData[] = [
-  {
-    uri: 'custom-resource://resource1',
-    name: 'Custom Resource',
-    description: 'Custom resource description',
-    mimeType: 'text/plain',
-    content: 'Custom resource content',
-  }
-];
+import { IResourceData } from '../core/index.js';
+
+export const customResources: IResourceData[] = [
+  {
+    uri: 'custom-resource://resource1',
+    name: 'Custom Resource',
+    description: 'Custom resource description',
+    mimeType: 'text/plain',
+    content: 'Custom resource content',
+  },
+];

package/src/template/prompts/agent-brief.ts

@@ -1,8 +1,8 @@
-/**
- * Level 1: Brief agent description
- * Used when LLM selects agents from a list based on user query
- * LLM doesn't see tools at this level
- */
-
-export const AGENT_BRIEF = 'Agent brief';
-
+/**
+ * Level 1: Brief agent description
+ * Used when LLM selects agents from a list based on user query
+ * LLM doesn't see tools at this level
+ */
+
+export const AGENT_BRIEF = 'Agent brief';
+

package/src/template/prompts/agent-prompt.ts

@@ -1,10 +1,10 @@
-/**
- * Level 2: Agent description This prompt becomes visible to the LLM after the
- * agent router has selected this agent from among others based on their short
- * descriptions. At that point, the LLM gains access to the full list of tools
- * and this detailed prompt, which may include instructions on how to call those
- * tools. In simple scenarios, this prompt can be very short or even empty if
- * the tool descriptions alone are sufficient.
- */
-
-export const AGENT_PROMPT = 'Agent Prompt';
+/**
+ * Level 2: Agent description This prompt becomes visible to the LLM after the
+ * agent router has selected this agent from among others based on their short
+ * descriptions. At that point, the LLM gains access to the full list of tools
+ * and this detailed prompt, which may include instructions on how to call those
+ * tools. In simple scenarios, this prompt can be very short or even empty if
+ * the tool descriptions alone are sufficient.
+ */
+
+export const AGENT_PROMPT = 'Agent Prompt';

package/src/template/prompts/custom-prompts.ts

@@ -1,12 +1,12 @@
-import { IPromptData, IGetPromptRequest } from '../../core/index.js';
-
-export const customPrompts: IPromptData[] = [
-  {
-    name: 'custom_prompt',
-    description: 'Custom prompt',
-    arguments: [],
-    content: (request: IGetPromptRequest) => {
-      return `Custom prompt content ${request.method}`;
-    },
-  },
-];
+import { IPromptData, IGetPromptRequest } from '../../core/index.js';
+
+export const customPrompts: IPromptData[] = [
+  {
+    name: 'custom_prompt',
+    description: 'Custom prompt',
+    arguments: [],
+    content: (request: IGetPromptRequest) => {
+      return `Custom prompt content ${request.method}`;
+    },
+  },
+];

package/src/template/start.ts

@@ -1,72 +1,71 @@
-// Import all project data from existing files
-import { appConfig, initMcpServer, McpServerData, getAsset } from '../core/index.js';
-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 { customPrompts } from './prompts/custom-prompts.js';
-import { customResources } from './custom-resources.js';
-import { apiRouter } from './api/router.js';
-
-const isConsulProd = (process.env.NODE_CONSUL_ENV || process.env.NODE_ENV) === 'production';
-
-/**
- * Main function that assembles all project data and starts the MCP server
- */
-const startProject = async (): Promise<void> => {
-  // Read logo from assets
-  const logoSvg = getAsset('logo.svg')!;
-
-  // Assemble all data to pass to the core
-  const serverData: McpServerData = {
-    // MCP components
-    tools,
-    toolHandler: handleToolCall,
-
-    // Prompts
-    agentBrief: AGENT_BRIEF,
-    agentPrompt: AGENT_PROMPT,
-    customPrompts,
-    usedHttpHeaders: [
-      { name: 'Authorization', description: 'JWT Token issued on request' },
-      { name: 'x-test-header', description: 'Any custom header', isOptional: true },
-    ],
-    // Resources
-    customResources,
-
-    // HTTP components
-    httpComponents: {
-      apiRouter,
-    },
-
-    // Assets
-    assets: {
-      logoSvg: logoSvg,
-      maintainerHtml: '<a href="https://support.com/page/2805" target="_blank" rel="noopener" class="clickable">Support</a>',
-    },
-    // Function to get Consul UI address (if consul enabled: consul.service.enable = true)
-    getConsulUIAddress: (serviceId: string) => {
-      const { agent } = appConfig.consul || {};
-      if (!agent?.dev?.host || !agent?.prd?.host) {
-        return '--consul-ui-not-configured--';
-      }
-      return `${isConsulProd
-        ? `https://${agent.prd.host}/ui/${agent.prd.dc}`
-        : `https://${agent.dev.host}/ui/${agent.dev.dc}`
-      }/services/${serviceId}/instances`;
-    },
-
-    // Custom startup diagnostic info displayed in the console at server start
-    customStartupInfo: [
-      ['Custom param', 'any value'],
-    ],
-  };
-
-  // Start MCP server with assembled data
-  await initMcpServer(serverData);
-};
-
-startProject().catch(error => {
-  console.error('Failed to start project:', error);
-  process.exit(1);
-});
+// Import all project data from existing files
+import { appConfig, initMcpServer, McpServerData, getAsset } from '../core/index.js';
+
+import { apiRouter } from './api/router.js';
+import { customResources } from './custom-resources.js';
+import { AGENT_BRIEF } from './prompts/agent-brief.js';
+import { AGENT_PROMPT } from './prompts/agent-prompt.js';
+import { customPrompts } from './prompts/custom-prompts.js';
+import { handleToolCall } from './tools/handle-tool-call.js';
+import { tools } from './tools/tools.js';
+
+const isConsulProd = (process.env.NODE_CONSUL_ENV || process.env.NODE_ENV) === 'production';
+
+/**
+ * Main function that assembles all project data and starts the MCP server
+ */
+const startProject = async (): Promise<void> => {
+  // Read logo from assets
+  const logoSvg = getAsset('logo.svg')!;
+
+  // Assemble all data to pass to the core
+  const serverData: McpServerData = {
+    // MCP components
+    tools,
+    toolHandler: handleToolCall,
+
+    // Prompts
+    agentBrief: AGENT_BRIEF,
+    agentPrompt: AGENT_PROMPT,
+    customPrompts,
+    usedHttpHeaders: [
+      { name: 'Authorization', description: 'JWT Token issued on request' },
+      { name: 'x-test-header', description: 'Any custom header', isOptional: true },
+    ],
+    // Resources
+    customResources,
+
+    // HTTP components
+    httpComponents: { apiRouter },
+
+    // Assets
+    assets: {
+      logoSvg: logoSvg,
+      maintainerHtml: '<a href="https://support.com/page/2805" target="_blank" rel="noopener" class="clickable">Support</a>',
+    },
+    // Function to get Consul UI address (if consul enabled: consul.service.enable = true)
+    getConsulUIAddress: (serviceId: string) => {
+      const { agent } = appConfig.consul || {};
+      if (!agent?.dev?.host || !agent?.prd?.host) {
+        return '--consul-ui-not-configured--';
+      }
+      return `${isConsulProd
+        ? `https://${agent.prd.host}/ui/${agent.prd.dc}`
+        : `https://${agent.dev.host}/ui/${agent.dev.dc}`
+      }/services/${serviceId}/instances`;
+    },
+
+    // Custom startup diagnostic info displayed in the console at server start
+    customStartupInfo: [
+      ['Custom param', 'any value'],
+    ],
+  };
+
+  // Start MCP server with assembled data
+  await initMcpServer(serverData);
+};
+
+startProject().catch(error => {
+  console.error('Failed to start project:', error);
+  process.exit(1);
+});