fa-mcp-sdk 0.2.125 → 0.2.131

package/cli-template/src/_examples/multi-auth-examples.ts

@@ -1,333 +0,0 @@
-/**
- * Примеры использования системы мультиаутентификации fa-mcp-sdk
- */
-
-import express from 'express';
-// @ts-ignore
-import { appConfig, enhancedAuthTokenMW, createConfigurableAuthMiddleware, getMultiAuthError, getAuthInfo, checkMultiAuth, detectAuthConfiguration, logAuthConfiguration } from 'fa-mcp-sdk';
-
-// ========================================================================
-// ПРИМЕР 1: ПРОСТАЯ ЗАМЕНА MIDDLEWARE
-// ========================================================================
-
-const app = express();
-
-// Вместо старого authTokenMW используем enhancedAuthTokenMW
-app.use('/api', enhancedAuthTokenMW);
-
-app.get('/api/protected', (req, res) => {
-  const authInfo = (req as any).authInfo;
-  res.json({
-    message: 'Access granted',
-    authType: authInfo?.authType,
-    username: authInfo?.username,
-    tokenType: authInfo?.tokenType,
-  });
-});
-
-// ========================================================================
-// ПРИМЕР 2: КОНФИГУРИРУЕМЫЙ MIDDLEWARE
-// ========================================================================
-
-// Middleware с логированием конфигурации при запуске
-const authWithLogging = createConfigurableAuthMiddleware({
-  logConfiguration: true,
-  forceMultiAuth: false, // Автоматически определяет нужна ли мультиаут
-});
-
-app.use('/api/v2', authWithLogging);
-
-// ========================================================================
-// ПРИМЕР 3: КАСТОМНАЯ ЛОГИКА АУТЕНТИФИКАЦИИ
-// ========================================================================
-
-app.use('/api/custom', async (req, res, next) => {
-  // Публичные эндпоинты
-  if (req.path.startsWith('/api/custom/public')) {
-    return next();
-  }
-
-  // Для админских эндпоинтов требуем только permanent tokens
-  if (req.path.startsWith('/api/custom/admin')) {
-    const token = (req.headers.authorization || '').replace(/^Bearer */, '');
-    const auth = appConfig.webServer.auth;
-
-    if (auth.permanentServerTokens.includes(token)) {
-      return next();
-    } else {
-      return res.status(403).json({ error: 'Admin access required' });
-    }
-  }
-
-  try {
-    // Для остальных используем полную мультиаутентификацию
-    const authError = await getMultiAuthError(req);
-    if (authError) {
-      res.status(authError.code).send(authError.message);
-      return;
-    }
-    next();
-  } catch (error) {
-    res.status(500).send('Authentication error');
-    return;
-  }
-});
-
-// ========================================================================
-// ПРИМЕР 4: РОУТЕР С РАЗНЫМИ УРОВНЯМИ ДОСТУПА
-// ========================================================================
-
-const apiRouter = express.Router();
-
-// Публичные роуты - без аутентификации
-apiRouter.get('/health', (req, res) => {
-  res.json({ status: 'ok' });
-});
-
-apiRouter.get('/info', (req, res) => {
-  const authInfo = getAuthInfo();
-  res.json({
-    authEnabled: authInfo.enabled,
-    configuredTypes: authInfo.configured,
-    validTypes: authInfo.valid,
-    usingMultiAuth: authInfo.usingMultiAuth,
-  });
-});
-
-// Защищенные роуты - с мультиаутентификацией
-apiRouter.use('/protected', enhancedAuthTokenMW);
-
-apiRouter.get('/protected/profile', (req, res) => {
-  const authInfo = (req as any).authInfo;
-  res.json({
-    profile: {
-      authType: authInfo.authType,
-      username: authInfo.username || 'anonymous',
-      permissions: getPermissionsForAuthType(authInfo.authType),
-    },
-  });
-});
-
-apiRouter.get('/protected/data', (req, res) => {
-  const authInfo = (req as any).authInfo;
-
-  // Разные данные в зависимости от типа аутентификации
-  let data;
-  switch (authInfo.authType) {
-    case 'permanentServerTokens':
-      data = { level: 'server', access: 'full' };
-      break;
-    case 'oauth2':
-      data = { level: 'user', access: 'scoped', scopes: authInfo.payload?.scope };
-      break;
-    case 'basic':
-      data = { level: 'basic', access: 'limited', username: authInfo.username };
-      break;
-    case 'pat':
-      data = { level: 'api', access: 'token-based' };
-      break;
-    case 'jwtToken':
-      data = { level: 'jwt', access: 'custom', payload: authInfo.payload };
-      break;
-    default:
-      data = { level: 'unknown', access: 'none' };
-  }
-
-  res.json({ data, authInfo: authInfo.authType });
-});
-
-app.use('/api/v3', apiRouter);
-
-// ========================================================================
-// ПРИМЕР 5: ПРОГРАММНОЕ ТЕСТИРОВАНИЕ ТОКЕНОВ
-// ========================================================================
-
-app.post('/api/test-token', async (req, res) => {
-  const { token } = req.body;
-
-  if (!token) {
-    return res.status(400).json({ error: 'Token required' });
-  }
-
-  try {
-    const authConfig = appConfig.webServer.auth;
-    const result = await checkMultiAuth(token, authConfig);
-
-    return res.json({
-      valid: result.success,
-      authType: result.authType,
-      tokenType: result.tokenType,
-      error: result.error,
-      username: result.username,
-      hasPayload: !!result.payload,
-    });
-  } catch (error) {
-    return res.status(500).json({ error: 'Authentication test failed' });
-  }
-});
-
-// ========================================================================
-// ПРИМЕР 6: MIDDLEWARE ДЛЯ РАЗНЫХ ТИПОВ API
-// ========================================================================
-
-// REST API - требует любую валидную аутентификацию
-app.use('/rest', enhancedAuthTokenMW);
-
-// GraphQL API - требует user-level аутентификацию (не server tokens)
-app.use('/graphql', async (req, res, next) => {
-  try {
-    const authError = await getMultiAuthError(req);
-    if (authError) {
-      return res.status(authError.code).send(authError.message);
-    }
-
-    const authInfo = (req as any).authInfo;
-    if (authInfo.authType === 'permanentServerTokens') {
-      return res.status(403).json({
-        error: 'GraphQL API requires user authentication, server tokens not allowed',
-      });
-    }
-
-    return next();
-  } catch (error) {
-    return res.status(500).send('Authentication error');
-  }
-});
-
-// WebSocket API - только JWT токены (для real-time connections)
-app.use('/ws', async (req, res, next) => {
-  try {
-    const authError = await getMultiAuthError(req);
-    if (authError) {
-      return res.status(authError.code).send(authError.message);
-    }
-
-    const authInfo = (req as any).authInfo;
-    if (authInfo.authType !== 'jwtToken' && authInfo.authType !== 'oauth2') {
-      return res.status(403).json({
-        error: 'WebSocket API requires JWT or OAuth2 tokens for session management',
-      });
-    }
-
-    return next();
-  } catch {
-    return res.status(500).send('Authentication error');
-  }
-});
-
-// ========================================================================
-// УТИЛИТНЫЕ ФУНКЦИИ
-// ========================================================================
-
-export function getPermissionsForAuthType (authType: string): string[] {
-  const permissions: Record<string, string[]> = {
-    'permanentServerTokens': ['read', 'write', 'admin', 'server'],
-    'oauth2': ['read', 'write', 'user'],
-    'jwtToken': ['read', 'write', 'session'],
-    'pat': ['read', 'write', 'api'],
-    'basic': ['read', 'basic'],
-  };
-
-  return permissions[authType] || ['read'];
-}
-
-// ========================================================================
-// ПРИМЕР 7: ИНИЦИАЛИЗАЦИЯ С ДИАГНОСТИКОЙ
-// ========================================================================
-
-export function initializeAuthSystem () {
-  const authConfig = appConfig.webServer.auth;
-
-  console.log('🔐 Initializing Multi-Authentication System...');
-
-  // Диагностика конфигурации
-  const detection = detectAuthConfiguration(authConfig);
-
-  console.log('📊 Auth Configuration:');
-  console.log(`   Enabled: ${authConfig.enabled}`);
-  console.log(`   Configured: ${detection.configured.join(', ')}`);
-  console.log(`   Valid: ${detection.valid.join(', ')}`);
-
-  if (Object.keys(detection.errors).length > 0) {
-    console.warn('⚠️  Configuration Issues:');
-    Object.entries(detection.errors).forEach(([type, errors]) => {
-      console.warn(`   ${type}: ${(errors as string[]).join(', ')}`);
-    });
-  }
-
-  // Логирование для отладки
-  logAuthConfiguration(authConfig);
-
-  console.log('✅ Multi-Authentication System initialized successfully');
-
-  return {
-    configured: detection.configured,
-    valid: detection.valid,
-    errors: detection.errors,
-    usingMultiAuth: !!(authConfig.pat || authConfig.basic || authConfig.oauth2),
-  };
-}
-
-// ========================================================================
-// ПРИМЕР 8: ТЕСТИРОВАНИЕ КОНФИГУРАЦИИ
-// ========================================================================
-
-export async function testAuthConfiguration () {
-  const authConfig = appConfig.webServer.auth;
-
-  console.log('🧪 Testing Authentication Configuration...');
-
-  const testCases = [
-    // Тест permanent token
-    {
-      name: 'Permanent Server Token',
-      token: authConfig.permanentServerTokens[0],
-      expectedType: 'permanentServerTokens',
-    },
-    // Тест PAT
-    {
-      name: 'Personal Access Token',
-      token: authConfig.pat,
-      expectedType: 'pat',
-    },
-    // Тест basic auth
-    {
-      name: 'Basic Authentication',
-      token: authConfig.basic
-        ? Buffer.from(`${authConfig.basic.username}:${authConfig.basic.password}`).toString('base64')
-        : undefined,
-      expectedType: 'basic',
-    },
-    // Тест OAuth2
-    {
-      name: 'OAuth2 Bearer Token',
-      token: authConfig.oauth2 ? `Bearer ${authConfig.oauth2.accessToken}` : undefined,
-      expectedType: 'oauth2',
-    },
-  ];
-
-  for (const testCase of testCases) {
-    if (!testCase.token) {
-      console.log(`⏭️  Skipping ${testCase.name}: not configured`);
-      continue;
-    }
-
-    try {
-      const result = await checkMultiAuth(testCase.token, authConfig);
-
-      if (result.success && result.authType === testCase.expectedType) {
-        console.log(`✅ ${testCase.name}: PASSED`);
-      } else {
-        console.log(`❌ ${testCase.name}: FAILED - ${result.error || 'Unexpected auth type'}`);
-      }
-    } catch (error) {
-      console.log(`❌ ${testCase.name}: FAILED - Authentication test error`);
-    }
-  }
-
-  console.log('🧪 Authentication testing completed');
-}
-
-// ========================================================================
-// ЭКСПОРТ ДЛЯ ИСПОЛЬЗОВАНИЯ
-// ========================================================================

