Agent Vcr

MCPAI代理

提供方 Jarvis2021

AI代理 stdio · 本地进程 会话登录 社区 / 第三方 Claude
查看接入方式

Agent VCR是一个用于记录、回放和比较MCP(Model Context Protocol)交互的测试框架,适用于需要离线测试和模拟MCP服务器行为的开发场景。

一句话选型结论

按资料字段整理

Agent Vcr 属于AI代理类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类AI代理 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 6 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

AI代理
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

测试框架Python本地部署MCP协议JSON-RPC离线测试交互模拟

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
pip install agent-vcr

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
给代理接外部能力

让代理在任务中途调用搜索、数据库等真实工具。

多步任务编排

把一串操作拆成步骤,由代理按顺序执行。

自动化重复流程

把固定流程交给代理跑,减少手工操作。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在AI代理场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Agent Vcr当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Filesystem 560c4363 13 未标注 本地部署 无 2026-05-17
Server Everything (everything) 11 stdio · 本地进程 本地部署 有 2026-05-17
Time 7365cb6d 2 SSE · 服务端推送 远程部署 有 2026-05-18
Everything Claude Code 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Openmemory 557e1585 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

AI代理
字段来自项目仓库与公开索引,中文说明由本站标注
提供方Jarvis2021上游标注的维护方 Jarvis2021
分类AI代理本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

17.6 KB
来自项目仓库与上游目录的原文,未做删改

VCR代理商

> 🚀 现在可用 PyPI 和 npm! 安装时使用 pip install agent-vcr 或 npm install @agent-vcr/core.

记录、回放和区分MCP交互——就像AI代理的VCR。

在没有不稳定的实时服务器的情况下测试MCP服务器和客户端。 用于测试的模拟MCP:录制一次,永远重播。CI中不再有“MCP服务器宕机”或“速率限制”——确定性、快速、离线。

Agent VCR是一个测试框架 模型上下文协议(MCP)它透明地记录MCP客户端和服务器之间的所有JSON-RPC 2.0交互,然后确定性地重放它们——不需要真正的服务器。 比自己开玩笑更容易: 一个安装,一个录制命令,一个回放命令。几秒钟内的金色卡带。

Python和TypeScript是一流的。 Python实现有250多个测试和一个完整的CLI;TypeScript实现有72个单元测试、完整的CLI,并作为 @agent-vcr/core 在npm上——非常适合大多数MCP服务器和客户端所在的TypeScript优先的MCP生态系统。录音是跨语言的:用Python录音,用TypeScript重放(或者反过来)。看 typescript/README.md.

问题

如果你正在构建MCP服务器或客户端,你遇到了这些问题:

“我的测试很不稳定,因为它们依赖于实时服务器。” 外部MCP服务器停机、速率限制或每次运行返回不同的结果。CI管道失败的原因与代码无关。

“如果不破坏服务器,我就无法测试错误处理。” 您如何验证您的客户端处理超时、格式错误的响应或服务器崩溃?您需要修改服务器本身,或者只是希望最好。

“我寄了一张破钞,但没收到。” 您更新了MCP服务器,下游客户端发生故障。无法检测到这一点 tools/call 开始返回不同的模式,直到用户提交了错误。

“针对真实API的测试既缓慢又昂贵。” 每次测试运行都会到达真实的服务器,等待真实的响应,并消耗掉API配额。一个需要几秒钟的测试套件需要几分钟的时间。

VCR代理商如何解决这个问题

