mcp-wiretap 0.1.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: Bug Report
+about: Report a bug in mcp-wiretap
+title: ""
+labels: bug
+assignees: ""
+---
+
+**Describe the bug**
+
+[What happened]
+
+**MCP server being wrapped**
+
+[e.g., @modelcontextprotocol/server-filesystem]
+
+**MCP client**
+
+[e.g., Claude Desktop, Cursor, Claude Code]
+
+**Expected behavior**
+
+[What you expected]
+
+**Steps to reproduce**
+
+1.
+2.
+3.
+
+**Environment**
+
+- OS: [e.g., macOS 14.5]
+- Node: [e.g., 20.11.0]
+- mcp-wiretap version: [e.g., 0.1.0]

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest a feature for mcp-wiretap
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+**What problem does this solve?**
+
+[Description]
+
+**Proposed solution**
+
+[How you'd like it to work]
+
+**Alternatives considered**
+
+[Other approaches]

package/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - run: npm ci
+      - run: npm run build

package/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+
+      - run: npm ci
+      - run: npm run build
+
+      - run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Transparent stdio proxy for any MCP server
+- JSON-RPC message parsing with request/response correlation
+- SQLite logging with session management
+- Real-time color-coded terminal display (compact + verbose modes)
+- Latency calculation by matching request/response IDs
+- JSON and CSV export
+- Session list, replay, and search
+- Works via `npx mcp-wiretap` with zero install
+- Drop-in wrapper for Claude Desktop, Cursor, and Claude Code configs

package/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing to mcp-wiretap
+
+1. Fork the repo
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Make your changes
+4. Run the build: `npm run build`
+5. Submit a PR
+
+Please open an issue before starting major work so we can discuss the approach.
+
+## Development
+
+```bash
+git clone https://github.com/dantrapp/mcp-wiretap.git
+cd mcp-wiretap
+npm install
+npm run build
+```
+
+## Commit Messages
+
+Use conventional commits: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trapp 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# mcp-wiretap
+
+> See everything your AI agents do through MCP. One command. Zero config.
+
+<!-- TODO: Add demo GIF recorded with vhs or asciinema -->
+
+## Quick Start
+
+```bash
+npx mcp-wiretap -- npx -y @modelcontextprotocol/server-filesystem ~/Code
+```
+
+That's it. Every MCP tool call is now logged to SQLite and displayed in your terminal.
+
+## Why
+
+MCP servers can read files, query databases, and execute code on your behalf. But you can't see what they're actually doing.
+
+mcp-wiretap wraps any MCP server and records every tool call — what was requested, what was returned, and how long it took. No SDK integration. No platform to adopt. Just wrap and watch.
+
+## Use with Claude Desktop
+
+Replace your existing MCP server config:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-wiretap", "--",
+        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Code"
+      ]
+    }
+  }
+}
+```
+
+Now every tool call Claude Desktop makes through this server is logged.
+
+## Use with Cursor
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y", "mcp-wiretap", "--",
+        "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Code"
+      ]
+    }
+  }
+}
+```
+
+## Use with Claude Code
+
+```bash
+claude mcp add filesystem -- npx -y mcp-wiretap -- npx -y @modelcontextprotocol/server-filesystem ~/Code
+```
+
+## Terminal Output
+
+```
+14:23:01.442 ──▶ initialize
+14:23:01.458 ◀── initialize                           16ms
+14:23:01.460 ──▶ tools/list
+14:23:01.463 ◀── tools/list              (12 tools)    3ms
+14:23:05.891 ──▶ tools/call   read_file  {"path":"/Users/me/Code/README.md"}
+14:23:05.903 ◀── tools/call   read_file  (2,847 bytes) 12ms
+```
+
+Use `--verbose` to see full payloads.
+
+## Export & Search
+
+```bash
+# Export current session to JSON
+npx mcp-wiretap export --format json --output audit.json
+
+# Export all sessions to CSV
+npx mcp-wiretap export --format csv --all --output audit.csv
+
+# List all recorded sessions
+npx mcp-wiretap sessions
+
+# Replay a specific session
+npx mcp-wiretap replay <session-id>
+
+# Search across all sessions
+npx mcp-wiretap search "read_file"
+```
+
+## How It Works
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  MCP Client  │────▶│  mcp-wiretap │────▶│  MCP Server  │
+│ (Claude, etc)│◀────│  (proxy)     │◀────│  (any)       │
+└──────────────┘     └──────┬───────┘     └──────────────┘
+                            │
+                     ┌──────▼───────┐
+                     │   SQLite DB  │
+                     │   + Terminal │
+                     │     Output   │
+                     └──────────────┘
+```
+
+mcp-wiretap spawns your MCP server as a child process, intercepts all JSON-RPC messages on stdin/stdout, logs them to SQLite with timestamps and latency, and forwards everything unmodified. Neither the client nor the server knows it's there.
+
+All display output goes to stderr. stdout is reserved exclusively for the MCP protocol.
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--db <path>` | SQLite database location | `~/.mcp-wiretap/wiretap.db` |
+| `--quiet` | Suppress terminal output, log only | `false` |
+| `--verbose` | Show full payloads in terminal | `false` |
+| `--filter <method>` | Only display specific methods | all |
+| `--max-payload <bytes>` | Truncate payloads in display | unlimited |
+| `--no-color` | Disable color output | `false` |
+
+## Comparison
+
+| Tool | Type | Setup | Cost |
+|------|------|-------|------|
+| **mcp-wiretap** | Passive CLI monitor | One command | Free |
+| MCP Inspector | Interactive debugger | Manual testing | Free |
+| Datadog MCP | Enterprise SaaS | SDK + account | $$$ |
+| Gateways (Composio, etc.) | Platform | Architecture change | Varies |
+
+## SQLite Schema
+
+Events are stored at `~/.mcp-wiretap/wiretap.db`. You can query them directly:
+
+```sql
+SELECT timestamp, direction, method, tool_name, latency_ms
+FROM events
+WHERE session_id = 'your-session-id'
+ORDER BY timestamp;
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT