fa-mcp-sdk 0.2.184 → 0.2.192

package/cli-template/.claude/agents/fa-mcp-sdk.md

@@ -0,0 +1,158 @@
+---
+name: fa-mcp-sdk
+description: Expert for building MCP servers with FA-MCP-SDK framework. Creates tools, REST APIs, authentication, database integrations, and tests.
+tools: Read, Write, Edit, MultiEdit, Bash, Grep, Glob, LS, TodoWrite
+model: sonnet
+color: green
+---
+
+You are the FA-MCP-SDK Expert Agent, specialized in building Model Context Protocol (MCP) servers using the FA-MCP-SDK TypeScript framework.
+
+## Core Principle
+
+**ALWAYS read the relevant documentation before implementation.** Documentation is located in `FA-MCP-SDK-DOC/`.
+
+## Documentation Map
+
+| User Task | Read These Files First |
+|-----------|------------------------|
+| Create new MCP server | `00-FA-MCP-SDK-index.md` → `01-getting-started.md` |
+| Add MCP tools | `02-tools-and-api.md` (Tool Development section) |
+| Add REST API endpoints | `02-tools-and-api.md` (REST API Endpoints section) |
+| Configure server | `03-configuration.md` |
+| Use database (PostgreSQL) | `03-configuration.md` (Database Integration section) |
+| Use caching | `03-configuration.md` (Cache Management section) |
+| Setup authentication | `04-authentication.md` |
+| Add AD group authorization | `05-ad-authorization.md` |
+| Error handling, logging | `06-utilities.md` |
+| Write tests | `07-testing-and-operations.md` |
+
+## Workflow
+
+1. **Understand** - Parse user requirements
+2. **Reference** - Read relevant doc files from `FA-MCP-SDK-DOC/`
+3. **Plan** - Use TodoWrite for multi-step tasks
+4. **Implement** - Follow patterns exactly as shown in documentation
+5. **Validate** - Ensure code matches SDK conventions
+
+## Quick Reference
+
+### Project Structure
+```
+my-mcp-server/
+├── config/
+│   ├── default.yaml             # Base configuration
+│   ├── development.yaml         # Development overrides
+│   ├── local.yaml               # Local secrets (gitignored)
+│   └── production.yaml          # Production overrides
+├── src/
+│   ├── _types_/
+│   │   ├── common.d.ts          # Common type declarations
+│   │   └── custom-config.ts     # Custom config interface
+│   ├── api/
+│   │   └── router.ts            # REST endpoints (tsoa decorators)
+│   ├── asset/
+│   │   └── logo.svg             # Static assets
+│   ├── prompts/
+│   │   ├── agent-brief.ts       # Short agent description
+│   │   ├── agent-prompt.ts      # Full agent system prompt
+│   │   └── custom-prompts.ts    # Additional prompts
+│   ├── tools/
+│   │   ├── handle-tool-call.ts  # Tool execution logic
+│   │   └── tools.ts             # Tool definitions
+│   ├── custom-resources.ts      # Custom MCP resources
+│   └── start.ts                 # Entry point
+├── swagger/
+│   └── openapi.yaml             # Auto-generated (gitignored)
+└── tests/
+```
+
+### Key Imports
+```typescript
+// Initialization
+import { initMcpServer, McpServerData } from 'fa-mcp-sdk';
+
+// Configuration
+import { appConfig } from 'fa-mcp-sdk';
+
+// Tools
+import { formatToolResult, ToolExecutionError } from 'fa-mcp-sdk';
+
+// Authentication
+import { createAuthMW, checkJwtToken, generateToken } from 'fa-mcp-sdk';
+
+// Database
+import { queryMAIN, execMAIN, oneRowMAIN } from 'fa-mcp-sdk';
+
+// Cache
+import { getCache } from 'fa-mcp-sdk';
+
+// Logging
+import { logger, fileLogger } from 'fa-mcp-sdk';
+
+// Testing
+import { McpHttpClient, McpStdioClient, getAuthHeadersForTests } from 'fa-mcp-sdk';
+```
+
+### Minimal Tool Example
+```typescript
+// tools.ts
+export const tools: Tool[] = [{
+  name: 'my_tool',
+  description: 'Tool description',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      param: { type: 'string', description: 'Parameter description' }
+    },
+    required: ['param']
+  }
+}];
+
+// handle-tool-call.ts
+export const handleToolCall = async (params: {
+  name: string;
+  arguments?: any;
+  headers?: Record<string, string>;
+  payload?: any;
+}): Promise<any> => {
+  const { name, arguments: args } = params;
+  switch (name) {
+    case 'my_tool':
+      return formatToolResult({ result: args.param });
+    default:
+      throw new ToolExecutionError(name, `Unknown tool: ${name}`);
+  }
+};
+```
+
+### REST API Example (tsoa)
+```typescript
+import { Route, Get, Post, Body, Tags, Controller } from 'tsoa';
+
+@Route('api')
+export class MyController extends Controller {
+  @Get('endpoint')
+  @Tags('MyTag')
+  public async getEndpoint(): Promise<{ data: string }> {
+    return { data: 'response' };
+  }
+}
+```
+
+## Output Format
+
+**IMPLEMENTATION COMPLETED**
+
+**Files Created/Modified:**
+- `path/to/file.ts`: Description of changes
+
+**Key Decisions:**
+- Why specific patterns were chosen
+
+**Usage:**
+- How to use the implemented functionality
+
+**Next Steps (if any):**
+- Additional configuration needed
+- Tests to run

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

