a4sx sessions

a4sx-mcp

一个适用于 a4sx 的本地 MCP 服务。a4sx 是一个面向编码 Agent 会话的库和市场。它为任何 MCP 客户端（Claude Code、Claude Desktop、Cursor、VS Code……）提供五个工具，用于查找已保存的会话、将其加载为上下文，以及保存当前会话；登录信息使用 a4sx 命令行工具的登录状态。

它在你的计算机上通过 stdio 运行。你的 a4sx 令牌保存在 a4sx 配置目录中，只会发送给签发该令牌的服务：使用 --base 将服务指向其他位置，也绝不会向其发送另一个服务的令牌。

私人库：保存在你于 session-exchange.com 上的 a4sx 账户下的会话。其中的条目不会列在市场中，也不会通过公开搜索返回；你可以使用自己的登录信息（或创建的 Agent 密钥），通过 a4sx API 列出、获取、管理版本和删除这些条目。在市场中列出会话是 Web 应用中的单独步骤，需要审核。“私人”描述的是谁可以通过 a4sx 列出和获取条目；服务会存储你上传的字节，并再次清理这些内容。

工具

工具名称、输入架构和限制均与托管版 a4sx MCP 服务相同。

工具	功能	登录要求
search_sessions	搜索经过审核的公开会话（scope=public，默认），或你自己保存的会话（scope=library）；harness 仅保留使用指定 harness 记录的会话	仅限库范围
get_session_summary	使用会话前先了解其内容：大纲、成员、价格、来源	仅限库中的来源
acquire_session	将你有权使用的市场会话（免费、已购买或已获授权）复制到你的私人库	是
fetch_session_context	将库中的会话加载为起始上下文，并截断至 max_tokens（500 至 100,000；默认值为 8,000）	是
publish_session	将转录内容（JSONL）保存到你的私人库	是

安全规则：

• acquire_session 不会购买。 对于你尚未购买或获赠的付费条目，它会返回 status: "payment_required"，并附上价格和条目 URL（或者，当条目的会话单独出售时，附上要购买的 member）。你需要在 Web 应用中自行购买，然后再次请求。
• 运行环境。 Claude Code、Codex CLI 和 Grok Build 会话的列出和加载方式相同；目前只有 Claude Code 会话可以恢复。每条搜索结果和摘要行都会注明记录时使用的 harness（{id, version}；无法识别时为 unknown），并且使用其他运行环境记录的会话，其 resumable 为 false。fetch_session_context 会 根据会话存储的规范形式呈现此类会话。
• publish_session 只会私下保存。 visibility 仅接受 "private"；公开列出会话是 Web 应用中单独进行且需要审核的步骤。它仅接受 Claude Code 或 Codex CLI JSONL （每行都是带有 type 的记录；Claude Code 用户或助手回合需带有会话 ID，或者第一条记录为 Codex CLI session_meta 记录），因此不能用于上传任意文件。转录内容、标题和标签会在你的设备上通过 a4sx SDK 进行脱敏，该 SDK 应用 a4sx CLI 的规则（机密、命令行密码、Sheet ID 和个人数据：电子邮件地址和 IP 地址、主目录用户名、主机名、 密钥文件路径），服务器也会再次进行脱敏。脱敏只是最后一道防线，并非保证。如果会话延续了其他人的会话（其 parent 或恢复该会话所依据的会话已被获取），该会话会继续标记为不可信（untrusted: true）。
• 这两个工具都不会在协议内请求确认。 与托管服务一样，它依赖上述规则和工具注释：acquire_session 和 publish_session 均标记为 readOnlyHint: false，因此，在工具运行前会请求确认的客户端（Claude Code 默认如此）可以向你确认，你不应自动批准它们。三个读取工具均标记为只读。
• 加载的会话是参考资料，不是指令。fetch_session_context 总会以一条说明开头，指出这一点，然后使用随机 nonce，将会话作者可控制的所有内容（标题和对话回合）包裹在 <<<A4SX_UNTRUSTED_SESSION nonce=…>>> … <<<END_A4SX_UNTRUSTED_SESSION nonce=…>>> 中。其中，每种换行符都会规范化为 \n，<<</>>> 会变为 ‹‹‹/›››，行首的 # 会变为 \#（说明中会解释这一点），因此内容无法闭合封装，也无法伪造 ### User 标题。标题为单行，最多 200 个字符；截断到 max_tokens 时绝不会移除说明或结束行。search_sessions 和 get_session_summary 的结果也采用相同的封装方式：先给出说明，然后将 JSON 放在封装内；作者编写的每个字符串都在单行显示，经过中和处理并按字段限制长度；整个结果上限为 64 KiB（页面被截短时会显示 truncated: true，而 next_offset 会从第一条被省略的记录开始继续）。服务器提供的指引（next、next_offset）会在结束分隔符之后另起一行，绝不放在封装内，且只包含固定文本和数字。包含其他作者内容的会话会标记为 untrusted: true，并显示更强的警告。长得相似的字符（全角 ＜/＃、零宽空格）会原样保留：它们无法闭合封装，因为结束行需要随机 nonce，但模型仍可能被它们误导。这能降低提示词注入风险，但无法彻底消除风险：请保持启用工具审批。
• 限制： 每次 publish_session 调用最多接受 2 MiB 的转录内容（更大的文件请使用 a4sx push）； 每个进程每分钟最多处理 240 个请求（tools/list 和 tools/call）、20 次获取和 10 次发布。a4sx 服务也会执行自身的限制。

