fa-mcp-sdk 0.2.121 → 0.2.131

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);
-});

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

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

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

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

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

@@ -1,96 +0,0 @@
-#!/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);

package/cli-template/tests/mcp/test-cases.js

@@ -1,143 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Shared test cases for the template MCP server (src/template)
- * Covers: prompts, resources, tools
- *
- * Each test case is a function(client) -> Promise<{ name, passed, details? }>
- * where client provides methods:
- *   - listPrompts(), getPrompt(name, args?)
- *   - listResources(), readResource(uri)
- *   - listTools(), callTool(name, args?)
- */
-
-const ok = (name, details) => ({ name, passed: true, details });
-const fail = (name, details) => ({ name, passed: false, details });
-
-// Utility: extract system text from prompts/get response
-const extractPromptText = (resp) => {
-  // resp may be raw result or wrapped; support both shapes used by clients
-  const r = resp?.result || resp;
-  const msg = r?.messages?.[0];
-  const text = msg?.content?.text || msg?.content?.[0]?.text || r?.messages?.[0]?.content?.[0]?.text;
-  return typeof text === 'string' ? text : undefined;
-};
-
-export const TEMPLATE_TESTS = {
-  prompts: [
-    async (client) => {
-      const name = 'List prompts contains agent_brief and agent_prompt';
-      try {
-        const list = await client.listPrompts();
-        const prompts = list?.prompts || list;
-        const names = Array.isArray(prompts) ? prompts.map(p => p.name) : [];
-        const okBrief = names.includes('agent_brief');
-        const okPrompt = names.includes('agent_prompt');
-        return (okBrief && okPrompt) ? ok(name, { names }) : fail(name, { names });
-      } catch (e) {
-        return fail(name, { error: e?.message });
-      }
-    },
-    async (client) => {
-      const name = 'Get agent_brief returns text';
-      try {
-        const resp = await client.getPrompt('agent_brief');
-        const text = extractPromptText(resp);
-        return text ? ok(name, { text }) : fail(name, { text });
-      } catch (e) {
-        return fail(name, { error: e?.message });
-      }
-    },
-    async (client) => {
-      const name = 'Get agent_prompt returns text';
-      try {
-        const resp = await client.getPrompt('agent_prompt');
-        const text = extractPromptText(resp);
-        return text ? ok(name, { text }) : fail(name, { text });
-      } catch (e) {
-        return fail(name, { error: e?.message });
-      }
-    },
-    async (client) => {
-      const name = 'Get custom_prompt returns dynamic text';
-      try {
-        const resp = await client.getPrompt('custom_prompt', { sample: '1' });
-        const text = extractPromptText(resp);
-        const hasWord = typeof text === 'string' && text.includes('Custom prompt content');
-        return hasWord ? ok(name, { text }) : fail(name, { text });
-      } catch (e) {
-        return fail(name, { error: e?.message });
-      }
-    },
-  ],
-
-  resources: [
-    async (client) => {
-      const name = 'List resources contains custom-resource://resource1';
-      try {
-        const list = await client.listResources();
-        const resources = list?.resources || list;
-        const uris = Array.isArray(resources) ? resources.map(r => r.uri) : [];
-        const found = uris.includes('custom-resource://resource1');
-        return found ? ok(name, { uris }) : fail(name, { uris });
-      } catch (e) {
-        return fail(name, { error: e?.message });
-      }
-    },
-    async (client) => {
-      const name = 'Read resource custom-resource://resource1 returns content';
-      try {
-        const resp = await client.readResource('custom-resource://resource1');
-        // Different clients return differently; normalize
-        const r = resp?.result || resp;
-        const text = r?.resource?.text || r?.contents?.[0]?.text || r?.text || r?.resource?.content;
-        const okText = typeof text === 'string' && text.length > 0;
-        return okText ? ok(name, { text }) : fail(name, { response: r });
-      } catch (e) {
-        return fail(name, { error: e?.message });
-      }
-    },
-  ],
-
-  tools: [
-    async (client) => {
-      const name = 'List tools contains example_tool and example_search';
-      try {
-        const list = await client.listTools();
-        const tools = list?.tools || list;
-        const names = Array.isArray(tools) ? tools.map(t => t.name) : [];
-        const ok1 = names.includes('example_tool');
-        const ok2 = names.includes('example_search');
-        return (ok1 && ok2) ? ok(name, { names }) : fail(name, { names });
-      } catch (e) {
-        return fail(name, { error: e?.message });
-      }
-    },
-    async (client) => {
-      const name = 'Call example_tool returns formatted result';
-      try {
-        const resp = await client.callTool('example_tool', { query: 'ping' });
-        const r = resp?.result || resp;
-        // Both structuredContent and text are acceptable; check message echo
-        const structured = r?.structuredContent;
-        const text = r?.content?.[0]?.text;
-        const hasProcessed = (structured && structured.message?.includes('Processed query'))
-          || (typeof text === 'string' && text.includes('Processed query'));
-        return hasProcessed ? ok(name, { response: r }) : fail(name, { response: r });
-      } catch (e) {
-        return fail(name, { error: e?.message });
-      }
-    },
-    async (client) => {
-      const name = 'Call example_tool without query should fail';
-      try {
-        await client.callTool('example_tool', {});
-        return fail(name, { error: 'Expected failure, got success' });
-      } catch (e) {
-        return ok(name, { error: e?.message });
-      }
-    },
-  ],
-};
-
-export default TEMPLATE_TESTS;

