fa-mcp-sdk 0.4.76 → 0.4.77

package/cli-template/FA-MCP-SDK-DOC/06-utilities.md

@@ -1,163 +1,163 @@
-# Utilities, Errors, and Logging
-
-## Error Classes
-
-```typescript
-import { BaseMcpError, ToolExecutionError, ValidationError, ServerError } from 'fa-mcp-sdk';
-
-throw new ValidationError('Input validation failed');
-throw new ToolExecutionError('my_tool', 'Execution failed');
-throw new ServerError('Database connection failed', { key: 'value' });
-
-// Custom error
-class MyError extends BaseMcpError {
-  constructor(msg: string) { super(msg, 'MY_ERROR'); }
-}
-```
-
-**ServerError**: `code: 'SERVER_ERROR'`, `httpStatus: 500`
-
-## Error Utilities
-
-```typescript
-import { createJsonRpcErrorResponse, toError, toStr, addErrorMessage } from 'fa-mcp-sdk';
-
-// Create JSON-RPC error response
-const response = createJsonRpcErrorResponse(error, 'request-123');
-
-// Safe error conversion
-const err = toError(anything);      // → Error object
-const msg = toStr(anything);        // → string message
-
-// Add context to error
-addErrorMessage(error, 'Operation failed');
-// error.message = 'Operation failed. Original message'
-```
-
-## Constants
-
-```typescript
-import { ROOT_PROJECT_DIR } from 'fa-mcp-sdk';
-
-const configPath = path.join(ROOT_PROJECT_DIR, 'config', 'default.yaml');
-```
-
-## General Utilities
-
-```typescript
-import { trim, isMainModule, isObject, isNonEmptyObject, ppj, encodeSvgForDataUri, getAsset } from 'fa-mcp-sdk';
-
-trim('  hello  ');      // 'hello'
-trim(null);             // ''
-isMainModule(import.meta.url);  // true if main entry
-isObject({});           // true
-isObject([]);           // false
-isNonEmptyObject({});   // false
-isNonEmptyObject({ k: undefined }); // false
-ppj({ user: 'john' });  // Pretty JSON string
-
-const encoded = encodeSvgForDataUri(svgContent);
-const logo = getAsset('logo.svg');  // From src/asset/
-```
-
-## HTTP Utilities
-
-```typescript
-import { normalizeHeaders } from 'fa-mcp-sdk';
-
-// Normalizes to lowercase, joins arrays with ', '
-const normalized = normalizeHeaders({
-  'Authorization': 'Bearer token',
-  'Accept-Language': ['en', 'ru']
-});
-// { 'authorization': 'Bearer token', 'accept-language': 'en, ru' }
-```
-
-## Tool Utilities
-
-```typescript
-import { getTools, formatToolResult, getJsonFromResult, asTextContent, asJson } from 'fa-mcp-sdk';
-
-const tools = await getTools();  // Get registered tools
-
-// Format based on appConfig.mcp.tools.answerAs
-const result = formatToolResult({ message: 'Done', data: {} });
-
-// Returns structuredContent or JSON from text depending on appConfig.mcp.tools.answerAs
-const original = getJsonFromResult<T>(result);
-
-// Direct formatting helpers (ignore tools.answerAs config):
-asTextContent('Hello');           // { content: [{ type: 'text', text: 'Hello' }] }
-asJson({ status: 'ok' });         // { structuredContent: { status: 'ok' } }
-```
-
-### When to Use Which
-
-- **`formatToolResult()`** — Primary choice in tool handlers. Respects `appConfig.mcp.tools.answerAs` config.
-- **`asTextContent()` / `asJson()`** — Direct formatting, ignores `tools.answerAs`. Use when specific format needed.
-- **`getJsonFromResult()`** — Inverse of `formatToolResult()`. Extracts JSON from either format. Use in tests.
-
-## Network Utilities
-
-```typescript
-import { isPortAvailable, checkPortAvailability } from 'fa-mcp-sdk';
-
-const available = await isPortAvailable(3000, 'localhost');
-
-// Throws/exits if port busy
-await checkPortAvailability(3000, 'localhost', true);
-```
-
-## Logging
-
-```typescript
-import { logger, fileLogger, Logger } from 'fa-mcp-sdk';
-
-logger.info('Server started');
-logger.warn('Warning');
-logger.error('Error', error);
-
-fileLogger.info('To file');
-await fileLogger.asyncFinish();  // Flush before shutdown
-
-// Logger type for typing custom logger references
-const myLogger: Logger = logger;
-```
-
-**`Logger`** — The logger type from 'af-logger-ts' is used to type variables and function parameters.
-
-## Event System
-
-```typescript
-import { eventEmitter } from 'fa-mcp-sdk';
-
-eventEmitter.on('server:started', (data) => console.log(data));
-eventEmitter.emit('custom:event', { data: 'example' });
-```
-
-## Consul Integration
-
-```typescript
-import { getConsulAPI, accessPointUpdater, deregisterServiceFromConsul } from 'fa-mcp-sdk';
-
-const consul = await getConsulAPI();
-const services = await consul.catalog.service.list();
-
-// accessPointUpdater is started/stopped by the SDK automatically — see 03-configuration.md → "Access Points".
-// The start()/stop() hooks below are exposed only for tests and diagnostics.
-accessPointUpdater.start();
-accessPointUpdater.stop();
-
-await deregisterServiceFromConsul();
-```
-
-## Graceful Shutdown
-
-```typescript
-import { gracefulShutdown } from 'fa-mcp-sdk';
-
-// Handles: Consul deregistration, DB close, log flush, etc.
-process.on('SIGUSR2', () => gracefulShutdown('SIGUSR2', 0));
-
-// SDK auto-registers SIGINT/SIGTERM handlers
-```
+# Utilities, Errors, and Logging
+
+## Error Classes
+
+```typescript
+import { BaseMcpError, ToolExecutionError, ValidationError, ServerError } from 'fa-mcp-sdk';
+
+throw new ValidationError('Input validation failed');
+throw new ToolExecutionError('my_tool', 'Execution failed');
+throw new ServerError('Database connection failed', { key: 'value' });
+
+// Custom error
+class MyError extends BaseMcpError {
+  constructor(msg: string) { super(msg, 'MY_ERROR'); }
+}
+```
+
+**ServerError**: `code: 'SERVER_ERROR'`, `httpStatus: 500`
+
+## Error Utilities
+
+```typescript
+import { createJsonRpcErrorResponse, toError, toStr, addErrorMessage } from 'fa-mcp-sdk';
+
+// Create JSON-RPC error response
+const response = createJsonRpcErrorResponse(error, 'request-123');
+
+// Safe error conversion
+const err = toError(anything);      // → Error object
+const msg = toStr(anything);        // → string message
+
+// Add context to error
+addErrorMessage(error, 'Operation failed');
+// error.message = 'Operation failed. Original message'
+```
+
+## Constants
+
+```typescript
+import { ROOT_PROJECT_DIR } from 'fa-mcp-sdk';
+
+const configPath = path.join(ROOT_PROJECT_DIR, 'config', 'default.yaml');
+```
+
+## General Utilities
+
+```typescript
+import { trim, isMainModule, isObject, isNonEmptyObject, ppj, encodeSvgForDataUri, getAsset } from 'fa-mcp-sdk';
+
+trim('  hello  ');      // 'hello'
+trim(null);             // ''
+isMainModule(import.meta.url);  // true if main entry
+isObject({});           // true
+isObject([]);           // false
+isNonEmptyObject({});   // false
+isNonEmptyObject({ k: undefined }); // false
+ppj({ user: 'john' });  // Pretty JSON string
+
+const encoded = encodeSvgForDataUri(svgContent);
+const logo = getAsset('logo.svg');  // From src/asset/
+```
+
+## HTTP Utilities
+
+```typescript
+import { normalizeHeaders } from 'fa-mcp-sdk';
+
+// Normalizes to lowercase, joins arrays with ', '
+const normalized = normalizeHeaders({
+  'Authorization': 'Bearer token',
+  'Accept-Language': ['en', 'ru']
+});
+// { 'authorization': 'Bearer token', 'accept-language': 'en, ru' }
+```
+
+## Tool Utilities
+
+```typescript
+import { getTools, formatToolResult, getJsonFromResult, asTextContent, asJson } from 'fa-mcp-sdk';
+
+const tools = await getTools();  // Get registered tools
+
+// Format based on appConfig.mcp.tools.answerAs
+const result = formatToolResult({ message: 'Done', data: {} });
+
+// Returns structuredContent or JSON from text depending on appConfig.mcp.tools.answerAs
+const original = getJsonFromResult<T>(result);
+
+// Direct formatting helpers (ignore tools.answerAs config):
+asTextContent('Hello');           // { content: [{ type: 'text', text: 'Hello' }] }
+asJson({ status: 'ok' });         // { structuredContent: { status: 'ok' } }
+```
+
+### When to Use Which
+
+- **`formatToolResult()`** — Primary choice in tool handlers. Respects `appConfig.mcp.tools.answerAs` config.
+- **`asTextContent()` / `asJson()`** — Direct formatting, ignores `tools.answerAs`. Use when specific format needed.
+- **`getJsonFromResult()`** — Inverse of `formatToolResult()`. Extracts JSON from either format. Use in tests.
+
+## Network Utilities
+
+```typescript
+import { isPortAvailable, checkPortAvailability } from 'fa-mcp-sdk';
+
+const available = await isPortAvailable(3000, 'localhost');
+
+// Throws/exits if port busy
+await checkPortAvailability(3000, 'localhost', true);
+```
+
+## Logging
+
+```typescript
+import { logger, fileLogger, Logger } from 'fa-mcp-sdk';
+
+logger.info('Server started');
+logger.warn('Warning');
+logger.error('Error', error);
+
+fileLogger.info('To file');
+await fileLogger.asyncFinish();  // Flush before shutdown
+
+// Logger type for typing custom logger references
+const myLogger: Logger = logger;
+```
+
+**`Logger`** — The logger type from 'af-logger-ts' is used to type variables and function parameters.
+
+## Event System
+
+```typescript
+import { eventEmitter } from 'fa-mcp-sdk';
+
+eventEmitter.on('server:started', (data) => console.log(data));
+eventEmitter.emit('custom:event', { data: 'example' });
+```
+
+## Consul Integration
+
+```typescript
+import { getConsulAPI, accessPointUpdater, deregisterServiceFromConsul } from 'fa-mcp-sdk';
+
+const consul = await getConsulAPI();
+const services = await consul.catalog.service.list();
+
+// accessPointUpdater is started/stopped by the SDK automatically — see 03-configuration.md → "Access Points".
+// The start()/stop() hooks below are exposed only for tests and diagnostics.
+accessPointUpdater.start();
+accessPointUpdater.stop();
+
+await deregisterServiceFromConsul();
+```
+
+## Graceful Shutdown
+
+```typescript
+import { gracefulShutdown } from 'fa-mcp-sdk';
+
+// Handles: Consul deregistration, DB close, log flush, etc.
+process.on('SIGUSR2', () => gracefulShutdown('SIGUSR2', 0));
+
+// SDK auto-registers SIGINT/SIGTERM handlers
+```

