MCP Abap Adt Interfaces

@mcp-abap-adt/接口


MCP ABAP ADT包的共享接口。

此包提供了MCP ABAP ADT生态系统中使用的所有TypeScript接口，确保了所有包的一致性和类型安全性。

安装

npm install @mcp-abap-adt/interfaces

概述

此包包含按域组织的所有接口：

• adt/ -ADT对象操作接口（IAdtObject、操作选项、错误代码）
• auth/ -核心身份验证接口（配置、身份验证类型）
• token/ -令牌相关接口（令牌提供者、结果、选项）
• session/ -会话存储接口
• serviceKey/ -服务密钥存储接口
• connection/ -连接和实时传输接口（AbapConnection、请求选项、WebSocket传输契约）
• execution/ -可运行实体的执行合同(IExecutor)
• feeds/ -提要访问接口（IFeedRepository、提要条目、系统消息、网关错误）
• runtime/ -运行时分析域接口（调试器、分析器、跟踪、转储、日志、内存快照等）
• sap/ -SAP特定配置（SapConfig、SapAuthType）
• service/ -业务服务生命周期合同(IAdtService，服务绑定参数）
• storage/ -存储接口（会话存储、状态）
• logging/ -日志接口（ILogger、LogLevel枚举）
• validation/ -验证接口
• utils/ -公用设施类型和接口

接口命名约定

所有接口均以开头 I 前缀 （例如。， IAbapConnection, ISapConfig, ITokenProvider).

这确保了所有包之间的一致性，并遵循接口的TypeScript命名约定。

用法

基本进口

import {
  IAuthorizationConfig,
  IConnectionConfig,
  ISessionStore,
  IServiceKeyStore,
  ITokenProvider,
  IAbapConnection,
  IExecutor,
  IWebSocketTransport,
  IWebSocketMessageEnvelope,
  ISapConfig,
  ILogger,
  TOKEN_PROVIDER_ERROR_CODES,
  STORE_ERROR_CODES
} from '@mcp-abap-adt/interfaces';

ADT对象操作

import {
  IAdtObject,
  IAdtOperationOptions,
  AdtObjectErrorCodes,
  LogLevel
} from '@mcp-abap-adt/interfaces';

// Example: Read with long polling
const domain = await adtDomain.read(
  { domainName: 'Z_TEST' },
  'active',
  { withLongPolling: true } // Wait until object is available
);

// Example: Read metadata with long polling and version selection
const metadata = await adtDomain.readMetadata(
  { domainName: 'Z_TEST' },
  { withLongPolling: true, version: 'active' }
);

错误处理

import {
  TOKEN_PROVIDER_ERROR_CODES,
  STORE_ERROR_CODES
} from '@mcp-abap-adt/interfaces';

// Token Provider Error Codes
try {
  await tokenProvider.getTokens(authConfig);
} catch (error: any) {
  if (error.code === TOKEN_PROVIDER_ERROR_CODES.VALIDATION_ERROR) {
    console.error('Invalid auth config:', error.missingFields);
  } else if (error.code === TOKEN_PROVIDER_ERROR_CODES.REFRESH_ERROR) {
    console.error('Token refresh failed:', error.cause);
  }
}

// Store Error Codes
try {
  const authConfig = await serviceKeyStore.getAuthorizationConfig('TRIAL');
} catch (error: any) {
  if (error.code === STORE_ERROR_CODES.FILE_NOT_FOUND) {
    console.error('Service key not found:', error.filePath);
  } else if (error.code === STORE_ERROR_CODES.PARSE_ERROR) {
    console.error('Invalid JSON:', error.filePath, error.cause);
  } else if (error.code === STORE_ERROR_CODES.INVALID_CONFIG) {
    console.error('Missing fields:', error.missingFields);
  }
}

责任和设计原则

核心开发原则

仅接口通信：此包定义 仅限接口它不包含任何实现，不依赖于其他包（仅类型导入除外），并且是所有接口定义的唯一真实来源。

包装责任

该包负责：

1. 定义接口：提供跨MCP ABAP ADT包使用的所有TypeScript接口
2. 类型安全性：确保所有包中的类型定义一致
3. 版本管理：所有接口的单一版本
4. 文档：所有接口的集中文档

这个包有什么作用

