Adoption¶
This guide describes the supported path for running ANCHOR outside the repository and connecting it to an MCP-capable agent harness.
1. Install and run¶
Install the packaged application:
The wheel includes the web frontend. You need Node.js and pnpm only when
working on web/ from a source checkout:
git clone https://github.com/Novia-RDI-Seafaring/anchor
cd anchor
uv sync --extra dev
pnpm --dir web install
uv run anchor serve
# in another terminal:
pnpm --dir web dev
Source development requires Node.js 20+ and pnpm 10. If pnpm is not
installed globally, use Corepack for the frontend commands instead:
ANCHOR serves the UI and HTTP API at http://127.0.0.1:8002 by default.
It is unauthenticated, so bind to a network interface only behind an
authentication layer.
The recommended setup is one environment with a project inside it. Run
anchor env create to choose the AI provider / data zone; it creates a named
environment and its default project. Then run anchor init inside a working
folder to start a project bound to that environment:
anchor env create local
cd ~/work/pumps
anchor init
anchor ingest /path/to/datasheet.pdf
anchor serve
Storage is structural. A project is a folder with an anchor.toml marker and a
hidden .anchor_data/ holding its corpus. A managed project lives under
~/.anchor/envs/<env>/projects/<project>/. The environment keeps a
projects.toml registry mapping each project name to its folder.
anchor demo creates a demo workspace and placeholder nodes. It ingests an
optional local sample PDF when one is present, but the public package does not
ship a vendor PDF. In normal use, ingest a PDF you are allowed to process.
2. Agent harness setup¶
ANCHOR exposes MCP tools through the anchor-mcp stdio executable. Register it
with the installer, which points at an environment by name:
anchor install claude-code # MCP entry + skill (default env)
anchor install claude-desktop --env work
anchor install cursor --env work
The entry runs anchor-mcp --env <name>. The server serves that one
environment; projects inside it are addressed by a per-call project argument
(list_projects enumerates them). A second environment is a second named
server.
Cursor has no global skills directory, so the MCP entry alone gives a Cursor
agent the tools and the server's own briefing but not the project conventions.
For a Cursor workspace that is an Anchor project, add --rules to also write a
project-scoped .cursor/rules/anchor.mdc that points the agent at AGENTS.md
plus the CLI/MCP surfaces:
The rules file is a short pointer, not a copy of AGENTS.md. The write is
idempotent and will not overwrite a file you have edited unless you pass
--force; use --project-dir to target a directory other than the current
one.
Restart the harness and verify that anchor appears in its MCP server list.
The set of tools depends on available optional extensions, such as the FMU
runtime.
If reinstalling ANCHOR fails on Windows because anchor-mcp.exe is in use,
close the MCP client and follow the reinstall steps in
Install.
See Agent configuration for verified Claude Code, Codex, Gemini CLI, OpenCode, Cursor, and generic stdio examples.
anchor serve exposes the browser UI, HTTP API, and browser SSE updates. It
does not expose an authenticated remote-MCP HTTP endpoint. A hosted or remote
MCP integration therefore requires additional transport and authentication
work.
3. Viewing and snapshotting canvases¶
Keep a browser open on:
Changes written through HTTP, CLI, or MCP are reflected through the browser's SSE subscription.
Snapshots render the same browser canvas through headless Chromium and
therefore require a running anchor serve:
From MCP, use canvas_snapshot(..., format="inline") when the harness can
render image content directly. Use format="path" for local agents that can
read files from the same machine, or format="base64" when raw transfer is
needed.
4. LLM endpoints and local operation¶
Without an LLM key, PDF ingestion still creates the local bronze and silver layers. Gold-region extraction and page polishing require a vision-capable OpenAI-compatible endpoint.
For OpenAI:
For an OpenAI-compatible endpoint, set ANCHOR_OPENAI_BASE_URL as well. For
example, Azure OpenAI v1 uses deployment names as model identifiers:
ANCHOR_OPENAI_API_KEY=<your-azure-key>
ANCHOR_OPENAI_BASE_URL=https://<resource-name>.openai.azure.com/openai/v1/
ANCHOR_POLISH_MODEL=<vision-capable-deployment-name>
ANCHOR_REGION_MODEL=<vision-capable-deployment-name>
For Azure, ANCHOR_OPENAI_API_KEY must be the Azure resource key. A personal
OPENAI_API_KEY in your shell is not proof that the Azure project is
configured. The model values must be Azure deployment names, not base model
names.
An Ollama or other local OpenAI-compatible server can use the same wiring:
ANCHOR_OPENAI_API_KEY=local
ANCHOR_OPENAI_BASE_URL=http://localhost:11434/v1
ANCHOR_POLISH_MODEL=<vision-model-name>
ANCHOR_REGION_MODEL=<vision-model-name>
Use a model that accepts image input and evaluate extraction quality on your own documents before relying on extracted engineering values.
Embeddings use the local sentence-transformer model
BAAI/bge-small-en-v1.5 by default. The Python dependency ships with ANCHOR;
the model weights must already be cached or downloaded before fully offline
use.
5. Offline boundary¶
| Step | Local without a hosted API? | Notes |
|---|---|---|
| Store source PDF and render pages | Yes | Files stay under the project's .anchor_data/. |
| Silver extraction | Yes | Docling and local rendering. |
| Gold extraction and page polish | Conditional | Requires a configured vision endpoint; this may be local. |
| Region embeddings and search | Yes, after model availability | Local sentence-transformer default. |
| Workspace state, HTTP, SSE, MCP-stdio | Yes | Runs on the local machine. |
| Canvas snapshot | Yes | Requires local anchor serve and Chromium support. |
| Agent harness model calls | Outside ANCHOR | Governed by the harness you choose. |
Code pointers¶
- Harness installer:
src/anchor/adapters/cli/install.py - CLI wiring:
src/anchor/adapters/cli/main.py - MCP stdio entry:
src/anchor/adapters/mcp/stdio_main.py - MCP snapshot promotion:
src/anchor/adapters/mcp/server.py - Runtime configuration:
src/anchor/infra/config.py - PDF LLM adapters:
src/anchor/extensions/anchor_pdfs/infra/llm/