{"id":"e380d43b-05cc-4382-bcc3-c7b6a5724f12","slug":"veritymcp","kind":"mcp","name":"VerityMCP","summary":"Connect ChatGPT Web Chat directly to your local computer. Verified file editing, terminal execution, Playwright browser automation, and desktop control via Model Context Protocol (MCP).","owner":"tanishqbaweja","repoUrl":"https://github.com/tanishqbaweja/VerityMCP","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-10-04T23:36:47.000Z","addedAt":"2026-10-21T06:53:55.377Z","logoUrl":"https://avatars.githubusercontent.com/u/74068132?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["browser-web","memory-knowledge","files-documents"],"tags":["ai-agent","autonomous-agent","browser-automation","chatgpt","chatgpt-web","coding-agent","developer-tools","local-computer"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-27T01:48:51.950Z","sample":false,"url":"https://conduits.dev/tools/veritymcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"verity-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# VerityMCP: Connect ChatGPT Web Directly to Your Local Computer\n\n[![MCP Protocol](https://img.shields.io/badge/MCP-Streamable%20HTTP%20%2B%20SSE-blue.svg)](https://modelcontextprotocol.io)\n[![Client Support](https://img.shields.io/badge/Client-ChatGPT%20Web-green.svg)](https://chatgpt.com)\n[![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-orange.svg)](https://nodejs.org)\n[![Tools](https://img.shields.io/badge/Tools-65%20Verified%20Tools-purple.svg)](#complete-65-tool-reference)\n[![License](https://img.shields.io/badge/License-MIT-brightgreen.svg)](LICENSE)\n[![M8ven Score](https://m8ven.ai/badge/mcp/tanishqbaweja-veritymcp-j1l1jm)](https://m8ven.ai/mcp/tanishqbaweja-veritymcp-j1l1jm?s=readme)\n\n> **Connect ChatGPT Web Chat directly to your local computer.**  \n> Execute terminal commands, edit local files, automate Playwright browsers, inspect desktop windows, and run tests—backed by an ironclad **Verification Engine** that guarantees ChatGPT never hallucinates a successful action.\n\n---\n\n## ⚡ Quickstart: Install and Connect ChatGPT Web\n\nGive ChatGPT Web hands-on terminal, code editing, and browser automation capabilities on your local computer.\n\n### Step 0: Install Dependencies (First Run Only)\n\nClone this repository and enter its directory. VerityMCP needs **Node.js 20 or newer**.\nThe setup scripts check prerequisites, install missing Node.js/pnpm/Git/cloudflared where supported,\ninstall dependencies from `pnpm-lock.yaml`, download Playwright Chromium, and build the app.\nDepending on your OS, installing system prerequisites may prompt for administrator permission.\n\n**Windows:** Double-click `setup.bat` or use PowerShell:\n\n```powershell\n.\\setup.bat\n# Or run the PowerShell script directly:\npowershell -NoProfile -ExecutionPolicy Bypass -File .\\setup.ps1\n```\n\n**macOS / Linux:**\n\n```bash\nbash ./setup.sh\n```\n\nTo check prerequisites without installing anything, run `setup.bat -CheckOnly` on Windows or\n`bash ./setup.sh --check` on macOS/Linux. For local-only use, skip the Cloudflare dependency\nwith `-SkipCloudflared` (Windows) or `--skip-cloudflared` (macOS/Linux). You can skip\nChromium with `-SkipBrowser` / `--skip-browser`, but browser automation may not work.\nIf a Linux distribution's Node.js package is older than 20, install a supported version\nfrom [Node.js](https://nodejs.org/) and rerun setup.\n\n**Windows troubleshooting: `\"node\" is not recognized` while running `pnpm.cmd`:** This\nusually means Node.js was installed but the current terminal cannot find it. Close the\ninstaller, open a new Command Prompt, and run `node --version` and `pnpm --version`.\nIf Node.js is still missing, run `winget install --id OpenJS.NodeJS.LTS --exact`, then\nopen a new terminal and run `setup.bat` again. The setup script now checks that CMD can\nrun Node.js before attempting pnpm, and fixes the session PATH when possible.\n\n### Step 1: Launch VerityMCP\nDouble-click `start.bat` on Windows (or run `pnpm start` on macOS/Linux):\n\n```cmd\nstart.bat\n```\n\n```text\n==========================================================\n    VERITY MCP (Verified Local Computer Engineering Layer)    \n==========================================================\n[Launcher] Starting Cloudflare tunnel on port 7980...\n\n==========================================================\n                 CONNECTION READY!                        \n==========================================================\n  MCP Server URL:   https://neat-agent-tunnel.trycloudflare.com/mcp (COPIED TO CLIPBOARD)\n  Owner Token:      <YOUR-GENERATED-OWNER-TOKEN>\n==========================================================\n```\n> On Windows, the secure Cloudflare tunnel URL is **automatically copied to your clipboard**.\n\n**macOS/Linux:** `pnpm start` starts a local server but does not create a remote tunnel.\nRun `cloudflared tunnel --url http://127.0.0.1:7980` in one terminal, then start the\nserver in another with `VERITY_PUBLIC_BASE_URL=https://YOUR-TUNNEL.trycloudflare.com pnpm start`\n(substitute the URL Cloudflare printed). Connect to that HTTPS URL with `/mcp` appended.\nIf the Linux installer placed cloudflared in `~/.local/bin`, ensure that folder is on your PATH.\n\n### Step 2: Add to ChatGPT Web\n1. Open [ChatGPT](https://chatgpt.com) in your browser.\n2. Go to **Settings** → **Connected Apps** (or **Developer Settings** → **MCP Servers**).\n3. Click **Add Server**:\n   - **Name**: `Local PC (VerityMCP)`\n   - **URL**: Paste the clipboard URL (e.g. `https://neat-agent-tunnel.trycloudflare.com/mcp`)\n   - **Authorization**: Enter your `Owner Token` from the terminal window.\n4. Click **Save & Connect**.\n\n### Step 3: Tell ChatGPT What to Do!\nAsk ChatGPT anything in your chat:\n> *\"Inspect my current project directory, fix the broken login unit test, run `pnpm test`, and capture a browser screenshot of the web app running on localhost:3000 to verify the fix.\"*\n\nChatGPT now interacts with your real local environment in real time, with mathematical proof that every command and file write succeeded.\n\n---\n\n## 🔍 Why Normal MCP Servers Fail (And How VerityMCP Solves It)\n\nStandard MCP servers provide naive wrappers around `fs.writeFile` or `child_process.exec`. When autonomous agents in ChatGPT use them, they constantly hallucinate success:\n\n```\n[ChatGPT asks to update file]\nNaive MCP Server: \"Success!\" ───► ChatGPT believes file was changed.\nReality: Hunks did not match, disk file unchanged, build fails later, agent gets stuck in a loop.\n```\n\n**VerityMCP is engineered around one primary design law:**\n> ### *\"AN AGENT MUST BE ABLE TO TRUST ITS TOOLS.\"*\n> A tool returning success when nothing happened is worse than a tool returning an error.\n\nVerityMCP enforces **mandatory pre- and post-condition verification** on every operation:\n\n| Failure in Standard MCP Servers | What Really Happens | How VerityMCP Solves It |\n| :--- | :--- | :--- |\n| **Silent Patch Failure** | Unified patches with offset hunks return \"Success\" without altering bytes on disk. | **SHA-256 Readback Assertion**: VerityMCP reads the raw bytes from disk post-mutation, computes SHA-256, and verifies exact equality. Atomically rolls back if mismatched. |\n| **Silent Terminal Output Loss** | Long-running processes drop stdout/stderr chunks due to unbuffered closures. | **Durable Chunk Ring Buffering**: Stdout and stderr are stored in persistent memory with monotonic sequence IDs and cursor pagination (`read_process_output`). |\n| **Windows Shell Crashes** | MCP servers hardcode `bash`, invoking unconfigured WSL and crashing with `execvpe failed`. | **Windows-First Shell Detection**: Probes PowerShell 7, Windows PowerShell 5.1, cmd.exe, and Git Bash. Provides clear fallback guides if Bash is unavailable. |\n| **Visual Blindness** | Reading `.png` / `.jpg` files returns plain text strings (`[Image file: logo.png]`). | **Direct MCP Image Content**: Automatically detects image extensions and returns both metadata AND native base64 `ImageContent` blocks so vision models can see. |\n| **Flaky Browser Automation** | Puppeteer/Playwright clicks pass without waiting for DOM hydration. | **Live DOM Readback**: Checks element visibility, fills inputs, and validates actual DOM property values (`inputValue`, `.isChecked()`) before responding. |\n\n---\n\n## 🏛️ Architecture\n\nVerityMCP acts as the secure, high-integrity bridge between ChatGPT and your local machine:\n\n```mermaid\nflowchart TD\n    subgraph Remote[\"OpenAI Cloud\"]\n        GPT[\"ChatGPT Web Chat (chatgpt.com)\"]\n    end\n\n    subgraph Transport[\"Secure Transport\"]\n        Tunnel[\"Cloudflare Secure Tunnel<br/>(HTTPS / WSS)\"]\n        LocalSSE[\"Local HTTP / SSE<br/>(127.0.0.1:7980)\"]\n    end\n\n    subgraph VerityCore[\"VerityMCP Execution Runtime\"]\n        Auth[\"RFC 9728 / 8414 OAuth & Bearer Guard\"]\n        Router[\"Streamable MCP Tool Router (65 Tools)\"]\n        \n        subgraph Subsystems[\"Verified Engines\"]\n            FS[\"Filesystem Engine<br/>Atomic Edit, Patch & Rollback\"]\n            Shell[\"Shell Runtime<br/>PowerShell, cmd, Git Bash, ConPTY\"]\n            Browser[\"Playwright Engine<br/>Stable Refs, Snapshots & Screenshots\"]\n            LSP[\"LSP & Symbol Engine<br/>AST Outline, Definition & Types\"]\n            Desk[\"Desktop Automation<br/>GDI Screenshots & Window Focus\"]\n        end\n\n        Engine[\"VERIFICATION ENGINE<br/>- SHA-256 Byte Readback<br/>- In-DOM Property Checks<br/>- Monotonic Cursor Pagination<br/>- Git Status & Diff Validation\"]\n    end\n\n    GPT -->|Secure HTTPS| Tunnel\n    Tunnel --> LocalSSE\n    LocalSSE --> Auth\n    Auth --> Router\n    Router --> Subsystems\n    Subsystems --> Engine\n    Engine -->|Verified Results + Base64 Visuals| Router\n```\n\n---\n\n## ⚡ Fast Agent Profile\n\nVerityMCP defaults to a **fast** tool profile. Common filesystem, shell, browser, Git, diagnostics, and durable-run tools are exposed directly so the model has a much smaller tool menu to reason over before its first action.\n\n- Specialist capabilities are not removed. Use `discover_tools` to find them and `invoke_tool` to execute them on demand.\n- Use `task_bootstrap` at the start of repository work when you need workspace, fresh Git status, optional relevant-code matches, managed processes, and recent activity together.\n- Set `VERITY_TOOL_PROFILE=full` to restore direct exposure of the complete legacy tool surface.\n- Tool calls default to compact response metadata to avoid repeating large structured payloads in model context. Pass `response_detail: \"full\"` on an individual call, or set `VERITY_RESPONSE_DETAIL=full`, when complete structured diagnostics are needed.\n- Verification remains enabled in both profiles; the optimization reduces schema/context overhead rather than skipping state checks.\n- For interactive ChatGPT agent work with VerityMCP, prefer **GPT-5.6 Sol** over GPT-6 Sol unless GPT-6 Sol is specifically required.\n\nAgents are instructed to make an early safe inspection/action call for clear tasks instead of spending a long planning phase before touching the machine.\n\n---\n\n## 🛠️ Complete Tool Reference\n\nVerityMCP exposes a unified, production-ready tool surface organized across 12 engineering domains:\n\n### 1. Workspace Onboarding & Repo Map\n- `open_workspace`: Opens a local directory or Git repo. In a single call, generates an architectural repo map, Git status/branch, package manifest scripts, detected shells, and discovered project skills.\n\n### 2. Verified Filesystem & Mutations\n- `read_file`: Reads files with line slicing (`line_start`, `line_end`) and SHA-256 hash. Returns direct base64 image blocks for visual formats (`.png`, `.jpg`, `.svg`, etc.).\n- `write_file`: Atomically writes file content with mandatory post-write byte readback and SHA-256 integrity check.\n- `edit_file`: Performs exact-string replacements with occurrence validation, unified diff output, and post-mutation hash checks.\n- `apply_patch`: Applies multi-file Codex or unified diffs with atomic staging, automatic rollback on mismatch, and post-write SHA-256 verification.\n- `delete_file`: Deletes files or directories with post-unlinking existence confirmation.\n- `move_file`: Renames or relocates files with source-removed and destination-verified checks.\n- `copy_file`: Duplicates files with byte-for-byte equality verification.\n- `list_directory`: Recursively lists directories with depth controls and `.gitignore` parsing.\n- `locate_files`: Fast file locator by glob pattern or filename substring.\n- `file_metadata`: Inspects file size, line counts, MIME types, timestamps, and SHA-256 hashes.\n\n### 3. Code Search & Structural Intelligence\n- `search_code`: Ultra-fast code search powered by native ripgrep with line numbers, regex, and file filtering.\n- `get_outline`: Extracts structural symbols (functions, classes, interfaces, methods, types) from code files without reading entire files.\n\n### 4. Language Server Protocol (LSP) Tools\n- `lsp_goto_definition`: Jump directly to the declaration location of a symbol.\n- `lsp_find_references`: Find all references to a symbol across the entire repository.\n- `lsp_hover`: Retrieve type signatures and docstrings at cursor position.\n- `lsp_document_symbols`: Extract document symbol hierarchies (`outline`, `normal`, `full`).\n- `lsp_workspace_symbols`: Project-wide symbol search by name query.\n- `lsp_type_definition`: Navigate directly to symbol type definitions.\n\n### 5. Jupyter Notebook Engine\n- `read_notebook`: Structurally parses `.ipynb` files into markdown, code cells, execution counts, and outputs.\n- `edit_notebook`: Atomically edits, replaces, inserts, or deletes notebook cells with schema integrity checks.\n\n### 6. Shell, Terminal & Process Runtime\n- `exec_command`: Executes commands in explicit shells (`powershell`, `cmd`, `git-bash`). Returns immediately if finished within `yield_ms`, or yields a durable process session ID.\n- `read_process_output`: Streams stdout/stderr chunks using cursor pagination without dropping output.\n- `write_stdin`: Interacts with running processes via stdin.\n- `interrupt_process`: Terminates process trees cleanly using native Windows `taskkill /F /T` or SIGINT.\n- `get_environment`: Deep audit of local developer toolchains (Node, pnpm, Python, uv, Git, Docker, shells).\n\n### 7. Playwright Browser Automation\n- `browser_navigate`: Navigates persistent browser session to a URL and verifies load status.\n- `browser_snapshot`: Builds an accessibility snapshot tree with stable element references (`[ref=e1]`), names, and roles.\n- `browser_click`: Clicks element by stable ref or CSS selector.\n- `browser_double_click`: Double clicks element.\n- `browser_hover`: Triggers hover state.\n- `browser_fill`: Types text into form fields with **live DOM `inputValue` readback verification**.\n- `browser_check`: Checks or unchecks checkboxes with **live DOM `.isChecked()` assertion**.\n- `browser_select_option`: Selects dropdown option by value or label.\n- `browser_upload_file`: Uploads local files to file input elements.\n- `browser_press_key`: Sends keystrokes (`Enter`, `Tab`, `Escape`, etc.).\n- `browser_evaluate`: Evaluates JavaScript inside page context safely.\n- `browser_pdf`: Prints current page to a disk PDF file.\n- `browser_screenshot`: Captures viewport or full page, verifies the disk file, and returns a direct base64 `ImageContent` block.\n- `browser_console_logs`: Inspects real-time browser console warnings, errors, and logs.\n- `browser_network_requests`: Inspects HTTP requests made by the page.\n- `browser_close`: Closes browser sessions cleanly.\n\n### 8. Desktop Automation (Windows-First)\n- `screenshot_desktop`: Captures full screen or region via Windows GDI and returns a direct base64 image block.\n- `list_windows`: Enumerates open desktop windows with handles, titles, and process IDs.\n- `focus_window`: Brings specific window to the foreground.\n\n### 9. Git & Isolated Worktrees\n- `git_status`: Inspects branch name, staged changes, and unstaged modifications.\n- `git_diff`: Produces unified diff against HEAD or specified commit.\n- `show_changes`: Unified summary of all uncommitted workspace modifications.\n- `revert_changes`: Reverts uncommitted changes with post-revert verification.\n- `worktree_create`: Creates an isolated Git worktree branch for safe experimentation.\n- `worktree_list`: Lists all active Git worktrees.\n- `worktree_remove`: Removes worktree with dirty-state safety guard.\n\n### 10. Planning & Tasks\n- `task_create`: Registers a goal in the persistent planning store.\n- `task_update`: Updates task state (`pending`, `in_progress`, `completed`, `failed`).\n- `task_list`: Inspects all tasks and execution progress.\n\n### 11. Live Observability & Diagnostics\n- `activity_list`: Lists live activity stream events (intent, action, verifications, fallbacks, warnings, results).\n- `activity_read`: Cursor-paginated operational stream for live execution monitoring.\n- `activity_clear`: Resets active activity stream buffer.\n- `verity_diagnostics`: Returns system health, available shells, browser status, and tool reliability audit logs.\n- `verity_self_test`: Fast automated self-test of core subsystems.\n- `verity_acceptance_test`: Deep end-to-end acceptance test verification.\n\n---\n\n## 💻 Configuration Guides\n\n### 1. ChatGPT Web Setup (Recommended)\n1. Launch VerityMCP with `start.bat`.\n2. Copy the generated Cloudflare URL (`https://<subdomain>.trycloudflare.com/mcp`).\n3. In ChatGPT Web, navigate to **Settings** → **Connected Apps** → **Add Server**.\n4. Configure:\n   - **URL**: `https://<subdomain>.trycloudflare.com/mcp`\n   - **Authentication**: Bearer Token\n   - **Token**: Copy the owner password displayed by `start.bat`, or read it from the ignored project `.verity/auth.json` (unless you configured `VERITY_OWNER_TOKEN` or a legacy home-directory credential).\n\n### 2. Local IDE & Agent Setup\nTo run VerityMCP locally with standard MCP clients:\n- **Command**: `node dist/cli.js serve --port 7980`\n- **HTTP / SSE Endpoint**: `http://127.0.0.1:7980/mcp`\n\n---\n\n## 🔒 Security & Local Authority\n\nVerityMCP runs with access to your local machine. We treat security as a first-class product boundary:\n\n1. **Approved Roots Boundary**: File operations are strictly confined within configured directory roots. Attempting path traversal outside allowed boundaries is immediately rejected.\n2. **Owner Token Authentication**: The HTTP/SSE endpoint requires Bearer authentication based on RFC 9728 and RFC 8414 standards.\n3. **User-Controlled Tunnel**: Tunnels run via Cloudflare's quick tunnel service or local loopback. VerityMCP does not store your credentials on third-party servers.\n4. **Isolated Worktrees**: When asking ChatGPT to make large architectural changes, use `worktree_create` to ensure work happens in an isolated Git worktree without touching your main working directory.\n\n---\n\n## 🧪 Testing & Verification\n\nVerityMCP includes a rigorous test suite validating all verification mechanisms:\n\n```bash\npnpm test\n```\n\nTest coverage includes:\n- `test/patcher.test.ts`: Validates Codex patches, unified diffs, and guarantees prevention of false-success patch mutations.\n- `test/process_manager.test.ts`: Verifies durable chunk buffering and cursor pagination under high stdout volume.\n- `test/browser.test.ts`: Persistent Playwright browser automation, element refs, verified form inputs, and screenshot generation.\n- `test/todomvc.test.ts`: 14-step automated TodoMVC scenario verifying accessibility snapshots, form fill, checkbox assertions, and console logs.\n- `test/server.test.ts`: End-to-end HTTP MCP protocol handshake, OAuth metadata endpoints, and tool execution.\n\n---\n\n## ❓ Frequently Asked Questions (FAQ)\n\n### Can ChatGPT Web really edit files on my local Windows PC?\n**Yes.** By using the Model Context Protocol (MCP) and a secure tunnel (such as Cloudflare or local reverse proxy), ChatGPT Web can call VerityMCP tools running on your machine to read files, write code, run build scripts, and verify tests.\n\n### How is VerityMCP different from standard MCP servers?\nStandard MCP servers are fire-and-forget: they run a command and assume it succeeded. If a file edit doesn't apply cleanly or a test hangs, ChatGPT gets confused and hallucinates. **VerityMCP enforces mathematical verification**—reading back disk bytes via SHA-256 and testing live DOM states before confirming success.\n\n### Do I need to open firewall ports or have a public static IP?\n**No.** `start.bat` launches an encrypted Cloudflare Tunnel (`cloudflared`) that establishes an outbound HTTPS tunnel. No port forwarding, DNS configuration, or firewall changes are required.\n\n### Does VerityMCP work on macOS and Linux?\n**Yes.** VerityMCP runs on Node.js >= 20 across Windows, macOS, and Linux. On Windows, it includes specialized PowerShell/cmd/Git Bash detection and native GDI desktop tools.\n\n---\n\n## 📄 License\n\nMIT © VerityMCP\n"}