在真实服务器上记录一次MCP交互,并将其另存为 .vcr 卡带,并永远重放它们:```
Record (once) Replay (every test run)
───────────── ─────────────────────────
Client ←→ Agent VCR ←→ Real Server Client ←→ Agent VCR (mock)
│ │
└──→ session.vcr ────────────────────┘


- **确定性的**:每次输入相同,输出相同
- **快速**:无网络呼叫,即时响应
- **离线**:测试在没有服务器访问权限的情况下运行
- **安全**:在不修改真实服务器的情况下注入错误
- **可见的**:在发货前区分两个记录以捕捉回归

**结果:** 曾经缓慢而不稳定的CI(实时MCP服务器、超时、速率限制)变得快速而确定——在几秒钟内运行,在部署前捕获破坏性的更改。

## 真实世界用例

**开源MCP服务器作者:** 船a `.vcr` 使用服务器的盒式磁带,这样用户就可以在不安装或运行服务器的情况下运行他们的客户端测试——这是其他人无法实现的分发故事。
**拥有多代理系统的企业:** 许多AI代理与许多MCP服务器通信?当服务器团队A推送一个新版本时,diff功能会在生产之前捕捉到破坏性的更改。平台团队使用Agent VCR来控制部署。
**CI/CD:** 不再因为MCP服务器宕机、速率受限或运行缓慢而进行不稳定的测试。录制金色录音带;测试以毫秒为单位运行,每次都是确定性的。
**成本控制:** 调用付费API的MCP服务器?记录一次——永远不要在测试中再次消耗配额。

## 真实世界的例子

### 1.金盒测试

记录“已知良好”会话,提交 `.vcr` 将文件保存到您的仓库中,并在CI中重放。如果您的代码更改破坏了交互模式,测试将立即失败。```bash
# Record the golden cassette (once, using the included demo server)
agent-vcr record --transport stdio --server-command "python demo/servers/calculator_v1.py" -o cassettes/golden.vcr

# Every CI run replays it
pytest tests/ --vcr-dir=cassettes

2.MCP服务器兼容性门

在部署新的服务器版本之前,记录新旧版本,然后记录差异:```bash
agent-vcr record --transport stdio --server-command "python demo/servers/calculator_v1.py" -o v1.vcr
agent-vcr record --transport stdio --server-command "python demo/servers/calculator_v2.py" -o v2.vcr
agent-vcr diff v1.vcr v2.vcr --fail-on-breaking


如果 `tools/call` 更改了响应模式,或者删除了一个方法,diff会捕获它并以代码1退出——阻止部署。

### 3.弹性测试的错误注入

使用响应覆盖来模拟故障,而无需修改服务器:```python
replayer = MCPReplayer(recording)

# Inject a server error for request id=3
replayer.set_response_override(3, {
"jsonrpc": "2.0",
"id": 3,
"error": {"code": -32603, "message": "Internal server error"}
})

# Your client code should handle this gracefully
response = replayer.handle_request(request)
assert handle_error(response) == expected_fallback

4.线下开发

在飞机上工作?在WiFi不好的咖啡店?事先记录您的MCP服务器交互,并根据回放进行开发:```bash

Before going offline

agent-vcr record --transport sse --server-url http://localhost:3000/sse -o dev-session.vcr

While offline — full mock server on port 3100

agent-vcr replay --file dev-session.vcr --transport sse --port 3100


### 5.多智能体回归测试

当多个AI代理共享MCP基础设施时,一个代理的服务器更改可能会破坏另一个代理。Agent VCR允许每个团队维护自己的磁带并独立运行兼容性检查。

### 6.协议演进跟踪

随着MCP规范的发展,使用差异来跟踪服务器在协议版本之间的行为变化:```python
result = MCPDiff.compare("mcp-2024-11.vcr", "mcp-2025-03.vcr")
print(f"Added methods: {len(result.added_interactions)}")
print(f"Breaking changes: {len(result.breaking_changes)}")

快速开始

> 初次接触VCR探员? 跟随 实践教程 --8个动手实验室,涵盖每个用例和真实命令。

安装

python```bash

Recommended

uv pip install agent-vcr

Or with pip

pip install agent-vcr


**Types/Node.js:**```bash
npm install @agent-vcr/core
# or
pnpm add @agent-vcr/core