package/cli-template/src/_types_/common.d.ts

@@ -1,27 +0,0 @@
-export interface ISearchParams {
-  query: string; // Search query string
-  limit?: number; // Maximum number of results (default: 20)
-  threshold?: number; // Minimum similarity threshold (0-1)
-}
-
-export interface ISearchResultRow {
-  similarity_score: number;
-  word_similarity_score: number;
-  final_score: number;
-  similarity: number; // mapped from final_score
-
-  [prop: string]: number | string;
-}
-
-export interface ISearchResultRow {
-  similarity_score: number;
-  word_similarity_score: number;
-  final_score: number;
-
-  [prop: string]: number | string;
-}
-
-export type ISearchResult = {
-  similarity: number; // mapped from final_score
-  [prop: string]: number | string | undefined;
-}[]

package/cli-template/src/api/router.ts

@@ -1,35 +0,0 @@
-import { Router, Request, Response } from 'express';
-import { logger, authTokenMW, IEndpointsOn404 } from 'fa-mcp-sdk';
-
-export const apiRouter: Router | null = Router();
-
-/**
- * Template for API routes
- * Modify this file to implement your specific API endpoints
- */
-
-// Example protected endpoint using auth middleware
-apiRouter.get('/example', authTokenMW, 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',
-    });
-  }
-});
-
-export const endpointsOn404: IEndpointsOn404 = {
-  myEndpoints1: ['/my-endpoint-1', '/my-endpoint-2'],
-  myEndpoint3: '/my-endpoint-3',
-};

