fa-mcp-sdk 0.2.38 → 0.2.78

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

@@ -0,0 +1,167 @@
+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

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
+  <path fill="currentColor"
+    d="m 17.622437,19.155864 v -2.611959 h 2.251659 v 2.611959 H 22.468 v 2.251688 h -2.593904 v 2.581936 h -2.251659 v -2.581936 h -2.632933 v -2.251688 z m -5.686183,2.592444 v 2.251688 H 1.4 V 0 H 22.404961 V 15.011256 H 20.153302 V 2.251689 H 3.6516577 V 21.748308 H 11.937755 Z M 7.4959862,7.535651 V 6.034525 h 8.9705968 v 1.501126 z m 0.02402,4.552914 v -1.501126 h 8.9180578 v 1.501126 z m 0.02252,4.420814 v -1.501125 h 5.9278628 v 1.501125 z" />
+</svg>

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

@@ -0,0 +1,11 @@
+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

@@ -0,0 +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';
+

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

@@ -0,0 +1 @@
+export const AGENT_PROMPT = 'Agent Prompt';

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

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

package/cli-template/src/start.ts

@@ -0,0 +1,84 @@
+// Import all project data from existing files
+// @ts-ignore
+import { appConfig, initMcpServer, McpServerData } from 'fa-mcp-sdk';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+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';
+
+/**
+ * Template main function that assembles all project data and starts the MCP server
+ * This serves as an example of how to use the fa-mcp-sdk library
+ */
+const startProject = async (): Promise<void> => {
+  // Read favicon from assets
+  const faviconPath = join(process.cwd(), 'src/template/asset/favicon.svg');
+  let favicon: string;
+
+  try {
+    favicon = readFileSync(faviconPath, 'utf-8');
+  } catch (_error) {
+    // Fallback if favicon not found
+    favicon = `<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16">
+<rect width="16" height="16" fill="${appConfig.uiColor.primary || '#007ACC'}"/>
+</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);
+});

package/cli-template/src/tools/handle-tool-call.ts

@@ -0,0 +1,55 @@
+import { logger as lgr, formatToolResult, ToolExecutionError } from 'fa-mcp-sdk';
+import chalk from 'chalk';
+
+const logger = lgr.getSubLogger({ name: chalk.bgGrey('tools') });
+
+/**
+ * Template tool handler - customize this for your specific tools
+ * This handles MCP tool execution requests
+ */
+export const handleToolCall = async (params: { name: string, arguments?: any }): Promise<any> => {
+  const { name, arguments: args } = params;
+
+  logger.info(`Tool called: ${name}`);
+
+  try {
+    // TODO: Implement your tool routing logic here
+    switch (name) {
+      case 'example_tool':
+        return await handleExampleTool(args);
+
+      default:
+        throw new ToolExecutionError(name, `Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    logger.error(`Tool execution failed for ${name}:`, error);
+    throw error;
+  }
+};
+
+/**
+ * Example tool implementation
+ * Replace this with your actual tool logic
+ */
+async function handleExampleTool (args: any): Promise<string> {
+  const { query } = args || {};
+
+  if (!query) {
+    throw new ToolExecutionError('example_tool', 'Query parameter is required');
+  }
+
+  // Simulate some work
+  await new Promise(resolve => setTimeout(resolve, 100));
+
+  const result = {
+    message: `Processed query: ${query}`,
+    timestamp: new Date().toISOString(),
+  };
+
+  return formatToolResult(result);
+}
+
+// TODO: Add more tool handlers here
+// async function handleAnotherTool(args: any): Promise<string> {
+//   // Your implementation
+// }

package/cli-template/src/tools/tools.ts

