fa-mcp-sdk 0.2.38 → 0.2.78

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

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

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

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

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+/**
+ * SSE transport tests for the template MCP server (src/template)
+ * Uses McpSseClient to send requests via HTTP and receive responses via SSE
+ */
+
+import { appConfig, McpSseClient } 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(`  ❌  ${test.name || 'test'}:`, e.message);
+    }
+  }
+  console.log(`  Result: ${passed}/${tests.length} passed`);
+  return passed;
+}
+
+async function main () {
+  console.log('🧪 SSE tests for template MCP server');
+  console.log('='.repeat(60));
+
+  const client = new McpSseClient(baseUrl);
+  try {
+    // Health check (optional)
+    await client.health().catch(() => undefined);
+
+    // Initialize over RPC channel used by SSE client (POST /rpc)
+    await client.sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      clientInfo: { name: 'sse-test', version: '1.0.0' },
+    }).catch(() => undefined);
+
+    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);
+});

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

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+/**
+ * STDIO transport tests for the template MCP server (src/template)
+ * Uses a minimal NDJSON JSON-RPC client over child_process stdio
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import TEMPLATE_TESTS from './test-cases.js';
+import { McpStdioClient } from 'fa-mcp-sdk';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const projectRoot = join(__dirname, '../../../');
+
+const serverPath = join(projectRoot, 'dist/template/start.js');
+
+async function runTestGroup (title, tests, client) {
+  console.log(`\n${title}:`);
+  let passed = 0;
+  for (const test of tests) {
+    const name = (await test).name || 'test';
+    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(`  ❌  ${name}:`, e.message);
+    }
+  }
+  console.log(`  Result: ${passed}/${tests.length} passed`);
+  return passed;
+}
+
+async function main () {
+  console.log('🧪 STDIO tests for template MCP server');
+  console.log('='.repeat(60));
+
+  const proc = spawn('node', [serverPath, 'stdio'], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, NODE_ENV: 'test' },
+  });
+
+  const client = new McpStdioClient(proc);
+
+  try {
+    // Initialize handshake (optional for stdio server; safe to send)
+    await client.send('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      clientInfo: { name: 'stdio-test', version: '1.0.0' },
+    }).catch(() => undefined);
+
+    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 {
+    try { proc.kill(); } catch {}
+  }
+}
+
+main().catch((e) => {
+  console.error('Test failed:', e?.message || e);
+  process.exit(1);
+});

package/cli-template/tests/utils.ts

@@ -0,0 +1,154 @@
+import '../src/core/bootstrap/dotenv.js';
+import fsp from 'fs/promises';
+import fss from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+
+const testResultLogsDir = process.env.TEST_RESULT_LOGS_DIR || '_logs/mcp';
+
+const RESULTS_DIR = path.join(process.cwd(), testResultLogsDir);
+
+if (!fss.existsSync(RESULTS_DIR)) {
+  fss.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+export interface ITestResult {
+  // Test / tool identifiers
+  fullId: string;
+  toolName: string;
+  description: string;
+
+  // Tool invocation parameters
+  parameters: unknown | null;
+
+  // Temporal metadata
+  timestamp: string; // ISO string
+  duration: number;  // milliseconds
+
+  // Execution status
+  status: 'pending' | 'passed' | 'failed' | 'skipped' | 'expected_failure';
+
+  // Marker icon for logs (may be absent in "pending")
+  marker?: string;
+
+  // MCP response
+  response: unknown | null;
+
+  // Error (human-readable message)
+  error: string | null;
+
+  // Additional error details (structured)
+  errorDetails?: unknown | null;
+
+  // Full MCP response on error (JSON-RPC response)
+  fullMcpResponse?: unknown;
+
+  // Request headers used for the MCP server call
+  requestHeaders?: Record<string, string>;
+}
+
+/**
+ * Format test result as Markdown
+ */
+export const formatResultAsMarkdown = (result: ITestResult) => {
+  const t = '```';
+  const mdText = (s: string | null) => `${t}\n${s}\n${t}`;
+  const mdDescr = (s: string) => `${t}description\n${s}\n${t}`;
+  const mdJson = (v: any) => `${t}json\n${v && JSON.stringify(v, null, 2)}\n${t}`;
+
+  let resultStatus = '⚠️ RESULT STATUS UNKNOWN';
+  let errorText = '';
+  // md += `## Response\n\n\`\`\`json\n${JSON.stringify(result.response, null, 2)}\n\`\`\`\n\n`;
+
+  if (result.status === 'passed') {
+    resultStatus = '✅  PASSED';
+  } else {
+    // Show full MCP response as seen by the agent, or fallback to separate sections
+    if (result.fullMcpResponse) {
+      errorText = `## MCP Response (as seen by agent)\n\n${mdJson(result.fullMcpResponse)}\n\n`;
+    } else {
+      errorText = `## Error\n\n${mdText(result.error)}\n\n`;
+      // Add detailed error information if available
+      if (result.errorDetails) {
+        errorText += `## Error Details\n\n${mdJson(result.errorDetails)}\n\n`;
+      }
+    }
+    if (result.status === 'expected_failure') {
+      resultStatus = '⚠️  Expected failure - test validation successful';
+    } else {
+      resultStatus = '❌  FAILED';
+    }
+  }
+
+  let requestHeaders = '';
+  if (result.requestHeaders && Object.keys(result.requestHeaders).length > 0) {
+    requestHeaders = `\nHeaders:\n${Object.entries(result.requestHeaders).map(([k, v]) => `  ${k}: ${v}`).join('\n')}\n`;
+  }
+
+  // Format response section
+  let responseText = '';
+  if (result.response !== null && result.response !== undefined) {
+    try {
+      let parsedResponse: any = result.response;
+      let isJsonParsed = false;
+
+      // If response is a string, try to parse as JSON first
+      if (typeof result.response === 'string') {
+        try {
+          parsedResponse = JSON.parse(result.response);
+          isJsonParsed = true;
+        } catch {
+          // If not valid JSON, treat as text
+          responseText = `## Response\n\n${mdText(result.response)}\n\n`;
+        }
+      } else if (typeof result.response === 'object') {
+        isJsonParsed = true;
+      }
+
+      // If we have a successfully parsed or original object
+      if (isJsonParsed && typeof parsedResponse === 'object') {
+        let text = parsedResponse;
+        let addText = '';
+        // Check if response has content[0].text structure and extract text
+        if (Array.isArray(parsedResponse?.content) && parsedResponse.content[0]?.text) {
+          const textContent = parsedResponse.content[0].text;
+          parsedResponse.content[0].text = '📋';
+          text = parsedResponse;
+          addText = `## Formatted Text 📋\n${mdText(textContent)}\n\n`;
+        }
+        responseText = `## Response\n\n${mdJson(text)}\n\n${addText}`;
+      }
+
+    } catch {
+      // Fallback to text if any parsing errors
+      responseText = `## Response\n\n${mdText(String(result.response))}\n\n`;
+    }
+  }
+
+  return `${resultStatus} / ${result.timestamp} / ${result.duration}ms
+# ${result.toolName}
+${requestHeaders}
+${mdDescr(result.description)}
+
+parameters:
+${mdJson(result.parameters)}
+
+${responseText}${errorText}`;
+};
+
+/**
+ * Log test result to individual file
+ */
+export const logResultToFile = async (result: ITestResult) => {
+  // const filename = `${result.fullId}_${result.toolName}.md`;
+  const filename = `${result.toolName}.md`;
+  const filepath = path.join(RESULTS_DIR, filename);
+
+  const content = formatResultAsMarkdown(result);
+
+  try {
+    await fsp.writeFile(filepath, content, 'utf-8');
+  } catch (error: Error | any) {
+    console.log(chalk.red(`  Failed to write log file: ${error.message}`));
+  }
+};

package/cli-template/tsconfig.json

@@ -0,0 +1,48 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "removeComments": false,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "baseUrl": "./"
+  },
+  "include": [
+    "src/**/*",
+    "tests/**/*"
+  ],
+  "exclude": [
+    ".claude",
+    ".idea",
+    ".run",
+    "_misc",
+    "_tmp",
+    "config",
+    "deploy",
+    "dist",
+    "doc",
+    "node_modules",
+    "coverage"
+  ],
+  "ts-node": {
+    "esm": true
+  }
+}