@mcp-abap-adt/连接
MCP ABAP ADT服务器的ABAP连接层。提供了一个统一的接口，用于通过ADT（ABAP开发工具）协议连接到SAP ABAP系统，支持内部（基本身份验证）和云（JWT/OAuth2）身份验证方法。
主要特点
- 🔐 多种身份验证方法:
- 本地SAP系统的基本身份验证 - 用于SAP BTP ABAP环境的JWT/OAuth2 - 用于预认证企业流的SAML会话Cookie
- 🔄 许可证管理:
- 令牌刷新由处理 @mcp-abap-adt/auth-broker 包裹 - 连接包仅关注HTTP通信
- 💾 会话管理:
- 会话头管理（Cookie、CSRF令牌） - 会话状态持久性由处理 @mcp-abap-adt/auth-broker 包裹
- 🏗️ 清洁建筑:
- 通用HTTP/会话逻辑的抽象基类 - 特定于身份验证类型的实现（BaseAbapConnection、JwtAbapConnections、SamlAbapConnection） - 适当的关注点分离——基类中没有JWT逻辑
- 🔌 实时运输脚手架:
- 通用的 GenericWebSocketTransport 使用可插拔的WS工厂 - 可用于调试器/跟踪和其他事件驱动流
- 📝 自定义日志记录：可插拔的记录仪接口，可与任何记录仪系统集成
- 🛠️ CLI工具：参见 JWT身份验证工具 用于获取SAP BTP令牌
- 📦 TypeScript：完全支持TypeScript，包括类型定义
- ⚡ 超时管理：不同操作类型的可配置超时
建筑
该包使用了清晰的关注点分离：
AbstractAbapConnection（摘要，仅限内部）：
- 通用HTTP请求逻辑 - 会话管理（Cookie、CSRF令牌） - 重新尝试CSRF令牌获取 - 身份不可知-对Basic或JWT一无所知
BaseAbapConnection（混凝土，出口）：
- 基本身份验证实现 - 简单连接（）-获取CSRF令牌 - 适用于本地SAP系统
JwtAbapConnection（混凝土，出口）：
- JWT/OAuth2身份验证实现 - Simple connect（）-使用JWT令牌建立连接 - 适用于SAP BTP ABAP环境 - 由身份验证代理包处理的令牌刷新
SamlAbapConnection（混凝土，出口）：
- 基于会话cookie的身份验证(authType: "saml") - 使用现有的SSO/SAML会话Cookie - 获取CSRF令牌并在相同的HTTP模型中执行ADT请求
GenericWebSocketTransport（混凝土，出口）：
- 实时WS消息流的传输抽象 - 可插拔的工厂，基于信封的发送/接收 - 用于更高级别的调试器/跟踪会话编排
责任和设计原则
核心开发原则
仅接口通信该方案遵循一个基本的发展原则： 所有与外部依赖关系的交互都只能通过接口进行代码知道 没有超出接口中定义的内容.
这意味着：
- 不知道其他包中的具体实现类
- 不了解接口中未定义的内部数据结构或方法
- 不假设接口契约之外的实现行为
- 不访问接口中未明确定义的属性或方法
这一原则确保：
- 松散结合：连接类与其他包中的具体实现解耦
- 灵活性：可以添加新的实现，而无需修改连接类
- 可测试性：易于模拟测试依赖关系
- 可维护性：对实现的更改不会影响连接类
包装责任
该包负责：
- 与SAP系统的HTTP通信：通过ADT协议向SAP ABAP系统发出HTTP请求
- 身份验证处理：支持基本身份验证和JWT/OAuth2身份验证方法
- 会话管理：管理Cookie、CSRF令牌和会话状态
- 错误处理：处理HTTP错误和连接问题
这个包有什么作用
- 提供连接抽象:
AbapConnection与SAP系统交互的界面 - 处理HTTP请求：使用适当的标头和身份验证向SAP ADT端点发出请求
- 管理会话：处理Cookie、CSRF令牌和会话状态持久性
此软件包不做什么
- 未获得令牌：代币获取由以下人员处理
@mcp-abap-adt/auth-providers和@mcp-abap-adt/auth-broker - 不存储令牌：令牌存储由以下人员处理
@mcp-abap-adt/auth-stores - 不刷新令牌：令牌刷新由处理
@mcp-abap-adt/auth-broker - 不编排身份验证：令牌生命周期管理由以下人员处理
@mcp-abap-adt/auth-broker - 不知道目的地：基于目标的身份验证由消费者处理
- 不处理OAuth2流：OAuth2流由令牌提供者处理
外部依赖项
此包与外部包交互 仅通过接口:
- 记录器界面：用途
ILogger日志记录接口-不了解具体的日志记录器实现 - 不直接依赖于auth包：所有与令牌相关的操作都是通过配置处理的(
SapConfig)通过消费者
文档
特性
- 🔐 多种身份验证方法：本地系统的基本身份验证，SAP BTP ABAP环境的JWT/OAuth2
- 💾 会话管理：HTTP通信的会话头管理（Cookie、CSRF令牌）
- 📝 自定义日志记录：可插拔记录器接口，可与任何日志系统集成（可选）
- 📦 TypeScript：完全支持TypeScript，包括类型定义
- ⚡ 超时管理：不同操作类型的可配置超时
- 🌐 网络错误检测：自动检测和正确处理网络级错误（连接被拒绝、超时、DNS故障）
安装
npm install @mcp-abap-adt/connection有关详细的安装说明，请参阅 安装指南.
快速开始
基本用途（内部）
import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
const config: SapConfig = {
url: "https://your-sap-system.com",
client: "100",
authType: "basic",
username: "your-username",
password: "your-password",
};
// Create a simple logger
const logger = {
info: (msg: string, meta?: any) => console.log(msg, meta),
error: (msg: string, meta?: any) => console.error(msg, meta),
warn: (msg: string, meta?: any) => console.warn(msg, meta),
debug: (msg: string, meta?: any) => console.debug(msg, meta),
};
// Create connection
const connection = createAbapConnection(config, logger);
// Make ADT request
const response = await connection.makeAdtRequest({
method: "GET",
url: "/sap/bc/adt/programs/programs/your-program",
});云使用情况（JWT/OAuth2）
import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
// JWT configuration
const config: SapConfig = {
url: "https://your-instance.abap.cloud.sap",
client: "100", // Optional
authType: "jwt",
jwtToken: "your-jwt-token-here", // Obtained via OAuth2 flow
};
const logger = {
info: (msg: string, meta?: any) => console.log(msg, meta),
error: (msg: string, meta?: any) => console.error(msg, meta),
warn: (msg: string, meta?: any) => console.warn(msg, meta),
debug: (msg: string, meta?: any) => console.debug(msg, meta),
};
// Logger is optional - if not provided, no logging output
const connection = createAbapConnection(config, logger);
// Note: Token refresh is handled by @mcp-abap-adt/auth-broker package
const response = await connection.makeAdtRequest({
method: "GET",
url: "/sap/bc/adt/programs/programs/your-program",
});SSO使用（SAML会话Cookie）
import { createAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
const config: SapConfig = {
url: "https://your-sap-system.com",
authType: "saml",
sessionCookies: "MYSAPSSO2=...; SAP_SESSIONID=...",
};
const connection = createAbapConnection(config, logger);
const response = await connection.makeAdtRequest({
method: "GET",
url: "/sap/bc/adt/programs/programs/your-program",
});自动令牌刷新的云使用情况
对于401/403错误的自动令牌刷新，请注入 ITokenRefresher:
import { JwtAbapConnection, SapConfig } from "@mcp-abap-adt/connection";
import type { ITokenRefresher } from "@mcp-abap-adt/interfaces";
// Token refresher provides token acquisition and refresh
// (created by @mcp-abap-adt/auth-broker or custom implementation)
const tokenRefresher: ITokenRefresher = {
getToken: async () => { /* return current token */ },
refreshToken: async () => { /* refresh and return new token */ },
};
// JWT configuration
const config: SapConfig = {
url: "https://your-instance.abap.cloud.sap",
authType: "jwt",
jwtToken: await tokenRefresher.getToken(), // Get initial token
};
// Create connection with token refresher - 401/403 handled automatically
const connection = new JwtAbapConnection(config, logger, undefined, tokenRefresher);
// Requests automatically retry with refreshed token on auth errors
const response = await connection.makeAdtRequest({
method: "GET",
url: "/sap/bc/adt/programs/programs/your-program",
});有意义的会议
对于需要会话状态的操作（例如，对象修改），您可以启用有状态会话：
import { createAbapConnection } from "@mcp-abap-adt/connection";
const connection = createAbapConnection(config, logger);
// Enable stateful session mode (adds x-sap-adt-sessiontype: stateful header)
connection.setSessionType("stateful");
// Make requests - SAP will maintain session state
await connection.makeAdtRequest({
method: "POST",
url: "/sap/bc/adt/objects/domains",
data: { /* domain data */ },
});
// Note: Session state persistence is handled by @mcp-abap-adt/auth-broker package自定义记录器
import { ILogger } from "@mcp-abap-adt/connection";
class MyLogger implements ILogger {
info(message: string, meta?: any): void {
// Your logging implementation
}
error(message: string, meta?: any): void {
// Your logging implementation
}
warn(message: string, meta?: any): void {
// Your logging implementation
}
debug(message: string, meta?: any): void {
// Your logging implementation
}
csrfToken(action: "fetch" | "retry" | "success" | "error", message: string, meta?: any): void {
// CSRF token specific logging
}
tlsConfig(rejectUnauthorized: boolean): void {
// TLS configuration logging
}
}
const logger = new MyLogger();
const connection = createAbapConnection(config, logger);CLI工具
该软件包包括一个CLI工具，用于使用服务密钥与SAP BTP进行身份验证：
安装选项
- 本地项目安装
npm install @mcp-abap-adt/connection --save-dev
npx sap-abap-auth auth -k path/to/service-key.json- 全局安装
npm install -g @mcp-abap-adt/connection
sap-abap-auth auth -k path/to/service-key.json- 按需（npx）
npx @mcp-abap-adt/connection sap-abap-auth auth -k path/to/service-key.json用法
# Show help
sap-abap-auth --help
# Authenticate with service key
sap-abap-auth auth -k service-key.json
# Specify browser
sap-abap-auth auth -k service-key.json --browser chrome
# Custom output file
sap-abap-auth auth -k service-key.json --output .env.production选项
- `-k, --key
` -服务密钥JSON文件的路径（必需）
-b, --browser-要打开的浏览器（chrome、edge、firefox、system、none）- `-o, --output
` -输出.env文件的路径（默认值：.env）
-h, --help-显示帮助消息
使用via npx （无全局安装）
如果 @mcp-abap-adt/connection 如果项目中列出了依赖项，则可以直接调用CLI：
npx sap-abap-auth auth -k service-key.json即使您没有全局安装该软件包，这也能正常工作。对于一次性使用，您还可以运行：
npx @mcp-abap-adt/connection sap-abap-auth auth -k service-key.json这将按需下载包并执行CLI。
API 参考
类型
SapConfig
SAP ABAP连接的配置。
type SapConfig = {
url: string;
client?: string;
authType: "basic" | "jwt" | "saml";
// For basic auth
username?: string;
password?: string;
// For JWT auth
jwtToken?: string;
// For SAML session cookies
sessionCookies?: string;
};AbapConnection
ABAP连接的主界面。
interface AbapConnection {
makeAdtRequest(options: AbapRequestOptions): Promise;
reset(): void;
setSessionType(type: "stateless" | "stateful"): void; // Switch session type
getSessionMode(): "stateless" | "stateful"; // Get current session mode
getSessionId(): string | null; // Get current session ID
}会话管理：
setSessionType(type)：以编程方式在有状态和无状态模式之间切换getSessionMode()：返回当前会话模式getSessionId()：返回当前会话ID（自动生成的UUID）
ILogger
用于自定义日志记录实现的记录器接口。
interface ILogger {
info(message: string, meta?: any): void;
error(message: string, meta?: any): void;
warn(message: string, meta?: any): void;
debug(message: string, meta?: any): void;
csrfToken?(action: "fetch" | "retry" | "success" | "error", message: string, meta?: any): void;
tlsConfig?(rejectUnauthorized: boolean): void;
}函数
createAbapConnection(config, logger?, sessionId?)
创建ABAP连接实例的工厂函数。
function createAbapConnection(
config: SapConfig,
logger?: ILogger | null,
sessionId?: string
): AbapConnection;CSRF_CONFIG 和 CSRF_ERROR_MESSAGES
0.1.13+中的新功能： 导出常量，用于跨不同连接实现进行一致的CSRF令牌处理。
import { CSRF_CONFIG, CSRF_ERROR_MESSAGES } from '@mcp-abap-adt/connection';
// CSRF_CONFIG contains:
// - RETRY_COUNT: number (default: 3)
// - RETRY_DELAY: number (default: 1000ms)
// - ENDPOINT: string (default: '/sap/bc/adt/core/discovery')
// - REQUIRED_HEADERS: { 'x-csrf-token': 'fetch', 'Accept': 'application/atomsvc+xml' }
// CSRF_ERROR_MESSAGES contains:
// - FETCH_FAILED(attempts: number, cause: string): string
// - NOT_IN_HEADERS: string
// - REQUIRED_FOR_MUTATION: string使用案例： 在实现自定义连接类（例如基于Cloud SDK）时，您可以使用这些常量来确保一致的CSRF令牌处理：
import { CSRF_CONFIG, CSRF_ERROR_MESSAGES } from '@mcp-abap-adt/connection';
async function fetchCsrfToken(baseUrl: string): Promise {
const csrfUrl = `${baseUrl}${CSRF_CONFIG.ENDPOINT}`;
for (let attempt = 0; attempt setTimeout(resolve, CSRF_CONFIG.RETRY_DELAY));
continue;
}
throw new Error(CSRF_ERROR_MESSAGES.NOT_IN_HEADERS);
}
return token;
} catch (error) {
if (attempt >= CSRF_CONFIG.RETRY_COUNT) {
throw new Error(
CSRF_ERROR_MESSAGES.FETCH_FAILED(
CSRF_CONFIG.RETRY_COUNT + 1,
error instanceof Error ? error.message : String(error)
)
);
}
await new Promise(resolve => setTimeout(resolve, CSRF_CONFIG.RETRY_DELAY));
}
}
}看 PR提案 了解更多详情。
需求
- Node.js>=18.0.0
- 访问SAP ABAP系统（内部部署或BTP）
更新日志
看 更改日志.md 查看详细的版本历史和突破性更改。
最新版本：0.2.0
- 已删除令牌刷新功能（由处理
@mcp-abap-adt/auth-broker) - 已删除会话存储功能（由处理
@mcp-abap-adt/auth-broker) - 记录器现在是可选的
- 看 更改日志.md 有关完整详细信息
文档
许可证
麻省理工学院
仓库
https://github.com/fr0ster/mcp-abap-adt
相关项目
- mcp-abap-adt -ABAP ADT的主MCP服务器