package/cli-template/FA-MCP-SDK-DOC/07-testing-and-operations.md

@@ -1,127 +1,127 @@
-# Testing and Operations
-
-## Test Clients
-
-### STDIO Transport
-
-```typescript
-import { McpStdioClient } from 'fa-mcp-sdk';
-import { spawn } from 'child_process';
-
-const proc = spawn('node', ['dist/start.js', 'stdio'], {
-  stdio: ['pipe', 'pipe', 'pipe'],
-  env: { ...process.env, NODE_ENV: 'test' },
-});
-
-const client = new McpStdioClient(proc);
-const result = await client.callTool('my_tool', { query: 'test' });
-const prompt = await client.getPrompt('agent_brief');
-```
-
-### HTTP Transport
-
-```typescript
-import { McpHttpClient } from 'fa-mcp-sdk';
-
-const client = new McpHttpClient('http://localhost:3000');
-const result = await client.callTool('my_tool', { query: 'test' }, {
-  'Authorization': 'Bearer token'
-});
-```
-
-### SSE Transport
-
-```typescript
-import { McpSseClient } from 'fa-mcp-sdk';
-
-const client = new McpSseClient('http://localhost:3000');
-const result = await client.callTool('my_tool', { query: 'test' });
-```
-
-### Streamable HTTP (MCP 2025)
-
-```typescript
-import { McpStreamableHttpClient } from 'fa-mcp-sdk';
-
-const client = new McpStreamableHttpClient('http://localhost:3000', {
-  headers: { 'Authorization': 'Bearer token' },
-  requestTimeoutMs: 60000,
-});
-
-await client.initialize({
-  protocolVersion: '2024-11-05',
-  clientInfo: { name: 'test-client', version: '1.0.0' },
-});
-
-const result = await client.callTool('my_tool', { query: 'test' });
-const prompt = await client.getPrompt('agent_brief');
-const resources = await client.listResources();
-const content = await client.readResource('custom://data');
-
-// Notifications
-const unsub = client.onNotification('notifications/tools/list_changed', (p) => console.log(p));
-
-await client.close();
-```
-
-**Methods:** `initialize`, `close`, `callTool`, `getPrompt`, `listResources`, `readResource`, `listTools`, `listPrompts`, `sendRpc`, `notify`, `onNotification`
-
-## Transport Types
-
-| Transport | Config | Use Case |
-|-----------|--------|----------|
-| STDIO | `mcp.transportType: "stdio"` | CLI, local dev |
-| HTTP | `mcp.transportType: "http"` | Web integrations, REST API |
-| SSE | HTTP transport | Long-running ops, streaming |
-
-## Running Tests
-
-```bash
-npm test                               # All tests (Jest)
-npx jest tests/path/file.test.ts       # Single file
-npx jest --testNamePattern="pattern"   # Filter by test name
-npm run test:mcp                       # STDIO transport tests
-npm run test:mcp-http                  # HTTP transport tests
-npm run test:mcp-sse                   # SSE transport tests
-```
-
-### Auth Headers for Tests
-
-```typescript
-import { getAuthHeadersForTests } from 'fa-mcp-sdk';
-
-const headers = getAuthHeadersForTests(); // Uses config auth settings
-const result = await client.callTool('my_tool', { query: 'test' }, headers);
-```
-
-### What to Test
-
-- **Happy path** — tool returns expected result for valid input
-- **Error cases** — invalid params, missing required fields, service errors
-- **Auth flows** — authenticated vs unauthenticated, different auth methods
-- **Transport parity** — same behavior across STDIO, HTTP, SSE
-- **Edge cases** — empty strings, large payloads, special characters
-
-## Best Practices
-
-### Project Organization
-- One responsibility per tool
-- Use TypeScript throughout
-- Separate configs for dev/prod
-
-### Tool Development
-- Validate all inputs
-- Use `formatToolResult()` for responses
-- Use error classes for failures
-- Log operations with `logger`
-
-### Testing
-- Test all transport types
-- Include error cases
-- Use provided test clients
-
-### Security
-- Environment variables for secrets
-- Enable auth for production
-- Validate all user inputs
-- Don't leak sensitive info in errors
+# Testing and Operations
+
+## Test Clients
+
+### STDIO Transport
+
+```typescript
+import { McpStdioClient } from 'fa-mcp-sdk';
+import { spawn } from 'child_process';
+
+const proc = spawn('node', ['dist/start.js', 'stdio'], {
+  stdio: ['pipe', 'pipe', 'pipe'],
+  env: { ...process.env, NODE_ENV: 'test' },
+});
+
+const client = new McpStdioClient(proc);
+const result = await client.callTool('my_tool', { query: 'test' });
+const prompt = await client.getPrompt('agent_brief');
+```
+
+### HTTP Transport
+
+```typescript
+import { McpHttpClient } from 'fa-mcp-sdk';
+
+const client = new McpHttpClient('http://localhost:3000');
+const result = await client.callTool('my_tool', { query: 'test' }, {
+  'Authorization': 'Bearer token'
+});
+```
+
+### SSE Transport
+
+```typescript
+import { McpSseClient } from 'fa-mcp-sdk';
+
+const client = new McpSseClient('http://localhost:3000');
+const result = await client.callTool('my_tool', { query: 'test' });
+```
+
+### Streamable HTTP (MCP 2025)
+
+```typescript
+import { McpStreamableHttpClient } from 'fa-mcp-sdk';
+
+const client = new McpStreamableHttpClient('http://localhost:3000', {
+  headers: { 'Authorization': 'Bearer token' },
+  requestTimeoutMs: 60000,
+});
+
+await client.initialize({
+  protocolVersion: '2024-11-05',
+  clientInfo: { name: 'test-client', version: '1.0.0' },
+});
+
+const result = await client.callTool('my_tool', { query: 'test' });
+const prompt = await client.getPrompt('agent_brief');
+const resources = await client.listResources();
+const content = await client.readResource('custom://data');
+
+// Notifications
+const unsub = client.onNotification('notifications/tools/list_changed', (p) => console.log(p));
+
+await client.close();
+```
+
+**Methods:** `initialize`, `close`, `callTool`, `getPrompt`, `listResources`, `readResource`, `listTools`, `listPrompts`, `sendRpc`, `notify`, `onNotification`
+
+## Transport Types
+
+| Transport | Config | Use Case |
+|-----------|--------|----------|
+| STDIO | `mcp.transportType: "stdio"` | CLI, local dev |
+| HTTP | `mcp.transportType: "http"` | Web integrations, REST API |
+| SSE | HTTP transport | Long-running ops, streaming |
+
+## Running Tests
+
+```bash
+npm test                               # All tests (Jest)
+npx jest tests/path/file.test.ts       # Single file
+npx jest --testNamePattern="pattern"   # Filter by test name
+npm run test:mcp                       # STDIO transport tests
+npm run test:mcp-http                  # HTTP transport tests
+npm run test:mcp-sse                   # SSE transport tests
+```
+
+### Auth Headers for Tests
+
+```typescript
+import { getAuthHeadersForTests } from 'fa-mcp-sdk';
+
+const headers = getAuthHeadersForTests(); // Uses config auth settings
+const result = await client.callTool('my_tool', { query: 'test' }, headers);
+```
+
+### What to Test
+
+- **Happy path** — tool returns expected result for valid input
+- **Error cases** — invalid params, missing required fields, service errors
+- **Auth flows** — authenticated vs unauthenticated, different auth methods
+- **Transport parity** — same behavior across STDIO, HTTP, SSE
+- **Edge cases** — empty strings, large payloads, special characters
+
+## Best Practices
+
+### Project Organization
+- One responsibility per tool
+- Use TypeScript throughout
+- Separate configs for dev/prod
+
+### Tool Development
+- Validate all inputs
+- Use `formatToolResult()` for responses
+- Use error classes for failures
+- Log operations with `logger`
+
+### Testing
+- Test all transport types
+- Include error cases
+- Use provided test clients
+
+### Security
+- Environment variables for secrets
+- Enable auth for production
+- Validate all user inputs
+- Don't leak sensitive info in errors