• 定义接口：MCP ABAP ADT包中使用的所有接口
• 按域组织：按功能域分组的接口
• 遵循命名约定：所有接口均以开头 I 前缀
• 仅键入导出：没有运行时代码，只有类型定义

此软件包不做什么

• 不执行任何操作：这是一个仅限类型的包
• 没有运行时依赖关系：只有devDependencies用于TypeScript编译
• 不了解实现：接口独立于实现

接口域

ADT域(adt/)

• IAdtObject -高级ADT对象操作界面

- 通过自动操作链、错误处理和资源清理提供简化的CRUD操作 - 方法： validate(), create(), read(), readMetadata(), readTransport(), update(), delete(), activate(), check() - 所有读取方法都支持可选 withLongPolling 用于等待对象可用的参数 - 支持完整的操作链： - 创建：验证→ 创造→ 检查→ lock → 检查（未激活）→ 更新→ 解锁→ 检查→ 激活 - 更新：锁定→ 检查（未激活）→ 更新→ 解锁→ 检查→ 激活 - 删除：勾选（删除）→ 删除

• IAdtOperationOptions -创建和更新操作的统一选项

- 领域： activateOnCreate, activateOnUpdate, deleteOnFailure, sourceCode, xmlContent, timeout

• AdtObjectErrorCodes -ADT对象操作的错误代码常量

- 常量： OBJECT_NOT_FOUND, OBJECT_NOT_READY, VALIDATION_FAILED, CREATE_FAILED, UPDATE_FAILED, DELETE_FAILED, ACTIVATE_FAILED, CHECK_FAILED, LOCK_FAILED, UNLOCK_FAILED

• IAdtObjectState -ADT对象操作的基本状态接口

- 领域： validationResponse, createResult, lockHandle, updateResult, checkResult, unlockResult, activateResult, deleteResult, readResult, metadataResult, transportResult, errors

• IAdtObjectConfig -ADT对象的基本配置界面

- 常见字段： packageName, description, transportRequest

身份验证域(auth/)

• IAuthorizationConfig -授权值（UAA凭据、刷新令牌）
• IConnectionConfig -连接值（服务URL、令牌、客户端、语言）
• IConfig -授权和连接配置的组成
• AuthType -身份验证类型： 'jwt' | 'xsuaa' | 'basic'

令牌域(token/)

• ITokenProvider -令牌提供者接口（有状态令牌生命周期）
• ITokenProviderOptions -令牌提供商的选项
• ITokenResult -令牌结果有效载荷（支持 expiresAt 和 tokenType 对于非JWT代币）
• IConnectionConfig / ISapConfig -现在支持 authType: 'saml' 和 sessionCookies
• ITokenRefresher -DI到连接的令牌刷新接口

- 由...创建 AuthBroker.createTokenRefresher(destination) - 注入到 JwtAbapConnection 启用自动令牌刷新 - 方法： getTokens()

会话域(session/)

• ISessionStore -会话存储接口

服务密钥域(serviceKey/)

• IServiceKeyStore -服务密钥存储接口

连接域(connection/)

• IAbapConnection -ADT操作的最小连接接口

- 面向消费者的方法： connect(), getBaseUrl(), getSessionId(), setSessionType(), makeAdtRequest() - connect() 在任何ADT请求之前初始化会话（CSRF令牌+Cookie） - 封装了实现细节（身份验证、CSRF、Cookie、令牌刷新） - 对于JWT：令牌刷新通过内部处理 ITokenRefresher - 对于Basic：无需刷新令牌

• IAdtResponse -返回的最小响应形状 makeAdtRequest()
• IWebSocketTransport -基于WS的流的通用实时传输契约

- 方法： connect(), disconnect(), send(), onMessage(), onOpen(), onError(), onClose(), isConnected()

• IWebSocketConnectOptions -WS连接选项(protocols, headers、超时、心跳）
• IWebSocketMessageEnvelope -具有关联id的通用请求/响应/事件/错误消息形状
• IWebSocketCloseInfo / IWebSocketMessageHandler -关闭有效负载和消息回调合约
• IAbapConnectionExtended -出于向后兼容性考虑，已弃用

- 扩展 IAbapConnection 与： getConfig(), getAuthHeaders(), reset() - 将在下一个主要版本中删除

• IAbapRequestOptions -请求ADT操作选项

订阅源域(feeds/)

• IAbapTimestamp -ABAP时间戳字符串类型别名（格式 YYYYMMDDHHMMSS)
• IFeedRepository -面向域的提要访问接口

