使用说明

MCP检查员包装

一种生产就绪的包装 @modelcontextprotocol/inspector 与Kubernetes兼容的健康检查端点。

🎯 概述

此包装器运行MCP检查器，其中所有内容都可以在 单端口（3000）:

健康检查端点(/health, /healthz)
MCP检查器UI（代理到端口3000）
MCP检查器服务器（内部端口6277）
默认情况下已禁用身份验证 通过代理更容易访问

非常适合具有内置健康探测器的Kubernetes/Pod部署。

🚀 快速开始

1.安装依赖项

npm install

2.运行应用程序

npm start

3.访问应用程序

MCP检查器UI: http://localhost:3000（无需令牌！）
健康检查: http://localhost:3000/health（返回“ok”）
详细健康状况: http://localhost:3000/healthz（返回JSON）

备注：默认情况下禁用身份验证(DANGEROUSLY_OMIT_AUTH=true)因此，您可以直接访问UI，而不需要令牌。这在具有网络隔离的容器化/吊舱环境中是安全的。

📦 可用命令

命令	描述
`npm start`	启动应用程序（生产模式）
`npm run dev`	从调试环境变量开始
`npm run build`	将package.json和node_modules复制到 `dist/` 文件夹

🔧 环境变量

通过配置 .env 文件或环境：

变量	默认值	描述
`NODE_ENV`	`development`	节点环境
`NODE_TLS_REJECT_UNAUTHORIZED`	`0`	TLS证书验证（0=已禁用）
`DEBUG`	`1`	启用调试模式
`PORT`	`3000`	主应用程序端口（健康+UI）
`SERVER_PORT`	`6277`	MCP检查器服务器端口（内部）
`MCP_AUTO_OPEN_ENABLED`	`false`	启动时自动打开浏览器
`DANGEROUSLY_OMIT_AUTH`	`true`	禁用身份验证令牌要求

关于身份验证

默认情况下， DANGEROUSLY_OMIT_AUTH=true 已设置，这将禁用身份验证令牌要求。这意味着：

✅ 您可以访问http://localhost:3000直接没有令牌
✅ 在容器化环境中使用更简单
⚠️ 应仅在受信任/隔离的网络中使用（如Kubernetes Pod）

如果需要启用身份验证，请设置 DANGEROUSLY_OMIT_AUTH=false 在你的 .env 文件。

🏥 健康检查端点

`/health`

返回带有纯文本“ok”的HTTP 200-非常适合Kubernetes探测。

curl http://localhost:3000/health
# Response: ok

`/healthz`

返回HTTP 200，其中包含详细的JSON健康信息。

curl http://localhost:3000/healthz
# Response: {"status":"ok","timestamp":"...","service":"mcp-inspector-wrapper",...}

☸️ Kubernetes/Pod部署

该应用程序旨在与标准Kubernetes部署配合使用。

完整Pod配置示例

apiVersion: v1
kind: Pod
metadata:
  name: mcp-inspector
spec:
  containers:
  - name: mcp-inspector
    image: your-registry/mcp-inspector-wrapper:latest
    command: ["npm", "start"]
    ports:
    - containerPort: 3000
      name: app
    - containerPort: 6277
      name: server
    env:
    - name: NODE_TLS_REJECT_UNAUTHORIZED
      value: "0"
    - name: NODE_ENV
      value: "production"
    - name: PORT
      value: "3000"
    - name: MCP_AUTO_OPEN_ENABLED
      value: "false"
    - name: DANGEROUSLY_OMIT_AUTH
      value: "true"  # Safe in isolated pod network
    livenessProbe:
      httpGet:
        path: /health
        port: 3000
      initialDelaySeconds: 30
      periodSeconds: 10
    readinessProbe:
      httpGet:
        path: /health
        port: 3000
      initialDelaySeconds: 15
      periodSeconds: 5

要点

启动命令: npm start （已配置）
主要港口: 3000 （健康检查+UI）
健康探测：指向 /health 在港口3000
认证：默认情况下禁用，以便更容易访问pod
无需更改Docker/K8s配置

📊 建筑