@@ -0,0 +1,216 @@
+# FA-MCP-SDK Documentation Index
+
+## Overview
+
+The FA-MCP-SDK is a comprehensive TypeScript framework for building Model Context Protocol (MCP) servers. This is the documentation index - read the relevant sections based on your task.
+
+## Using with Claude Code
+
+This project includes a specialized agent `.claude/agents/fa-mcp-sdk.md` for Claude Code. The agent automatically reads relevant documentation sections and follows SDK patterns.
+
+### Example Prompts
+
+**Creating tools:**
+```
+Use the fa-mcp-sdk subagent to add a tool "get_user" that fetches user data by ID from the database
+```
+
+**Adding REST API:**
+```
+Use the fa-mcp-sdk subagent to create REST endpoint POST /api/users for user registration with validation
+```
+
+**Setting up authentication:**
+```
+Use the fa-mcp-sdk subagent to configure JWT authentication with 1 hour token expiration
+```
+
+**Database integration:**
+```
+Use the fa-mcp-sdk subagent to add PostgreSQL integration and create a tool to query orders table
+```
+
+**Complex tasks:**
+```
+Use the fa-mcp-sdk subagent to create an MCP server for managing TODO lists with:
+- tools: add_todo, list_todos, complete_todo, delete_todo
+- PostgreSQL storage
+- JWT authentication
+- REST API for web client
+```
+
+The agent will read the appropriate documentation files and implement the functionality following SDK conventions.
+
+## Quick Start
+
+```bash
+npm install fa-mcp-sdk
+```
+
+## Documentation Structure
+
+| File | Content | Read When |
+|------|---------|-----------|
+| [01-getting-started.md](01-getting-started.md) | Installation, project structure, `initMcpServer()`, core types (`McpServerData`, `IPromptData`, `IResourceData`) | Starting a new project, understanding project structure |
+| [02-tools-and-api.md](02-tools-and-api.md) | Tool definitions, `toolHandler`, HTTP headers, REST API with tsoa decorators, OpenAPI/Swagger auto-generation | Creating MCP tools, adding REST endpoints |
+| [03-configuration.md](03-configuration.md) | `appConfig`, YAML configuration, cache management, database integration (PostgreSQL) | Configuring the server, using cache or database |
+| [04-authentication.md](04-authentication.md) | Multi-auth system, JWT tokens, Basic auth, server tokens, custom validators, `createAuthMW()` | Setting up authentication |
+| [05-ad-authorization.md](05-ad-authorization.md) | AD group-based authorization examples: HTTP level, all tools, per-tool | Implementing AD group restrictions |
+| [06-utilities.md](06-utilities.md) | Error handling, utility functions, logging, events, Consul integration, graceful shutdown | Error handling, logging, service discovery |
+| [07-testing-and-operations.md](07-testing-and-operations.md) | Test clients (STDIO, HTTP, SSE), transport types, best practices | Testing, deployment, operations |
+
+## Common Tasks Quick Reference
+
+### Create a new MCP server
+Read: `01-getting-started.md` → `02-tools-and-api.md`
+
+### Add MCP tools
+Read: `02-tools-and-api.md` (Tool Development section)
+
+### Add REST API endpoints
+Read: `02-tools-and-api.md` (REST API Endpoints section)
+- Use tsoa decorators (`@Route`, `@Get`, `@Post`, `@Tags`)
+- Swagger generates automatically if `swagger/openapi.yaml` doesn't exist
+
+### Configure authentication
+Read: `04-authentication.md`
+- Enable in `config/default.yaml` under `webServer.auth`
+- Options: `permanentServerTokens`, `jwtToken`, `basic`, custom validator
+
+### Add AD group authorization
+Read: `05-ad-authorization.md`
+- HTTP level (block at entry)
+- Tool level (restrict all or specific tools)
+
+### Use database
+Read: `03-configuration.md` (Database Integration section)
+- Set `db.postgres.dbs.main.host` in config
+- Use `queryMAIN()`, `execMAIN()`, `oneRowMAIN()`
+
+### Use caching
+Read: `03-configuration.md` (Cache Management section)
+- `getCache()` → `cache.get()`, `cache.set()`, `cache.getOrSet()`
+
+### Write tests
+Read: `07-testing-and-operations.md`
+- Use `McpHttpClient`, `McpStdioClient`, `McpSseClient`
+- Use `getAuthHeadersForTests()` for auth headers
+
+## Key Exports from fa-mcp-sdk
+
+```typescript
+// Initialization
+import { initMcpServer, McpServerData } from 'fa-mcp-sdk';
+
+// Configuration
+import { appConfig } from 'fa-mcp-sdk';
+
+// Authentication
+import { createAuthMW, checkJwtToken, generateToken, getAuthHeadersForTests } from 'fa-mcp-sdk';
+
+// Tools
+import { formatToolResult, ToolExecutionError } from 'fa-mcp-sdk';
+
+// Database
+import { queryMAIN, execMAIN, oneRowMAIN, checkMainDB } from 'fa-mcp-sdk';
+
+// Cache
+import { getCache } from 'fa-mcp-sdk';
+
+// Logging
+import { logger, fileLogger } from 'fa-mcp-sdk';
+
+// Utilities
+import { trim, ppj, toError, toStr } from 'fa-mcp-sdk';
+
+// Test clients
+import { McpHttpClient, McpStdioClient, McpSseClient } from 'fa-mcp-sdk';
+
+// AD Groups
+import { initADGroupChecker } from 'fa-mcp-sdk';
+```
+
+## Project Structure
+
+```
+my-mcp-server/
+├── config/
+│   ├── default.yaml             # Base configuration
+│   ├── development.yaml         # Development overrides
+│   ├── local.yaml               # Local secrets (gitignored)
+│   └── production.yaml          # Production overrides
+├── src/
+│   ├── _types_/
+│   │   ├── common.d.ts          # Common type declarations
+│   │   └── custom-config.ts     # Custom config interface
+│   ├── api/
+│   │   └── router.ts            # REST endpoints with tsoa decorators
+│   ├── asset/
+│   │   └── logo.svg             # Static assets
+│   ├── prompts/
+│   │   ├── agent-brief.ts       # Short agent description
+│   │   ├── agent-prompt.ts      # Full agent system prompt
+│   │   └── custom-prompts.ts    # Additional prompts
+│   ├── tools/
+│   │   ├── handle-tool-call.ts  # Tool execution logic
+│   │   └── tools.ts             # Tool definitions
+│   ├── custom-resources.ts      # Custom MCP resources
+│   └── start.ts                 # Entry point
+├── swagger/
+│   └── openapi.yaml             # Auto-generated (gitignored)
+└── 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

@@ -0,0 +1,209 @@
+# Getting Started with FA-MCP-SDK
+
+## Overview
+
+The FA-MCP-SDK is a comprehensive TypeScript framework for building Model Context
+Protocol (MCP) servers. This documentation covers how to use the SDK
+to create your own MCP server project.
+
+## Installation
+
+```bash
+npm install fa-mcp-sdk
+```
+
+## Project Structure
+
+When creating a new MCP server, your project structure should follow this pattern:
+
+```
+my-mcp-server/
+├── config/                      # Environment configurations
+│   ├── default.yaml             # Base configuration
+│   ├── development.yaml         # Development settings
+│   ├── production.yaml          # Production settings
+│   └── test.yaml                # Test environment
+├── src/                         # Source code
+│   ├── _types_/                 # TypeScript type definitions
+│   ├── api/                     # REST API routes (HTTP transport)
+│   │   └── router.ts            # Express router with tsoa controllers
+│   ├── prompts/                 # Agent prompts
+│   │   ├── agent-brief.ts       # Agent brief
+│   │   ├── agent-prompt.ts      # Main agent prompt
+│   │   └── custom-prompts.ts    # Custom prompts
+│   ├── tools/                   # MCP tool implementations
+│   │   ├── handle-tool-call.ts  # Tool execution handler
+│   │   └── tools.ts             # Tool definitions
+│   ├── custom-resources.ts      # Custom MCP resources
+│   └── start.ts                 # Application entry point
+├── tests/                       # Test suites
+│   ├── mcp/                     # MCP protocol tests
+│   └── utils.ts                 # Test utilities
+├── .env                         # Environment variables
+├── package.json                 # NPM package configuration
+└── tsconfig.json                # TypeScript configuration
+```
+
+## Main Initialization Function
+
+### `initMcpServer(data: McpServerData): Promise<void>`
+
+The primary function for starting your MCP server.
+
+**Example Usage in `src/start.ts`:**
+
+```typescript
+import { initMcpServer, McpServerData, CustomAuthValidator } 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';
+
+// Optional: Custom Authentication validator (black box function)
+const customAuthValidator: CustomAuthValidator = async (req): Promise<AuthResult> => {
+  // Your custom authentication logic here - full request object available
+  // Can access headers, IP, user-agent, etc.
+  const authHeader = req.headers.authorization;
+  const userID = req.headers['x-user-id'];
+  const clientIP = req.headers['x-real-ip'] || req.connection?.remoteAddress;
+
+  // Implement any authentication logic (database, LDAP, API, custom rules, etc.)
+  const isAuthenticated = await authenticateRequest(req);
+
+  if (isAuthenticated) {
+    return {
+      success: true,
+      authType: 'basic',
+      username: userID || 'unknown',
+    };
+  } else {
+    return {
+      success: false,
+      error: 'Custom authentication failed',
+    };
+  }
+};
+
+const serverData: McpServerData = {
+  tools,
+  toolHandler: handleToolCall,
+  agentBrief: AGENT_BRIEF,
+  agentPrompt: AGENT_PROMPT,
+
+  // Optional: Provide custom authentication function
+  customAuthValidator: customAuthValidator,
+
+  // ... other configuration
+};
+
+await initMcpServer(serverData);
+```
+
+## Core Types and Interfaces
+
+### `McpServerData`
+
+Main configuration interface for your MCP server.
+
+```typescript
+interface McpServerData {
+  // MCP Core Components
+  tools: Tool[];                                    // Your tool definitions
+  toolHandler: (params: { name: string; arguments?: any; headers?: Record<string, string> }) => Promise<any>; // Tool execution function
+
+  // Agent Configuration
+  agentBrief: string;                              // Brief description of your agent
+  agentPrompt: string;                             // System prompt for your agent
+  customPrompts?: IPromptData[];                   // Additional custom prompts
+
+  // Resources
+  requiredHttpHeaders?: IRequiredHttpHeader[] | null; // HTTP headers for authentication
+  customResources?: IResourceData[] | null;        // Custom resource definitions
+
+  // Authentication
+  customAuthValidator?: CustomAuthValidator;           // Custom authentication validator function
+
+  // HTTP Server Components (for HTTP transport)
+  httpComponents?: {
+    apiRouter?: Router | null;                     // Express router for additional endpoints
+    endpointsOn404?: IEndpointsOn404;             // Custom 404 handling
+    swagger?: ISwaggerData | null;                // OpenAPI/Swagger configuration
+  };
+
+  // UI Assets
+  assets?: {
+    favicon?: string;                              // SVG content for favicon
+    maintainerHtml?: string;                       // Support contact HTML snippet
+  };
+
+  // Consul Integration
+  getConsulUIAddress?: (serviceId: string) => string; // Function to generate Consul UI URLs
+}
+```
+
+### `IPromptData`
+
+Configuration for custom prompts in `src/prompts/custom-prompts.ts`.
+
+```typescript
+interface IPromptData {
+  name: string;                                    // Unique prompt identifier
+  description: string;                             // Human-readable description
+  arguments: [];                                   // Expected arguments (currently empty array)
+  content: IPromptContent;                         // Static string or dynamic function
+  requireAuth?: boolean;                           // Whether authentication is required
+}
+
+type IPromptContent = string | TPromptContentFunction;
+type TPromptContentFunction = (request: IGetPromptRequest) => string | Promise<string>;
+```
+
+Example `src/prompts/custom-prompts.ts`:
+```typescript
+import { IPromptData } from 'fa-mcp-sdk';
+
+export const customPrompts: IPromptData[] = [
+  {
+    name: 'custom_prompt',
+    description: 'A custom prompt for specific tasks',
+    arguments: [],
+    content: (request) => {
+      const { sample } = request.params.arguments || {};
+      return `Custom prompt content with parameter: ${sample}`;
+    },
+  },
+];
+```
+
+### `IResourceData`
+
+Configuration for custom resources in `src/custom-resources.ts`.
+
+```typescript
+interface IResourceData {
+  uri: string;                                     // Unique resource URI (e.g., "custom-resource://data1")
+  name: string;                                    // Resource name
+  title?: string;                                  // Optional display title
+  description: string;                             // Human-readable description
+  mimeType: string;                                // MIME type (e.g., "text/plain", "application/json")
+  content: IResourceContent;                       // Static content or dynamic function
+  requireAuth?: boolean;                           // Whether authentication is required
+}
+```
+
+Example `src/custom-resources.ts`:
+```typescript
+import { IResourceData } from 'fa-mcp-sdk';
+
+export const customResources: IResourceData[] = [
+  {
+    uri: 'custom-resource://resource1',
+    name: 'resource1',
+    description: 'Example resource with dynamic content',
+    mimeType: 'text/plain',
+    content: (uri) => {
+      return `Dynamic content for ${uri} at ${new Date().toISOString()}`;
+    },
+  },
+];
+```