package/cli-template/src/api/swagger.ts

@@ -1,167 +0,0 @@
-import swaggerJsdoc from 'swagger-jsdoc';
-import swaggerUi from 'swagger-ui-express';
-import { appConfig } from 'fa-mcp-sdk';
-
-/**
- * Generic Swagger configuration template for MCP Server
- * Customize this file according to your API endpoints and schemas
- */
-
-// Build servers array from config with fallback
-const buildServers = () => {
-  const servers = [];
-
-  // Use servers from config if available
-  if (appConfig.swagger?.servers?.length) {
-    appConfig.swagger.servers.forEach((server: any) => {
-      servers.push({
-        url: server.url,
-        description: server.description
-      });
-    });
-  } else {
-    // Fallback to default development server
-    servers.push({
-      url: `http://localhost:${appConfig.webServer.port}`,
-      description: 'Development server'
-    });
-  }
-
-  return servers;
-};
-
-const options = {
-  definition: {
-    openapi: '3.0.0',
-    info: {
-      title: 'MCP Server API',
-      version: appConfig.version,
-      description: `
-        REST API for your MCP Server. This is a template configuration.
-        Customize the endpoints, schemas, and documentation according to your needs.
-      `,
-    },
-    servers: buildServers(),
-    components: {
-      schemas: {
-        HealthResponse: {
-          type: 'object',
-          description: 'Health check response',
-          properties: {
-            status: {
-              type: 'string',
-              example: 'ok'
-            },
-            timestamp: {
-              type: 'string',
-              format: 'date-time',
-              example: '2024-11-05T12:00:00.000Z'
-            },
-            version: {
-              type: 'string',
-              example: '1.0.0'
-            }
-          },
-          required: ['status', 'timestamp', 'version']
-        },
-        ErrorResponse: {
-          type: 'object',
-          description: 'Error response format',
-          properties: {
-            success: {
-              type: 'boolean',
-              description: 'Indicates failed operation',
-              example: false
-            },
-            error: {
-              type: 'string',
-              description: 'Human-readable error message',
-              example: 'Validation failed'
-            },
-            code: {
-              type: 'string',
-              description: 'Error code for programmatic handling',
-              example: 'VALIDATION_ERROR'
-            }
-          },
-          required: ['success', 'error', 'code']
-        }
-      }
-    },
-    paths: {
-      '/health': {
-        get: {
-          summary: 'Health check',
-          description: 'Simple health check endpoint for monitoring',
-          tags: ['Server'],
-          responses: {
-            '200': {
-              description: 'Service is healthy',
-              content: {
-                'application/json': {
-                  schema: {
-                    $ref: '#/components/schemas/HealthResponse'
-                  }
-                }
-              }
-            }
-          }
-        }
-      },
-      '/example': {
-        get: {
-          summary: 'Example endpoint',
-          description: 'Template endpoint - customize as needed',
-          tags: ['Example'],
-          responses: {
-            '200': {
-              description: 'Success response',
-              content: {
-                'application/json': {
-                  schema: {
-                    type: 'object',
-                    properties: {
-                      success: {
-                        type: 'boolean',
-                        example: true
-                      },
-                      message: {
-                        type: 'string',
-                        example: 'Template endpoint response'
-                      }
-                    }
-                  }
-                }
-              }
-            },
-            '400': {
-              description: 'Bad request',
-              content: {
-                'application/json': {
-                  schema: {
-                    $ref: '#/components/schemas/ErrorResponse'
-                  }
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    tags: [
-      {
-        name: 'Server',
-        description: 'Server management endpoints'
-      },
-      {
-        name: 'Example',
-        description: 'Template endpoints to customize'
-      }
-    ]
-  },
-  apis: [] // Add your API files here if using JSDoc comments
-};
-
-const swaggerSpecs = swaggerJsdoc(options);
-
-export const swagger = { swaggerSpecs, swaggerUi };

package/cli-template/src/asset/favicon.svg

@@ -1,3 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16">
-  <rect width="16" height="16" fill="${appConfig.uiColor.primary || '#007ACC'}"/>
-</svg>

package/cli-template/src/custom-resources.ts

@@ -1,12 +0,0 @@
-// @ts-ignore
-import { IResourceData } from 'fa-mcp-sdk';
-
-export const customResources: IResourceData[] = [
-  {
-    uri: 'custom-resource://resource1',
-    name: 'Custom Resource',
-    description: 'Custom resource description',
-    mimeType: 'text/plain',
-    content: 'Custom resource content',
-  }
-];

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

@@ -1,8 +0,0 @@
-/**
- * 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/cli-template/src/prompts/agent-prompt.ts

@@ -1,10 +0,0 @@
-/**
- * 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/cli-template/src/prompts/custom-prompts.ts

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

package/cli-template/src/start.ts

@@ -1,71 +0,0 @@
-// Import all project data from existing files
-// @ts-ignore
-import { appConfig, initMcpServer, McpServerData, getAsset } 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 { customPrompts } from './prompts/custom-prompts.js';
-import { customResources } from './custom-resources.js';
-import { apiRouter, endpointsOn404 } from './api/router.js';
-import { swagger } from './api/swagger.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 favicon from assets
-  const favicon = getAsset('favicon.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,
-    requiredHttpHeaders: [{ name: 'Authorization', description: 'JWT Token issued on request' }],
-    // Resources
-    customResources,
-
-    // HTTP components
-    httpComponents: {
-      apiRouter,
-      endpointsOn404,
-      swagger: {
-        swaggerSpecs: swagger.swaggerSpecs,
-        swaggerUi: swagger.swaggerUi,
-      },
-    },
-
-    // Assets
-    assets: {
-      favicon,
-      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/dc-msk-infra`
-        : `https://${agent.dev.host}/ui/dc-dev`
-      }/services/${serviceId}/instances`;
-    },
-  };
-
-  // Start MCP server with assembled data
-  await initMcpServer(serverData);
-};
-
-startProject().catch(error => {
-  console.error('Failed to start project:', error);
-  process.exit(1);
-});