portal MCP server
Commit Nov 10, 2026Converts websites into walkable 3D environments that AI agents can navigate to understand site structure and content.
Also known as nirholas/portal
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- Apache-2.0
What is portal MCP?
portal converts websites into walkable 3D environments that AI agents can navigate to understand site structure and content.
Summary generated from the project's README
About portal MCP server
Transforming websites into navigable 3D environments allows AI agents to understand site structure through spatial relationships rather than just text. By converting headings into buildings, links into doors, and images into billboards, this tool provides a visual representation of a page's weight and layout. It is designed for developers and AI agents who need to move beyond simple text scraping to grasp the actual shape and hierarchy of a web domain.
Users can interact with this server via the walk_site and site_shape tools through an MCP client. The walk_site tool provides a full world description including districts, doors, and a link to a walkable version, while site_shape offers a lightweight structural read of the heading spine. The system operates using a public API that requires no accounts or API keys, though it respects robots.txt and imposes a 3 MB HTML limit per request to ensure responsible crawling.
What you can do with it
- 1Visualize site hierarchy spatiallyAsk an AI agent to explore the physical layout of a website to identify its most significant sections.
- 2Generate 3D assets from URLsConvert a web address into a downloadable 3D file for use in other applications.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenirholas/portal is public and reachablegithub.com/nirholas/portal ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/nirholas/portal ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHub@three-ws/portal
Turn any website into a walkable 3D world.
Paste an address; get a place. Every section becomes a building sized by what it
says, every link becomes a door you can step through, every image becomes a
billboard, every code block becomes a monolith. Walk it in the browser, download
it as a .glb, embed it in your own page, or hand it to an agent over MCP.
Quick start · How a page becomes a place · API · CLI · MCP · Manners
Why
Every tool that "visualizes a website" draws a node graph. A graph tells you a site has 40 pages; it does not tell you which section carries the weight, where the dead ends are, or what it feels like to arrive. A place does, because size, distance and direction are things people read without being taught.
Portal turns the page you already have into that place, deterministically, with no model in the loop: the same URL always builds the same city, so a link you share opens the world you walked.
Quick start
npm install @three-ws/portal
import { fetchWorld, describeWorld } from '@three-ws/portal';
const { world } = await fetchWorld('example.com');
console.log(describeWorld(world));
// { host: 'example.com', sections: 2, doors: 1, tallest: { name: 'Example Domain', … } }
Put a live, walkable world on your own page:
import { mountPortal } from '@three-ws/portal';
mountPortal(document.querySelector('#stage'), { url: 'example.com', height: 560 });
Or without any JavaScript at all:
<iframe
src="https://three.ws/portal?url=example.com&embed=1"
width="100%" height="520" style="border:0;border-radius:14px"
loading="lazy" title="Walk example.com in 3D"></iframe>
No key, no account, no wallet. fetchWorld reads the public three.ws Portal API,
which fetches the page once and caches the result for an hour.
How a page becomes a place
The mapping is fixed, documented, and testable, which is what makes a world predictable enough to share:
| On the page | In the world |
|---|---|
| The page itself | A plaza with an obelisk carrying the title |
Each h1/h2/h3 section |
A district with one building |
| How many words a section has | The building's height, on a log scale |
| How many blocks it holds | The building's footprint |
| Each link | A door on the building's wall. Same-site doors rebuild the world where they point; outside links open the page |
| Each image | A billboard beside the building, showing the real image |
| Each code block | A monolith: a tall, dark, emissive slab |
theme-color, or the host name |
The palette, so a site looks like itself |
Layout is a pure function with a seeded PRNG. Call it yourself on any outline:
import { buildWorld, collidersFor } from '@three-ws/portal/layout';
const world = buildWorld(outline); // no network, no DOM, no three.js
const solids = collidersFor(world); // circles, for your own player controller
API
| Export | What it does |
|---|---|
fetchWorld(url, opts?) |
Build (or read from cache) { world, outline, cached, stale } |
fetchOutline(url, opts?) |
The structural read only: headings, weights, links, images |
fetchWorldGlb(url, opts?) |
The world as a glTF binary (ArrayBuffer) |
mountPortal(el, { url, height? }) |
Mount a live walkable world into an element |
embedSnippet(url, opts?) |
The same thing as an HTML string |
describeWorld(world) |
A compact summary: districts, doors, tallest section |
buildWorld(outline, opts?) |
The pure layout function |
collidersFor(world) |
Collision circles for the solids in a world |
paletteFor(outline) |
The deterministic palette for a site |
PortalError |
Every failure, carrying the API's own code |
opts accepts endpoint (default https://three.ws/api/portal), fetch (bring
your own), and signal.
Errors are typed rather than thrown as strings:
import { fetchWorld, PortalError } from '@three-ws/portal';
try {
await fetchWorld('example.com/private');
} catch (err) {
if (err instanceof PortalError && err.code === 'robots_disallowed') {
console.log('That site asks crawlers to stay out, so Portal does.');
}
}
Codes you can branch on: invalid_url, robots_disallowed, blocked_host,
not_html, no_structure, too_large, unreachable, upstream_status,
rate_limited.
CLI
npx @three-ws/portal three.ws # the world, summarized
npx @three-ws/portal three.ws --glb site.glb # save it as a 3D file
npx @three-ws/portal three.ws --json world.json # save the world document
npx @three-ws/portal three.ws --open # print the walkable link
three.ws
24 districts · 1563 words · 42 doors (38 internal) · 2 billboards · 0 code monoliths
███████████··········· 109w Your 3D agent. In your room.
█████████············· 66w Your agents don't just talk. They trade.
█████················· 20w One tag. Any site.
MCP
An agent that fetches a page gets a wall of text. Over MCP it can ask for the page's shape instead.
claude mcp add portal -- npx -y @three-ws/portal portal-mcp
| Tool | Returns |
|---|---|
walk_site |
The world: districts, doors (with targets), billboards, plus a walkable link and a GLB URL |
site_shape |
The heading spine with the weight of each section. The cheap read |
Both accept any public URL and honour the same manners as the API.
Manners
Portal is a crawler that runs on a person's request, and behaves like one:
- It identifies itself as
ThreeWSPortalBot/1.0 (+https://three.ws/portal). - It reads robots.txt first and honours a
Disallowfor that token with a cleanrobots_disallowederror. Rules are matched per RFC 9309: most specific user-agent group, longest matching rule,Allowwins a tie. - It reads a page once. Worlds are cached for an hour fleet-wide, so a link shared with a thousand people is one request to the origin.
- It is bounded: 3 MB of HTML, a 12 second deadline, and an SSRF guard that re-resolves the host, refuses private address ranges, and pins the socket to the address it validated.
License
Apache-2.0. Built by three.ws.
Part of three.ws, the open-source platform for 3D AI agents. This repository is exported from the monorepo, which is the source of truth: open issues here, and send larger changes there.
Support the project
If portal saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Built for AI agents too
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/portal and it has the context it needs.
More from the same author
- All repositories by nirholas: the full catalog, grouped by topic
- three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
- Questions or ideas: open an issue or start a discussion
Contributors
Star history
portal MCP questions
How can an AI agent use Portal?
An agent can use the MCP server to ask for a page's shape or walk the site to receive districts, doors, billboards, and a walkable link.
Does Portal respect robots.txt?
Yes, Portal reads robots.txt first and honors Disallow rules, returning a robots_disallowed error if a site asks crawlers to stay out.
Can I download the 3D world as a file?
Yes, you can download the world as a .glb file using the CLI or the API.