@@ -0,0 +1,88 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { IToolInputSchema, IToolProperties } from 'fa-mcp-sdk';
+
+/**
+ * Template tools configuration for MCP Server
+ * Define your tools according to your server's functionality
+ */
+
+
+const getGenericInputSchema = (
+  queryDescription?: string,
+  additionalProperties?: IToolProperties,
+): IToolInputSchema => {
+  const properties = {
+    query: {
+      type: 'string',
+      description: queryDescription || 'Input query or text',
+    },
+    ...additionalProperties,
+  };
+
+  return {
+    type: 'object',
+    properties,
+    required: ['query'],
+  };
+};
+
+const getSearchInputSchema = (): IToolInputSchema => {
+  return {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'Search query',
+      },
+      limit: {
+        type: 'number',
+        description: 'Maximum number of results to return (1-100, default: 20)',
+        minimum: 1,
+        maximum: 100,
+      },
+      threshold: {
+        type: 'number',
+        description: 'Minimum similarity threshold (0-1)',
+        minimum: 0,
+        maximum: 1,
+      },
+    },
+    required: ['query'],
+  };
+};
+
+// Template tools - customize according to your needs
+export const tools: Tool[] = [
+  {
+    name: 'example_tool',
+    description: 'Example tool that processes text input. Replace with your actual tools.',
+    inputSchema: getGenericInputSchema('Text to process'),
+  },
+  {
+    name: 'example_search',
+    description: 'Example search tool with pagination and filtering. Template for search-based tools.',
+    inputSchema: getSearchInputSchema(),
+  },
+  // TODO: Add your actual tools here
+  // {
+  //   name: 'your_tool_name',
+  //   description: 'Description of what your tool does',
+  //   inputSchema: getGenericInputSchema('Your query description', {
+  //     // additional parameters
+  //     param1: {
+  //       type: 'string',
+  //       description: 'Description of param1',
+  //     },
+  //   }),
+  // },
+];
+
+// Helper to get tool by name
+export const getToolByName = (name: string): Tool | undefined => {
+  return tools.find(tool => tool.name === name);
+};
+
+// Helper to get all tool names
+export const getToolNames = (): string[] => {
+  return tools.map(tool => tool.name);
+};

package/cli-template/tests/jest-simple-reporter.js

@@ -0,0 +1,10 @@
+export default class SimpleReporter {
+  onRunComplete (contexts, runResults) {
+    const { numPassedTests, numFailedTests, numPendingTests } = runResults;
+    const total = numPassedTests + numFailedTests + numPendingTests;
+    const actualSuccess = numFailedTests === 0 && total > 0;
+
+    console.log(`\nTest Results: ${numPassedTests} passed, ${numFailedTests} failed, ${numPendingTests} skipped (${total} total)`);
+    console.log(`Status: ${actualSuccess ? 'PASSED' : 'FAILED'}`);
+  }
+}

package/cli-template/tests/mcp/sse/mcp-sse-client-handling.md

@@ -0,0 +1,111 @@
+# MCP SSE Client - Preventing unhandledRejection
+
+## Problem
+
+When using `fa-mcp-sdk` as an npm package in tests where `McpSseClient` is imported, `unhandledRejection` errors may occur. This happens because MCP errors are handled asynchronously through SSE (Server-Sent Events) and may not be properly caught in the test context.
+
+## Why this happens
+
+1. **Local tests**: Run in the same process as the MCP server
+2. **NPM package**: The test runs in a separate process
+3. **SSE asynchronicity**: Errors may occur after the promise is created but before they are handled
+
+## Solutions
+
+### Solution 1: Use a static method (recommended)
+
+```javascript
+import { McpSseClient } from 'fa-mcp-sdk';
+
+// Create a client with automatic unhandledRejection handling
+const client = McpSseClient.createWithErrorHandler('http://localhost:3000');
+
+try {
+  const response = await client.callTool('execute_sql_query', { sql: test.sql });
+  console.log('✅ Success:', response);
+} catch (error) {
+  console.log('❌ Error:', error.message);
+}
+```
+
+### Solution 2: Global unhandledRejection handler
+
+Add at the beginning of the test file:
+
+```javascript
+// Global handling of MCP errors
+process.on('unhandledRejection', (reason) => {
+  if (typeof reason === 'object' && reason?.message?.includes('MCP Error:')) {
+    // Ignore MCP errors — they are handled in try-catch
+    return;
+  }
+});
+
+// Or using the built-in method
+import { McpSseClient } from 'fa-mcp-sdk';
+McpSseClient.setupGlobalErrorHandler();
+```
+
+### Solution 3: Promise with error handling
+
+```javascript
+import { McpSseClient } from 'fa-mcp-sdk';
+
+const client = new McpSseClient('http://localhost:3000');
+
+// Wrap all calls in an additional catch
+async function safeCallTool(toolName, args) {
+  try {
+    return await client.callTool(toolName, args);
+  } catch (error) {
+    // Additional handling to prevent unhandledRejection
+    if (error.message.includes('MCP Error:')) {
+      throw error;
+    }
+    throw new Error(`Unexpected error: ${error.message}`);
+  }
+}
+```
+
+## Full test example
+
+```javascript
+import { McpSseClient } from 'fa-mcp-sdk';
+
+async function testToolExecution() {
+  // Create a client with error handling
+  const client = McpSseClient.createWithErrorHandler('http://localhost:3000');
+
+  try {
+    // Test successful execution
+    const successResponse = await client.callTool('example_tool', { query: 'ping' });
+    console.log('✅ Tool executed successfully:', successResponse);
+
+    // Test error handling (as in your example)
+    try {
+      await client.callTool('example_tool', {}); // No query — should error
+      console.log('❌ Expected error but got success');
+    } catch (error) {
+      console.log('✅ Expected error caught:', error.message);
+    }
+
+  } catch (error) {
+    console.error('❌ Unexpected test error:', error);
+  } finally {
+    await client.close();
+  }
+}
+
+testToolExecution();
+```
+
+## Important notes
+
+1. **For npm packages only**: The issue usually does not occur in local tests
+2. **MCP errors**: The handler filters only errors containing 'MCP Error:'
+3. **Global handler**: Installed once per process
+4. **Resources**: Don’t forget to call `client.close()` for cleanup
+
+## Technical details
+
+The issue arises because SSE errors are handled in `McpSseClient.handleSseEvent()` and may cause a promise rejection that is not yet caught at the moment the error occurs. New methods provide an additional layer of handling to prevent unhandledRejection.

