Claude MCP Workbench

Public GitHub repo audit, over MCP.

Live demo: https://mcp.fotios.org

A live MCP host with a small web UI. v1 audits public GitHub repositories only. Caps instead of accounts. Not a startup product page — a tool.

What it is

• A FastAPI host (one Uvicorn worker) plus a Vite/React UI.

• One skill pack, repo-audit: classify a URL → start a Task → shallow-clone → scan without executing → publish MCP resources.

• Streamable HTTP at /mcp (protocol 2026-07-28). Tasks are SEP-2663-shaped.

• Public UI: one task chip (GitHub repo), three owner example tiles, URL field, live SSE progress, filtered findings, tree, brief, Open PDF / Download PDF, markdown report.

• SQLite WAL. Cache by owner/repo@sha (6 h). Settings page for Anthropic key/model/effort.

Related MCP server: Orcorus Repository Scanner

What it is not

• Not a SaaS, account system, or marketplace.

• Not a vulnerability scanner or CVE database — it does not invent secrets or CVEs.

• Not a general git host: no GitLab, gist, issues, PRs, blobs, or SSH.

• Not an executor: cloned code is never run, installed, or tested.

• Not MCP Apps: there is no iframe. The tree is a host widget + UI resource (ui://audit-tree/{run}).

Architecture

  Browser / MCP client
        │
        ├─ REST + SSE  /api/runs…     ─┐
        ├─ UI          / , /settings   │  FastAPI host (1 worker)
        └─ Streamable  /mcp            ─┘
                          │
              ┌───────────┼───────────┐
              ▼           ▼           ▼
         Task worker   SQLite WAL   Anthropic
         (clone+scan)  + artifacts  (optional brief)
              │
              ▼
         shallow clone → manifests | ci | secrets | tests
              │
              ▼
         audit://  tree://  findings://  ui://audit-tree/{run}

Stages (SSE, progress ≤ ~500 ms cadence):

queued → resolving → cloning → walking → [input_required] → scanning:manifests|ci|secrets|tests → writing → briefing

If the tree exceeds ELICIT_FILE_THRESHOLD (default 1500 files), the Task moves to input_required (top-level-only | full-tree, wait ELICIT_WAIT_SECONDS=300).

Features

Quick start

Linux

cd Claude-MCP-Workbench   # or your clone path
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
cd web && npm ci && npm run build && cd ..
cp .env.example .env      # edit as needed
uvicorn src.host.main:app --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000. Dev UI with proxy: cd web && npm run dev (Vite proxies /api, /healthz, /mcp).

Helpers: scripts/build.sh (install + web build); scripts/smoke_test.sh (classify without network; SMOKE_NETWORK=1 hits GitHub).

Windows

cd Claude-MCP-Workbench
python -m venv .venv
.venv\Scripts\pip install -e .
cd web && npm ci && npm run build

Copy .env.example → .env, then:

uvicorn src.host.main:app --host 127.0.0.1 --port 8000

Or npm run dev in web/ (Vite proxy).

Requires Python 3.11+, Node/npm, and git on PATH.

MCP honesty (tools / resources / prompts / tasks)

Implemented

Official mcp SDK is preferred for tools / resources / prompts when importable; otherwise a fallback Streamable HTTP router is used. Tasks live beside the SDK because SEP-2663 coverage is incomplete.

Deferred / not in v1

• skills/list — skills are published as resources + the repo-audit prompt (skill://index.json)

• MCP Apps / iframe UI

• OAuth, authenticated GitHub, private repos

• Completions, resource subscriptions, sampling

• Multi-skill routing beyond github_repo → repo-audit

Try /mcp from the command line

/mcp is Streamable HTTP JSON-RPC, not a webpage. A browser GET usually only shows keep-alive ping events. Use POST with Content-Type: application/json.

Base URL in the examples: https://mcp.fotios.org/mcp (local: http://127.0.0.1:8000/mcp).

1) initialize

Handshake: negotiate protocol version and learn server capabilities.

Returns: result.protocolVersion, serverInfo, capabilities (tools/resources/prompts + Tasks extension), and short instructions.

Linux / macOS (curl):

curl -sS https://mcp.fotios.org/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"curl-demo","version":"1"}}}'

Windows PowerShell (Invoke-RestMethod):

Invoke-RestMethod https://mcp.fotios.org/mcp -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"curl-demo","version":"1"}}}' | ConvertTo-Json -Depth 20

2) tools/list

List every MCP tool this host exposes.

Returns: result.tools[] with name, description, and inputSchema for each tool (classify, resolve, scanners, start_repo_audit, …).

Linux / macOS:

curl -sS https://mcp.fotios.org/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Windows PowerShell:

Invoke-RestMethod https://mcp.fotios.org/mcp -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | ConvertTo-Json -Depth 20

3) tools/call → classify_url

Ask whether a URL is an accepted public GitHub repo (and which skill it maps to).

Returns: classification payload (accepted, kind, skill, reason, and when accepted owner / repo / normalized URLs). Rejects gist/issues/blob/GitLab/SSH with a precise reason.

Linux / macOS:

curl -sS https://mcp.fotios.org/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"classify_url","arguments":{"url":"https://github.com/fotiosb/MacPresenterView"}}}'