录制会话```bash

Record stdio-based MCP server (try it now with the included demo server)

agent-vcr record --transport stdio --server-command "python demo/servers/calculator_v1.py" -o session.vcr

Record SSE-based MCP server (replace URL with your server)

agent-vcr record --transport sse --server-url http://localhost:3000/sse -o session.vcr


### 作为模拟服务器重播```bash
# Replay via stdio (pipe to your client)
agent-vcr replay --file session.vcr --transport stdio

# Replay via HTTP+SSE
agent-vcr replay --file session.vcr --transport sse --port 3100

区分两个录音```bash

agent-vcr diff baseline.vcr current.vcr
agent-vcr diff baseline.vcr current.vcr --format json --fail-on-breaking


### 索引和搜索许多磁带```bash
agent-vcr index recordings/ -o index.json
agent-vcr search index.json --method tools/list
agent-vcr search index.json --endpoint-id github

批次差异```bash

pairs.json: {"pairs": [{"baseline": "v1.vcr", "current": "v2.vcr"}, ...]}

agent-vcr diff-batch pairs.json --fail-on-breaking


### 验证、合并和分析```bash
# Validate a recording's schema and structure
agent-vcr validate session.vcr

# Merge multiple recordings into one
agent-vcr merge session1.vcr session2.vcr -o combined.vcr --deduplicate

# Show statistics (method distribution, latency percentiles, error rate)
agent-vcr stats session.vcr

检查记录```bash

agent-vcr inspect session.vcr
agent-vcr inspect session.vcr --format table


## 比赛策略

重放器支持5种匹配策略来查找记录的响应:

|策略|描述|用例|
|----------|-------------|----------|
| `exact` |完全JSON匹配(不包括jsonrpc和id字段)|最严格的测试|
| `method` |仅按方法名称匹配|广泛匹配|
| `method_and_params` |匹配方法+完整参数 *(默认)* |标准测试|
| `subset` |匹配方法+部分参数(子集)|灵活测试|
| `sequential` |按顺序返回交互|有序回放|

*注: `fuzzy` 该策略已被弃用;使用 `subset` 相反。 `fuzzy` 为了向后兼容,保留为别名。*

## 重播者功能

重放器支持延迟模拟以进行真实测试:```bash
# Simulate latency during replay
agent-vcr replay --file session.vcr --simulate-latency

# Scale recorded latencies (1.0 = original, 2.0 = double)
agent-vcr replay --file session.vcr --simulate-latency --latency-multiplier 2.0

差异特征

增强的差异功能:```bash

Compare latency between recordings

agent-vcr diff baseline.vcr current.vcr --compare-latency


## 立即尝试

回购随附样品 `.vcr` 卡带,以便您可以立即尝试CLI:```bash
# Inspect a recording
agent-vcr inspect examples/recordings/calculator-v1.vcr

# Diff two server versions — spot the new tool and schema changes
agent-vcr diff examples/recordings/calculator-v1.vcr examples/recordings/calculator-v2.vcr

# See error handling in action
agent-vcr inspect examples/recordings/calculator-errors.vcr

样本盒包括:

文件 描述 交互
calculator-v1.vcr 计算器MCP服务器v1--加、乘 3
calculator-v2.vcr 计算器v2--添加除法工具+响应元数据 4
calculator-errors.vcr 错误场景--除以零,找不到方法 4

程序化使用

