fa-mcp-sdk 0.4.76 → 0.4.77

package/cli-template/FA-MCP-SDK-DOC/00-FA-MCP-SDK-index.md

@@ -1,132 +1,132 @@
-# FA-MCP-SDK Documentation Index
-
-TypeScript framework for building MCP servers.
-
-## Quick Start
-
-```bash
-npm install fa-mcp-sdk
-```
-
-## Documentation Structure
-
-| File | Content | Read When |
-|------|---------|-----------|
-| [01-getting-started](01-getting-started.md) | `initMcpServer()`, `McpServerData`, `IPromptData`, `IResourceData`, `AppConfig` | Starting new project |
-| [02-1-tools-and-api](02-1-tools-and-api.md) | Tool definitions, `toolHandler`, outbound webhooks, REST API with tsoa, OpenAPI/Swagger | Creating tools, REST endpoints, webhook callbacks |
-| [02-2-prompts-and-resources](02-2-prompts-and-resources.md) | Standard/custom prompts, resources, `requireAuth` | Configuring prompts/resources |
-| [03-configuration](03-configuration.md) | `appConfig`, YAML config, access points for external services, cache | Server configuration, external services |
-| [04-authentication](04-authentication.md) | JWT, Basic auth, server tokens, `createAuthMW()`, Token Generator, CLI Token Generator, JWT Generation API | Authentication setup |
-| [05-ad-authorization](05-ad-authorization.md) | AD group authorization at HTTP/tool levels | AD group restrictions |
-| [06-utilities](06-utilities.md) | `ServerError`, `normalizeHeaders`, logging, Consul, graceful shutdown | Error handling, utilities |
-| [07-testing-and-operations](07-testing-and-operations.md) | Test clients (STDIO, HTTP, SSE, Streamable HTTP) | Testing, deployment |
-| [08-agent-tester-and-headless-api](08-agent-tester-and-headless-api.md) | Agent Tester, Headless API, structured logging, automated testing, UI `data-testid` reference | Agent-driven tool development, CLI automation, UI E2E tests |
-| [09-database](09-database.md) | PostgreSQL sugar layer (`queryMAIN`, `execMAIN`, `getInsertSqlMAIN`, `getMergeSqlMAIN`, `mergeByBatch`), `pgvector`, secondary DBs | Database access, upserts, batching |
-
-## Key Exports
-
-```typescript
-// Core
-import { initMcpServer, McpServerData, appConfig, getProjectData, getSafeAppConfig, ROOT_PROJECT_DIR } from 'fa-mcp-sdk';
-
-// Auth
-import { createAuthMW, generateToken, getAuthHeadersForTests, TTokenType, generateTokenApp } from 'fa-mcp-sdk';
-
-// Tools & Errors
-import { formatToolResult, ToolExecutionError, ServerError, BaseMcpError, ValidationError, getTools } from 'fa-mcp-sdk';
-
-// Database & Cache
-import {
-  queryMAIN, queryRsMAIN, oneRowMAIN, execMAIN,
-  getInsertSqlMAIN, getMergeSqlMAIN, mergeByBatch,
-  checkMainDB, getMainDBConnectionStatus,
-  IQueryPgArgsCOptional,
-  getCache,
-} from 'fa-mcp-sdk';
-
-// Utilities
-import { logger, fileLogger, Logger, trim, ppj, toError, toStr, normalizeHeaders } from 'fa-mcp-sdk';
-
-// Test Clients
-import { McpHttpClient, McpStdioClient, McpSseClient, McpStreamableHttpClient } from 'fa-mcp-sdk';
-
-// AD Groups
-import { initADGroupChecker, IADConfig, IDcConfig } from 'fa-mcp-sdk';
-
-// OpenAPI
-import { configureOpenAPI, OpenAPISpecResponse, SwaggerUIConfig } from 'fa-mcp-sdk';
-```
-
-## Project Structure
-
-```
-my-mcp-server/
-├── config/
-│   ├── default.yaml        # Base configuration
-│   ├── development.yaml    # Dev overrides
-│   ├── local.yaml          # Local secrets (gitignored)
-│   └── production.yaml     # Prod overrides
-├── src/
-│   ├── _types_/
-│   │   └── custom-config.ts    # Custom config interface
-│   ├── api/
-│   │   └── router.ts           # REST endpoints (tsoa)
-│   ├── prompts/
-│   │   ├── agent-brief.ts      # Short agent description
-│   │   ├── agent-prompt.ts     # Full agent prompt
-│   │   └── custom-prompts.ts   # Additional prompts
-│   ├── tools/
-│   │   ├── handle-tool-call.ts # Tool execution
-│   │   └── tools.ts            # Tool definitions
-│   ├── custom-resources.ts     # Custom MCP resources
-│   └── start.ts                # Entry point
-└── tests/
-```
-
-## Minimal Example
-
-**`src/start.ts`:**
-```typescript
-import { initMcpServer, McpServerData } from 'fa-mcp-sdk';
-import { tools } from './tools/tools.js';
-import { handleToolCall } from './tools/handle-tool-call.js';
-
-const serverData: McpServerData = {
-  tools,
-  toolHandler: handleToolCall,
-  agentBrief: 'My MCP Server',
-  agentPrompt: 'You are a helpful assistant.',
-};
-
-await initMcpServer(serverData);
-```
-
-**`src/tools/tools.ts`:**
-```typescript
-import { Tool } from '@modelcontextprotocol/sdk/types.js';
-
-export const tools: Tool[] = [{
-  name: 'hello',
-  description: 'Say hello',
-  inputSchema: {
-    type: 'object',
-    properties: { name: { type: 'string', description: 'Name to greet' } },
-    required: ['name']
-  }
-}];
-```
-
-**`src/tools/handle-tool-call.ts`:**
-```typescript
-import { formatToolResult, ToolExecutionError } from 'fa-mcp-sdk';
-
-export const handleToolCall = async (params: { name: string; arguments?: any }): Promise<any> => {
-  const { name, arguments: args } = params;
-  switch (name) {
-    case 'hello':
-      return formatToolResult({ message: `Hello, ${args.name}!` });
-    default:
-      throw new ToolExecutionError(name, `Unknown tool: ${name}`);
-  }
-};
-```
+# FA-MCP-SDK Documentation Index
+
+TypeScript framework for building MCP servers.
+
+## Quick Start
+
+```bash
+npm install fa-mcp-sdk
+```
+
+## Documentation Structure
+
+| File | Content | Read When |
+|------|---------|-----------|
+| [01-getting-started](01-getting-started.md) | `initMcpServer()`, `McpServerData`, `IPromptData`, `IResourceData`, `AppConfig` | Starting new project |
+| [02-1-tools-and-api](02-1-tools-and-api.md) | Tool definitions, `toolHandler`, outbound webhooks, REST API with tsoa, OpenAPI/Swagger | Creating tools, REST endpoints, webhook callbacks |
+| [02-2-prompts-and-resources](02-2-prompts-and-resources.md) | Standard/custom prompts, resources, `requireAuth` | Configuring prompts/resources |
+| [03-configuration](03-configuration.md) | `appConfig`, YAML config, access points for external services, cache | Server configuration, external services |
+| [04-authentication](04-authentication.md) | JWT, Basic auth, server tokens, `createAuthMW()`, Token Generator, CLI Token Generator, JWT Generation API | Authentication setup |
+| [05-ad-authorization](05-ad-authorization.md) | AD group authorization at HTTP/tool levels | AD group restrictions |
+| [06-utilities](06-utilities.md) | `ServerError`, `normalizeHeaders`, logging, Consul, graceful shutdown | Error handling, utilities |
+| [07-testing-and-operations](07-testing-and-operations.md) | Test clients (STDIO, HTTP, SSE, Streamable HTTP) | Testing, deployment |
+| [08-agent-tester-and-headless-api](08-agent-tester-and-headless-api.md) | Agent Tester, Headless API, structured logging, automated testing, UI `data-testid` reference | Agent-driven tool development, CLI automation, UI E2E tests |
+| [09-database](09-database.md) | PostgreSQL sugar layer (`queryMAIN`, `execMAIN`, `getInsertSqlMAIN`, `getMergeSqlMAIN`, `mergeByBatch`), `pgvector`, secondary DBs | Database access, upserts, batching |
+
+## Key Exports
+
+```typescript
+// Core
+import { initMcpServer, McpServerData, appConfig, getProjectData, getSafeAppConfig, ROOT_PROJECT_DIR } from 'fa-mcp-sdk';
+
+// Auth
+import { createAuthMW, generateToken, getAuthHeadersForTests, TTokenType, generateTokenApp } from 'fa-mcp-sdk';
+
+// Tools & Errors
+import { formatToolResult, ToolExecutionError, ServerError, BaseMcpError, ValidationError, getTools } from 'fa-mcp-sdk';
+
+// Database & Cache
+import {
+  queryMAIN, queryRsMAIN, oneRowMAIN, execMAIN,
+  getInsertSqlMAIN, getMergeSqlMAIN, mergeByBatch,
+  checkMainDB, getMainDBConnectionStatus,
+  IQueryPgArgsCOptional,
+  getCache,
+} from 'fa-mcp-sdk';
+
+// Utilities
+import { logger, fileLogger, Logger, trim, ppj, toError, toStr, normalizeHeaders } from 'fa-mcp-sdk';
+
+// Test Clients
+import { McpHttpClient, McpStdioClient, McpSseClient, McpStreamableHttpClient } from 'fa-mcp-sdk';
+
+// AD Groups
+import { initADGroupChecker, IADConfig, IDcConfig } from 'fa-mcp-sdk';
+
+// OpenAPI
+import { configureOpenAPI, OpenAPISpecResponse, SwaggerUIConfig } from 'fa-mcp-sdk';
+```
+
+## Project Structure
+
+```
+my-mcp-server/
+├── config/
+│   ├── default.yaml        # Base configuration
+│   ├── development.yaml    # Dev overrides
+│   ├── local.yaml          # Local secrets (gitignored)
+│   └── production.yaml     # Prod overrides
+├── src/
+│   ├── _types_/
+│   │   └── custom-config.ts    # Custom config interface
+│   ├── api/
+│   │   └── router.ts           # REST endpoints (tsoa)
+│   ├── prompts/
+│   │   ├── agent-brief.ts      # Short agent description
+│   │   ├── agent-prompt.ts     # Full agent prompt
+│   │   └── custom-prompts.ts   # Additional prompts
+│   ├── tools/
+│   │   ├── handle-tool-call.ts # Tool execution
+│   │   └── tools.ts            # Tool definitions
+│   ├── custom-resources.ts     # Custom MCP resources
+│   └── start.ts                # Entry point
+└── tests/
+```
+
+## Minimal Example
+
+**`src/start.ts`:**
+```typescript
+import { initMcpServer, McpServerData } from 'fa-mcp-sdk';
+import { tools } from './tools/tools.js';
+import { handleToolCall } from './tools/handle-tool-call.js';
+
+const serverData: McpServerData = {
+  tools,
+  toolHandler: handleToolCall,
+  agentBrief: 'My MCP Server',
+  agentPrompt: 'You are a helpful assistant.',
+};
+
+await initMcpServer(serverData);
+```
+
+**`src/tools/tools.ts`:**
+```typescript
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const tools: Tool[] = [{
+  name: 'hello',
+  description: 'Say hello',
+  inputSchema: {
+    type: 'object',
+    properties: { name: { type: 'string', description: 'Name to greet' } },
+    required: ['name']
+  }
+}];
+```
+
+**`src/tools/handle-tool-call.ts`:**
+```typescript
+import { formatToolResult, ToolExecutionError } from 'fa-mcp-sdk';
+
+export const handleToolCall = async (params: { name: string; arguments?: any }): Promise<any> => {
+  const { name, arguments: args } = params;
+  switch (name) {
+    case 'hello':
+      return formatToolResult({ message: `Hello, ${args.name}!` });
+    default:
+      throw new ToolExecutionError(name, `Unknown tool: ${name}`);
+  }
+};
+```