Windows PowerShell:

Invoke-RestMethod https://mcp.fotios.org/mcp -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"classify_url","arguments":{"url":"https://github.com/fotiosb/MacPresenterView"}}}' | ConvertTo-Json -Depth 20

4) tools/call → start_repo_audit

Start a long-running repo-audit Task (shallow clone + scans + brief). Subject to the same IP caps as the web UI.

Returns: a Task / run handle (id fields depend on the fallback shape — typically a task/run id you can poll). Does not wait for the full audit inline.

Linux / macOS:

curl -sS https://mcp.fotios.org/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"start_repo_audit","arguments":{"url":"https://github.com/fotiosb/MacPresenterView"}}}'

Windows PowerShell:

Invoke-RestMethod https://mcp.fotios.org/mcp -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"start_repo_audit","arguments":{"url":"https://github.com/fotiosb/MacPresenterView"}}}' | ConvertTo-Json -Depth 20

5) tasks/get

Poll Task status until completed / failed / cancelled (or input_required).

Returns: task state (working, input_required, completed, …), progress/stage fields when available, and result refs when done. Replace PASTE_TASK_OR_RUN_ID_HERE with the id from step 4.

Linux / macOS:

curl -sS https://mcp.fotios.org/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":5,"method":"tasks/get","params":{"taskId":"PASTE_TASK_OR_RUN_ID_HERE"}}'

Windows PowerShell:

Invoke-RestMethod https://mcp.fotios.org/mcp -Method Post -ContentType 'application/json' -Body '{"jsonrpc":"2.0","id":5,"method":"tasks/get","params":{"taskId":"PASTE_TASK_OR_RUN_ID_HERE"}}' | ConvertTo-Json -Depth 20

Note: On Windows, Prefer Invoke-RestMethod (or curl.exe --data-binary @file.json). Inline curl.exe -d "..." is easy for PowerShell to mangle, which surfaces as MCP -32700 Parse error.

Safety model

• GIT_TERMINAL_PROMPT=0, GIT_LFS_SKIP_SMUDGE=1, no --recurse-submodules

• Shallow clone (--depth 1) only under CLONE_DIR; delete always

• Path jail; skip binaries; 256 KB read cap; secret redaction

• Public findings filter strips noisy/vendor secret hits on API read

• Never execute, install, or test cloned code

• Client IP from X-Real-IP only when TRUSTED_PROXY=1

Caps (no auth)

Cached example runs do not consume the daily run cap. Claude is skipped on a cache hit.

Deploy

• Production (fotios): DEPLOY-mcp.fotios.org.md — nginx VPS, mcp.fotios.org, SSH/SFTP, certbot.

• Generic Ubuntu: DEPLOY.md — service user mcpwork, env /etc/mcp-workbench.env, systemd + nginx samples under systemd/ and nginx/.

Apt note: do not install distro npm alongside NodeSource nodejs (NodeSource already ships npm). On Python 3.14 hosts, install matching python3.14-venv as well as python3-venv.

Owner example tiles

Shipped under web/public/examples/ (local SVGs — no hotlinks). Author: fotiosb.

1. Multi-Agent Behavioral Video Analysis — RTSP anomaly, YOLO + Gemini + Claude, FastAPI / React (small).

2. Residential Proxy Aggregator — Windows edge nodes → SOCKS5 pool (~27 MB binaries; cache warm).

3. MacPresenterView — Slides → NDI notes, Node + Chrome extension (small).

WARM_EXAMPLES=1 warms #1 and #3 first, then #2.

How to add a skill

1. Create src/skills/<name>/SKILL.md.

2. Teach src/skills/router.py a new kind → skill id.

3. Add tools / resources / a prompt in src/mcp_server/.

4. If the skill is long-running, enqueue through src/tasks/worker.py so it shares Task states, SSE, and cleanup.

v1 only routes github_repo → repo-audit. Everything else is unsupported with a one-line reason.

HTTP API (host)

Project layout

.
├── LICENSE
├── README.md
├── ANALYSIS.md
├── DEPLOY.md
├── DEPLOY-mcp.fotios.org.md
├── .env.example
├── package.json              # workspace root → web/
├── pyproject.toml            # mcp-workbench (Python)
├── nginx/                    # sample site configs
├── systemd/                  # service + GC timer
├── scripts/
│   ├── build.sh
│   ├── smoke_test.sh
│   └── cap_accounting_probe.py
├── src/
│   ├── host/                 # FastAPI app, config, examples, settings
│   ├── mcp_server/           # SDK mount + Streamable HTTP fallback
│   ├── skills/               # router + repo_audit/SKILL.md
│   ├── tasks/                # audit worker
│   ├── audit/                # clone, scans, report, PDF, brief
│   └── store/                # SQLite
└── web/
    ├── public/examples/      # tile SVGs
    └── src/                  # React UI (Workbench + Settings)

Runtime data (DATA_DIR, clones, artifacts, cache) stays local and is gitignored.

License

MIT © Fotios Basagiannis. The three example repositories remain under their own licenses.

Author

Fotios Basagiannis — fotiosb · live host mcp.fotios.org