- 方法： list(), variants(), dumps(), systemMessages(), gatewayErrors(), gatewayErrorDetail() - 所有方法都返回域类型（没有原始传输响应）

• IFeedQueryOptions -提要方法的查询参数(user, maxResults, from, to)
• IFeedEntry -通用提要条目(id, title, updated, link, content)
• IFeedDescriptor -馈送元数据(id, title, url, category)
• IFeedVariant -馈送变量元数据(id, title, url)
• ISystemMessageEntry -具有严重性和有效期的系统消息
• IGatewayErrorEntry -基本网关错误日志条目
• IGatewayErrorDetail -带有服务信息、错误上下文、源代码和调用堆栈的扩展错误
• IGatewayException, ICallStackEntry, ISourceCodeLine -错误详细信息的支持类型

执行域(execution/)

• IExecutor

- 支持以下内容的实体的通用合同： - run(target) - runWithProfiler(target, options) - runWithProfiling(target, options?)

运行时域(runtime/)

• IRuntimeAnalysisObject --带类型的基本界面 readonly kind: TKind 类型窄化鉴别器
• IListableRuntimeObject --扩展 IRuntimeAnalysisObject 随着 list() 方法
• 调试器: IDebugger （复合）， IAbapDebugger （会话、断点、变量、观察点、批处理）， IAmdpDebugger （AMDP特定调试）
• 记忆: IMemorySnapshots （带增量分析的快照）
• 分析器: IProfiler （跟踪、命中列表、语句、数据库访问）
• 痕迹: ICrossTrace （跨层迹线）， ISt05Trace （SQL跟踪）
• 日志: IApplicationLog, IAtcLog （ATC检查日志）
• DDIC: IDdicActivation （激活图）
• 垃圾: IRuntimeDumps （带视图的运行时转储）
• 动态: ISystemMessages, IGatewayErrorLog （重复使用 IFeedQueryOptions)
• 所有运行时接口都使用文字 kind 鉴别器（例如。， 'profiler', 'debugger')用于类型安全缩窄

SAP域(sap/)

• ISapConfig -SAP连接配置
• SapAuthType -身份验证类型： "basic" | "jwt"

服务域(service/)

• IAdtService -非CRUD服务操作的服务绑定生命周期契约

- 绑定发现/验证、传输检查、创建/读取/更新、激活/检查和生成的方法 - updateServiceBinding() 使用显式 desiredPublicationState 并验证允许的状态转换

• 参数/枚举类型：

- ServiceBindingVariant — 'ODATA_V2_UI' | 'ODATA_V2_WEB_API' | 'ODATA_V4_UI' | 'ODATA_V4_WEB_API' - SERVICE_BINDING_VARIANT_MAP --地图变体 { bindingType, bindingVersion, bindingCategory, serviceType } - ServiceBindingType, ServiceBindingVersion, GeneratedServiceType, DesiredPublicationState - ICreateServiceBindingParams （使用 binding_variant: ServiceBindingVariant), IUpdateServiceBindingParams, IReadServiceBindingParams - ITransportCheckServiceBindingParams, ICheckServiceBindingParams, IActivateServiceBindingParams - IGenerateServiceBindingParams, ICreateAndGenerateServiceBindingParams

存储域(storage/)

• ISessionStorage -会话存储接口
• ISessionState -会话状态结构

日志记录域(logging/)

• ILogger -记录器界面
• LogLevel -日志级别枚举(ERROR = 0, WARN = 1, INFO = 2, DEBUG = 3)

- 从包根导出： import { LogLevel } from '@mcp-abap-adt/interfaces'

验证域(validation/)

• IValidatedAuthConfig -验证身份验证配置
• IHeaderValidationResult -标头验证结果
• AuthMethodPriority -身份验证方法优先级枚举

实用程序域(utils/)

• ITokenRefreshResult -令牌刷新结果
• ITimeoutConfig -超时配置

依赖项

此包具有 无运行时依赖关系.它只有TypeScript编译的devDependencies：

• typescript -TypeScript编译器
• @types/node -Node.js类型定义

文档

• 包依赖性分析 -分析所有之间的依赖关系 @mcp-abap-adt/* 包，验证接口包没有运行时依赖关系，以及消除不必要依赖关系的路线图

许可证

麻省理工学院