Fa MCP Server Core

MCP服务器模板生成器

用于构建MCP（模型上下文协议）服务器的生产就绪核心框架，具有全面的 基础设施支持。

CLI实用程序，用于从官方模板创建即用型MCP（模型上下文协议）服务器项目。

概述

该框架为构建企业级MCP服务器提供了完整的基础设施：

• 双重运输：STDIO（克劳德桌面）和HTTP/SSE（web客户端）
• 代理驱动工具开发：内置AI代理系统（agent Tester），用于通过自动化测试周期迭代改进MCP工具——代理调用您的工具，您观察行为，调整描述/参数/提示，并重新测试
• 无头试验API：直接HTTP端点(POST /agent-tester/api/chat/test)返回每个工具调用、参数、结果和LLM决策的结构化跟踪，无需浏览器即可实现基于CLI的自动化测试
• 认证：JWT（具有可选的IP限制）、基本身份验证、永久令牌、自定义验证器
• 数据库集成：PostgreSQL与pgvector用于向量操作
• 服务发现：微服务的Consul集成
• 速率限制：所有端点的可配置速率限制
• API文档：自动生成Swagger/OpenAPI
• 生产测井：带数据屏蔽的结构化日志记录
• 配置管理：基于YAML的环境覆盖
• 部署就绪：PM2脚本、Nginx模板、ESLint、Jest测试

该框架使用依赖注入来保持核心对项目特定实现的完全不可知性。

入门步骤

1. 安装 fa-mcp-sdk 全球地：

   npm install -g fa-mcp-sdk

1. 运行CLI，指定目标目录，然后按照交互式提示进行操作：

   fa-mcp

或者使用配置文件：

   fa-mcp config.yaml

1. 启动模板MCP服务器：

- 导航到目标目录： cd - 安装依赖项： npm install - 构建项目： npm run build - 启动服务器： npm start

1. Vibe对MCP服务器逻辑进行编码：

- 为您首选的AI编码助手创建一个指令文件（提示）。 fa-mcp-sdk 已准备好与一起使用 Claude Code. 您可以在中找到创建MCP服务器（例如货币汇率提供者）的示例提示 cli-template/prompt-example-new-MCP.md. - 启动您的AI编码器，并向其提供构建新MCP服务器的说明。

配置

CLI通过交互式提示或配置文件收集必需和可选参数。

必需参数

可选参数

配置文件示例

链接： 带有详细注释的YAML示例

该实用程序支持这两种功能 JSON 和 YAML 配置格式。 使用其中之一 .json, .yaml，或 .yml 文件扩展名。

用途：

# 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

项目结构

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

注： dist/ 运行后创建目录（编译的JavaScript） npm run build.

可用脚本

服务器运行于

http://localhost:3000 与：

• MCP端点位于 /mcp/*
• 用于生成访问令牌的管理面板 /admin

- 当 adminPanel.authType 包括 jwtTokenJWT 必须 携带 allow: 'gen-token' 其有效载荷将被接受。没有此声明的令牌（例如短寿命的JWT 为Agent Tester页面自动生成的）被拒绝，这会阻止它们 被重放以铸造任意的长期代币。 permanentServerTokens 和 basic 管理员身份验证不受影响。 生成具有管理员功能的JWT： node scripts/generate-jwt.js -u admin -ttl 30d -p "allow=gen-token"

• API JWT代 /gen-jwt （当 webServer.genJwtApiEnable: true)
• Swagger用户界面位于 /docs
• 健康检查在 /health

代理测试员

内置聊天界面，用于使用AI代理（OpenAI兼容的LLM）测试MCP服务器工具。 代理会自动发现可用的工具，并在对话循环中调用它们。

要启用，请设置环境变量(.env 或外壳）：

AGENT_TESTER_ENABLED=true
AGENT_TESTER_OPENAI_API_KEY=sk-...

或在中配置 config/default.yaml （或 local.yaml):

agentTester:
  enabled: true
  openAi:
    apiKey: sk-...

测试仪用户界面可在 http://localhost: /agent-tester 并自动连接到本地MCP服务器。 支持自定义LLM端点、可配置的系统提示和动态HTTP标头。推荐的测试模型： gpt-5.2.

升级导游技能

Claude Code技能，为基于fa-mcp-sdk构建的项目生成逐步升级指南。 分析两个版本/提交之间的git差异，并生成一个MD文件，其中包括配置更改、模板文件更新、脚本更改、API更改和依赖项更新。

克劳德代码中的用法：

/upgrade-guide 0.4.30 0.4.37
/upgrade-guide 0.4.30
/upgrade-guide abc1234
/upgrade-guide 0.4.30 0.4.37 на русском

默认情况下，输出语言为英语。添加自然语言提示（例如，“наруском”，“德语”）以更改它。

技能位置： .claude/skills/upgrade-guide/SKILL.md

目录要求

• 为目标目录使用绝对路径

• 仅空目录 -如果文件存在，CLI将中止，但以下文件除外：

  .git/
  .idea/
  .vscode
  .DS_Store
  node_modules/
  dist/
  __misc/
  _tmp/
  .swp
  .swo
  .sublime-project
  .sublime-workspace
  ~last-cli-config.json

部署

PM2生产

npm run build
pm2 start deploy/pm2.config.js

系统化服务

npm run build
chmod +x deploy/srv.cjs
./deploy/srv.cjs install

领事注册

集 consul.service.enable: true 并提供自动服务注册所需的令牌。

Nginx配置

在中生成nginx配置文件 deploy/NGINX/ 用于基于域的路由。

许可证

MIT许可证