package/cli-template/tests/mcp/sse/test-sse-npm-package.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+/**
+ * Example of using fa-mcp-sdk as an npm package without unhandledRejection issues
+ *
+ * To use this example:
+ * 1. Install fa-mcp-sdk: npm install fa-mcp-sdk
+ * 2. Start MCP server: npm run template:start (in fa-mcp-sdk project)
+ * 3. Run this example: node test-npm-package.js
+ */
+
+import { McpSseClient } from 'fa-mcp-sdk';
+
+const SERVER_URL = 'http://localhost:{{port}}';
+
+async function testMcpClient () {
+  console.log('🧪 Testing MCP client as npm package');
+  console.log('='.repeat(50));
+
+  // Use the new method that handles unhandledRejection
+  const client = McpSseClient.createWithErrorHandler(SERVER_URL);
+
+  try {
+    // Health check
+    console.log('1. Health check...');
+    try {
+      const health = await client.health();
+      console.log('✅ Health check passed:', health.status);
+    } catch (error) {
+      console.log('⚠️  Health check failed:', error.message);
+    }
+
+    // Initialize
+    console.log('2. Initializing...');
+    await client.sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      clientInfo: { name: 'npm-test', version: '1.0.0' },
+    });
+    console.log('✅ Initialized successfully');
+
+    // List tools
+    console.log('3. Listing tools...');
+    const tools = await client.listTools();
+    const toolNames = tools.tools?.map(t => t.name) || [];
+    console.log('✅ Available tools:', toolNames.join(', '));
+
+    // Test successful tool call
+    console.log('4. Testing successful tool call...');
+    try {
+      const response = await client.callTool('example_tool', { query: 'ping' });
+      console.log('✅ Tool call successful:', response.result?.structuredContent?.message || response.result?.content?.[0]?.text);
+    } catch (error) {
+      console.log('❌ Tool call failed:', error.message);
+    }
+
+    // Test expected error (like the test case in test-cases.js)
+    console.log('5. Testing expected error handling...');
+    try {
+      await client.callTool('example_tool', {}); // Missing query parameter
+      console.log('❌ Expected error but got success');
+    } catch (error) {
+      console.log('✅ Expected error caught:', error.message);
+      // This error should NOT cause unhandledRejection
+    }
+
+    // Test with invalid tool name
+    console.log('6. Testing invalid tool name...');
+    try {
+      await client.callTool('nonexistent_tool', {});
+      console.log('❌ Expected error but got success');
+    } catch (error) {
+      console.log('✅ Expected error caught:', error.message);
+      // This error should NOT cause unhandledRejection
+    }
+
+    console.log('\n🎉 All tests completed successfully!');
+    console.log('✨ No unhandledRejection errors occurred');
+
+  } catch (error) {
+    console.error('❌ Unexpected error:', error.message);
+  } finally {
+    await client.close();
+    console.log('🔚 Client closed');
+  }
+}
+
+// Global handler for any unexpected unhandled rejections
+process.on('unhandledRejection', (reason, promise) => {
+  console.error('💥 UNHANDLED REJECTION (this should not happen):');
+  console.error('Reason:', reason);
+  console.error('Promise:', promise);
+  process.exit(1);
+});
+
+testMcpClient().catch(console.error);