┌─────────────────────────────────────────┐
│         Port 3000 (External)            │
├─────────────────────────────────────────┤
│  GET /health    → "ok" (200)            │
│  GET /healthz   → JSON health info      │
│  GET /*         → MCP Inspector UI      │
│                   (proxied internally)  │
│                   NO AUTH TOKEN NEEDED  │
└─────────────────────────────────────────┘
              ↓ (proxy)
┌─────────────────────────────────────────┐
│  Port 6274 - MCP Inspector Client       │
│  (internal, not exposed)                │
│  Auth disabled via DANGEROUSLY_OMIT_AUTH│
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  Port 6277 - MCP Inspector Server       │
│  (internal communication)               │
└─────────────────────────────────────────┘

运作原理

MCP检查器在端口6274（客户端）和6277（服务器）上内部启动
通过禁用身份验证 DANGEROUSLY_OMIT_AUTH=true
Express代理服务器在端口3000上运行：
- /health 和 /healthz 立即返回响应
- 所有其他请求都代理到MCP检查器UI
无需身份验证令牌-直接访问UI

🧪 测试

测试运行状况端点

npm start

# In another terminal
curl http://localhost:3000/health
# Expected: ok (HTTP 200)

测试UI访问（不需要令牌！）

# Open in browser
open http://localhost:3000

# Or test with curl
curl http://localhost:3000/
# Expected: HTML of MCP Inspector

或者使用附带的测试脚本

chmod +x test-health.sh
./test-health.sh

🛠️ 故障排除

日志中的“来源无效”错误

这些都是正常的，可以忽略不计。它们发生的原因是代理更改了源标头，但检查器仍然正常工作。

健康检查失败

验证服务器是否正在运行：
```
npm start
```
检查端口是否可访问：
```
curl http://localhost:3000/health
```
确保端口3000未被使用：
```
lsof -i :3000
```

检查器未启动

检查中的环境变量 .env
确保Node.js版本为18或更高： node --version

清除并重新安装依赖关系：

rm -rf node_modules package-lock.json
npm install

需要身份验证？

如果要启用身份验证，请设置 DANGEROUSLY_OMIT_AUTH=false 在你的 .env 文件。然后，检查器将生成一个出现在启动日志中的令牌。

📁 项目结构

mcp-inspector/
├── server.js              # Main wrapper with health endpoint & proxy
├── package.json           # Dependencies and scripts
├── package-lock.json      # Locked dependencies
├── .env                   # Environment configuration
├── .gitignore            # Git ignore rules
├── README.md             # This file
├── test-health.sh        # Health check test script
└── Dockerfile.example    # Optional Docker file

🐳 Docker支持（可选）

Dockerfile示例如下 Dockerfile.example:

# Build the image
docker build -f Dockerfile.example -t mcp-inspector-wrapper .

# Run the container
docker run -p 3000:3000 -p 6277:6277 mcp-inspector-wrapper

📝 命令参考

原始命令如下：

NODE_TLS_REJECT_UNAUTHORIZED=0 NODE_ENV=development DEBUG=1 npx @modelcontextprotocol/inspector

现在只需运行：

npm start

所有环境变量都在中预先配置 .env，并且禁用身份验证以便于访问。

🔒 安全说明

默认情况下已禁用身份验证

DANGEROUSLY_OMIT_AUTH=true 意味着不需要身份验证令牌
这是 安全的 在隔离环境中（具有网络策略的Kubernetes Pod）
请勿将端口3000暴露于公共互联网 禁用身份验证
对于生产外部访问，请考虑：
- 使用网络策略限制访问
- 通过设置启用身份验证 DANGEROUSLY_OMIT_AUTH=false
- 将服务置于经过身份验证的反向代理之后

✅ 生产就绪

✅ 健康端点返回HTTP 200并显示“ok”
✅ 运行通过 npm start （吊舱兼容）
✅ 客户端和服务器组件都会自动启动
✅ 正确设置环境变量
✅ SIGTERM/SIGINT上的优雅关机
✅ 单端口简化部署
✅ 禁用身份验证以方便pod访问
✅ 无需更改Docker/Kubernetes配置

📄 许可证

麻省理工学院