Skip to content

Commit 9d42deb

Browse files
Arman-LuthraArman-Luthra
committed
docs: clean up mcp README
1 parent 6a7d7ee commit 9d42deb

1 file changed

Lines changed: 33 additions & 34 deletions

File tree

‎mcp/README.md‎

Lines changed: 33 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
1-
# Fortress MCP — a stealth browser for AI agents
1+
# Fortress MCP: a stealth browser for AI agents
22

3-
> **Beta** · 29 tools · runs **local & free** · **hosted cloud coming soon**
3+
> **Beta** · 29 tools · local and free · hosted cloud coming soon
44
>
5-
> 📖 **[Full usage guide → mcp/USAGE.md](USAGE.md)** — every tool, the block-handling decision model, workflow recipes, and config.
5+
> Full usage guide: **[USAGE.md](USAGE.md)** covers every tool, the block-handling decision model, workflow recipes, and config.
66
7-
An [MCP](https://modelcontextprotocol.io) server that gives any AI agent the **Fortress
8-
stealth engine** the moment it gets blocked. When a fetch hits Cloudflare, DataDome,
9-
PerimeterX, a 403, or a CAPTCHA, the agent calls these tools and gets the page — driving a
10-
real, recompiled Chromium on your own machine and IP.
7+
An [MCP](https://modelcontextprotocol.io) server that gives any AI agent the Fortress
8+
stealth engine the moment a fetch gets blocked. When a request hits Cloudflare, DataDome,
9+
PerimeterX, a 403, or a CAPTCHA, the agent calls these tools and gets the page. The tools
10+
drive a real, recompiled Chromium on your own machine and IP.
1111

1212
<p align="center"><img src="demo.gif" alt="Same site, same prompt: a vanilla browser is blocked by PerimeterX while an agent with the Fortress MCP returns clean JSON" width="760"/></p>
1313

14-
<sub><i>Real, dated run against <b>stockx.com</b> (PerimeterX). A stock browser gets <b>HTTP 403 — “Access denied”</b>; an agent with the Fortress MCP returns clean JSON. Reproduce with the demo scripts in the framework repo.</i></sub>
14+
<sub><i>Real, dated run against <b>stockx.com</b> (PerimeterX). A stock browser gets <b>HTTP 403 ("Access denied")</b>; an agent with the Fortress MCP returns clean JSON. Reproduce with the demo scripts in the framework repo.</i></sub>
1515

1616
## Install
1717

@@ -74,13 +74,13 @@ server, then confirm with `get_egress_info`.
7474

7575
## Add to your client
7676

77-
**Claude Desktop / Cursor** — add to the MCP config:
77+
**Claude Desktop / Cursor**: add to the MCP config:
7878

7979
```json
8080
{ "mcpServers": { "fortress": { "command": "tilion-mcp" } } }
8181
```
8282

83-
**Cline / Windsurf** (VS Code settings → MCP servers):
83+
**Cline / Windsurf** (VS Code settings, MCP servers):
8484
```json
8585
{ "fortress": { "command": "tilion-mcp" } }
8686
```
@@ -89,38 +89,37 @@ If `tilion-mcp` isn't on PATH, use `"command": "python", "args": ["-m", "tilion.
8989

9090
## The 29 tools
9191

92-
*Full per-tool detail + workflows in [USAGE.md](USAGE.md).*
92+
*Full per-tool detail and workflows in [USAGE.md](USAGE.md).*
9393

9494
| Tool | What the agent uses it for |
9595
|---|---|
9696
| `fetch_protected_page` | get a page behind Cloudflare / DataDome / 403 / CAPTCHA |
97-
| `read_page` | clean reader-mode **markdown of any page** (+ tables) |
97+
| `read_page` | clean reader-mode markdown of any page, tables included |
9898
| `extract_page` | markdown + tables + metadata (or a schema-shaped record) |
99-
| `extract_document` | extract a PDF/DOCX/XLSX/CSV/HTML file (path or URL) → markdown |
99+
| `extract_document` | convert a PDF/DOCX/XLSX/CSV/HTML file (path or URL) to markdown |
100100
| `page_elements` | the page's buttons / links / fields / headings |
101101
| `click_button` · `fill_field` · `press_key` | drive a form by visible text / selector / key |
102102
| `current_page` · `get_page_html` · `evaluate_js` · `wait_for` | inspect / script / wait on the working page |
103-
| `crawl_site` | crawl a whole site (auto-handles SPA/JS) → pages + sitemap |
103+
| `crawl_site` | crawl a whole site (handles SPA/JS) into pages and a sitemap |
104104
| `recon_site_apis` | reverse-engineer a site's private XHR/JSON API (secret-scrubbed) |
105-
| `detect_waf` | identify the anti-bot vendor (Cloudflare/DataDome/PerimeterX/Akamai/Kasada) + strategy |
105+
| `detect_waf` | identify the anti-bot vendor (Cloudflare/DataDome/PerimeterX/Akamai/Kasada) and a strategy |
106106
| `run_browser_task` · `list_browser_tasks` | 20 multi-step flows: login, paginate, infinite-scroll, checkout… |
107107
| `search_web` | web search through the stealth browser (no SERP API) |
108108
| `screenshot_page` · `save_page` · `download_file` | capture PNG / export pdf·html·text / download a file |
109-
| `get_cookies` · `save_profile` · `load_profile` | read cookies · persist/restore an authenticated session |
109+
| `get_cookies` · `save_profile` · `load_profile` | read cookies · persist and restore an authenticated session |
110110
| `list_tabs` · `close_tab` | manage open tabs |
111-
| `get_stealth_cdp_endpoint` | a CDP url to point your OWN browser-use / Playwright / Puppeteer at |
112-
| `solve_captcha` | detect + solve a reCAPTCHA/hCaptcha/Turnstile (needs `CAPTCHA_API_KEY`) |
113-
| `get_egress_info` | report proxy/region + the real public IP the target sees (verify residential egress) |
111+
| `get_stealth_cdp_endpoint` | a CDP URL for your own Playwright, Puppeteer, or browser-use setup |
112+
| `solve_captcha` | detect and solve a reCAPTCHA/hCaptcha/Turnstile (needs `CAPTCHA_API_KEY`) |
113+
| `get_egress_info` | report proxy/region and the real public IP the target sees (verify residential egress) |
114114

115-
Tools are **annotated** (`readOnlyHint` / `destructiveHint`) so clients auto-approve reads
116-
and gate writes. Every tool is **timeout- and SSRF-guarded**, caps its output, and returns a
117-
structured error instead of hanging. The browser is **pre-warmed at startup**, so the first
118-
call is ~100 ms.
115+
Tools carry `readOnlyHint`/`destructiveHint` annotations, so clients auto-approve reads and
116+
gate writes. Every tool is timeout- and SSRF-guarded, caps its output, and returns a
117+
structured error instead of hanging. The browser is pre-warmed at startup, so the first
118+
call takes about 100 ms.
119119

120-
## Why reach for it — benchmarks
120+
## Benchmarks
121121

122-
Real head-to-head — an agent with only its built-in web fetch vs. the same task through the
123-
Fortress MCP:
122+
The same tasks, run once with an agent's built-in web fetch and again through the Fortress MCP:
124123

125124
| Task | Built-in web fetch | **Fortress MCP** |
126125
|------|--------------------|------------------|
@@ -129,7 +128,7 @@ Fortress MCP:
129128
| Wikipedia article | ✗ 403 to bots | **✓ 52 k markdown** |
130129
| Hacker News top stories | ✓ 30 · 24 s | **✓ 30 · 2 s** (~12× faster) |
131130

132-
Fingerprint suites: **Sannysoft all-green · CreepJS 0% headless · BrowserScan “Normal.”**
131+
Fingerprint suites: Sannysoft all green, CreepJS 0% headless, BrowserScan "Normal".
133132

134133
## Configuration (env)
135134

@@ -139,22 +138,22 @@ Fingerprint suites: **Sannysoft all-green · CreepJS 0% headless · BrowserScan
139138
| `TILION_MCP_HEADLESS` | `1` | `0` to show a visible window |
140139
| `TILION_ALLOW_PRIVATE_EGRESS` | `0` | `1` to allow localhost / private IPs (SSRF guard off) |
141140
| `TILION_MCP_TOOL_TIMEOUT` | `120` | per-tool wall-clock cap (seconds) |
142-
| `TILION_BASE_URL` / `TILION_API_KEY` | — | hosted mode (**coming soon**) |
143-
| `TILION_PROXY` | — | egress proxy `http://user:pass@host:port` (residential/mobile) |
144-
| `TILION_REGION` | — | egress region hint (e.g. `us`) — aligns timezone/locale to the IP |
145-
| `CAPTCHA_API_KEY` | — | solver key; `fetch` then auto-solves + `solve_captcha` works |
141+
| `TILION_BASE_URL` / `TILION_API_KEY` | (none) | hosted mode (coming soon) |
142+
| `TILION_PROXY` | (none) | egress proxy `http://user:pass@host:port` (residential/mobile) |
143+
| `TILION_REGION` | (none) | egress region hint (e.g. `us`); aligns timezone and locale to the IP |
144+
| `CAPTCHA_API_KEY` | (none) | solver key; enables auto-solve during fetches and the `solve_captcha` tool |
146145
| `CAPTCHA_PROVIDER` | `2captcha` | `2captcha` \| `anticaptcha` \| `capsolver` |
147146

148147
## How it works
149148

150-
`tilion-mcp` → the `tilion` framework (local mode) → attaches over CDP to the Fortress
151-
engine. Stealth is applied **natively in the C++ engine**, so there's no detectable JS
149+
`tilion-mcp` calls the `tilion` framework in local mode, which attaches over CDP to the
150+
Fortress engine. Stealth is applied natively in the C++ engine, so there is no detectable JS
152151
injection. One warm browser backs every tool for the server's lifetime.
153152

154153
Registry manifests: [`server.json`](server.json) (MCP registry) · [`smithery.yaml`](smithery.yaml) (Smithery).
155154
Agent skill: [`skill/SKILL.md`](skill/SKILL.md).
156155

157156
## License
158157

159-
BSD-3-Clause (the MCP server and framework funnel). The engine binary ships via
158+
BSD-3-Clause covers the MCP server and the `tilion` framework. The engine binary ships via
160159
`tilion-fortress`. Hosted cloud with residential egress is coming soon.

0 commit comments

Comments
 (0)