模型上下文协议服务器

🔌 MCP Nexus

具有通用访问能力的模型上下文协议（MCP）服务器的全面演示

🌟 概述

MCP Nexus 是一个Next.js应用程序，展示了功能齐全的模型上下文协议（MCP）服务器实现。该项目演示了如何构建一个可以从多个入口点访问的MCP服务器，使其成为将AI功能集成到应用程序中的通用解决方案。

✨ 主要特点

🔄 通用访问

该项目的主要优势在于它能够通过以下方式提供MCP服务器访问 所有可能的渠道:

• 🌐 外部客户端 -从外部工具（如Cursor、Claude Desktop或任何兼容MCP的客户端）连接
• 💻 客户端访问 -直接从Next.js客户端组件使用MCP工具
• ⚙️ 服务器端访问 -利用Next.js API路由和服务器组件中的MCP功能

这种多通道方法使MCP Nexus成为构建可集成到堆栈中任何位置的生产就绪MCP服务器的完整参考实现。

🚀 在线演示

在此处尝试公共部署：
👉 https://mcp-nexus-fgka.onrender.com/

• /api/health-check → 应返回 OK
• MCP端点需要 MCP_API_KEY （参见 连接外部客户端)

🚀 入门指南

先决条件

• Node.js 25或以上
• pnpm 10或更高

安装

pnpm install

环境变量

复制 apps/web/.env.example 到 apps/web/.env 并调整值：

# Server Configuration
NODE_ENV=development
HOST=localhost
PORT=4004
MCP_PORT=4005
NEXT_PUBLIC_MCP_PORT=4005
NEXT_PUBLIC_OPENAI_SECURITY_KEY=replace-with-your-key

# OpenAI credentials for GPT proxy (server-only — never NEXT_PUBLIC_*)
OPENAI_API_KEY=sk-...
OPENAI_PROJECT_KEY=proj_...

# MCP access control (required in production)
MCP_API_KEY=generate-a-long-random-secret

# Firebird (optional — enables Firebird MCP tools: search_tables, list_tables, describe_table, execute_sql)
ISC_USER=SYSDBA
ISC_PASSWORD=your_password
NODE_FB_HOST=localhost
NODE_FB_PORT=3050
NODE_FB_DB=D:/path/to/database.fdb
# FIREBIRD_MAX_ROWS=500
# FIREBIRD_QUERY_TIMEOUT_MS=30000
# FIREBIRD_SQL_DIALECT=2.5

集 MCP_API_KEY 在部署之前，先隐藏一个长长的随机秘密。在生产环境中，MCP服务器拒绝未经身份验证的请求。web UI必须在中验证此密钥 设置BFF在 /api/mcp 转发客户端 Authorization 标头，并且不会自动注入密钥。

集 OPENAI_API_KEY 并且可选 OPENAI_PROJECT_KEY 在 .env 聊天；它们以如下方式发送到GPT代理 openai_api_key 和 project.代理人 安全密钥 按用户输入 设置.

这 .env 文件在 .gitignore如果没有Firebird变量，MCP服务器仍然会启动；Firebird工具返回一个明确的配置错误。

Firebird本机驱动程序（Windows/本地开发）

node-firebird-driver-native 取决于本机插件(node-firebird-native-api).之后 pnpm install，如果工具出现故障 找不到绑定文件:

1. 确保 Firebird客户端 (fbclient.dll)已安装并打开 PATH.
2. 构建插件（需要Visual Studio构建工具和Python node-gyp):

pnpm firebird:build-native

如果这不产生 addon.node，在包内手动运行：

cd node_modules/node-firebird-native-api
npm run gyp:configure
npm run gyp:build

针对您的烟雾测试（只读） .env:

# optional: use another project's .env without copying secrets into apps/web
$env:FIREBIRD_ENV_FILE="D:\git\gdmn-nxt\.env"   # PowerShell
pnpm firebird:smoke

发展

启动开发环境（运行Next.js应用程序和MCP服务器）：

pnpm dev

该应用程序将在 http://{host}:{port}，MCP服务器将在上并行运行 MCP_PORT （默认值 4005).

web UI通过以下方式连接到MCP BFF路线 在 /api/mcp (apps/web/app/api/mcp/route.ts).在“设置”中验证MCP密钥后，浏览器会发送 Authorization: Bearer <key> 在每个MCP请求上；BFF验证它并转发给MCP服务器。

运行特定组件

# Run only the Next.js app
pnpm --filter web dev:next

# Run only the MCP server
pnpm --filter web dev

清理

全部删除 node_modules 以及缓存文件：

pnpm clean

这将删除：

• 全部 node_modules 目录
• Turbo缓存(.turbo)
• Next.js构建缓存(.next)
• TypeScript构建信息(.tsbuildinfo)
• 构建和分发目录

Docker部署

本地建设（开发）

在您的计算机上从源代码构建和运行。秘密来自 apps/web/.env 在 运行时 仅（未烘焙到图像中）。

pnpm docker:s:up
pnpm docker:s:down

.env 文件通过以下方式从Docker构建上下文中排除 .dockerignore请勿通过 MCP_API_KEY，Firebird凭据或OpenAI密钥作为Docker构建参数。

CI：GitHub操作→ GHCR

每一次推 main （以及版本标签 v*), .github/workflows/docker-publish.yml 构建图像并将其推送到：

ghcr.io/hirurg-lybitel/mcp-nexus

仅 NEXT_PUBLIC_MCP_PORT 在构建时传递（不是秘密）。所有敏感值都保留在服务器上。

将GHCR包设为私有（推荐）

公共GitHub仓库仍然可以使用 私人的 集装箱包装：

1. 推至 main 一旦完成，工作流就会创建包。
2. 打开 GitHub→ 您的个人资料/组织→ 包裹→ mcp关系.
3. 软件包设置→ 更改可见性→ 私人.

仅限以下账户 read:packages （或您的组织）可以 docker pull 图像。

VPS上的生产

在服务器上，在git repo之外保守秘密：

sudo mkdir -p /opt/mcp-nexus
sudo nano /opt/mcp-nexus/.env          # copy from .env.example, fill production values
sudo chmod 600 /opt/mcp-nexus/.env

使用创建GitHub个人访问令牌 read:packages，然后登录GHCR：

echo "$GITHUB_PAT" | docker login ghcr.io -u YOUR_GITHUB_USERNAME --password-stdin

复制 docker-compose.prod.yaml 到服务器（或克隆没有 .env):

cd /opt/mcp-nexus
docker compose -f docker-compose.prod.yaml pull
docker compose -f docker-compose.prod.yaml --env-file .env up -d

在新推送后进行更新 main:

docker compose -f docker-compose.prod.yaml pull
docker compose -f docker-compose.prod.yaml --env-file .env up -d

确保VPS可以访问您的Firebird主机(NODE_FB_HOST).如果没有VPN或隧道，局域网IP将无法在公共服务器上工作。

🛠️ API终点

/api/health-check --一条总是返回状态200和文本“OK”的简约路线。 适用于：

• Docker/Kubernetes中的健康检查
• 监控服务可用性
• 检查Next.js应用程序是否正确启动

连接外部客户端

MCP直接访问位于 http://localhost:4005/mcp （或你主人的 MCP_PORT). 需要认证 当 MCP_API_KEY 已设置。

光标

添加到 .cursor/mcp.json:

{
  "mcpServers": {
    "local-mcp": {
      "url": "http://localhost:4005/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MCP_API_KEY}"
      }
    }
  }
}

集 MCP_API_KEY 在您的环境（或Cursor env）中进行匹配 apps/web/.env.

Firebird MCP服务器（只读，便携式）

暴露在 http://localhost:4005/mcp --可从Cursor、VS Code或任何MCP客户端使用。需要 Authorization: Bearer <MCP_API_KEY> 当配置密钥时。

数据库访问存在 packages/db-firebird.MCP接线： apps/web/lib/mcp/firebird-tools.ts.

只读保证

所有SQL都通过一个执行器(ReadQueryExecutor)深度防御：

1. SQL文本保护 (assertReadOnlySql)--只有 SELECT / WITH；块 ;DML/DDL关键字， EXECUTE, GEN_ID, FOR UPDATE, INTO.
2. 方言警卫 (assertDialectCompatibleSql)--什么时候 FIREBIRD_SQL_DIALECT=2.5 （默认），阻止CTE(WITH)，窗口功能(OVER, ROW_NUMBER，…），以及 RECURSIVE.Set FIREBIRD_SQL_DIALECT=3 Firebird 3+部署允许使用现代SQL。在中镜像相同的值 NEXT_PUBLIC_FIREBIRD_SQL_DIALECT 因此聊天系统提示与服务器验证相匹配。
3. 火鸟交易 --每个查询都在 accessMode: 'READ_ONLY'.
4. 预点火打开 execute_sql --根据模式验证的表名； SELECT * 用敏感列挡住桌子；行和超时限制。

有 不 运行时开关以允许写入(FIREBIRD_ALLOW_WRITE 未实现）。

剩余风险 （记录在案，仅在代码中没有消除）：

• 可选择的存储过程 (SELECT * FROM MY_PROC(...))可能有副作用，具体取决于手术主体； READ_ONLY 事务应该拒绝数据修改，但这是特定于环境的。
• 特权数据库用户 --使用专用的只读Firebird用户，而不是 SYSDBA 生产中（见 .env.example).
• 表名飞行前 不解析引用的或模式限定的标识符；这会影响发现验证，而不是写访问。

本地验证：

pnpm --filter @mcp-nexus/db-firebird test
pnpm --filter @mcp-nexus/db-firebird test:integration   # needs Firebird in apps/web/.env

MCP Nexus网络代理（仅主机工具）

已在Next.js聊天室注册(GptFunctions)，不在Firebird MCP服务器上：

实施： apps/web/lib/agent/.

光标/外部MCP客户端：指向 http://localhost:4005/mcp （参见 .cursor/mcp.json local-mcp)--他们只获得Firebird工具；计划/呈现需要网络助手。

🛠️ 技术栈

• 框架：Next.js 16
• 语言：TypeScript
• 单体仓库：涡轮增压
• 包管理器：pnpm
• MCP-SDK：@modelcontextprotocol/sdk
• 数据库：火鸟经 node-firebird-driver-native (@mcp-nexus/db-firebird)

🎯 用例

• 学习MCP -了解如何从头开始实施MCP服务器
• 集成参考 -了解如何将MCP集成到Next.js应用程序中
• 多通道接入 -了解如何从客户端、服务器和外部工具启用MCP访问
• 开发模板 -用作您自己的MCP供电应用程序的起点

📚 了解更多

• 模型上下文协议文档
• Next.js文档
• Turbo文档

📄 许可证

该项目是开源的，可用于教育和开发目的。

内置于❤️ 展示通用MCP接入的强大功能