{"_id":"@agent-vcr/core","name":"@agent-vcr/core","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agent-vcr/core","version":"0.1.0","description":"Record, replay, and diff MCP (Model Context Protocol) interactions — like VCR for AI agents","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./jest":{"types":"./dist/integrations/jest.d.ts","import":"./dist/integrations/jest.js"},"./vitest":{"types":"./dist/integrations/vitest.d.ts","import":"./dist/integrations/vitest.js"}},"bin":{"agent-vcr":"dist/cli.js"},"scripts":{"build":"tsc","watch":"tsc --watch","test":"vitest","test:unit":"vitest run tests/unit","test:integration":"vitest run tests/integration","lint":"eslint src --ext .ts","format":"prettier --write src tests","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["mcp","model-context-protocol","testing","recording","replay","ai-agents","vcr","mock","jsonrpc"],"author":{"name":"Pramod Voola","email":"pramod.voola@icloud.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/jarvis2021/agent-vcr.git","directory":"typescript"},"engines":{"node":">=18.0.0"},"dependencies":{"zod":"^3.23.8","commander":"^12.1.0","chalk":"^5.3.0"},"devDependencies":{"@types/node":"^20.14.0","@typescript-eslint/eslint-plugin":"^7.13.0","@typescript-eslint/parser":"^7.13.0","eslint":"^8.57.0","prettier":"^3.3.2","typescript":"^5.5.2","vitest":"^1.6.0","@vitest/ui":"^1.6.0"},"peerDependencies":{"jest":">=29.0.0","vitest":">=1.0.0"},"peerDependenciesMeta":{"jest":{"optional":true},"vitest":{"optional":true}},"gitHead":"e551d68ad08e0066f882e0c2b90adeb9ae721279","_id":"@agent-vcr/core@0.1.0","bugs":{"url":"https://github.com/jarvis2021/agent-vcr/issues"},"homepage":"https://github.com/jarvis2021/agent-vcr#readme","_nodeVersion":"25.5.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-uLaiE6HzdkMikCPDHkS8PwKb16mynZtM/ReXF9z3OP/nYHBL7V8zoV8EV7HrzHu8DV89d/NHLuJePgBHcWvoDw==","shasum":"92df4d4e963fa290a42021909ef06b4509440234","tarball":"https://registry.npmjs.org/@agent-vcr/core/-/core-0.1.0.tgz","fileCount":54,"unpackedSize":175171,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC0MqR56rh+9keEx2kLTmCjEG7UpYj/nvvHiJBzYd438gIgEND6JOmF2SdAf4LB4zpXq5Z7+br+lVthpYW8n24Pcec="}]},"_npmUser":{"name":"pramodvoola","email":"pramod.voola@icloud.com"},"directories":{},"maintainers":[{"name":"pramodvoola","email":"pramod.voola@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.1.0_1770606717060_0.6743588431117611"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-09T03:11:56.944Z","0.1.0":"2026-02-09T03:11:57.189Z","modified":"2026-02-09T03:11:57.425Z"},"maintainers":[{"name":"pramodvoola","email":"pramod.voola@icloud.com"}],"description":"Record, replay, and diff MCP (Model Context Protocol) interactions — like VCR for AI agents","homepage":"https://github.com/jarvis2021/agent-vcr#readme","keywords":["mcp","model-context-protocol","testing","recording","replay","ai-agents","vcr","mock","jsonrpc"],"repository":{"type":"git","url":"git+https://github.com/jarvis2021/agent-vcr.git","directory":"typescript"},"author":{"name":"Pramod Voola","email":"pramod.voola@icloud.com"},"bugs":{"url":"https://github.com/jarvis2021/agent-vcr/issues"},"license":"MIT","readme":"# Agent VCR - TypeScript/Node.js\n\n**Record, replay, and diff MCP interactions — like VCR for AI agents.**\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node 18+](https://img.shields.io/badge/node-18+-blue.svg)](https://nodejs.org/)\n\nFirst-class TypeScript implementation for the MCP ecosystem. **72 tests** cover format, matcher, replayer, recorder, and diff. **npm-ready** as `@agent-vcr/core`. Same functionality as the Python version with full cross-language compatibility — record with Python, replay with TypeScript (or the other way around). For implementation details and contributor notes, see [docs/typescript-implementation.md](../docs/typescript-implementation.md).\n\n## Installation\n\n```bash\nnpm install @agent-vcr/core\n```\n\nFor testing framework integrations:\n\n```bash\n# Jest\nnpm install --save-dev @agent-vcr/core\n\n# Vitest\nnpm install --save-dev @agent-vcr/core\n```\n\n## Quick Start\n\n### Recording MCP Interactions (CLI)\n\n```bash\n# Record stdio transport\nnpx agent-vcr record \\\n  --transport stdio \\\n  --server-command \"node my-mcp-server.js\" \\\n  -o my-recording.vcr\n\n# Record SSE transport\nnpx agent-vcr record \\\n  --transport sse \\\n  --server-command \"node my-mcp-server.js\" \\\n  --host 127.0.0.1 \\\n  --port 3000 \\\n  -o my-recording.vcr\n```\n\n### Replaying Recordings (CLI)\n\n```bash\n# Replay via stdio\nnpx agent-vcr replay -i my-recording.vcr --transport stdio\n\n# Replay via SSE\nnpx agent-vcr replay -i my-recording.vcr --transport sse --port 3000\n```\n\n### Diffing Recordings (CLI)\n\n```bash\nnpx agent-vcr diff \\\n  --baseline v1-recording.vcr \\\n  --current v2-recording.vcr \\\n  --fail-on-breaking\n```\n\n## Programmatic Usage\n\n### Recording\n\n```typescript\nimport { MCPRecorder } from \"@agent-vcr/core\";\n\nconst recorder = new MCPRecorder({\n  transport: \"stdio\",\n  command: \"node my-mcp-server.js\",\n  metadata: {\n    tags: { env: \"test\" },\n  },\n});\n\nawait recorder.start();\n\n// Let it record interactions...\n// Press Ctrl+C or call stop()\n\nconst recording = await recorder.stop();\nawait recorder.save(recording, \"recording.vcr\");\n```\n\n### Replaying\n\n```typescript\nimport { MCPReplayer } from \"@agent-vcr/core\";\n\n// Load from file\nconst replayer = await MCPReplayer.fromFile(\"recording.vcr\");\n\n// Handle a request\nconst request = {\n  jsonrpc: \"2.0\",\n  id: 1,\n  method: \"tools/list\",\n};\n\nconst response = replayer.handleRequest(request);\nconsole.log(response);\n\n// Serve as a mock server\nawait replayer.serveStdio(); // or serveSSE(host, port)\n```\n\n### Error Injection\n\n```typescript\nconst replayer = await MCPReplayer.fromFile(\"recording.vcr\");\n\n// Inject an error for request id=3\nreplayer.setResponseOverride(3, {\n  jsonrpc: \"2.0\",\n  id: 3,\n  error: {\n    code: -32603,\n    message: \"Internal server error\",\n  },\n});\n\n// Test your error handling\nconst response = replayer.handleRequest({\n  jsonrpc: \"2.0\",\n  id: 3,\n  method: \"tools/call\",\n  params: { name: \"calculator\" },\n});\n```\n\n### Diffing\n\n```typescript\nimport { MCPDiff } from \"@agent-vcr/core\";\n\nconst result = await MCPDiff.compareFiles(\"v1.vcr\", \"v2.vcr\");\n\nconsole.log(`Breaking changes: ${result.summary.breaking_count}`);\nconsole.log(`Added methods: ${result.summary.added_count}`);\nconsole.log(`Removed methods: ${result.summary.removed_count}`);\n\n// Check for specific breaking changes\nfor (const change of result.breaking_changes) {\n  console.log(`⚠️ ${change.type}: ${change.method}`);\n  console.log(`   ${change.details}`);\n}\n```\n\n## Testing Framework Integration\n\n### Vitest\n\n```typescript\nimport { describe, it, expect } from \"vitest\";\nimport { useVCRCassette } from \"@agent-vcr/core/vitest\";\n\ndescribe(\"My MCP client\", () => {\n  it(\"should list tools correctly\", async () => {\n    const { replayer, cassette } = await useVCRCassette({\n      name: \"list-tools\",\n      dir: \"tests/fixtures/cassettes\",\n    });\n\n    try {\n      const response = replayer.handleRequest({\n        jsonrpc: \"2.0\",\n        id: 1,\n        method: \"tools/list\",\n      });\n\n      expect(response?.result).toBeDefined();\n      expect(response?.result?.tools).toHaveLength(3);\n    } finally {\n      await cassette.eject();\n    }\n  });\n});\n```\n\n### Jest\n\n```typescript\nimport { useVCRCassette } from \"@agent-vcr/core/jest\";\n\ndescribe(\"My MCP client\", () => {\n  it(\"should list tools correctly\", async () => {\n    const { replayer, cassette } = await useVCRCassette({\n      name: \"list-tools\",\n      dir: \"__fixtures__/cassettes\",\n    });\n\n    try {\n      const response = replayer.handleRequest({\n        jsonrpc: \"2.0\",\n        id: 1,\n        method: \"tools/list\",\n      });\n\n      expect(response?.result).toBeDefined();\n    } finally {\n      await cassette.eject();\n    }\n  });\n});\n```\n\n## Match Strategies\n\nWhen replaying, you can choose how requests are matched to recorded interactions:\n\n| Strategy             | Description                          | Best For                 |\n| -------------------- | ------------------------------------ | ------------------------ |\n| `exact`              | Full JSON equality                   | Strictest regression     |\n| `method`             | Method name only                     | Broad acceptance tests   |\n| `method_and_params`  | Method + params equality (default)   | Standard testing         |\n| `fuzzy`              | Method + params subset matching      | Flexible testing         |\n| `sequential`         | Returns in order, ignores content    | Scripted replay          |\n\n```typescript\nconst replayer = await MCPReplayer.fromFile(\"recording.vcr\", \"fuzzy\");\n```\n\n## Cross-Language Compatibility\n\nRecordings are stored as JSON and are fully compatible between Python and TypeScript implementations:\n\n```bash\n# Record with Python\npython -m agent_vcr record --server-command \"node server.js\" -o recording.vcr\n\n# Replay with TypeScript\nnpx agent-vcr replay -i recording.vcr\n\n# Or vice versa!\n```\n\n## CLI Reference\n\n```bash\nagent-vcr record --help\nagent-vcr replay --help\nagent-vcr diff --help\nagent-vcr inspect --help\nagent-vcr convert --help\n```\n\n## API Documentation\n\nFull TypeScript API documentation is available in the source code with JSDoc comments. Key exports:\n\n```typescript\nimport {\n  // Core types\n  VCRRecording,\n  VCRInteraction,\n  JSONRPCRequest,\n  JSONRPCResponse,\n\n  // Main classes\n  MCPRecorder,\n  MCPReplayer,\n  MCPDiff,\n\n  // Transport\n  StdioTransport,\n  SSETransport,\n\n  // Matching\n  createMatcher,\n  MatchStrategy,\n\n  // Testing integrations\n} from \"@agent-vcr/core\";\n```\n\n## Examples\n\nSee the `/examples` directory in the repository for complete examples:\n\n- **Basic recording and replay**\n- **Error injection for resilience testing**\n- **CI/CD integration patterns**\n- **Multi-version compatibility testing**\n\n## Contributing\n\nSee [CONTRIBUTING.md](../CONTRIBUTING.md) in the repository root.\n\n## License\n\nMIT — see [LICENSE](../LICENSE)\n\n## Related Projects\n\n- [Python implementation](../python/README.md)\n- [Model Context Protocol](https://modelcontextprotocol.io)\n","readmeFilename":"README.md","_rev":"1-8cd8f085fc698b41fe1291ab33751864"}