# https://github.com/Neal006/mcptail Project Manual Generated at: 2026-07-06 14:41:13 UTC ## Table of Contents - [Introduction and Quickstart](#page-overview) - [System Architecture and Data Pipeline](#page-architecture) - [Client Adapters and Configuration Management](#page-adapters) - [Dashboard, Replay, and Common Operations](#page-operations) ## Introduction and Quickstart ### Related Pages Related topics: [System Architecture and Data Pipeline](#page-architecture), [Dashboard, Replay, and Common Operations](#page-operations)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/Neal006/mcptail/blob/main/README.md) - [ROADMAP.md](https://github.com/Neal006/mcptail/blob/main/ROADMAP.md) - [CONTRIBUTING.md](https://github.com/Neal006/mcptail/blob/main/CONTRIBUTING.md) - [package.json](https://github.com/Neal006/mcptail/blob/main/package.json) - [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts) - [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts) - [src/server.ts](https://github.com/Neal006/mcptail/blob/main/src/server.ts) - [src/replay.ts](https://github.com/Neal006/mcptail/blob/main/src/replay.ts) - [src/adapters/index.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/index.ts) - [src/pricing.json](https://github.com/Neal006/mcptail/blob/main/src/pricing.json) - [ui/src/app.tsx](https://github.com/Neal006/mcptail/blob/main/ui/src/app.tsx) - [ui/src/style.css](https://github.com/Neal006/mcptail/blob/main/ui/src/style.css) - [tests/store.test.ts](https://github.com/Neal006/mcptail/blob/main/tests/store.test.ts) - [tests/taps.test.ts](https://github.com/Neal006/mcptail/blob/main/tests/taps.test.ts)
# Introduction and Quickstart mcptail is a record-and-replay proxy for [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers. It sits between an MCP client (such as Claude Code, Cursor, or Windsurf) and the underlying stdio MCP servers, capturing every JSON-RPC message exchanged while staying a transparent transport. The goal is to give developers an inspectable timeline of tool calls, an offline replay harness for testing, and a foundation for downstream exporters (HAR, OpenTelemetry, regression-test specs) without changing how the client or server behave on the hot path. Source: [README.md:1-40]() The project is published as `mcptail` on npm and currently tracks the **v0.1.0** release line. v0.1 is scoped to **stdio servers only**; Streamable HTTP / SSE transport capture is on the roadmap and tracked separately. Source: [ROADMAP.md:1-30]() ## What mcptail does At runtime, mcptail performs four jobs: 1. **Adapter rewrite** — rewrites a host's MCP config (e.g. Claude Desktop's `claude_desktop_config.json`, Cursor's `mcp.json`, Windsurf's `mcp_config.json`) so the `command` field points at `mcptail tap `. The original server still runs unchanged; mcptail is just a wrapper in the middle. Source: [src/adapters/index.ts:1-80]() 2. **Line tap** — frames the byte stream on each side of the stdio pipe into newline-delimited JSON-RPC messages, correlates request `id`s with their responses, and records latency and error status. Source: [src/store.ts:1-120]() 3. **Session storage** — appends correlated calls to JSONL files under `~/.mcptail/sessions/`, one file per server run, via a `SessionWriter` that has a configurable size cap. Source: [src/store.ts:120-220]() 4. **Local UI + HTTP API** — serves a small dashboard on a local port that lists sessions, shows a call timeline, and exposes endpoints for export (e.g. `GET /api/export?file=...&format=har`). Source: [src/server.ts:1-160]() The proxy follows a **degrade-to-pipe** philosophy: if recording fails, errors are written to stderr and the proxy still forwards traffic, so a broken tap never breaks the user's MCP client. Source: [src/store.ts:200-260]() ## Install mcptail is a Node.js project. The recommended path is via `npm`: ```bash npm install -g mcptail mcptail --help ``` A local-from-source install is supported for contributors: ```bash git clone https://github.com/Neal006/mcptail cd mcptail npm install npm run build node dist/cli.js --help ``` Source: [package.json:1-60]() The package declares CLI entry points, a `build` script that bundles the TypeScript sources in `src/`, and a `test` script that runs the Vitest suites under `tests/`. Source: [package.json:30-80]() ## Quickstart: from zero to a captured session The minimum loop to get value out of mcptail is three commands. The example below assumes a Claude Desktop install — the same flow works for Cursor and Windsurf via their respective adapters. ```bash # 1. Wrap every MCP server in your host config with `mcptail tap`. mcptail init # 2. Use your MCP client normally — call a few tools. # (mcptail runs in the background; the client sees no change.) # 3. Open the dashboard and inspect the timeline. mcptail ui ``` `mcptail init` is the only command that mutates a host config. It detects the active adapter, reads the existing `mcpServers` block, and rewrites each `command` to invoke `mcptail tap` first; the server's argv is preserved. Source: [src/adapters/index.ts:40-120]() Source: [src/cli.ts:1-140]() `mcptail doctor` is the companion command for verifying the wiring: it parses the host config, confirms each server is wrapped, and prints any drift between the config and what mcptail last recorded. Source: [src/cli.ts:140-220]() To undo the rewrite, run `mcptail remove`, which restores the original commands from mcptail's own bookkeeping file. Source: [src/cli.ts:220-280]() ## Common follow-up commands | Command | Purpose | Backed by | | --- | --- | --- | | `mcptail ui` | Open the local dashboard and timeline | `src/server.ts`, `ui/src/app.tsx` | | `mcptail clear` / `mcptail clear --older-than 7d` | Prune session files in `~/.mcptail/sessions/` | `src/store.ts`, `src/cli.ts` | | `mcptail export --format har ` | Emit a HAR file for a captured session | `src/server.ts` (`/api/export`) | | `mcptail test spec.yaml` | Replay a captured call against a server | `src/replay.ts` | Sessions accumulate forever by default, so `mcptail clear` (proposed in issue #12) is the expected first habit after experimenting. The size cap on `SessionWriter` (issue #13, default ~50 MB) protects a single chatty server from filling the disk before you remember to clean up. Source: [tests/store.test.ts:1-80]() ## Where to go next - For adapter coverage (Claude Desktop, Cursor, Windsurf) and how to add a new host, see the **Adapters** page. - For the session file format and the `correlate()` helper that powers diffing, see **Session Storage & Replay**. - For UI work (keyboard nav, search, light theme) the active issues are #10, #11, and #15; all touch `ui/src/app.tsx` and `ui/src/style.css`. - For the planned HTTP/SSE proxy mode, OpenTelemetry exporter, and "export as regression test" feature, track issues #18, #19, and #20 on GitHub. Source: [ROADMAP.md:30-120]() Source: [CONTRIBUTING.md:1-60]() --- ## System Architecture and Data Pipeline ### Related Pages Related topics: [Introduction and Quickstart](#page-overview), [Client Adapters and Configuration Management](#page-adapters), [Dashboard, Replay, and Common Operations](#page-operations)
Related Source Files The following source files were used to generate this page: - [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts) - [src/proxy.ts](https://github.com/Neal006/mcptail/blob/main/src/proxy.ts) - [src/taps.ts](https://github.com/Neal006/mcptail/blob/main/src/taps.ts) - [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts) - [src/frames.ts](https://github.com/Neal006/mcptail/blob/main/src/frames.ts) - [src/cost.ts](https://github.com/Neal006/mcptail/blob/main/src/cost.ts) - [src/pricing.json](https://github.com/Neal006/mcptail/blob/main/src/pricing.json) - [src/server.ts](https://github.com/Neal006/mcptail/blob/main/src/server.ts) - [src/export.ts](https://github.com/Neal006/mcptail/blob/main/src/export.ts) - [src/replay.ts](https://github.com/Neal006/mcptail/blob/main/src/replay.ts) - [src/adapters/index.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/index.ts) - [src/adapters/cursor.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/cursor.ts)
# System Architecture and Data Pipeline mcptail is a record-and-replay proxy for Model Context Protocol (MCP) servers. It sits transparently between an MCP client (Cursor, Windsurf, Claude Desktop, …) and a stdio MCP server, parses the newline-delimited JSON-RPC traffic, correlates request/response pairs, persists them as session files on disk, and surfaces them through a local HTTP UI plus exportable artifacts. This page describes the moving parts and how a single tool call travels end-to-end through the system. ## Component Layout mcptail is organized as a CLI front-end that dispatches to one of several subsystems: - **CLI entry (`src/cli.ts`)** — registers `init`, `remove`, `doctor`, `clear`, `export`, `test`, and the implicit `proxy` mode that wraps a child server. Source: [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts). - **Proxy (`src/proxy.ts`, `src/taps.ts`)** — the core: it spawns (or attaches to) the upstream MCP server, splices its stdio through a framing layer, and emits a stream of normalized events. `taps.ts` defines the transport-specific behavior (stdio in v0.1, Streamable HTTP/SSE planned). Source: [src/proxy.ts](https://github.com/Neal006/mcptail/blob/main/src/proxy.ts). - **Frame parser (`src/frames.ts`)** — converts raw bytes into newline-delimited JSON-RPC frames, the smallest unit of the pipeline. Source: [src/frames.ts](https://github.com/Neal006/mcptail/blob/main/src/frames.ts). - **Session store (`src/store.ts`)** — `SessionWriter` writes one JSONL file per session under `~/.mcptail/sessions/`, with a planned size cap (issue #13) and pruning helpers (issue #12). Source: [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts). - **Cost engine (`src/cost.ts`, `src/pricing.json`)** — translates payload sizes into model-specific dollar estimates. Currently Claude-only (issue #9 asks for GPT and Gemini). Source: [src/cost.ts](https://github.com/Neal006/mcptail/blob/main/src/cost.ts). - **HTTP server (`src/server.ts`)** — read-only API serving session files for the React UI and offering download endpoints (e.g. `GET /api/export?format=har`, issue #14). Source: [src/server.ts](https://github.com/Neal006/mcptail/blob/main/src/server.ts). - **Adapters (`src/adapters/*.ts`)** — translate each host client's MCP config file format (`cursor.ts`, the planned `windsurf.ts` per issue #6, more via `index.ts`). Source: [src/adapters/index.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/index.ts). - **Replay / export (`src/replay.ts`, `src/export.ts`)** — re-drive a recorded call against a server for testing (issue #20) and convert sessions to alternate formats such as HAR (issue #14). Source: [src/replay.ts](https://github.com/Neal006/mcptail/blob/main/src/replay.ts). ## End-to-End Data Pipeline The pipeline is best read as five stages: **capture → frame → correlate → persist → serve/export**. The diagram below summarizes the runtime path for a single tool call invoked from an MCP-aware editor. ```mermaid flowchart LR A[MCP client
Cursor / Windsurf] -->|stdio JSON-RPC| B[mcptail proxy
src/proxy.ts] B --> C[Frame parser
src/frames.ts] C --> D[Correlator
matches id to response] D --> E[SessionWriter
src/store.ts] E --> F[(~/.mcptail/sessions/*.jsonl)] F --> G[HTTP server
src/server.ts] G --> H[React UI
ui/src/app.tsx] F --> I[Exporters
src/export.ts] D --> J[Cost engine
src/cost.ts] I --> K[HAR / OTel / test spec] ``` Capture starts when `mcptail init` rewrites the client's config to point at the proxy instead of the upstream server directly; the original command is preserved so the proxy can spawn the real server on first use. The proxy then owns both ends of the child's stdio. Source: [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts) and [src/proxy.ts](https://github.com/Neal006/mcptail/blob/main/src/proxy.ts). Frames arriving from either direction are normalized by `src/frames.ts`, which keeps the rest of the pipeline transport-agnostic. This is the same layer the planned Streamable HTTP/SSE tap (issue #18) will plug into, so the correlator and storage paths do not change when remote transports are added. The correlator joins outbound requests with their inbound responses using the JSON-RPC `id` and timestamps them, producing `Call` records that the UI can sort and filter (issues #10, #15). Correlator output is also the input to the cost engine, which reads `src/pricing.json` and annotates each call with an estimated input cost. Source: [src/frames.ts](https://github.com/Neal006/mcptail/blob/main/src/frames.ts) and [src/cost.ts](https://github.com/Neal006/mcptail/blob/main/src/cost.ts). Persistence is append-only JSONL (`SessionWriter` in `src/store.ts`), one file per session, which makes rotation (issue #13), pruning (`mcptail clear`, issue #12), and batch export (issue #19) straightforward — OTel exporters and the planned `mcptail export --otlp` both read from the same on-disk format rather than from the live proxy. Source: [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts). Serving and exporting share the same source of truth: `src/server.ts` exposes the JSONL files over HTTP, while `src/export.ts` converts them into portable artifacts such as HAR (issue #14). The planned OpenTelemetry exporter (issue #19) and regression-test exporter (issue #20) are additional readers over the same files, reusing `src/replay.ts` for the test-generation path. ## Design Conventions and Extensibility A few rules show up across modules and are worth knowing when contributing: - **Degrade-to-pipe philosophy.** If recording fails — disk full, file too large (issue #13), JSON parse error — the proxy logs a single stderr warning and continues forwarding bytes. `SessionWriter` and the frame parser both follow this rule. Source: [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts). - **One adapter per host client.** New editors plug in by adding `src/adapters/.ts` that round-trips the host's MCP config JSON, then registering it in `src/adapters/index.ts`. The Windsurf adapter (issue #6) is a ~15-line copy of `cursor.ts`. Source: [src/adapters/cursor.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/cursor.ts). - **Pure diff helpers over `correlate()` output.** Cross-cutting features like session diffing (issue #21) consume the same normalized `Call` objects the UI uses, so they can be tested without a live proxy. Source: [src/proxy.ts](https://github.com/Neal006/mcptail/blob/main/src/proxy.ts). - **Pricing as data.** Model costs live in `src/pricing.json`, not in code, so adding GPT or Gemini (issue #9) is a JSON edit plus a link to the provider's pricing page. Source: [src/pricing.json](https://github.com/Neal006/mcptail/blob/main/src/pricing.json). These conventions keep the boundary between the always-on capture path and the optional analysis/export path clean: the proxy stays a fast pipe, while richer features (UI filters, HAR, OTel, regression tests) are layered on top of stable on-disk artifacts. --- ## Client Adapters and Configuration Management ### Related Pages Related topics: [Introduction and Quickstart](#page-overview), [System Architecture and Data Pipeline](#page-architecture)
Related Source Files The following source files were used to generate this page: - [src/adapters/index.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/index.ts) - [src/adapters/types.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/types.ts) - [src/adapters/claude-code.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/claude-code.ts) - [src/adapters/cursor.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/cursor.ts) - [src/adapters/vscode.ts](https://github.com/Neal006/mcptail/blob/main/src/adapters/vscode.ts) - [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts) - [tests/taps.test.ts](https://github.com/Neal006/mcptail/blob/main/tests/taps.test.ts)
# Client Adapters and Configuration Management ## Purpose and Scope mcptail integrates with multiple Model Context Protocol (MCP) clients, each of which stores its MCP server list in a different file format at a different path. The adapters subsystem isolates those client-specific details behind a small, uniform interface so that the rest of the codebase (proxying, recording, UI, exports) stays host-agnostic. The current release ships with three built-in adapters — `claude-code`, `cursor`, and `vscode` — and the community backlog tracks additional clients such as Windsurf. Every adapter is responsible for three operations: locating the client's config file on disk, rewriting its `mcpServers` entries so the client's stdio transport is rerouted through the local mcptail proxy, and round-tripping the original server definitions back into place on remove. Source: [src/adapters/index.ts:1-30]() Source: [src/adapters/types.ts:1-40]() ## Adapter Contract The shared `Adapter` interface in `src/adapters/types.ts` defines the surface every adapter must implement. Its members are deliberately small: - `id` — a short stable identifier (e.g. `"claude-code"`, `"cursor"`, `"vscode"`) used on the CLI and in log output. - `configPath()` — returns the absolute path of the client's MCP config file, resolved against platform conventions such as `~/.claude/`, `~/.cursor/`, or the VS Code user directory. - `apply(servers, options)` — rewrites a list of MCP server entries so each entry's `command`/`args` is wrapped in a mcptail invocation while preserving the original arguments and environment. - `remove(servers)` — the inverse of `apply`; restores the original command list when mcptail is detached from a client. - `doctor()` — runs lightweight diagnostics and returns per-server status suitable for the `mcptail doctor` command. `apply` and `remove` are kept symmetric so the same fixture can be round-tripped in tests without state drift, and so any future "diff two configurations" feature (raised in community discussion) can reuse the pair directly. Source: [src/adapters/types.ts:1-60]() Source: [src/adapters/index.ts:1-30]() ## Built-in Adapters and CLI Integration Three adapters ship with v0.1. Each module is intentionally small — typically under 50 lines — because the heavy lifting (proxying, recording, correlation, exports) lives in `src/proxy.ts` and `src/store.ts` and not in the adapter layer. | Adapter | Config file | Notes | | --- | --- | --- | | `claude-code` | `~/.claude/mcp_servers.json` | Reference implementation; the canonical example. | | `cursor` | `~/.cursor/mcp.json` | Mirrors `claude-code`'s structure; tracked as the template for new adapters. | | `vscode` | VS Code user-config MCP entry | Uses VS Code's nested server schema. | The CLI does not import each adapter by name. Instead, `src/adapters/index.ts` exports a `registry` object keyed by adapter id; `src/cli.ts` resolves a `--client` flag against that registry to dispatch `init`, `remove`, and `doctor`. The `init` flow reads the current file via the chosen adapter's `configPath()`, runs `apply()` against every `mcpServers` entry the user confirms, and writes the result back atomically. `remove` performs the inverse. `doctor` reports the result of the `apply`/`remove` round-trip plus proxy reachability. The same fixtures used by `tests/taps.test.ts` exercise this path so the CLI behavior stays aligned with the adapter contract. The Windsurf adapter is a planned addition that follows the same shape as `cursor.ts` and reads `~/.codeium/windsurf/mcp_config.json` under `mcpServers`; this work is tracked in the community backlog (issue #6) along with the accompanying fixture test. Source: [src/adapters/claude-code.ts:1-50]() Source: [src/adapters/cursor.ts:1-50]() Source: [src/adapters/vscode.ts:1-50]() Source: [src/cli.ts:1-120]() Source: [tests/taps.test.ts:1-40]() ## Adding a New Adapter The community-documented recipe for adding a new client (issue #6, Windsurf) is: 1. Create `src/adapters/.ts` exporting an `Adapter` that satisfies `src/adapters/types.ts`. The body can start as a copy of `cursor.ts` and adjust only `id`, `configPath()`, and any client-specific field names — the documented Windsurf copy is expected to be roughly 15 lines. 2. Register the adapter in `src/adapters/index.ts` so `--client ` resolves through the registry. 3. Add a fixture round-trip test in `tests/taps.test.ts` that runs `apply` then `remove` against a sample config and asserts the original payload is restored byte-for-byte. 4. Verify `mcptail init`, `mcptail remove`, and `mcptail doctor` all pass against the new fixture in CI. Because the adapter layer is deliberately thin, no changes are required in the proxy, store, or UI packages to support a new client — only the four steps above. This keeps the addition cost predictable and lets the project absorb new MCP hosts without expanding the surface area of the core recorder. Source: [src/adapters/index.ts:1-30]() Source: [src/adapters/types.ts:1-60]() Source: [src/adapters/cursor.ts:1-50]() Source: [src/cli.ts:1-120]() Source: [tests/taps.test.ts:1-40]() --- ## Dashboard, Replay, and Common Operations ### Related Pages Related topics: [Introduction and Quickstart](#page-overview), [System Architecture and Data Pipeline](#page-architecture)
Related Source Files The following source files were used to generate this page: - [src/server.ts](https://github.com/Neal006/mcptail/blob/main/src/server.ts) - [src/replay.ts](https://github.com/Neal006/mcptail/blob/main/src/replay.ts) - [src/cli.ts](https://github.com/Neal006/mcptail/blob/main/src/cli.ts) - [src/store.ts](https://github.com/Neal006/mcptail/blob/main/src/store.ts) - [src/export.ts](https://github.com/Neal006/mcptail/blob/main/src/export.ts) - [ui/src/app.tsx](https://github.com/Neal006/mcptail/blob/main/ui/src/app.tsx) - [ui/src/api.ts](https://github.com/Neal006/mcptail/blob/main/ui/src/api.ts) - [ui/src/main.tsx](https://github.com/Neal006/mcptail/blob/main/ui/src/main.tsx) - [ui/src/style.css](https://github.com/Neal006/mcptail/blob/main/ui/src/style.css) - [src/pricing.json](https://github.com/Neal006/mcptail/blob/main/src/pricing.json)
# Dashboard, Replay, and Common Operations mcptail ships with a small web dashboard for inspecting captured MCP traffic, a replay engine for re-driving recorded JSON-RPC calls against a server, and a CLI surface for day-to-day operations such as `init`, `doctor`, `remove`, `test`, and `clear`. Together these three pieces form the operator-facing side of the project — the proxy records, the dashboard visualises, and the CLI/replay layer lets users replay or clean up. ## Dashboard The dashboard is a React app served by the local mcptail server. `ui/src/main.tsx` mounts the root component, and `ui/src/app.tsx` renders the timeline table that lists captured calls with their method/tool, latency, and status dot. Each row links to a detail view of the request and response bodies. `ui/src/api.ts` wraps fetch calls against the JSON endpoints exposed by the HTTP server in `src/server.ts`, so the UI speaks the same protocol the CLI uses. ```text Browser (ui/src/app.tsx) │ HTTP ▼ src/server.ts ──► session files on disk ▲ │ same JSON shape mcptail CLI (src/cli.ts) ``` The dashboard's current palette is dark-only (`ui/src/style.css`), and feature parity gaps are tracked in upstream issues: keyboard navigation (j/k + Enter) in #15, a light theme toggle in #11, and live substring search plus an errors-only toggle in #10. A planned download button behind `GET /api/export?file=…&format=har` (issue #14) will surface a HAR export route handled by `src/export.ts`. ## Replay Replay lives in `src/replay.ts` and consumes the same JSONL session files the proxy writes. It is the backbone of the planned "export a captured call as a regression test" workflow in issue #20: a captured call can be frozen into a YAML spec (server command, request, expected response matcher) and later run via `mcptail test spec.yaml` in CI. Replay is also the foundation for the session-diffing idea in issue #21, which proposes a pure diff helper over two `correlate()` outputs, aligned by method + tool, surfacing response diffs and latency deltas across runs. ```yaml # planned spec shape (issue #20) server: { command: ["npx", "@modelcontextprotocol/server-filesystem"] } request: { method: "tools/call", params: { name: "read_file", arguments: … } } expect: { matcher: { path: "result", equals: … } } ``` Because replay operates on already-correlated JSON-RPC pairs, it does not need to know anything about the underlying transport; this is the same decoupling that lets stdio-only v0.1 (issue #18 notes the gap for Streamable HTTP / SSE) defer remote-transport support without rewriting the recorder. ## Common CLI operations The command surface in `src/cli.ts` covers the lifecycle of an mcptail installation: - `init` — registers the proxy against an editor adapter (Cursor, Claude Code, Windsurf per issue #6, etc.) so the IDE launches MCP servers through mcptail. - `remove` — undoes `init` for the same adapter. - `doctor` — sanity-checks that the adapter's tap still points at mcptail and that `~/.mcptail/sessions/` is writable. - `test ` — runs a replay spec (see Replay above). - `clear` — prunes recorded sessions; per issue #12 this should support `mcptail clear` (delete all) and `mcptail clear --older-than 7d`, printing a summary like `removed 12 sessions, 3.2 MB`. The helper backing these flags is in `src/store.ts`. `src/store.ts` also owns the `SessionWriter` used by the proxy. Issue #13 proposes a per-session size cap (default ~50 MB, env-overridable) so a chatty server cannot grow a session file unbounded; when the cap is hit, `SessionWriter` should stop recording with a single stderr warning and continue piping traffic — the same degrade-to-pipe philosophy the rest of the proxy follows. ## Pricing context for replayed payloads Replayed payloads are still useful as input-context cost signals regardless of which model the user drives, so `src/pricing.json` is the single source of truth for $/MTok numbers shown next to each captured call. v0.1 lists Claude entries; issue #9 asks for OpenAI and Gemini input prices to be added alphabetically, with links to each provider's pricing page in the same PR. Keeping the file provider-agnostic lets the dashboard and `export` paths stay model-independent. ## Known gaps and community requests A bounded list of operator-facing work that the community has already filed: - Streamable HTTP / SSE capture (#18) — v0.1 taps stdio only; a reverse-proxy mode is the proposed extension. - OpenTelemetry exporter (#19) — batch-export correlated calls as OTel spans via `mcptail export --otlp `. - Session size cap (#13), session prune `clear` (#12), HAR export (#14), session diffing (#21), regression-test export (#20), README translations (#16, #17), UI keyboard nav (#15), UI light theme (#11), UI search/filter (#10), Windsurf adapter (#6), and broader pricing coverage (#9). These together describe the next operator-visible layer of mcptail beyond recording: search, diff, export, prune, and replay-as-test. --- --- ## Pitfall Log Project: Neal006/mcptail Summary: Found 30 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/20 ## 2. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/13 ## 3. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | https://github.com/Neal006/mcptail ## 4. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: Adapter: Cline - User impact: Developers may misconfigure credentials, environment, or host setup: Adapter: Cline - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/8 ## 5. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: Adapter: Windsurf - User impact: Developers may misconfigure credentials, environment, or host setup: Adapter: Windsurf - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/6 ## 6. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: Adapter: Zed - User impact: Developers may misconfigure credentials, environment, or host setup: Adapter: Zed - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/7 ## 7. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this configuration risk before relying on the project: Streamable HTTP / SSE transport capture - User impact: Developers may misconfigure credentials, environment, or host setup: Streamable HTTP / SSE transport capture - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/18 ## 8. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | https://github.com/Neal006/mcptail ## 9. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/11 ## 10. Runtime risk - Runtime risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a runtime risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/10 ## 11. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: Add GPT and Gemini input prices to pricing.json - User impact: Developers may hit a documented source-backed failure mode: Add GPT and Gemini input prices to pricing.json - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/9 ## 12. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: Session diffing — compare two runs of the same server - User impact: Developers may hit a documented source-backed failure mode: Session diffing — compare two runs of the same server - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/21 ## 13. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: mcptail clear — prune recorded sessions - User impact: Developers may hit a documented source-backed failure mode: mcptail clear — prune recorded sessions - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/12 ## 14. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/21 ## 15. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/Neal006/mcptail ## 16. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | https://github.com/Neal006/mcptail ## 17. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | https://github.com/Neal006/mcptail ## 18. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/19 ## 19. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/Neal006/mcptail/issues/18 ## 20. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: Export a captured call as a regression test - User impact: Developers may hit a documented source-backed failure mode: Export a captured call as a regression test - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/20 ## 21. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: Session log rotation: cap per-session file size - User impact: Developers may hit a documented source-backed failure mode: Session log rotation: cap per-session file size - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/13 ## 22. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: UI: keyboard navigation (j/k + enter) in the timeline - User impact: Developers may hit a documented source-backed failure mode: UI: keyboard navigation (j/k + enter) in the timeline - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/15 ## 23. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: UI: light theme - User impact: Developers may hit a documented source-backed failure mode: UI: light theme - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/11 ## 24. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: UI: search / filter in the timeline - User impact: Developers may hit a documented source-backed failure mode: UI: search / filter in the timeline - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/10 ## 25. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this conceptual risk before relying on the project: README translation: हिन्दी (hi) - User impact: Developers may hit a documented source-backed failure mode: README translation: हिन्दी (hi) - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/17 ## 26. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Project evidence flags a capability evidence risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/16 ## 27. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: Export a session as HAR - User impact: Developers may hit a documented source-backed failure mode: Export a session as HAR - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/14 ## 28. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: OpenTelemetry exporter - User impact: Developers may hit a documented source-backed failure mode: OpenTelemetry exporter - Evidence: failure_mode_cluster:github_issue | https://github.com/Neal006/mcptail/issues/19 ## 29. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/Neal006/mcptail ## 30. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | https://github.com/Neal006/mcptail