fa-sdk
Core infrastructure and templates for building Model Context Protocol (MCP) servers with TypeScript
Installation
npx fa-mcp-sdkAsk AI about fa-sdk
Powered by Claude Β· Grounded in docs
I know everything about fa-sdk. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP Server Template Generator
Production-ready core framework for building MCP (Model Context Protocol) servers with comprehensive infrastructure support.
CLI utility that creates ready-to-use MCP (Model Context Protocol) server projects from the official template.
Overview
This framework provides complete infrastructure for building enterprise-grade MCP servers:
- Dual Transport: STDIO (Claude Desktop) and HTTP/SSE (web clients)
- Agent-Driven Tool Development: Built-in AI agent system (Agent Tester) for iterative refinement of MCP tools through automated testing cycles β the agent calls your tools, you observe behavior, adjust descriptions/parameters/prompts, and re-test
- Headless Test API: Direct HTTP endpoint (
POST /agent-tester/api/chat/test) returns structured trace of every tool call, argument, result, and LLM decision β enabling CLI-based automated testing without a browser - Authentication: JWT (with optional IP restriction), Basic auth, permanent tokens, custom validators
- Database Integration: PostgreSQL with pgvector for vector operations
- Service Discovery: Consul integration for microservices
- Rate Limiting: Configurable rate limiting for all endpoints
- API Documentation: Automatic Swagger/OpenAPI generation
- Production Logging: Structured logging with data masking
- Configuration Management: YAML-based with environment overrides
- Deployment Ready: PM2 scripts, Nginx templates, ESLint, Jest testing
The framework uses dependency injection to keep the core completely agnostic of project-specific implementations.
Steps to Get Started
-
Install
fa-mcp-sdkglobally:npm install -g fa-mcp-sdk -
Run the CLI, specify the target directory, and follow the interactive prompts:
fa-mcpOr using configuration file:
fa-mcp config.yaml -
Launching the template MCP server:
- Navigate to the target directory:
cd <targetPath> - Install dependencies:
npm install - Build the project:
npm run build - Start the server:
npm start
- Navigate to the target directory:
-
Vibe-coding your MCP server logic:
- Create an instruction file (prompt) for your preferred AI coding assistant.
fa-mcp-sdkcomes ready for use withClaude Code. You can find an example prompt for creating an MCP server (e.g., a currency exchange rate provider) incli-template/prompt-example-new-MCP.md. - Launch your AI coder and provide it with the instructions to build your new MCP server.
- Create an instruction file (prompt) for your preferred AI coding assistant.
Configuration
The CLI collects required and optional parameters through interactive prompts or configuration file.
Required Parameters
| Parameter | Description | Example |
|---|---|---|
project.name | Package.json name and MCP server identification | "my-mcp-server" |
project.description | Package.json description | "A custom MCP server" |
project.productName | Display name for UI and documentation | "My MCP Server" |
port | Web server port for HTTP and MCP protocol | "3000" |
Optional Parameters
| Parameter | Description | Default |
|---|---|---|
author.name | Package.json author name | "" |
author.email | Package.json author email | "" |
git-base-url | Git repository base URL | "github.com/username" |
consul.service.enable | Enable Consul service registration | "false" |
consul.agent.reg.token | Token for registering service with Consul | "***" |
consul.envCode.dev | Development environment code | "<envCode.dev>" |
consul.envCode.prod | Production environment code | "<envCode.prod>" |
consul.agent.dev.dc | Development Consul datacenter | "" |
consul.agent.dev.host | Development Consul UI host | "consul.my.ui" |
consul.agent.dev.token | Development Consul access token | "***" |
consul.agent.prd.dc | Production Consul datacenter | "" |
consul.agent.prd.host | Production Consul UI host | "consul.my.ui" |
consul.agent.prd.token | Production Consul access token | "***" |
mcp.domain | Domain name for nginx configuration | "" |
ssl-wildcard.conf.rel.path | Relative path to SSL config in /etc/nginx | "snippets/ssl-wildcard.conf" |
webServer.auth.enabled | Enable token authorization | "false" |
webServer.auth.token.checkMCPName | Check MCP name in token | "false" |
isProduction | Production mode flag | "false" |
SERVICE_INSTANCE | Service name suffix for Consul and PM2 | "" |
maintainerUrl | Support/maintainer URL | "" |
logger.useFileLogger | Enable file logging | "" |
Configuration File Examples
Link: YAML Example with detailed comments
The utility supports both JSON and YAML configuration formats.
Use either .json, .yaml, or .yml file extensions.
Usage:
# Interactive setup (will prompt for all parameters)
fa-mcp
# Using JSON configuration
fa-mcp config.json
fa-mcp --config=my-config.json
# Using YAML configuration (NEW!)
fa-mcp config.yaml
fa-mcp --config=my-config.yml
Project Structure
my-mcp-server/
βββ .claude/ # Settings, Agents, Hooks for Claude Code
β βββ agents/ # Folder with Claude Code agents. Including the agent fa-mcp-sdk
β βββ hooks/ # Code formatting hook after changes made by Claude Code
β βββ settings.json # Claude Code settings
βββ .run/ # JetBrains IDE run configurations
βββ config/ # Environment configurations
β βββ _local.yaml # Local configuration template
β βββ custom-environment-variables.yaml # Environment mapping
β βββ default.yaml # Base configuration
β βββ development.yaml # Development settings
β βββ local.yaml # Local configuration
β βββ production.yaml # Production settings
β βββ test.yaml # Test environment
βββ deploy/ # Deployment configurations
β βββ .gitkeep # Git directory keeper
β βββ NGINX/ # Nginx configuration templates
β β βββ sites-enabled/ # Nginx site configurations
β β βββ snippets/ # Nginx configuration snippets
β βββ config.example.yml # Deployment config example
β βββ pm2.config.js # PM2 process manager config
β βββ pm2reg.sh # PM2 registration script
β βββ srv.cjs # Server management script
β βββ srv.sh.readme.md # Server script documentation
βββ FA-MCP-SDK-DOC/ # FA-MCP-SDK Documentation
βββ scripts/ # Utility scripts
β βββ npm/ # NPM utility scripts
β βββ generate-jwt.js # CLI JWT token generator
β βββ kill-port.js # Port cleanup utility
β βββ pre-commit # Git pre-commit hook
β βββ remove-nul.js # File cleanup utility
βββ src/ # Source code
β βββ _types_/ # TypeScript type definitions
β βββ api/ # REST API routes
β β βββ router.ts # Express router
β βββ asset/ # Static assets
β β βββ logo.svg # Application logo/favicon
β βββ 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
βββ swagger/
β βββ openapi.yaml # API description. Generated if none
βββ tests/ # Test suites
β βββ mcp/ # MCP protocol tests
β βββ jest-simple-reporter.js # Custom Jest reporter
β βββ utils.ts # Test utilities
βββ .editorconfig # Editor configuration
βββ .env # Environment variables
βββ .env.example # Environment variables template
βββ .envrc # direnv configuration
βββ .gitignore # Git ignore rules
βββ eslint.config.js # ESLint configuration
βββ jest.config.js # Jest test configuration
βββ LICENSE # MIT license file
βββ package.json # NPM package configuration
βββ prompt-example-new-MCP.md # Example of instructions for Claude Code for vibe coding of a custom MCP server
βββ README.md
βββ tsconfig.json # TypeScript configuration
βββ update.cjs # Project update script
Note: The dist/ directory (compiled JavaScript) is created after running npm run build.
Available Scripts
| Script | Description |
|---|---|
npm start | Start compiled MCP server |
npm run build | Compile TypeScript |
npm run cb | Clean and build |
npm run ci | Install dependencies |
npm run reinstall | Reinstall all dependencies |
npm run lint | Run ESLint |
npm run lint:fix | Fix ESLint issues |
npm run test:mcp | Test MCP tools |
npm run test:mcp-http | Test HTTP transport |
npm run test:mcp-sse | Test SSE transport |
npm run test:mcp-stdio | Test STDIO transport |
npm run generate-token | Generate JWT tokens (Web UI) |
node scripts/generate-jwt.js | Generate JWT token (CLI) |
/gen-jwt | Generate JWT token (Claude Code skill) |
/upgrade-guide | Generate upgrade guide for downstream projects (Claude Code skill) |
npm run consul:unreg | Deregister from Consul |
Server runs at
http://localhost:3000 with:
- MCP endpoints at
/mcp/* - Admin panel for generating access tokens at
/admin- When
adminPanel.authTypeincludesjwtToken, the JWT must carryallow: 'gen-token'in its payload to be accepted. Tokens without this claim (e.g. the short-lived JWT auto-generated for the Agent Tester page) are rejected β this prevents them from being replayed to mint arbitrary long-lived tokens.permanentServerTokensandbasicadmin auth are unaffected. Generate an admin-capable JWT:node scripts/generate-jwt.js -u admin -ttl 30d -p "allow=gen-token"
- When
- JWT generation API at
/gen-jwt(whenwebServer.genJwtApiEnable: true) - Swagger UI at
/docs - Health check at
/health
Agent Tester
Built-in chat interface for testing MCP server tools using an AI agent (OpenAI-compatible LLM). The agent automatically discovers available tools and calls them in a conversational loop.
To enable, set environment variables (.env or shell):
AGENT_TESTER_ENABLED=true
AGENT_TESTER_OPENAI_API_KEY=sk-...
Or configure in config/default.yaml (or local.yaml):
agentTester:
enabled: true
openAi:
apiKey: sk-...
The tester UI is available at http://localhost:<port>/agent-tester and auto-connects to the local MCP server.
Supports custom LLM endpoints, configurable system prompts, and dynamic HTTP headers. Recommended model for testing: gpt-5.2.
Upgrade Guide Skill
Claude Code skill that generates a step-by-step upgrade guide for projects built on fa-mcp-sdk. Analyzes git diff between two versions/commits and produces an MD file covering config changes, template file updates, script changes, API changes, and dependency updates.
Usage in Claude Code:
/upgrade-guide 0.4.30 0.4.37
/upgrade-guide 0.4.30
/upgrade-guide abc1234
/upgrade-guide 0.4.30 0.4.37 Π½Π° ΡΡΡΡΠΊΠΎΠΌ
Output language is English by default. Add a natural-language hint (e.g., "Π½Π° ΡΡΡΡΠΊΠΎΠΌ", "in German") to change it.
Skill location: .claude/skills/upgrade-guide/SKILL.md
Directory Requirements
-
Use absolute paths for target directory
-
Empty directories only - CLI aborts if files exist except for the following:
.git/ .idea/ .vscode .DS_Store node_modules/ dist/ __misc/ _tmp/ .swp .swo .sublime-project .sublime-workspace ~last-cli-config.json
Deployment
PM2 Production
npm run build
pm2 start deploy/pm2.config.js
Systemd Service
npm run build
chmod +x deploy/srv.cjs
./deploy/srv.cjs install
Consul Registration
Set consul.service.enable: true and provide required tokens for automatic service registration.
Nginx Configuration
Generated nginx configuration files in deploy/NGINX/ for domain-based routing.
License
MIT License