package/cli-template/tests/mcp/test-http.js

@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * HTTP transport tests for the template MCP server (src/template)
- * Uses McpHttpClient (simple POST requests)
- */
-
-import { appConfig, McpHttpClient } from 'fa-mcp-sdk';
-import TEMPLATE_TESTS from './test-cases.js';
-
-const baseUrl = (process.env.TEST_MCP_SERVER_URL || `http://localhost:${appConfig.webServer.port}`).replace(/\/+$/,'');
-
-async function runTestGroup (title, tests, client) {
-  console.log(`\n${title}:`);
-  let passed = 0;
-  for (const test of tests) {
-    try {
-      const res = await test(client);
-      if (res.passed) {
-        console.log(`  ✅  ${res.name}`);
-        passed++;
-      } else {
-        console.log(`  ❌  ${res.name}`);
-        if (res.details) {
-          console.log('     ', res.details);
-        }
-      }
-    } catch (e) {
-      console.log(`  ❌  ${(await test).name || 'test'}:`, e.message);
-    }
-  }
-  console.log(`  Result: ${passed}/${tests.length} passed`);
-  return passed;
-}
-
-async function main () {
-  console.log('🧪 HTTP tests for template MCP server');
-  console.log('='.repeat(60));
-
-  const client = new McpHttpClient(baseUrl);
-  try {
-    await client.initialize({
-      protocolVersion: '2024-11-05',
-      capabilities: { tools: {} },
-      clientInfo: { name: 'http-test', version: '1.0.0' },
-    });
-
-    const p1 = await runTestGroup('Prompts', TEMPLATE_TESTS.prompts, client);
-    const p2 = await runTestGroup('Resources', TEMPLATE_TESTS.resources, client);
-    const p3 = await runTestGroup('Tools', TEMPLATE_TESTS.tools, client);
-
-    const total = TEMPLATE_TESTS.prompts.length + TEMPLATE_TESTS.resources.length + TEMPLATE_TESTS.tools.length;
-    const sum = p1 + p2 + p3;
-    console.log(`\nSummary: ${sum}/${total} tests passed`);
-  } finally {
-    await client.close().catch(() => undefined);
-  }
-}
-
-main().catch((e) => {
-  console.error('Test failed:', e?.message || e);
-  process.exit(1);
-});