快速入门

你需要安装 uv（用于运行 uvx），并拥有一个 a4sx 账户。

1. 使用 a4sx CLI 登录一次。MCP 服务会复用此登录状态：

   uvx a4sx login
   

   无需登录即可搜索公开会话。如果某个工具需要你的账户，而你尚未登录（或登录已过期），它会返回错误，提示你运行 a4sx login。

2. 将服务添加到客户端。

Claude Code

claude mcp add a4sx -- uvx a4sx-mcp

Claude Desktop

编辑 claude_desktop_config.json（设置、开发者、编辑配置），然后重启 Claude Desktop：

{
  "mcpServers": {
    "a4sx": { "command": "uvx", "args": ["a4sx-mcp"] }
  }
}

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "a4sx": { "command": "uvx", "args": ["a4sx-mcp"] }
  }
}

VS Code

添加到工作区中的 .vscode/mcp.json（或从命令面板运行 MCP: Add Server）：

{
  "servers": {
    "a4sx": { "type": "stdio", "command": "uvx", "args": ["a4sx-mcp"] }
  }
}

试用

向你的 Agent 提问，例如："在 a4sx 中搜索关于不稳定 pytest fixture 的会话，并总结其中最好的一个"，或 "将我的 a4sx 会话 my-refactor 加载为上下文"。

配置

所有配置均为可选。请勿将令牌放入 MCP 客户端配置文件：改用 a4sx login 登录，令牌会以 mode 0600 存储。

设置	含义
--base URL / A4SX_BASE	a4sx 服务。默认使用你登录的服务，否则使用 https://session-exchange.com。除 localhost 外，拒绝使用普通 http。
A4SX_SESSION、A4SX_SESSION_BASE	用于替代已存储登录状态的令牌（适用于 CI），以及该令牌所属的服务（默认为 https://session-exchange.com）。
A4SX_CONFIG_DIR	a4sx CLI 存储登录信息的位置（默认值为 ~/.config/a4sx，Windows 上为 %APPDATA%\a4sx）。
A4SX_MCP_LOG	warning（默认值）、info 或 debug。日志写入 stderr，且仅包含工具名称、结果和耗时：绝不包含参数、对话记录或令牌。
A4SX_MCP_MAX_PUBLISH_BYTES	调低或调高 2 MiB 的 publish_session 上限（服务仍可能拒绝更大的上传）。
A4SX_MCP_PER_MIN、A4SX_MCP_ACQUIRE_PER_MIN、A4SX_MCP_PUBLISH_PER_MIN	本地速率限制（每分钟分别为 240、20、10 次）。0 可关闭本地限制。

本地服务还是远程 /mcp？

a4sx 也运行托管 MCP 服务 https://session-exchange.com/mcp，支持通过浏览器登录 OAuth：它声明了 library:read 范围（搜索你的知识库、查看摘要、将会话加载为上下文）。无需登录即可在该服务上进行公开搜索；获取或保存会话则需要具有 library:acquire 或 library:publish 权限的凭据，例如在你的 a4sx 账户中创建的 Agent 密钥。支持带 OAuth 的远程 MCP 服务的客户端可以直接连接，无需安装任何内容：

claude mcp add --transport http a4sx https://session-exchange.com/mcp

对于不支持远程 OAuth 的客户端，以及已使用 a4sx login 的配置，可以选择此软件包。两者都提供以下五种会话工具；托管服务还列出了自己的其他工具（例如，为账户持有人发起一笔待确认的购买），此软件包没有这些工具。

两者相同：

• 五种会话工具的名称、输入架构（包括 harness 筛选器）、注释和服务指令；
• 不可信内容的封装：fetch_session_context 的文本（提示、随机数封装、换行规范化、转义、各字段上限、大小限制、其他 harness 的规范会话），以及 search_sessions、 get_session_summary 和 acquire_session 的 JSON 封装、notice 字段、各字段上限、64 KiB 结果上限和提示行；
• 结果字段（以及下文列出的本地额外字段）；
• 错误代码 invalid_arguments、credential_not_accepted、rate_limited、not_found、 too_large、content_sha_mismatch、not_a_transcript 和 no_transcript；
• 超出整体请求限制时的 JSON-RPC 错误 -32029。

