Quickstart
From a clone to a working MCP call in about ten minutes.
Install from npm
The CLI is published as @abubakarsiddiik/portolan. This guide uses a source checkout so you can run the demo fixtures, but you can install the CLI directly:
npm install -g @abubakarsiddiik/portolan1. Prerequisites
- Node 22.12 or newer.
- Google Chrome or Chromium. Set
CHROME_PATHif it is not in a usual place.
node --version2. Build
git clone https://github.com/abubakarsiddik31/portolan.git
cd portolan
pnpm install
pnpm build3. Start the demo site and the server
The repository ships a store fixture. In one terminal:
pnpm --filter @abubakarsiddiik/bench fixtures:storeThat serves the store on http://127.0.0.1:4100. In a second terminal, from the repository root:
DATABASE_PATH=:memory: MAPS_DIR=maps node packages/cli/dist/bin.js mcpThis is the MCP server on stdio. It reads maps from maps/ and keeps sessions in memory.
4. Connect a client
Point a client at the command. For Claude Code:
claude mcp add portolan -- env MAPS_DIR="$PWD/maps" DATABASE_PATH=:memory: \
node "$PWD/packages/cli/dist/bin.js" mcpOr use the JSON/TOML snippets in Client setup for Claude Desktop, Codex CLI, Cursor, Gemini CLI, or VS Code.
5. Make a call
Ask the client to call open_site with { "site": "store" }. It returns the compact map:
store · map v1
search(query, page) Search the catalog. [read]
get_product(product_id) ...
add_to_cart(...) [write]
checkout(...) [irreversible]Then call view to read the page. You should see the catalog, the search box, and a ranked list of affordances.
That is the loop: open_site tells the agent what the site can do, call runs a named operation, and view / act / read are the fallback when no operation fits.
6. Check the install
node packages/cli/dist/bin.js doctordoctor reports the browser, config, provider variables, and client configs.
What works today
open_site,call,view,act, andreadwork throughportolan mcp.callruns the operation through the cheapest verified tier:url, in-pagehttp, thenui. A write goes through confirmation and idempotency.webmcpis in the map format but has no executor yet; an operation that only has awebmcpimplementation returnsop_broken.servewires the same browser factory, so the HTTP MCP surface executes operations too.
Where next
- Using maps — the call loop an agent runs.
- Concepts — map, state, op, tier, session.
- MCP tools — every tool and its result shape.
- Write safety — confirmation, idempotency, unknown outcomes.
- Map format — the full field reference.