# Hunt Workbench (local MCP) Hunt Workbench is a local-only companion for a security research project. It keeps project state in a portable SQLite file under a directory you choose; it does not require an account and contains no network calls. The public `https://vulns.co/mcp` server remains the read-only research library. ## Install Requires Node 24 or newer for the built-in `node:sqlite` module. Keep these three files together: `hunt-workbench.mjs`, `workbench.mjs`, and `schema.sql`. After downloading the ZIP, extract it and point your client at `vulns-hunt-workbench/src/hunt-workbench/hunt-workbench.mjs`. ```json { "mcpServers": { "hunt-workbench": { "command": "node", "args": ["/absolute/path/to/hunt-workbench.mjs", "--workspace", "/absolute/path/to/my-hunt"] } } } ``` Codex CLI: `codex mcp add hunt-workbench -- node /absolute/path/to/hunt-workbench.mjs --workspace /absolute/path/to/my-hunt` Claude Code: `claude mcp add --transport stdio hunt-workbench -- node /absolute/path/to/hunt-workbench.mjs --workspace /absolute/path/to/my-hunt` Grok Build CLI: `grok mcp add hunt-workbench -- node /absolute/path/to/hunt-workbench.mjs --workspace /absolute/path/to/my-hunt`. Grok.com custom connectors require public HTTP, so this local companion is for Grok CLI. See the [Codex](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [Claude Code](https://code.claude.com/docs/en/mcp), and [Grok Build](https://docs.x.ai/build/features/mcp-servers) MCP guides. On Windows, use full paths and quote paths with spaces. For example: ```powershell codex mcp add hunt-workbench -- node "C:\Users\YourName\Downloads\vulns-hunt-workbench\src\hunt-workbench\hunt-workbench.mjs" --workspace "C:\Users\YourName\Documents\My Hunt" ``` The workspace must be an absolute, non-symlink directory. Imported files, evidence references, and handoff exports must be paths beneath it. The server rejects traversal and symlink paths. It enables SQLite WAL mode and uses short `BEGIN IMMEDIATE` transactions so separate MCP clients can safely reopen the same workspace. The server itself stores records locally and never calls the hosted MCP. A cloud-backed MCP client can still include tool results in prompts sent to its model provider; only ask that client to read records you are prepared to share. ## Durable files and portability - `hunt-workbench.sqlite` is the complete durable state and change history. - `imports/` holds source recon files; `evidence/` holds referenced captures; `exports/` holds Markdown handoffs. - Evidence records store a workspace-relative path, byte size, and SHA-256. Large evidence is not copied into record rows. - SQLite is readable with standard SQLite tools. `export_handoff` creates a standalone Markdown summary with record IDs and evidence references. ## Typical flow 1. Call `init_hunt_workspace` with the authorized scope and rule URLs. 2. Place recon output beneath `imports/`, then call `import_recon`. Repeating the same file unchanged is a no-op; a different source file retains its own provenance even if its contents match. 3. Use `record_check` for planned and completed work. `partial`, `blocked`, `failed`, and `not_tested` remain distinct states. 4. Use `upsert_lead` for hypotheses. Its required `observations` field is kept separate from possible impact and missing proof. 5. Use `next_actions` and `export_handoff` to resume elsewhere. Research links are deterministic public URLs generated locally; no workspace record is sent to the hosted MCP. `init_hunt_workspace` requires `scope` and `rules_references`; those values are immutable once recorded. Recon imports remain inventory only. A host matching a saved pattern still requires confirmation against live program rules before testing. `next_actions` provides only scope-confirmation actions until then. The tool inputs are JSON-schema validated: imports require a relative `path`; checks require `title` and a listed `status`; leads require `hypothesis` and nonempty `observations`. The prototype accepts imported output only. A future executor must be an explicit opt-in, scope-bound local extension; none is present in this release. ## Future local execution interface An optional executor can later consume a planned `check_id`, its recorded limits, a workspace-relative output path, and a user-selected tool profile. Before launch it must confirm the current program rules and selected asset against the saved scope, then require an explicit per-workspace opt-in. Its output should enter through `import_recon` or `record_check` so provenance and revision history remain intact. The current server exposes no process execution tool and has no implicit path from a discovered asset to an approved target. Run `node examples/hunt-workbench/demo.mjs` from the extracted package root to create a sample workspace in your system's temporary directory and demonstrate the full sequence. It prints that directory so you can inspect the SQLite file, imported assets, evidence references, and Markdown handoff.