package/cli-template/FA-MCP-SDK-DOC/01-getting-started.md

@@ -1,146 +1,146 @@
-# Getting Started
-
-## initMcpServer(data: McpServerData): Promise<void>
-
-Primary function for starting your MCP server.
-
-```typescript
-import { initMcpServer, McpServerData, CustomAuthValidator } from 'fa-mcp-sdk';
-import { tools } from './tools/tools.js';
-import { handleToolCall } from './tools/handle-tool-call.js';
-
-const serverData: McpServerData = {
-  tools,
-  toolHandler: handleToolCall,
-  agentBrief: 'My agent description',
-  agentPrompt: 'Full agent instructions',
-  customAuthValidator: async (req) => { /* custom auth logic */ },
-};
-
-await initMcpServer(serverData);
-```
-
-## Core Types
-
-### McpServerData
-
-```typescript
-interface McpServerData {
-  tools: Tool[] | (() => Promise<Tool[]>);           // Tool definitions
-  toolHandler: (params: IToolHandlerParams) => Promise<any>;
-  agentBrief: string;                                 // Brief description
-  agentPrompt: string;                                // System prompt
-  customPrompts?: IPromptData[];                      // Additional prompts
-  usedHttpHeaders?: IUsedHttpHeader[] | null;         // HTTP headers for auth
-  customResources?: IResourceData[] | null;           // Custom resources
-  customAuthValidator?: CustomAuthValidator;          // Runs FIRST: bypass or fallback to standard auth
-  tokenGenAuthHandler?: TokenGenAuthHandler;          // Token Generator auth
-  httpComponents?: { apiRouter?: Router | null };     // Express router
-  assets?: { logoSvg?: string };
-  getConsulUIAddress?: (serviceId: string) => string;
-}
-
-interface IToolHandlerParams {
-  name: string;
-  arguments?: any;
-  headers?: Record<string, string>;
-  payload?: { user: string; [key: string]: any };     // JWT payload if authenticated
-  transport?: 'stdio' | 'sse' | 'http';
-}
-```
-
-### IPromptData
-
-For custom prompts in `src/prompts/custom-prompts.ts`:
-
-```typescript
-interface IPromptData {
-  name: string;
-  description: string;
-  arguments: [];
-  content: string | ((request: IGetPromptRequest) => string | Promise<string>);
-  requireAuth?: boolean;
-}
-
-// Example:
-export const customPrompts: IPromptData[] = [{
-  name: 'custom_prompt',
-  description: 'A custom prompt',
-  arguments: [],
-  content: (request) => `Content with param: ${request.params.arguments?.sample}`,
-}];
-```
-
-### IResourceData
-
-For custom resources in `src/custom-resources.ts`:
-
-```typescript
-interface IResourceData {
-  uri: string;            // e.g., "custom-resource://data1"
-  name: string;
-  title?: string;
-  description: string;
-  mimeType: string;       // e.g., "text/plain", "application/json"
-  content: string | object | ((uri: string) => string | Promise<string>);
-  requireAuth?: boolean;
-}
-
-// Example:
-export const customResources: IResourceData[] = [{
-  uri: 'custom-resource://resource1',
-  name: 'resource1',
-  description: 'Dynamic content example',
-  mimeType: 'text/plain',
-  content: (uri) => `Dynamic content for ${uri}`,
-}];
-```
-
-## Configuration API
-
-### appConfig
-
-Singleton with merged configuration from YAML files and environment variables:
-
-```typescript
-import { appConfig, AppConfig } from 'fa-mcp-sdk';
-
-const port = appConfig.webServer.port;
-const serviceName = appConfig.name;
-const isAuthEnabled = appConfig.webServer.auth.enabled;
-
-// Nested config access
-const dbHost = appConfig.db.postgres.dbs.main.host;
-const rateLimit = appConfig.mcp.rateLimit.maxRequests;
-const dbEnabled = appConfig.isMainDBUsed;
-```
-
-| Property | Description |
-|----------|-------------|
-| `name` | Package name from package.json |
-| `shortName` | Name without 'mcp' suffix |
-| `version` | Package version |
-| `webServer` | HTTP server config (host, port, auth) |
-| `mcp` | MCP settings (transportType, rateLimit, tools.answerAs, tools.hideAnnotations) |
-| `logger` | Logging config |
-| `ad` | Active Directory config |
-| `consul` | Service discovery settings |
-| `homePage` | Home page footer settings (help link) |
-
-### getProjectData(): McpServerData
-
-Returns the data passed to `initMcpServer()`.
-
-```typescript
-const projectData = getProjectData();
-console.log(projectData.agentBrief, projectData.tools.length);
-```
-
-### getSafeAppConfig(): any
-
-Returns config clone with sensitive data masked. Use for logging:
-
-```typescript
-const safeConfig = getSafeAppConfig();
-console.log(JSON.stringify(safeConfig, null, 2)); // passwords masked
-```
+# Getting Started
+
+## initMcpServer(data: McpServerData): Promise<void>
+
+Primary function for starting your MCP server.
+
+```typescript
+import { initMcpServer, McpServerData, CustomAuthValidator } from 'fa-mcp-sdk';
+import { tools } from './tools/tools.js';
+import { handleToolCall } from './tools/handle-tool-call.js';
+
+const serverData: McpServerData = {
+  tools,
+  toolHandler: handleToolCall,
+  agentBrief: 'My agent description',
+  agentPrompt: 'Full agent instructions',
+  customAuthValidator: async (req) => { /* custom auth logic */ },
+};
+
+await initMcpServer(serverData);
+```
+
+## Core Types
+
+### McpServerData
+
+```typescript
+interface McpServerData {
+  tools: Tool[] | (() => Promise<Tool[]>);           // Tool definitions
+  toolHandler: (params: IToolHandlerParams) => Promise<any>;
+  agentBrief: string;                                 // Brief description
+  agentPrompt: string;                                // System prompt
+  customPrompts?: IPromptData[];                      // Additional prompts
+  usedHttpHeaders?: IUsedHttpHeader[] | null;         // HTTP headers for auth
+  customResources?: IResourceData[] | null;           // Custom resources
+  customAuthValidator?: CustomAuthValidator;          // Runs FIRST: bypass or fallback to standard auth
+  tokenGenAuthHandler?: TokenGenAuthHandler;          // Token Generator auth
+  httpComponents?: { apiRouter?: Router | null };     // Express router
+  assets?: { logoSvg?: string };
+  getConsulUIAddress?: (serviceId: string) => string;
+}
+
+interface IToolHandlerParams {
+  name: string;
+  arguments?: any;
+  headers?: Record<string, string>;
+  payload?: { user: string; [key: string]: any };     // JWT payload if authenticated
+  transport?: 'stdio' | 'sse' | 'http';
+}
+```
+
+### IPromptData
+
+For custom prompts in `src/prompts/custom-prompts.ts`:
+
+```typescript
+interface IPromptData {
+  name: string;
+  description: string;
+  arguments: [];
+  content: string | ((request: IGetPromptRequest) => string | Promise<string>);
+  requireAuth?: boolean;
+}
+
+// Example:
+export const customPrompts: IPromptData[] = [{
+  name: 'custom_prompt',
+  description: 'A custom prompt',
+  arguments: [],
+  content: (request) => `Content with param: ${request.params.arguments?.sample}`,
+}];
+```
+
+### IResourceData
+
+For custom resources in `src/custom-resources.ts`:
+
+```typescript
+interface IResourceData {
+  uri: string;            // e.g., "custom-resource://data1"
+  name: string;
+  title?: string;
+  description: string;
+  mimeType: string;       // e.g., "text/plain", "application/json"
+  content: string | object | ((uri: string) => string | Promise<string>);
+  requireAuth?: boolean;
+}
+
+// Example:
+export const customResources: IResourceData[] = [{
+  uri: 'custom-resource://resource1',
+  name: 'resource1',
+  description: 'Dynamic content example',
+  mimeType: 'text/plain',
+  content: (uri) => `Dynamic content for ${uri}`,
+}];
+```
+
+## Configuration API
+
+### appConfig
+
+Singleton with merged configuration from YAML files and environment variables:
+
+```typescript
+import { appConfig, AppConfig } from 'fa-mcp-sdk';
+
+const port = appConfig.webServer.port;
+const serviceName = appConfig.name;
+const isAuthEnabled = appConfig.webServer.auth.enabled;
+
+// Nested config access
+const dbHost = appConfig.db.postgres.dbs.main.host;
+const rateLimit = appConfig.mcp.rateLimit.maxRequests;
+const dbEnabled = appConfig.isMainDBUsed;
+```
+
+| Property | Description |
+|----------|-------------|
+| `name` | Package name from package.json |
+| `shortName` | Name without 'mcp' suffix |
+| `version` | Package version |
+| `webServer` | HTTP server config (host, port, auth) |
+| `mcp` | MCP settings (transportType, rateLimit, tools.answerAs, tools.hideAnnotations) |
+| `logger` | Logging config |
+| `ad` | Active Directory config |
+| `consul` | Service discovery settings |
+| `homePage` | Home page footer settings (help link) |
+
+### getProjectData(): McpServerData
+
+Returns the data passed to `initMcpServer()`.
+
+```typescript
+const projectData = getProjectData();
+console.log(projectData.agentBrief, projectData.tools.length);
+```
+
+### getSafeAppConfig(): any
+
+Returns config clone with sensitive data masked. Use for logging:
+
+```typescript
+const safeConfig = getSafeAppConfig();
+console.log(JSON.stringify(safeConfig, null, 2)); // passwords masked
+```