诺克斯-MCP代理

Name: 诺克斯-MCP代理
Author: lmccay

作者：lmccay2 星标更新：2025-08-17

安装使用来源：spider==github.com

项目介绍

Knox MCP 代理

一个全面的 Apache Knox 扩展，将多个模型上下文协议（MCP）服务器聚合到统一的 MCP 网关中，提供对分布式人工智能工具和资源的无缝访问，并具有完整的传输兼容性。

🌟 概述

Knox MCP 代理扩展了 Apache Knox，使其成为 MCP 生态系统中的中央网关。它提供了一个基于 Jersey 的 REST API 和 MCP 服务器，该服务器使用任何传输协议连接到多个下游 MCP 服务器，并通过安全、经过身份验证的 HTTP 终端节点公开它们的聚合功能。

✨ 主要特性

🔗 全面的 MCP 兼容性：支持所有 MCP 传输协议（stdio、HTTP、SSE、自定义）
� 符合 MCP 规范的可流式传输 HTTP：实现官方 MCP 规范，具有统一的终端节点和内容协商
�🚀 多服务器聚合：无缝结合来自多个 MCP 服务器的工具和资源
🛡️ Knox 安全集成：利用 Knox 的认证、授权和安全提供者
🏷️ 智能命名空间：通过服务器前缀名称防止工具/资源冲突
🔄 向后兼容性：在添加规范兼容性的同时，与现有的 SSE 客户端保持完全兼容

🏗️ 架构

AI 代理及应用程序
    |
    v
Knox 网关（安全、认证、SSL）
    |
    v
Jersey REST API (/mcp/v1/*)
    |
    v
MCP 代理资源（聚合）
    |
    ├── stdio://python calculator_server.py    (进程)
    ├── http://webapi.example.com              (HTTP)
    ├── sse://realtime.service.com             (SSE)
    └── custom-http-sse://gateway.internal     (自定义)

🚀 传输支持矩阵

传输	终端节点格式	兼容于	最适合
stdio	`stdio://python server.py`	标准 MCP 子进程服务器	本地 Python/Node.js 工具
HTTP	`http://localhost:3000`	标准 MCP HTTP 服务器	无状态 Web 服务
SSE	`sse://localhost:4000`	标准 MCP SSE 服务器	实时应用
自定义 HTTP+SSE	`custom-http-sse://localhost:5000`	Knox 优化的服务器	多客户端网关

⚙️ 配置

Knox 拓扑设置

<service>
    <role>MCPPROXY</role>
    <name>mcp</name>
    <version>1.0.0</version>
    <param>
        <name>mcp.servers</name>
        <value>calculator:stdio://python /path/to/calculator_server.py,
               webapi:http://localhost:3000,
               realtime:sse://localhost:4000,
               gateway:custom-http-sse://localhost:5000</value>
    </param>
</service>

支持的终端节点格式

stdio://命令参数 - 基于子进程的 MCP 服务器（Python、Node.js 等）
http://主机:端口 - 标准 HTTP 请求/响应 MCP 服务器
https://主机:端口 - 安全 HTTP MCP 服务器
sse://主机:端口 - 标准 SSE 双向 MCP 服务器
sses://主机:端口 - 安全 SSE MCP 服务器
custom-http-sse://主机:端口 - Knox 优化的混合传输
custom-https-sse://主机:端口 - 安全 Knox 混合传输

🔒 安全配置

Stdio 命令白名单

为了防止远程代码执行，基于 stdio 的 MCP 服务器被限制在一个允许的命令列表中：

<param>
    <n>mcp.stdio.allowed.commands</n>
    <value>python,node,java,npm</value>
</param>

安全特性：

✅ 命令验证：仅允许白名单中的命令执行
✅ 路径保护：命令通过基础名称进行验证（例如，/usr/bin/python → python）
✅ 默认安全：如果没有配置白名单，则记录警告
✅ 清晰错误消息：阻止的命令会收到描述性的错误响应

示例安全配置：

<service>
    <role>MCPPROXY</role>
    <n>mcp</n>
    <version>1.0.0</version>
    <param>
        <n>mcp.servers</n>
        <value>calculator:stdio://python /opt/mcp/calculator.py</value>
    </param>
    <param>
        <n>mcp.stdio.allowed.commands</n>
        <value>python,node</value>
    </param>
</service>

📚 API 参考

� 符合 MCP 规范的可流式传输 HTTP 终端节点

Knox MCP 代理现在支持官方 MCP 可流式传输 HTTP 规范，具有统一的终端节点：

# 符合 MCP 规范的统一终端节点
GET /gateway/sandbox/mcp/v1/      # 服务信息或 SSE 连接
POST /gateway/sandbox/mcp/v1/     # JSON-RPC 请求

# 内容协商示例：

# 1. 建立 SSE 连接（流式模式）
GET /gateway/sandbox/mcp/v1/
Accept: text/event-stream
# 返回：带有会话管理的 SSE 流

# 2. 标准 JSON-RPC 请求/响应
POST /gateway/sandbox/mcp/v1/
Content-Type: application/json
Accept: application/json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

# 3. JSON-RPC 带有流式响应（需要活跃的 SSE 会话）
POST /gateway/sandbox/mcp/v1/
Content-Type: application/json
Accept: text/event-stream
X-Session-ID: mcp-sse-12345
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {"name": "calculator", "arguments": {"operation": "add", "a": 5, "b": 3}},
  "id": 2
}

MCP 协议头：

mcp-version: 2024-11-05 - 自动添加到所有响应中
X-Session-ID: <会话ID> - 用于将消息路由到 SSE 会话

�🔍 发现终端节点

# 列出所有服务器上的可用工具
GET /gateway/sandbox/mcp/v1/tools

# 列出所有服务器上的可用资源
GET /gateway/sandbox/mcp/v1/resources

# 所有已连接服务器的健康检查
GET /gateway/sandbox/mcp/v1/health

⚡ 执行终端节点

# 使用参数执行工具
POST /gateway/sandbox/mcp/v1/tools/{服务器名.工具名}
Content-Type: application/json

{
  "param1": "值1",
  "param2": "值2"
}

# 访问资源
GET /gateway/sandbox/mcp/v1/resources/{服务器名.资源名}

🔄 遗留终端节点（向后兼容）

⚠️ 已弃用但完全支持现有客户端：

# 遗留 SSE 终端节点
GET /gateway/sandbox/mcp/v1/sse
# 仍然像以前一样工作 - 委托给统一终端节点

# 遗留 JSON-RPC 终端节点
POST /gateway/sandbox/mcp/v1/message
# 仍然像以前一样工作 - 包括 MCP 版本头

# 所有现有的 REST 终端节点保持不变
GET /gateway/sandbox/mcp/v1/tools
GET /gateway/sandbox/mcp/v1/resources
POST /gateway/sandbox/mcp/v1/tools/{工具名}
GET /gateway/sandbox/mcp/v1/resources/{资源名}
GET /gateway/sandbox/mcp/v1/health

迁移指南：

现有的客户端（Goose 桌面代理等）继续正常工作
新的实现应使用统一的 GET/POST / 终端节点
遗留终端节点记录弃用警告但仍然完全功能

💡 使用示例

多传输配置

<param>
    <name>mcp.servers</name>
    <value>
        python_tools:stdio://python /opt/mcp/python_server.py,
        web_services:http://api.internal.com:8080,
        live_data:sse://streaming.service.com:4000,
        legacy_system:custom-http-sse://legacy.gateway.com:9000
    </value>
</param>

API 使用

# 发现可用工具
curl -X GET https://knox.company.com/gateway/prod/mcp/v1/tools

# 调用基于 Python 的计算器工具
curl -X POST https://knox.company.com/gateway/prod/mcp/v1/tools/python_tools.calculate \
  -H "Content-Type: application/json" \
  -d '{"expression": "2 + 2 * 3"}'

# 访问 Web 服务 API
curl -X POST https://knox.company.com/gateway/prod/mcp/v1/tools/web_services.weather \
  -H "Content-Type: application/json" \
  -d '{"location": "San Francisco", "units": "metric"}'

# 读取实时数据
curl -X GET https://knox.company.com/gateway/prod/mcp/v1/resources/live_data.stock_prices

🛠️ 开发

先决条件

Java 8+（兼容 Knox 1.6.1）
Maven 3.6+
Apache Knox 1.6.1+

构建与测试

# 清洁构建
mvn clean compile

# 运行综合测试套件
mvn test

# 打包部署
mvn package

安装

构建 JAR 文件：mvn package
部署到 Knox：将 target/knox-mcp-proxy-1.0.0-SNAPSHOT.jar 复制到 Knox 的 ext/ 目录
配置拓扑：添加 MCP 服务配置
重启 Knox：重启 Knox 网关服务

项目结构

src/main/java/org/apache/knox/mcp/
├── McpProxyResource.java              # 主 REST API 资源
├── McpServerConnection.java           # 连接管理
├── client/                            # 传输实现
│   ├── McpJsonRpcClient.java         #   - stdio 传输
│   ├── McpHttpClient.java            #   - 标准 HTTP 传输
│   ├── McpSseClient.java             #   - 标准 SSE 传输
│   ├── McpCustomHttpSseClient.java   #   - Knox 自定义传输
│   ├── McpTool.java                  #   - 工具模型
│   ├── McpResource.java              #   - 资源模型
│   └── McpException.java             #   - 异常处理
└── deploy/
    └── McpProxyServiceDeploymentContributor.java  # Knox 集成

🎯 实现亮点

🔧 全面传输支持

4 种传输协议，完全符合 MCP 标准
自动协议检测，基于终端节点 URL
无缝回退和每种传输类型的错误处理

🚀 生产特性

Java 8 兼容性 - 不需要像官方 SDK 那样的 Java 17+
异步处理，使用 CompletableFuture
连接池和生命周期管理
全面错误处理和优雅降级
实时监控，通过健康检查终端节点

🛡️ 企业级安全

Knox 认证集成
基于角色的授权，针对工具和资源
审计日志，针对所有 MCP 操作
SSL/TLS 终止，通过 Knox

⚡ 性能优化

连接复用和适当的持久连接
请求批处理和响应缓存
资源清理和内存管理
可配置超时和重试逻辑

📊 与官方 MCP SDK 对比

功能	官方 MCP SDK	Knox MCP 代理
Java 版本	Java 17+	Java 8+
传输	stdio, HTTP, SSE	stdio, HTTP, SSE, 自定义 HTTP+SSE
多服务器	手动	自动聚合
安全性	无	Knox 企业级安全
网关功能	无	负载均衡, SSL, 认证
生产就绪	基础	企业级
Knox 集成	无	原生

🔮 高级功能

自定义传输协议

我们的 Knox 优化的 custom-http-sse:// 传输提供了：

HTTP POST 请求（无状态，可扩展）
服务器发送事件 响应（实时，持久）
消息关联，通过请求 ID
多客户端优化，适用于网关场景

工具及资源命名空间

{
  "calculator.add": {
    "description": "加两个数",
    "server": "calculator"
  },
  "webapi.weather": {
    "description": "获取天气数据",
    "server": "webapi"
  }
}

健康监控

{
  "status": "健康",
  "servers": {
    "calculator": {"status": "连接", "tools": 5, "resources": 2},
    "webapi": {"status": "连接", "tools": 12, "resources": 8}
  },
  "total_tools": 17,
  "total_resources": 10
}

🤝 贡献

分叉仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m '添加神奇功能')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

📄 许可证

此项目根据 Apache 许可证 2.0 授权 - 详情见 LICENSE 文件。

🔗 相关项目

Apache Knox - 适用于 Hadoop 集群的企业网关
模型上下文协议 - AI 工具集成的标准协议
MCP Java SDK - 官方 Java 实现