AI导哈

MCP服务器模板生成器

用于构建企业级MCP（Model Context Protocol）服务器的生产就绪核心框架，提供全面的基础设施支持，包括双传输协议、AI代理系统、数据库集成和服务发现等功能。

  • by Bazilio-san
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Bazilio-san/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集成
  • 速率限制：所有端点的可配置速率限制
  • 运输硬化：每个工具执行超时、JSON-RPC请求体上限和工具结果截断-- 所有驱动 mcp.limits 在 config/default.yaml:
    • mcp.limits.maxPayloadBytes --最大接受请求体（默认1 MiB；JSON-RPC -32005 /HTTP 413以上）
    • mcp.limits.maxToolResultBytes --最大序列化工具结果（默认值10 MiB；用显式标记截断）
    • mcp.limits.toolTimeoutMs --每个工具执行超时（默认值为30000毫秒；JSON-RPC -32004 /HTTP 504以上）
  • API文档：自动生成Swagger/OpenAPI
  • 生产测井：带数据屏蔽的结构化日志记录
  • 配置管理：基于YAML的环境覆盖
  • 部署就绪：PM2脚本、Nginx模板、ESLint、Jest测试

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

入门步骤

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

    npm install -g fa-mcp-sdk

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

    fa-mcp

    或者使用配置文件：

    fa-mcp config.yaml

  3. 启动模板MCP服务器：

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

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

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

配置

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

必需参数

参数 说明 示例
project.name Package.json名称和MCP服务器标识 "my-mcp-server"
project.description Package.json描述 "A custom MCP server"
project.productName UI和文档的显示名称 "My MCP Server"
port 用于HTTP和MCP协议的Web服务器端口 "3000"

可选参数

参数 说明 默认值
author.name Package.json作者姓名 ""
author.email Package.json作者电子邮件 ""
git-base-url Git存储库基URL "github.com/username"
consul.service.enable 启用Consul服务注册 "false"
consul.agent.reg.token 用于在Consul注册服务的令牌 "***"
consul.envCode.dev 开发环境代码 "<envCode.dev>"
consul.envCode.prod 生产环境代码 "<envCode.prod>"
consul.agent.dev.dc Development Consul数据中心 ""
consul.agent.dev.host 开发领事UI主机 "consul.my.ui"
consul.agent.dev.token Development Consul访问令牌 "***"
consul.agent.prd.dc 生产领事数据中心 ""
consul.agent.prd.host 生产领事UI主机 "consul.my.ui"
consul.agent.prd.token 生产领事访问令牌 "***"
mcp.domain nginx配置的域名 ""
ssl-wildcard.conf.rel.path /etc/nginx中SSL配置的相对路径 "snippets/ssl-wildcard.conf"
webServer.auth.enabled 启用令牌授权 "false"
webServer.auth.token.checkMCPName 检查令牌中的MCP名称 "false"
isProduction 生产模式标志 "false"
SERVICE_INSTANCE Consul和PM2的服务名称后缀 ""
maintainerUrl 支持/维护者URL ""
logger.useFileLogger 启用文件日志记录 ""

配置文件示例

链接： 带有详细注释的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
│   ├── CADDY/                   # Caddy reverse proxy template
│   │   └── Caddyfile            # Caddy site configuration
│   ├── 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.

可用脚本

脚本 描述
npm start 启动已编译的MCP服务器
npm run build 编译TypeScript
npm run cb 清洁和建造
npm run ci 安装依赖项
npm run reinstall 重新安装所有依赖项
npm run lint 运行Oxlint
npm run lint:fix 修复Oxlint问题
npm run format 通过Oxfmt检查格式
npm run format:fix 通过Oxfmt格式化项目
npm run quality Lint+格式检查
npm run quality:fix 自动修复lint+格式
npm run test:mcp 测试MCP工具
npm run test:mcp-http 测试HTTP传输
npm run test:mcp-sse 测试SSE传输
npm run test:mcp-stdio 测试STDIO传输
npm run generate-token 生成JWT令牌（Web UI）
node scripts/generate-jwt.js 生成JWT令牌（CLI）
/gen-jwt 生成JWT令牌（克劳德代码技能）
/upgrade-guide 为下游项目生成升级指南（Claude Code技能）
npm run agents:link 分享 .claude/skills OpenAI Codex（创建 .agents/skills 符号链接）
npm run agents:link:status 显示Codex技能链接的当前状态
npm run agents:link:remove 删除Codex技能链接
npm run consul:unreg 从领事处注销

服务器运行于

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:<port>/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 in Russian

默认情况下，输出语言为英语。添加自然语言提示（例如“俄语”、“德语”）以更改它。

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

与OpenAI Codex分享技能

Claude代码技能(.claude/skills/*)可重复使用 OpenAI Codex 没有重复。Codex正式从 .agents/skills/ 并支持符号链接技能 文件夹。捆绑 scripts/claude-2-agents-symlink.js 创建符号链接（Windows上的连接，相对符号链接 在macOS/Linux上），因此这两个工具在 .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

仅 技能 是链接的——其他Claude Code实体(.claude/agents/, .claude/commands/、挂钩、MCP config）使用与Codex不兼容的格式（中的TOML代理 .codex/agents/中的MCP服务器 .codex/config.toml)并且必须单独配置。克劳德代码的 CLAUDE.md 食品法典委员会 AGENTS.md, 保持单身 AGENTS.md 并从以下位置导入 CLAUDE.md 通过 @AGENTS.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/Caddy）

已准备好适应的反向代理模板在中生成 deploy/: NGINX/sites-enabled/<domain>.conf 连同 NGINX/snippets/mcp-proxy.conf，以及等效物 CADDY/Caddyfile两者都给MCP 协议端点(/mcp, /sse, /messages)无缓冲代理和长时间读取超时——服务器 使用缓冲代理将保留的服务器发送事件流来应答JSON-RPC调用，以及 服务器启动的流保持空闲的时间远远超过Nginx默认的60秒。Agent测试员 Prometheus度量端点和令牌发放端点(/admin, /gen-jwt)得到自己的块 分别具有更长的LLM回合超时时间和可选的网络允许列表。集 webServer.trustProxy: true 在配置中，应用程序尊重 X-Forwarded-* 标题。

许可证

MIT许可证

相关 MCP