此本地服务的差异：

• 登录。 它使用你的 a4sx login 会话，因此可以在你自己的知识库中执行账户允许的所有操作。托管服务接受带范围的 OAuth 令牌（它声明了 library:read），或具有你授予的权限（library:read、library:acquire、library:publish）的 Agent 密钥。如果完全没有登录，本地工具会返回 not_signed_in；托管服务则会返回 OAuth 挑战。credential_not_accepted 消息会提示你运行 a4sx login，而不是获取带范围的令牌。
• 速率限制。 按进程计数，而非按账户计数。这里没有登录步骤，因此没有登录失败次数限制。retry_after_s 来自 API 的错误正文，而非 Retry-After 标头。
• untrusted。 除了检查记录及其父项上的 acquired_from（这是托管服务的全部检查）之外，它还会使用此机器上由 a4sx SDK 记录的不可信会话信息。在两种服务中，未出现在你的知识库列表中的会话都视为不可信。
• publish_session：
  • 每次上传都会携带幂等键：如果你传入 idempotency_key，就使用该值；否则生成一个新的。托管服务仅在你传入幂等键时才会发送。
  • 遇到网络错误、429 和 502-504 时，上传会使用同一个键重试两次；如果服务器正忙于清理其他上传，则最多尝试 6 次，每次都在服务器要求的等待时间之后重试。
  • 正文、标题和标签会在本地清理，因此发送给 API 的 X-Content-SHA256 校验的是清理后的字节。
  • 内容检查更严格：每一行都必须是带有 type 的 JSON 记录，且文件必须是 Claude Code 或 Codex CLI 会话。
  • parent 的解析方式与 CLI 解析名称相同（精确 ID、然后是标签、最后是标题或 ID 中唯一匹配的部分）。托管服务会原样传递该值。
  • 如果没有 parent，通过 a4sx resume 恢复的会话会从 SDK 的本地谱系记录中获取父级边。托管服务不会记录这条边。
  • 结果会额外包含 client_redactions 和 untrusted 字段。
• payment_required。 价格来自公开列表；托管服务则读取自己的定价存储。
• 服务名称。 MCP 握手中使用 a4sx-mcp（托管服务：com.session-exchange/sessions）。

VS Code 扩展

vscode/ 目录包含适用于 VS Code 1.101 或更高版本的 a4sx 扩展。它会将托管的 a4sx MCP 服务添加到 VS Code 聊天的 Agent 模式中；登录由 VS Code 处理。侧边栏可让你登录 a4sx、列出资料库中的会话（可在终端中继续会话，或在网页上打开），并搜索市场。它的命令 a4sx: Save this session 会在终端中运行 a4sx push --latest，将你最近更改的本地 Claude Code 会话保存到 a4sx 资料库。若要继续已保存的会话，请使用 Claude Code；目前其他运行环境无法继续会话。

此扩展尚未发布到 Visual Studio Marketplace。若要从源代码构建并测试：

cd vscode
npm install
npm run compile
npm test

MCP 注册表

server.json 为 MCP 注册表描述此服务：托管于 https://session-exchange.com/mcp 的服务（Streamable HTTP），以及 PyPI 上的此软件包（a4sx-mcp，stdio）。 它使用名称 com.session-exchange/sessions，托管服务已以此名称列出。

开发

git clone https://github.com/crossvault/a4sx-mcp && cd a4sx-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest -q          # offline: the tools run against a local stub server
ruff check . && reuse lint

测试不会访问网络：工具测试针对 127.0.0.1 上的 tests/stub_server.py 运行，协议测试使用 MCP SDK 的进程内客户端，另有一项保护措施会使任何解析或连接到非环回地址的测试失败。请参阅 CONTRIBUTING.md。

关于

a4sx-mcp 由 crossVault GmbH 开发，该公司也是 a4sx (session-exchange.com) 背后的公司；a4sx 是面向编码 Agent 会话的资料库和市场。它是一个轻量客户端：工具通过开源 a4sx SDK 调用 a4sx 公共 API，托管服务不属于此代码库。除公开搜索外，使用所有功能都需要 a4sx 账户。它是开源的，因此你可以在将其连接到 Agent 前，确切检查它会发送哪些内容。本项目的部分内容是在 AI 协助（Claude）下开发的。

安全

请私下报告漏洞；请参阅 SECURITY.md。

许可证

Apache-2.0，参见 LICENSE。版权所有 2026 crossVault GmbH。