手动创建录制```python

from datetime import datetime
from agent_vcr.core.format import (
JSONRPCRequest, JSONRPCResponse, VCRInteraction,
VCRMetadata, VCRRecording, VCRSession,
)

Build the initialize handshake

init_req = JSONRPCRequest(id=0, method="initialize", params={
"protocolVersion": "2024-11-05",
"clientInfo": {"name": "my-client", "version": "1.0.0"},
})
init_resp = JSONRPCResponse(id=0, result={
"protocolVersion": "2024-11-05",
"serverInfo": {"name": "my-server", "version": "1.0.0"},
"capabilities": {"tools": {}},
})

Build an interaction

interaction = VCRInteraction(
sequence=0,
timestamp=datetime.now(),
direction="client_to_server",
request=JSONRPCRequest(id=1, method="tools/list", params={}),
response=JSONRPCResponse(id=1, result={
"tools": [{"name": "echo", "description": "Echo a message"}]
}),
latency_ms=12.5,
)

Assemble and save

recording = VCRRecording(
metadata=VCRMetadata(
version="1.0.0",
recorded_at=datetime.now(),
transport="stdio",
),
session=VCRSession(
initialize_request=init_req,
initialize_response=init_resp,
interactions=[interaction],
),
)
recording.save("session.vcr")


### 在代码中回放```python
from agent_vcr.core.format import VCRRecording
from agent_vcr.replayer import MCPReplayer

recording = VCRRecording.load("session.vcr")
replayer = MCPReplayer(recording, match_strategy="method_and_params")

response = replayer.handle_request({
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
})
print(response)  # Returns the recorded response

录音困难```python

from agent_vcr.diff import MCPDiff

result = MCPDiff.compare("baseline.vcr", "current.vcr")

if result.is_identical:
print("No changes!")
elif result.is_compatible:
print(f"Compatible changes: {len(result.modified_interactions)} modified")
else:
print("Breaking changes detected!")
for change in result.breaking_changes:
print(f" - {change}")


## Pytest集成

Agent VCR包括一个用于无缝测试集成的pytest插件。

### 使用夹具```python
import pytest

@pytest.mark.vcr("cassettes/test_tools_list.vcr")
def test_tools_list(vcr_replayer):
"""Test that tools/list returns expected tools."""
response = vcr_replayer.handle_request({
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {}
})
assert "result" in response
assert len(response["result"]["tools"]) > 0

使用异步上下文管理器```python

from agent_vcr.pytest_plugin import vcr_cassette

async def test_with_cassette():
async with vcr_cassette("my_test.vcr") as cassette:
response = cassette.replayer.handle_request({
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {"name": "echo", "arguments": {"message": "hello"}}
})
assert response["result"]["content"][0]["text"] == "hello"


### CLI选项```bash
pytest --vcr-record            # Record new cassettes
pytest --vcr-dir=my_cassettes  # Custom cassette directory

VCR文件格式

录制使用基于JSON的 .vcr 格式:```json
{
"format_version": "1.0.0",
"metadata": {
"version": "1.0.0",
"recorded_at": "2026-02-07T10:30:00",
"transport": "stdio",
"client_info": {"name": "claude-desktop"},
"server_info": {"name": "my-mcp-server"},
"tags": {"env": "staging"}
},
"session": {
"initialize_request": { "jsonrpc": "2.0", "id": 0, "method": "initialize", "params": {} },
"initialize_response": { "jsonrpc": "2.0", "id": 0, "result": { "capabilities": {} } },
"capabilities": {},
"interactions": [
{
"sequence": 0,
"timestamp": "2026-02-07T10:30:05",
"direction": "client_to_server",
"request": { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} },
"response": { "jsonrpc": "2.0", "id": 1, "result": { "tools": [] } },
"latency_ms": 12.5
}
]
}
}


## Python vs TypeScript

Python实现是 **完整并经过测试** (250+次测试)。Types/Node.js端口反映了相同的架构,并具有 **完整的单元测试套件** (72次测试)。

|特性| Python | TypeScript|
|--------|--------|------------|
|状态|生产就绪|72个单元测试,源代码完成|
|测试|250多个测试通过|72个单元测试 `tests/unit/` |
|CLI |功能齐全|功能齐全|
|测试框架|pytest插件|Jest/Vitest(回放模式)|
|录制格式| `.vcr` (JSON)| `.vcr` (JSON)--格式相同|
|集成中的记录模式|已实施|计划用于v0.2.0|

**跨语言录音:** 这 `.vcr` 格式是纯JSON,因此Python创建的记录可以通过TypeScript实现加载。

## 缩放(多MCP,代理到代理)

我们支持 **多MCP** 和 **代理人对代理人**:录制多个会话(一个 `.vcr` 每客户端↔服务器会话),用标签标记每个会话 `--session-id`, `--endpoint-id`,以及 `--agent-id`,并在测试或工具中关联它们。 **索引** (`agent-vcr index`, `agent-vcr search`)以及 **批量差异** (`agent-vcr diff-batch`)让你在许多磁带上工作。有关设计和代理到代理模式,请参见 docs/scaling.md.

**示例——相关性元数据(带有端点/会话ID的记录,inspect显示它们):**

## 建筑

看 docs/architecture.md 用于整个系统设计、数据流图和设计决策。

**python**```
python/src/agent_vcr/
├── core/
│   ├── format.py      # Pydantic models for .vcr format
│   ├── matcher.py     # Request matching strategies
│   └── session.py     # Session lifecycle management
├── transport/
│   ├── base.py        # Abstract transport interface
│   ├── stdio.py       # Subprocess stdio proxy
│   └── sse.py         # HTTP+SSE proxy
├── recorder.py        # Transparent recording proxy
├── replayer.py        # Mock server from recordings
├── diff.py            # Recording comparison engine
├── indexer.py         # Index/search many .vcr files
├── cli.py             # Command-line interface
└── pytest_plugin.py   # Pytest integration

