@aauth/mcp-代理服务器

MCP代理助理助理助理助理 Handles签署了 HTTP 请求, AAuth 挑战响应流, 与 Auth 服务器的符号交换, 以及 202 推迟/交互投票.

部分 (auth-dev-packages-js) (韩语)。协议规格: 迪克哈特/澳大利亚。 。 。 .

安装

npm install @aauth/mcp-agent

使用量

createAAuthFetch(options): FetchLike

创建一个自动处理 AAuth 全部流量的协议意识获取器: 签名请求, 剖析 401 个挑战, 与 auth 服务器交换令牌, 缓存 auth 令牌, 处理 AAuth-Access 不透明符 (双会模式),并重试.

import { createAAuthFetch } from '@aauth/mcp-agent'

const fetch = createAAuthFetch({
  getKeyMaterial: async () => ({
    signingKey: privateKeyJwk,
    signatureKey: { type: 'jwt', jwt: agentToken }
  }),
  // Optional: declare protocol capabilities
  capabilities: ['interaction', 'clarification'],
  // Optional: mission context (sets AAuth-Mission header)
  mission: { approver: 'https://ps.example', s256: '...' },
  // Optional callbacks
  onInteraction: (url, code) => {
    console.log(`Visit ${url}?code=${code}`)
  },
  onClarification: async (question) => {
    return prompt(question)
  },
  // Optional hints for the auth server
  justification: 'Read project files',
  loginHint: '[email protected]',
  tenant: 'acme.com',
  domainHint: 'acme.com',
})

const response = await fetch('https://resource.example/api')

何时 capabilities 设置,每个签名的请求包括 AAuth-Capabilities 头曰. 何时 mission 设置,每个签名的请求包括 AAuth-Mission 头曰.

获取自动缓存和再利用 AAuth-Access 以两党模式由资源返回的不透明符号,通过 Authorization: Bearer 关于随后的请求.

createSignedFetch(getKeyMaterial, options?): FetchLike

创建一个以 HTTP 信件签名签名请求但不能处理 AAuth 挑战的获取 。 只需请求签名即可使用 .

import { createSignedFetch } from '@aauth/mcp-agent'

const signedFetch = createSignedFetch(async () => ({
  signingKey: privateKeyJwk,
  signatureKey: { type: 'hwk' }
}), {
  capabilities: ['interaction'],
  mission: { approver: 'https://ps.example', s256: '...' },
})

parseAAuthHeader(headerValue): AAuthChallenge

解析 a AAuth-Requirement 反应头插入结构性挑战.

import { parseAAuthHeader } from '@aauth/mcp-agent'

const challenge = parseAAuthHeader(response.headers.get('aauth-requirement'))
// { requirement: 'auth-token', resourceToken: '...' }

回返情况:

interface AAuthChallenge {
  requirement: 'auth-token' | 'approval' | 'interaction' | 'clarification' | 'claims'
  resourceToken?: string
  url?: string
  code?: string
}

exchangeToken(options): Promise<TokenExchangeResult>

在个人服务器上交换一个资源令牌以获取一个认证令牌。 处理元数据发现/.well-known/aauth-person.json),202起推迟答复和互动投票.

import { exchangeToken } from '@aauth/mcp-agent'

const { authToken, expiresIn } = await exchangeToken({
  signedFetch,
  authServerUrl: 'https://ps.example',
  resourceToken: '...',
  justification: 'Read project files',
})

pollDeferred(options): Promise<DeferredResult>

输入202 位置 URL 直至终端响应. 处理 Retry-After, (中文(简体) ), Prefer: wait,澄清聊天,和交互代码.

import { pollDeferred } from '@aauth/mcp-agent'

const { response, error } = await pollDeferred({
  signedFetch,
  locationUrl: 'https://auth.example/pending/abc123',
  interactionCode: 'ABCD1234',
  onInteraction: (code, endpoint) => { /* show to user */ },
  maxPollDuration: 300, // seconds, default 300
})

密钥材料回调

所有签名函数都使用 a GetKeyMaterial 调用。 将密钥管理与协议脱钩——您可以任意提供密钥:

type GetKeyMaterial = () => Promise<{
  signingKey: JsonWebKey          // Ed25519 private key for HTTP signatures
  signatureKey:
    | { type: 'jwt', jwt: string }  // agent or auth token
    | { type: 'hwk' }               // bare public key (pseudonym)
}>

用于地方发展,使用 @aauth/local-keys 从 OS 键链中提供此回调 .

许可证

麻省理工学院