convez.ai
MCP ServerDevOps & InfraestruturaAvançado
Bazilio-san

FA MCP SDK

Bazilio-san/fa-mcp-sdk

Framework production-ready para servidores MCP com CLI, agentes de teste e duplo transporte

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de produção completo para construir servidores Model Context Protocol (MCP) em TypeScript com suporte a transportes duplos (STDIO e HTTP/SSE), autenticação, integração de banco de dados e testes automatizados. Inclui CLI para gerar projetos prontos para uso com infraestrutura enterprise.

Instalação

$npx convez-ai Bazilio-san/fa-mcp-sdk

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
—
Issues abertas
3
Contribuidores
3

Casos de uso

  • Criar servidores MCP empresariais com autenticação JWT e rate limiting
  • Gerar projetos MCP baseados em templates com infraestrutura completa
  • Testar ferramentas MCP automaticamente com agentes de teste integrados
  • Integrar MCP com PostgreSQL, pgvector e service discovery Consul

Veredito

Ferramenta madura e bem estruturada para quem precisa de infraestrutura enterprise em MCP servers TypeScript. O Agent Tester integrado e suporte a duplo transporte elevam a qualidade do desenvolvimento, embora exija conhecimento sólido de arquitetura de backend para aproveitar todo o potencial.

README

A tradução para o português deste README ainda está na fila.

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
  • Transport Hardening: Per-tool execution timeout, JSON-RPC request body cap and tool-result truncation — all driven by mcp.limits in config/default.yaml:
    • mcp.limits.maxPayloadBytes — max accepted request body (default 1 MiB; JSON-RPC -32005 / HTTP 413 above)
    • mcp.limits.maxToolResultBytes — max serialized tool result (default 10 MiB; truncated with explicit marker)
    • mcp.limits.toolTimeoutMs — per-tool execution timeout (default 30 000 ms; JSON-RPC -32004 / HTTP 504 above)
  • 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

  1. Install fa-mcp-sdk globally:

    npm install -g fa-mcp-sdk
    
  2. Run the CLI, specify the target directory, and follow the interactive prompts:

    fa-mcp
    

    Or using configuration file:

    fa-mcp config.yaml
    
  3. 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
  4. Vibe-coding your MCP server logic:

    • Create an instruction file (prompt) for your preferred AI coding assistant. fa-mcp-sdk comes ready for use with Claude Code. You can find an example prompt for creating an MCP server (e.g., a currency exchange rate provider) in cli-template/prompt-example-new-MCP.md.
    • Launch your AI coder and provide it with the instructions to build your new MCP server.

Configuration

The CLI collects required and optional parameters through interactive prompts or configuration file.

Required Parameters

ParameterDescriptionExample
project.namePackage.json name and MCP server identification"my-mcp-server"
project.descriptionPackage.json description"A custom MCP server"
project.productNameDisplay name for UI and documentation"My MCP Server"
portWeb server port for HTTP and MCP protocol"3000"

Optional Parameters

ParameterDescriptionDefault
author.namePackage.json author name""
author.emailPackage.json author email""
git-base-urlGit repository base URL"github.com/username"
consul.service.enableEnable Consul service registration"false"
consul.agent.reg.tokenToken for registering service with Consul"***"
consul.envCode.devDevelopment environment code"<envCode.dev>"
consul.envCode.prodProduction environment code"<envCode.prod>"
consul.agent.dev.dcDevelopment Consul datacenter""
consul.agent.dev.hostDevelopment Consul UI host"consul.my.ui"
consul.agent.dev.tokenDevelopment Consul access token"***"
consul.agent.prd.dcProduction Consul datacenter""
consul.agent.prd.hostProduction Consul UI host"consul.my.ui"
consul.agent.prd.tokenProduction Consul access token"***"
mcp.domainDomain name for nginx configuration""
ssl-wildcard.conf.rel.pathRelative path to SSL config in /etc/nginx"snippets/ssl-wildcard.conf"
webServer.auth.enabledEnable token authorization"false"
webServer.auth.token.checkMCPNameCheck MCP name in token"false"
isProductionProduction mode flag"false"
SERVICE_INSTANCEService name suffix for Consul and PM2""
maintainerUrlSupport/maintainer URL""
logger.useFileLoggerEnable 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
├── .oxlintrc.json               # Oxlint configuration
├── .oxfmtrc.json                # Oxfmt 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

ScriptDescription
npm startStart compiled MCP server
npm run buildCompile TypeScript
npm run cbClean and build
npm run ciInstall dependencies
npm run reinstallReinstall all dependencies
npm run lintRun Oxlint
npm run lint:fixFix Oxlint issues
npm run formatCheck formatting via Oxfmt
npm run format:fixFormat the project via Oxfmt
npm run qualityLint + format check
npm run quality:fixAuto-fix lint + format
npm run test:mcpTest MCP tools
npm run test:mcp-httpTest HTTP transport
npm run test:mcp-sseTest SSE transport
npm run test:mcp-stdioTest STDIO transport
npm run generate-tokenGenerate JWT tokens (Web UI)
node scripts/generate-jwt.jsGenerate JWT token (CLI)
/gen-jwtGenerate JWT token (Claude Code skill)
/upgrade-guideGenerate upgrade guide for downstream projects (Claude Code skill)
npm run agents:linkShare .claude/skills with OpenAI Codex (creates .agents/skills symlink)
npm run agents:link:statusShow current state of the Codex skills link
npm run agents:link:removeRemove the Codex skills link
npm run consul:unregDeregister from Consul

Server runs at

http://localhost:3000 with:

  • MCP endpoints at /mcp/*
  • Admin panel for generating access tokens at /admin
    • When adminPanel.authType includes jwtToken, the JWT must carry allow: '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. permanentServerTokens and basic admin auth are unaffected. Generate an admin-capable JWT: node scripts/generate-jwt.js -u admin -ttl 30d -p "allow=gen-token"
  • JWT generation API at /gen-jwt (when webServer.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

Sharing Skills with OpenAI Codex

Claude Code skills (.claude/skills/*) can be reused from OpenAI Codex without duplication. Codex officially reads project Skills from .agents/skills/ and supports symlinked skill folders. The bundled scripts/claude-2-agents-symlink.js creates the symlink (junction on Windows, relative symlink on macOS/Linux) so both tools share the same canonical storage in .claude/skills/.

npm run agents:link          # create .agents/skills -> .claude/skills
npm run agents:link:status   # inspect current link state
npm run agents:link:remove   # remove the link

Only skills are linked — other Claude Code entities (.claude/agents/, .claude/commands/, hooks, MCP config) use formats that are not compatible with Codex (TOML agents in .codex/agents/, MCP servers in .codex/config.toml) and must be configured separately. For Claude Code's CLAUDE.md and Codex's AGENTS.md, keep a single AGENTS.md and import it from CLAUDE.md via @AGENTS.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

Ver o original no GitHub

Bom para

Relacionados