TypeScript:```
typescript/src/
├── core/
│ ├── format.ts # Zod schemas for .vcr format
│ ├── matcher.ts # Request matching strategies
│ └── session.ts # Session lifecycle management
├── transport/
│ ├── base.ts # Abstract transport interface
│ ├── stdio.ts # Subprocess stdio proxy
│ └── sse.ts # HTTP+SSE proxy
├── recorder.ts # Transparent recording proxy
├── replayer.ts # Mock server from recordings
├── diff.ts # Recording comparison engine
├── cli.ts # Command-line interface
└── integrations/
├── jest.ts # Jest integration
└── vitest.ts # Vitest integration


## 发展

### python```bash
# Clone and install
git clone https://github.com/jarvis2021/agent-vcr.git
cd agent-vcr/python

# Setup with uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=src/agent_vcr --cov-report=html

# Lint
ruff check src/

# Type check
mypy src/

TypeScript```bash

cd agent-vcr/typescript

npm install
npm run build
npm test


### 创建演示GIF

使用 腹水瘤 和 agg。参见 **demo/READM-GIFS.md** 用于每个实验室的命令(`bash demo/make-lab-gifs.sh <1-12>`)以及相关性演示(`demo/record-correlation-demo.sh`).

- **记录** (上图): `assets/lab-1-record.gif` --来自实验室1(`make-lab-gifs.sh 1`)那么 `agg demo/lab-1.cast assets/lab-1-record.gif`.
- **回放** (上图): `assets/lab-2-replay.gif` --来自实验室2(`asciinema rec demo/lab-2.cast -c "bash demo/make-lab-gifs.sh 2"`)那么 `agg demo/lab-2.cast assets/lab-2-replay.gif`.
- **差异** (真实世界的例子): `assets/lab-3-diff.gif`. **相关性**: `assets/correlation-demo.gif` 通过 `demo/record-correlation-demo.sh`.

### 运行所有测试(Python+TypeScript)

从repo根目录:```bash
cd python && uv run pytest tests/ -v

贡献

欢迎投稿!请参阅 docs/architecture.md 用于系统设计上下文和 贡献.md 作为指导方针。

许可证

麻省理工学院

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Agent Vcr 怎么安装?

在客户端按下面的安装命令接入:pip install agent-vcr。装完在客户端配置里引用同一个包或端点。

Agent Vcr 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Agent Vcr 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Agent Vcr 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

Agent Vcr 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Agent Vcr 能提供哪些能力?

资料显示能力标签包括 测试框架、Python、Claude。具体工具清单以官方文档为准。

Agent Vcr 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Agent Vcr 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。