# @aauth/mcp-agent 中文文档

规范地址：https://npmcn.com/package/%40aauth/mcp-agent/

版本：2\.0\.0
npm 元数据更新时间：2026-08-07T15:43:44.147Z
中文译文更新时间：2026-11-08T01:05:55.965Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aauth/mcp-agent
原文对照：https://npmcn.com/package/%40aauth/mcp-agent/?lang=original
项目主页：https://github.com/aauth-dev/packages-js#readme
源码仓库：https://github.com/aauth-dev/packages-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：169 kB，58 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-03-01T20:17:57.965Z
- 最新版本发布：2026-08-07T15:43:43.746Z
- 近 30 天下载量：1951（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 32 个）

## 中文简介

用 HTTP 签名为 AAuth 代理认证的 MCP 传输

## 安装

```sh
npm install @aauth/mcp-agent
```

也可以使用：`pnpm add @aauth/mcp-agent`、`yarn add @aauth/mcp-agent`、`bun add @aauth/mcp-agent`

## README

# @aauth/mcp-代理服务器

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

部分 [(auth-dev-packages-js) (韩语)](https://github.com/aauth-dev/packages-js)。协议规格: [迪克哈特/澳大利亚](https://github.com/dickhardt/AAuth)。 。 。 .

## 安装

```bash
npm install @aauth/mcp-agent
```

## 使用量

### `createAAuthFetch(options): FetchLike`

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

```ts
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: 'user@example.com',
  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 挑战的获取 。 只需请求签名即可使用 .

```ts
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` 反应头插入结构性挑战.

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

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

回返情况:

```ts
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起推迟答复和互动投票.

```ts
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`,澄清聊天,和交互代码.

```ts
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` 调用。 将密钥管理与协议脱钩——您可以任意提供密钥:

```ts
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`](https://npmcn.com/package/%40aauth/local-keys) 从 OS 键链中提供此回调 .

## 许可证

麻省理工学院

## 常见问题

### @aauth/mcp-agent 是什么？

用 HTTP 签名为 AAuth 代理认证的 MCP 传输

### 如何安装 @aauth/mcp-agent？

在项目目录运行 npm install @aauth/mcp-agent，或使用 pnpm add / yarn add / bun add。

### @aauth/mcp-agent 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aauth/mcp-agent 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @aauth/mcp-agent 可以商用吗？

@aauth/mcp-agent 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @aauth/mcp-agent 的下载量有多少？

根据 npm 官方下载统计，@aauth/mcp-agent 在 2026/10/05 – 2026/11/03 这 30 天内被下载 1,951 次，日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aauth/mcp-agent 还在维护吗？

最新版本 2\.0\.0 发布于 2026/08/07（3 个月前）；至今共发布 32 个版本，其中过去 12 个月发布了 32 个；首次发布于 2026/03/02。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。