package/cli-template/jest.config.js

@@ -1,30 +1,27 @@
-export default {
-  preset: 'ts-jest',
-  testEnvironment: 'node',
-  testMatch: ['**/tests/**/*.test.ts', '**/tests/**/*.spec.ts'],
-  collectCoverageFrom: [
-    'src/**/*.ts',
-    '!src/**/*.d.ts',
-    '!src/index.ts'
-  ],
-  coverageDirectory: 'coverage',
-  coverageReporters: ['text', 'lcov'],
-  verbose: false,
-  silent: true,
-  reporters: ['<rootDir>/tests/jest-simple-reporter.js'],
-  moduleNameMapper: {
-    '^(\\.{1,2}/.*)\\.js$': '$1'
-  },
-  transform: {
-    '^.+\\.ts$': ['ts-jest', {
-      useESM: true
-    }]
-  },
-  transformIgnorePatterns: [
-    'node_modules/(?!(chalk|@modelcontextprotocol|af-.*)/)'
-  ],
-  extensionsToTreatAsEsm: ['.ts'],
-  forceExit: true,
-  detectOpenHandles: true,
-  testTimeout: 10000
-};
+export default {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.ts', '**/tests/**/*.spec.ts'],
+  collectCoverageFrom: ['src/**/*.ts', '!src/**/*.d.ts', '!src/index.ts'],
+  coverageDirectory: 'coverage',
+  coverageReporters: ['text', 'lcov'],
+  verbose: false,
+  silent: true,
+  reporters: ['<rootDir>/tests/jest-simple-reporter.js'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.ts$': [
+      'ts-jest',
+      {
+        useESM: true,
+      },
+    ],
+  },
+  transformIgnorePatterns: ['node_modules/(?!(chalk|@modelcontextprotocol|af-.*)/)'],
+  extensionsToTreatAsEsm: ['.ts'],
+  forceExit: true,
+  detectOpenHandles: true,
+  testTimeout: 10000,
+};