MCP Abap Adt Proxy

@mcp-abap-adt/proxy


SAP ABAP ADT的MCP代理服务器-使用JWT身份验证将本地请求代理到MCP服务器。

概述

此包充当本地MCP客户端（如Cline）和任何MCP服务器之间的简单代理。它拦截MCP请求，添加JWT身份验证令牌，并将其转发到目标MCP服务器。MCP服务器URL是从BTP目的地的服务密钥中获得的。

目的

使本地MCP客户端能够通过自动JWT令牌管理连接到远程MCP服务器 @mcp-abap-adt/auth-broker代理添加身份验证标头并透明地转发请求。

特性

• ✅ JWT代币管理 -通过身份验证代理自动检索、缓存和刷新令牌
• ✅ 基于服务密钥 -从BTP目的地的服务密钥中获取MCP服务器URL
• ✅ 错误处理 -重试逻辑、断路器和全面的错误处理
• ✅ 多种运输方式 -HTTP、SSE和stdio支持
• ✅ 配置灵活性 -环境变量、配置文件或默认值

快速开始

安装

npm install -g @mcp-abap-adt/proxy

基本用法

# Start proxy server (in-memory session storage, secure)
mcp-abap-adt-proxy

# With BTP destination
mcp-abap-adt-proxy --btp=ai

# Enable file-based session storage (persists tokens to disk)
mcp-abap-adt-proxy --btp=ai --unsafe

配置

代理支持多种配置方法：

• 命令行参数 （最高优先级）
• YAML/JSON配置文件 -请参阅 YAML配置指南
• 环境变量
• 默认值 （最低优先级）

快速示例（YAML配置）:

# Copy example config from documentation
cp docs/mcp-proxy-config.example.yaml mcp-proxy-config.yaml

# Edit mcp-proxy-config.yaml with your settings

# Run with config file
mcp-abap-adt-proxy --config=mcp-proxy-config.yaml
# Or short form:
mcp-abap-adt-proxy -c mcp-proxy-config.yaml

客户端配置

有关Cline和GitHub Copilot的详细设置说明，请参阅 客户端设置指南.

快速示例（临床）:

{
  "mcpServers": {
    "mcp-abap-adt-proxy": {
      "disabled": false,
      "timeout": 60,
      "type": "streamableHttp",
      "url": "http://localhost:3001/mcp/stream/http",
      "headers": {
        "x-sap-destination": "btp-cloud"
      }
    }
  }
}

所需标题：

• x-sap-destination -BTP Cloud授权令牌和MCP服务器URL的目标名称

命令行覆盖：

• --btp= -覆盖范围 x-sap-destination 标题（优先）
• --url= -覆盖MCP服务器URL（如果服务密钥缺少URL，则需要）
• `--browser=

-要使用的浏览器： system （默认）， chrome, edge, firefox, headless`

• `--browser-auth-port=

` -OAuth2回调端口（默认值：3333）

• --unsafe -启用基于文件的会话存储（将令牌持久化到磁盘）。默认情况下，会话存储在内存中（安全，重启时丢失）

默认标头：

像Cline和Claude Code这样的MCP客户端不能设置任意请求头。使用默认标头注入SAP特定标头（例如。 x-sap-destination, x-sap-client)这是目标MCP服务器所需要的。

客户端提供的标头始终优先于默认值。

通过YAML配置(defaultHeaders 地图）：

btpDestination: mcp
targetUrl: https://example.com
defaultHeaders:
  x-sap-destination: S4HANA_E19
  x-sap-client: "100"

通过CLI(--header，可重复）：

mcp-abap-adt-proxy --btp=mcp --url=https://example.com \
  --header x-sap-destination=S4HANA_E19 \
  --header x-sap-client=100

工作原理：

代理使用BTP/XSUAA身份验证：

1. BTP身份验证 （如果 --btp 或 x-sap-destination 存在）：

- 用途 AuthorizationCodeProvider （基于浏览器的OAuth2流） - 渴望身份验证：启动时立即打开浏览器以获取令牌 - 注入/覆盖 Authorization: Bearer 头球 - MCP服务器URL从BTP目标服务密钥获得或通过以下方式注入 --url - 服务密钥格式：包含 uaa （URL、客户、客户端机密）

BTP身份验证模式 （与 --btp):

1. 代理启动→ 打开浏览器登录（渴望授权）→ 获取/刷新JWT令牌
2. x-sap-destination （或 --btp) → Adds Authorization: Bearer 头球
3. 从服务密钥获取MCP服务器URL或 --url 参数

