pi Tor MCP Proxy Extension

Wraps the Tor MCP TypeScript v3.0 project (author: YogSotho) into a pi coding-agent extension that runs inside the pi TUI.

It exposes anonymous-network access to both the human operator (slash commands) and the agent itself (LLM-callable tools): fetch .onion pages, search deep-web indexes, and renew Tor circuits — all routed through a managed tor process with SOCKS5 circuit isolation, JA3 spoofing, User-Agent rotation, and per-IP rate limiting.

Features

• ✅ Spawns and supervises a hardened tor process (--Sandbox, --SafeSocks, --Isolate*, --ExitPolicy reject *:*)
• ✅ SOCKS5 proxy via socks-proxy-agent for all outbound fetches
• ✅ JA3 fingerprint spoofing via controlled TLS cipher suites
• ✅ Circuit isolation (per-request NEWNYM available on demand)
• ✅ Self-healing Tor (auto-restart on health-check failure, up to 5 attempts)
• ✅ Per-IP rate limiting (20 req / 60s) via rate-limiter-flexible
• ✅ User-Agent rotation across 8 real browser fingerprints
• ✅ Header sanitization (DNT, Sec-Fetch-*, etc.)
• ✅ Deep-web search engines: Ahmia, Torch, OnionCity
• ✅ Audit logging with rotation (Winston, ~/.pi/logs/tor-mcp/tor_mcp_proxy.log)
• ✅ TypeScript for type safety

Installation

Prerequisites

• Node.js 18+
• The tor binary on PATH:
  • Debian/Ubuntu: sudo apt install tor
  • macOS: brew install tor
  • Arch: sudo pacman -S tor
• pi coding agent (@earendil-works/pi-coding-agent)

Build

cd pi-tor-mcp-extension
npm install
npm run build      # outputs dist/
npm run typecheck  # optional: tsc --noEmit

Load the extension

# Standalone single-file load
pi -e ./pi-tor-mcp-extension/dist/index.js

# Or copy into your extension directory and pi picks it up automatically.

The first time the extension loads it auto-spawns tor; the agent remains usable even if Tor fails to start — run /tor start once you've installed the binary.

Slash commands

| Command | Description | | ------------------------------------------ | ---------------------------------------------- | | /tor fetch <url> | Fetch a URL through Tor | | /tor search <query> [ahmia|torch|onioncity] | Search the deep web | | /tor circuit | Renew the Tor circuit (SIGNAL NEWNYM) | | /tor health | Show Tor status, PID, ports, uptime | | /tor stats | Show proxy statistics | | /tor start / /tor stop | Manually control the Tor process | | /tor (no args) | Help | | /torfetch <url> | Quick fetch shortcut | | /torsearch <query> [engine] | Quick search shortcut |

Examples:

/tor fetch http://check.torproject.org
/tor search "leaked credentials" ahmia
/tor circuit
/tor health

LLM-callable tools

The agent can call these directly without you running a slash command:

tor_fetch

Fetch a URL through Tor.

| Parameter | Type | Required | Default | Notes | | ------------- | ------ | -------- | ------- | --------------------------------------------------------- | | url | string | yes | — | Full URL; http:// is prepended if scheme is missing | | timeout_ms | number | no | 45000 | Per-request timeout in milliseconds |

Returns the HTTP status, elapsed ms, size, and a truncated HTML/markdown body (full body is written to a /tmp/pi_tor_fetch_*.txt file when truncated).

tor_search

Search deep-web indexes.

| Parameter | Type | Required | Default | Notes | | --------- | ----------------------------------- | -------- | -------- | ------------------------------ | | query | string | yes | — | Search query | | engine | ahmia | torch | onioncity | no | ahmia | Which index to query |

Returns the raw HTML of the search results page (the model is expected to strip boilerplate before citing) plus HTTP metadata.

Repository layout

pi-tor-mcp-extension/
├── package.json
├── tsconfig.json
├── README.md
└── src/
    ├── index.ts          # Extension entry point (default export factory)
    ├── types.ts          # Type definitions
    ├── logger.ts         # Winston logger (file + console, with rotation)
    ├── rate-limiter.ts   # Per-IP rate limiting
    ├── tor-manager.ts    # Tor process lifecycle, health checks, NEWNYM
    ├── proxy-client.ts   # fetchWithTor() + searchDeepWeb() w/ JA3 spoofing
    ├── commands.ts       # Slash commands: /tor, /torfetch, /torsearch
    └── tor-tool.ts       # LLM tools: tor_fetch, tor_search

Configuration

All knobs are constants in the relevant module for now:

• Tor ports, data dir, restart attempts → src/tor-manager.ts (DEFAULT_CONFIG)
• Rate limit window / max requests / burst → src/rate-limiter.ts (DEFAULT_CONFIG)
• User-Agent pool, cipher suites → src/proxy-client.ts
• Max response size (in-LLM-context vs. saved-to-disk) → src/tor-tool.ts (MAX_CONTENT_BYTES)

Future work could expose a pi.registerFlag() + JSON config file, but the current values match the original v3.0 project.

Logging

• File: ~/.pi/logs/tor-mcp/tor_mcp_proxy.log (Winston, 50 MB rotation, 5 files)
• Console: [info] … lines via the same logger

Caveats & honest scope

• Tor binary required. The extension spawns tor itself but does not ship it. If tor is missing the auto-start logs a warning and the agent continues; run /tor start after installing.
• No SOCKS auth. The control-port auth is the default empty cookie / no-password flow; fine for single-user local installs, not appropriate for shared hosts.
• --Sandbox requires Linux + recent Tor. On macOS / older Tor the sandbox flag may fail to start; remove from tor-manager.ts if your platform rejects it.
• Search results are raw HTML. The agent must strip template chrome before citing; we deliberately don't bake a fragile per-engine parser into the extension.
• Exit policy is reject *:*. This is a client-only Tor (no relay), which is what you want for anonymity use; if you're trying to be an exit, change the policy in tor-manager.ts.

Disclaimer

For authorised security research, privacy-preserving research, and accessing sites you have a right to access. Don't use this to break the law in your jurisdiction. Tor itself is a tool; how you use it is on you.

Author

YogSotho — pi extension port of the original MCP Tor Proxy v3.0 TypeScript project.