Knox MCP Proxy

诺克斯MCP代理

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

🌟 概述

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

✨ 主要特点

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

🏗️ 建筑

AI Agents & Applications
    |
    v
Knox Gateway (Security, Auth, SSL)
    |
    v
Jersey REST API (/mcp/v1/*)
    |
    v
MCP Proxy Resource (Aggregation)
    |
    ├── stdio://python calculator_server.py    (Process)
    ├── http://webapi.example.com              (HTTP)
    ├── sse://realtime.service.com             (SSE)
    └── custom-http-sse://gateway.internal     (Custom)

🚀 运输支持矩阵

⚙️ 配置

Knox拓扑设置

    MCPPROXY
    mcp
    1.0.0
    

        mcp.servers
        calculator:stdio://python /path/to/calculator_server.py,
               webapi:http://localhost:3000,
               realtime:sse://localhost:4000,
               gateway:custom-http-sse://localhost:5000
    

支持的端点格式

• stdio://command args -基于子进程的MCP服务器（Python、Node.js等）
• http://host:port -标准HTTP请求/响应MCP服务器
• https://host:port -安全HTTP MCP服务器
• sse://host:port -标准SSE双向MCP服务器
• sses://host:port -安全的SSE MCP服务器
• custom-http-sse://host:port -诺克斯优化混合动力运输
• custom-https-sse://host:port -安全的诺克斯混合运输

🔒 安全配置

标准命令允许列表

为了防止远程代码执行，基于stdio的MCP服务器仅限于允许的命令列表：

    mcp.stdio.allowed.commands
    python,node,java,npm

安全功能：

• ✅ 命令验证：只能执行分配的命令
• ✅ 路径保护：命令仅通过基名称进行验证（例如。， /usr/bin/python → python)
• ✅ 默认安全性：如果未配置分配列表，则会记录警告
• ✅ 清除错误消息：被阻止的命令会收到描述性错误响应

安全配置示例：

    MCPPROXY
    mcp
    1.0.0
    

        mcp.servers
        calculator:stdio://python /opt/mcp/calculator.py
    

    

        mcp.stdio.allowed.commands
        python,node
    

📚 api参考

� MCP流式HTTP端点（符合规范）

Knox MCP Proxy现在支持具有统一端点的官方MCP Streamable HTTP规范：

# MCP-compliant unified endpoints
GET /gateway/sandbox/mcp/v1/      # Service info or SSE connection  
POST /gateway/sandbox/mcp/v1/     # JSON-RPC requests

# Content negotiation examples:

# 1. Establish SSE connection (streamable mode)
GET /gateway/sandbox/mcp/v1/
Accept: text/event-stream
# Returns: SSE stream with session management

# 2. Standard JSON-RPC request/response
POST /gateway/sandbox/mcp/v1/
Content-Type: application/json
Accept: application/json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

# 3. JSON-RPC with streaming response (requires active SSE session)
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: -用于将消息路由到SSE会话

�🔍 发现端点

# List all available tools across all servers
GET /gateway/sandbox/mcp/v1/tools

# List all available resources across all servers  
GET /gateway/sandbox/mcp/v1/resources

# Health check for all connected servers
GET /gateway/sandbox/mcp/v1/health

⚡ 执行端点

# Execute a tool with parameters
POST /gateway/sandbox/mcp/v1/tools/{serverName.toolName}
Content-Type: application/json

{
  "param1": "value1",
  "param2": "value2"
}

# Access a resource
GET /gateway/sandbox/mcp/v1/resources/{serverName.resourceName}

🔄 传统端点（向后兼容性）

⚠️ 失望但完全支持现有客户：

# Legacy SSE endpoint
GET /gateway/sandbox/mcp/v1/sse
# Still works exactly as before - delegates to unified endpoint

# Legacy JSON-RPC endpoint  
POST /gateway/sandbox/mcp/v1/message
# Still works exactly as before - includes MCP version headers

# All existing REST endpoints remain unchanged
GET /gateway/sandbox/mcp/v1/tools
GET /gateway/sandbox/mcp/v1/resources
POST /gateway/sandbox/mcp/v1/tools/{toolName}
GET /gateway/sandbox/mcp/v1/resources/{resourceName}
GET /gateway/sandbox/mcp/v1/health

迁移指南：

• 现有客户端（Goose Desktop Agent等）继续工作不变
• 新的实现应该使用统一的 GET/POST / 端点
• 传统端点会记录弃用警告，但仍能完全正常工作

💡 使用示例

多传输配置

    mcp.servers
    
        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
    

API使用

# Discover available tools
curl -X GET https://knox.company.com/gateway/prod/mcp/v1/tools

# Call a Python-based calculator tool
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"}'

# Access a web service 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"}'

# Read real-time data
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+
• 阿帕奇诺克斯1.6.1+

构建与测试

# Clean build
mvn clean compile

# Run comprehensive test suite  
mvn test

# Package for deployment
mvn package

安装

1. 构建JAR: mvn package
2. 部署到诺克斯：复制 target/knox-mcp-proxy-1.0.0-SNAPSHOT.jar 去诺克斯家 ext/ 目录
3. 配置拓扑：添加MCP服务配置
4. 重新启动Knox：重新启动Knox网关服务

项目结构

src/main/java/org/apache/knox/mcp/
├── McpProxyResource.java              # Main REST API resource
├── McpServerConnection.java           # Connection management
├── client/                            # Transport implementations
│   ├── McpJsonRpcClient.java         #   - stdio transport
│   ├── McpHttpClient.java            #   - standard HTTP transport  
│   ├── McpSseClient.java             #   - standard SSE transport
│   ├── McpCustomHttpSseClient.java   #   - Knox custom transport
│   ├── McpTool.java                  #   - Tool model
│   ├── McpResource.java              #   - Resource model
│   └── McpException.java             #   - Exception handling
└── deploy/
    └── McpProxyServiceDeploymentContributor.java  # Knox integration

🎯 实施要点

🔧 完整的运输支持

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

🚀 生产特点

• Java 8兼容性 -没有像官方SDK那样的Java 17+要求
• 异步处理 与复杂的未来
• 连接池 生命周期管理
• 全面的错误处理 优雅的退化
• 实时监控 通过健康检查端点

🛡️ 企业安全

• Knox身份验证 整合
• 基于角色的授权 工具和资源
• 审核日志记录 适用于所有MCP操作
• SSL/TLS终止 通过诺克斯

⚡ 性能优化

• 连接复用 以及在适当的情况下建立持久连接
• 请求批处理 以及响应缓存
• 资源清理 以及内存管理
• 可配置超时 重试逻辑

📊 与官方MCP SDK的比较

🔮 高级功能

自定义传输协议

我们的诺克斯优化 custom-http-sse:// 运输提供：

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

工具和资源命名空间

{
  "calculator.add": {
    "description": "Add two numbers",
    "server": "calculator"
  },
  "webapi.weather": {
    "description": "Get weather data", 
    "server": "webapi"
  }
}

健康监测

{
  "status": "healthy",
  "servers": {
    "calculator": {"status": "connected", "tools": 5, "resources": 2},
    "webapi": {"status": "connected", "tools": 12, "resources": 8}
  },
  "total_tools": 17,
  "total_resources": 10
}

🤝 贡献

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 分支机构(git push origin feature/amazing-feature)
5. 打开 拉取请求

📄 许可证

该项目根据 Apache许可证2.0 -看看 许可证 文件以获取详细信息。

🔗 相关项目

• 阿帕奇诺克斯 -Hadoop集群的企业网关
• 模型上下文协议 -AI工具集成的标准协议
• MCP Java SDK -官方Java实现

______________________________________________________________________

🎉 准备好通过Knox聚合您的MCP生态系统了吗？ 从 配置 上面的部分！