文档

• 客户端设置指南 -Cline和GitHub Copilot的分步设置
• 配置指南 -完整的配置参考
• YAML配置指南 -使用YAML/JSON配置文件
• 使用示例 -实际使用示例和模式
• API 文档 -API参考和接口
• 建筑 -系统架构与设计
• 故障排除 -常见问题和解决方案
• 路由逻辑规范 -详细的路由逻辑和场景
• 实现分析 -当前实施分析
• 路线图 -发展路线图和进展

运作原理

代理对每个请求执行以下步骤：

1. 提取标头：阅读 x-sap-destination 头球
2. 应用命令行替换: --btp 参数覆盖标头（如果提供）
3. 验证路由要求：需要 x-sap-destination/--btp
4. BTP身份验证 （如果 x-sap-destination 或 --btp 提供）：

- 用途 AuthorizationCodeProvider （基于浏览器的登录） - 热切地 启动时获取令牌（如果通过配置 --btp) - 使用缓存的刷新令牌检索JWT令牌或打开浏览器 - 注入/覆盖 Authorization: Bearer 头球

1. 获取MCP服务器URL:

- 从服务密钥 x-sap-destination

1. 转发请求：向MCP服务器URL发送包含所有注入标头的请求
2. 返回响应：将响应转发回客户端

请求流示例

Cline → Proxy (adds BTP token) → Target MCP Server → Proxy → Cline

代理是透明的，它只添加身份验证标头并转发请求。

配置

配置

环境变量

export MCP_HTTP_PORT=3001
export LOG_LEVEL=info
export MCP_PROXY_UNSAFE=true  # Enable file-based session storage (optional)
export AUTH_BROKER_PATH=~/.config/mcp-abap-adt  # Optional base path for service-keys/sessions

AUTH_BROKER_PATH 被视为基本目录。代理解析：

• service-keys 从 /service-keys
• sessions 从 /sessions

默认值为 AUTH_BROKER_PATH 未设置：

• Unix/Linux/macOS： ~/.config/mcp-abap-adt/service-keys 和 ~/.config/mcp-abap-adt/sessions
• 窗户： %USERPROFILE%\\Documents\\mcp-abap-adt\\service-keys 和 %USERPROFILE%\\Documents\\mcp-abap-adt\\sessions

配置文件

创建 mcp-proxy-config.json:

{
  "httpPort": 3001,
  "logLevel": "info",
  "maxRetries": 3,
  "circuitBreakerThreshold": 5,
  "unsafe": false
}

会话存储：

• unsafe: false （默认）-会话数据存储在内存中（安全，重启时丢失）
• unsafe: true -会话数据持久化到磁盘（令牌保存在会话存储路径下）

看 配置指南 完整的选项。

错误处理和弹性

• 重试逻辑 -失败请求的指数回退
• 断路器 -防止级联故障
• 令牌刷新 -到期时自动刷新令牌
• 连接池 -高效的资源管理
• 请求超时 -可配置的超时处理

需求

• Node.js>=18.0.0
• npm>=9.0.0

测试工具

启动两台服务器进行测试

使用附带的脚本启动两者 mcp-abap-adt 和 mcp-abap-adt-proxy 同时：

# Using npm script
npm run test:servers

# Direct execution
node tools/start-servers.js

# With SSE transport
node tools/start-servers.js --transport=sse

脚本会自动执行以下操作：

• 在端口3000（HTTP）或3001（SSE）上启动ADT服务器
• 在端口3001（HTTP）或3002（SSE）上启动代理服务器
• 生成 mcpUrl 基于ADT服务器配置
• 确保两台服务器使用相同的传输协议

看 工具/README.md 以获取完整的文档。

开发状态

✅ 核心功能已完成

• ✅ 项目设置和基础
• ✅ 请求拦截与分析
• ✅ JWT令牌管理和代理转发
• ✅ 配置和环境
• ✅ 错误处理和弹性
• ✅ 测试工具(tools/start-servers.js)
• ✅ 文档

🚧 未来工作

• ⏳ 单元测试
• ⏳ 性能与优化
• ⏳ 部署和发布

看 ROADMAP.md 了解详情。

许可证

麻省理工学院

链接

• 仓库: https://github.com/fr0ster/mcp-abap-adt-proxy
• 问题: https://github.com/fr0ster/mcp-abap-adt-proxy/issues
• 相关套餐:

- @mcp-abap-adt/auth代理 - @mcp-abap-adt/头部验证器