fa-mcp-sdk 0.2.217 → 0.2.218

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

@@ -14,18 +14,19 @@ You are the FA-MCP-SDK Expert Agent, specialized in building Model Context Proto
 
 ## 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` |
+| User Task                  | Read These Files First                                          |
+|----------------------------|-----------------------------------------------------------------|
+| Create new MCP server      | `00-FA-MCP-SDK-index.md` → `01-getting-started.md`              |
+| Add MCP tools              | `02-1-tools-and-api.md` (Tool Development section)              |
+| Add REST API endpoints     | `02-1-tools-and-api.md` (REST API Endpoints section)            |
+| Add required MCP prompts   | `02-2-prompts-and-resources.md` (Prompts and resources 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
 

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

@@ -2,14 +2,14 @@
 
 ## 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 
+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 
+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
@@ -43,7 +43,7 @@ Use the fa-mcp-sdk subagent to create an MCP server for managing TODO lists with
 - REST API for web client
 ```
 
-The agent will read the appropriate documentation files and implement the 
+The agent will read the appropriate documentation files and implement the
 functionality following SDK conventions.
 
 ## Quick Start
@@ -54,29 +54,42 @@ 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 |
+| 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-1-tools-and-api.md](02-1-tools-and-api.md)             | Tool definitions, `toolHandler`, HTTP headers, REST API with tsoa decorators, OpenAPI/Swagger auto-generation | Creating MCP tools, adding REST endpoints |
+| [02-2-prompts-and-resources.md](02-2-prompts-and-resources.md) | Standard prompts (agent-brief, agent-prompt), custom prompts, standard resources, custom resources, `requireAuth` | Configuring prompts and resources |
+| [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`
+Read: `01-getting-started.md` → `02-1-tools-and-api.md`
 
 ### Add MCP tools
-Read: `02-tools-and-api.md` (Tool Development section)
+Read: `02-1-tools-and-api.md` (Tool Development section)
 
 ### Add REST API endpoints
-Read: `02-tools-and-api.md` (REST API Endpoints section)
+Read: `02-1-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 prompts
+Read: `02-2-prompts-and-resources.md`
+- Standard: `agent-brief.ts` (short description), `agent-prompt.ts` (full instructions)
+- Custom: add to `customPrompts` array in `src/prompts/custom-prompts.ts`
+- Use `requireAuth: true` to protect prompts
+
+### Configure resources
+Read: `02-2-prompts-and-resources.md`
+- Standard: `project://id`, `project://name`, `doc://readme`, `required://http-headers`
+- Custom: add to `customResources` array in `src/custom-resources.ts`
+- Use `requireAuth: true` to protect resources
+
 ### Configure authentication
 Read: `04-authentication.md`
 - Enable in `config/default.yaml` under `webServer.auth`

package/cli-template/FA-MCP-SDK-DOC/02-2-prompts-and-resources.md

@@ -0,0 +1,342 @@
+# Prompts and Resources
+
+This document describes MCP prompts and resources provided by FA-MCP-SDK.
+
+## Prompts
+
+Prompts are text instructions that LLM receives when working with your MCP server. 
+The SDK provides two standard prompts that must be configured for each new MCP server.
+
+### Standard Prompts
+
+#### Agent Brief (`src/prompts/agent-brief.ts`)
+
+**Level 1: Brief agent description**
+
+This is a short description shown when LLM selects an agent from a list based on 
+user query. At this level, LLM doesn't see the list of tools — only the brief description.
+
+```typescript
+/**
+ * Level 1: Brief agent description
+ * Used when LLM selects agents from a list based on user query
+ * LLM doesn't see tools at this level
+ */
+
+export const AGENT_BRIEF = 'Your short agent description here';
+```
+
+**Example:**
+```typescript
+export const AGENT_BRIEF = 'Database management agent for PostgreSQL operations';
+```
+
+#### Agent Prompt (`src/prompts/agent-prompt.ts`)
+
+**Level 2: Full agent description**
+
+This prompt becomes visible to the LLM after the agent router has selected this 
+agent from among others based on their short descriptions. At this point, the 
+LLM gains access to the full list of tools and this detailed prompt, which may 
+include instructions on how to call those tools.
+
+In simple scenarios, this prompt can be very short or even empty if the tool descriptions alone are sufficient.
+
+```typescript
+/**
+ * Level 2: Agent description
+ * This prompt becomes visible to the LLM after the agent router has selected
+ * this agent from among others based on their short descriptions.
+ * At that point, the LLM gains access to the full list of tools and this
+ * detailed prompt, which may include instructions on how to call those tools.
+ * In simple scenarios, this prompt can be very short or even empty if the
+ * tool descriptions alone are sufficient.
+ */
+
+export const AGENT_PROMPT = `Your detailed agent instructions here.
+
+Available tools:
+- tool1: description
+- tool2: description
+
+Usage guidelines:
+...
+`;
+```
+
+**Example:**
+```typescript
+export const AGENT_PROMPT = `You are a database management assistant for PostgreSQL.
+
+Guidelines:
+- Always check table existence before operations
+- Use transactions for multi-step operations
+- Return results in JSON format
+
+Available tools will help you:
+- Query data from tables
+- Execute DDL/DML statements
+- Manage database schema
+`;
+```
+
+### Custom Prompts
+
+You can add additional prompts in `src/prompts/custom-prompts.ts`. These prompts 
+are exposed via the MCP `prompts/list` and `prompts/get` endpoints.
+
+#### Interface
+
+```typescript
+interface IPromptData {
+  name: string;           // Prompt identifier
+  description: string;    // Description shown in prompts list
+  arguments: [];          // Prompt arguments (currently empty array)
+  content: IPromptContent;// Static string or function returning content
+  requireAuth?: boolean;  // If true, prompt requires authentication
+}
+
+type TPromptContentFunction = (request: IGetPromptRequest) => string | Promise<string>;
+type IPromptContent = string | TPromptContentFunction;
+
+interface IGetPromptRequest {
+  id?: string | number;
+  method: 'prompts/get' | 'prompts/content';
+  params: {
+    name: string;
+    arguments?: Record<string, string>;
+  };
+}
+```
+
+#### Example
+
+```typescript
+import { IPromptData, IGetPromptRequest } from '../../core/index.js';
+
+export const customPrompts: IPromptData[] = [
+  // Simple static prompt
+  {
+    name: 'greeting',
+    description: 'Standard greeting message',
+    arguments: [],
+    content: 'Hello! How can I help you today?',
+  },
+
+  // Dynamic prompt with function
+  {
+    name: 'context_prompt',
+    description: 'Context-aware prompt',
+    arguments: [],
+    content: (request: IGetPromptRequest) => {
+      const args = request.params.arguments || {};
+      return `Processing request with context: ${JSON.stringify(args)}`;
+    },
+  },
+
+  // Protected prompt requiring authentication
+  {
+    name: 'admin_instructions',
+    description: 'Administrative instructions',
+    arguments: [],
+    content: 'Admin-only instructions for system management...',
+    requireAuth: true,  // Requires valid authentication
+  },
+];
+```
+
+#### Connecting Custom Prompts
+
+Pass custom prompts to `initMcpServer()` via `McpServerData`:
+
+```typescript
+import { initMcpServer, McpServerData } from 'fa-mcp-sdk';
+import { customPrompts } from './prompts/custom-prompts.js';
+
+const serverData: McpServerData = {
+  tools,
+  toolHandler: handleToolCall,
+  agentBrief: AGENT_BRIEF,
+  agentPrompt: AGENT_PROMPT,
+  customPrompts,  // Add custom prompts here
+};
+
+await initMcpServer(serverData);
+```
+
+---
+
+## Resources
+
+Resources are data exposed via MCP `resources/list` and `resources/read` endpoints. 
+The SDK provides standard resources and supports custom resources.
+
+### Standard Resources
+
+The SDK automatically provides the following resources:
+
+| URI                       | Name | Description |
+|---------------------------|------|-------------|
+| `project://id`            | project-id | Stable project identifier. Used for MCP server identification in registries and JWT authorization |
+| `project://name`          | product-name | Human-readable product name for UI display |
+| `doc://readme`            | README.md | Project documentation from README.md file. Used by RAG systems in MCP registries for search |
+| `required://http-headers` | Required http headers | List of required HTTP headers (if configured via `requiredHttpHeaders`) |
+
+**Resource content sources:**
+- `project://id` → `appConfig.name` from configuration
+- `project://name` → `appConfig.productName` from configuration
+- `doc://readme` → `README.md` file from project root
+- `required://http-headers` → `requiredHttpHeaders` array from `McpServerData`
+
+### Custom Resources
+
+Add custom resources in `src/custom-resources.ts`.
+
+#### Interface
+
+```typescript
+interface IResourceInfo {
+  uri: string;           // Resource URI (e.g., 'custom://my-resource')
+  name: string;          // Resource name
+  title?: string;        // Optional title
+  description: string;   // Description shown in resources list
+  mimeType: string;      // MIME type (e.g., 'text/plain', 'application/json')
+  requireAuth?: boolean; // If true, resource requires authentication
+}
+
+interface IResourceData extends IResourceInfo {
+  content: IResourceContent;
+}
+
+type TResourceContentFunction = (uri: string) => string | Promise<string>;
+type IResourceContent = string | object | TResourceContentFunction;
+```
+
+#### Example
+
+```typescript
+import { IResourceData } from '../core/index.js';
+
+export const customResources: IResourceData[] = [
+  // Simple static resource
+  {
+    uri: 'custom://config-info',
+    name: 'Configuration Info',
+    description: 'Server configuration summary',
+    mimeType: 'text/plain',
+    content: 'Server version: 1.0.0\nEnvironment: production',
+  },
+
+  // JSON resource
+  {
+    uri: 'custom://api-schema',
+    name: 'API Schema',
+    description: 'API schema definition',
+    mimeType: 'application/json',
+    content: {
+      version: '1.0',
+      endpoints: ['/api/users', '/api/orders'],
+    },
+  },
+
+  // Dynamic resource with async function
+  {
+    uri: 'custom://status',
+    name: 'Server Status',
+    description: 'Current server status',
+    mimeType: 'application/json',
+    content: async (uri: string) => {
+      const status = await getServerStatus();
+      return JSON.stringify(status);
+    },
+  },
+
+  // Protected resource requiring authentication
+  {
+    uri: 'custom://secrets',
+    name: 'Secret Configuration',
+    description: 'Protected configuration data',
+    mimeType: 'application/json',
+    content: { apiKeys: ['...'], credentials: {...} },
+    requireAuth: true,  // Requires valid authentication
+  },
+];
+```
+
+#### Connecting Custom Resources
+
+Pass custom resources to `initMcpServer()` via `McpServerData`:
+
+```typescript
+import { initMcpServer, McpServerData } from 'fa-mcp-sdk';
+import { customResources } from './custom-resources.js';
+
+const serverData: McpServerData = {
+  tools,
+  toolHandler: handleToolCall,
+  agentBrief: AGENT_BRIEF,
+  agentPrompt: AGENT_PROMPT,
+  customResources,  // Add custom resources here
+};
+
+await initMcpServer(serverData);
+```
+
+### Required HTTP Headers
+
+You can define required HTTP headers that clients must send when making requests:
+
+```typescript
+interface IRequiredHttpHeader {
+  name: string;         // Header name (e.g., "Authorization")
+  description: string;  // Description (e.g., "JWT Token issued on request")
+  isOptional?: boolean; // If true, header is optional
+}
+```
+
+**Example:**
+```typescript
+const serverData: McpServerData = {
+  tools,
+  toolHandler: handleToolCall,
+  agentBrief: AGENT_BRIEF,
+  agentPrompt: AGENT_PROMPT,
+  requiredHttpHeaders: [
+    {
+      name: 'Authorization',
+      description: 'JWT token in Bearer format',
+    },
+    {
+      name: 'X-Request-ID',
+      description: 'Optional request tracking ID',
+      isOptional: true,
+    },
+  ],
+};
+```
+
+When `requiredHttpHeaders` is configured, the resource `required://http-headers` becomes available with this information.
+
+---
+
+## Access Control with requireAuth
+
+Both prompts and resources support the `requireAuth` property for access control:
+
+```typescript
+{
+  // ... other properties
+  requireAuth: true,  // Requires valid authentication
+}
+```
+
+When `requireAuth: true`:
+- The prompt/resource is only accessible to authenticated users
+- Unauthenticated requests receive an error
+- Works with any authentication method configured in your server (JWT, Basic, NTLM, etc.)
+
+**Use cases:**
+- Sensitive configuration data
+- Admin-only instructions
+- Internal documentation
+- API keys and credentials

package/cli-template/package.json

@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.25.2",
     "dotenv": "^17.2.3",
-    "fa-mcp-sdk": "^0.2.217"
+    "fa-mcp-sdk": "^0.2.218"
   },
   "devDependencies": {
     "@types/express": "^5.0.6",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fa-mcp-sdk",
   "productName": "FA MCP SDK",
-  "version": "0.2.217",
+  "version": "0.2.218",
   "description": "Core infrastructure and templates for building Model Context Protocol (MCP) servers with TypeScript",
   "type": "module",
   "main": "dist/core/index.js",