Admin & Configuration Guide

For administrators. This page covers every configuration surface: the admin pages, the config files, the skills (the assistant's instructions), and the embeddings catalog and its command-line tools. admin role required for the management pages & APIs

./strata-geoai hash-password 'your-new-password'

1. How it fits together

Three layers drive the assistant, and you tune each one differently:

• Data — REST only. Every data answer comes from the live ArcGIS Feature Service REST API against your layers. There is no local SQL engine and no data cache to manage.
• Instructions — the skills. Always-injected guidance that tells the Orchestrator and each specialist how to map plain language to tool calls. Edit these as Markdown files (§8).
• Retrieval — the embeddings. A local semantic catalog of your layers + API docs + tools. The assistant matches a question to the right layer/field/API by meaning. Managed from the Embeddings page (§9) and the CLIs (§10).

A request flows: [MAP CONTEXT] + question → Orchestrator plans → specialists (DataExploration, Geoprocessing, MapControl, Charts, Help) run tools → reply.

2. Admin pages

These live in the slide-out drawer (☰) and are visible only to users whose role is admin (set in config/users.json). The pages and their /geoai/admin/* APIs are enforced server-side, so they stay protected even if linked directly.

The pages share one Settings tab bar, so once you're on any of them you can hop between the rest.

Admin role is granted in config/users.json (each account has a role — see §3). The drawer links unhide for admins; the /geoai/admin/* endpoints return 403 for everyone else, so the pages stay protected even if linked directly.

3. Authentication, users & roles

Access is controlled by one flag: server.require_login in config.json (shipped default true). With it on, every data / chat / admin surface needs an identity; with it off (local dev) everything is open and no sign-in is asked. The bundled web UI signs in with a session cookie; external apps use OAuth tokens (§4) — both issued by the same user store, so identity is unified.

Signing in

• Login page — /login.html. A valid username + password sets an HttpOnly session cookie (cng_session, 12-hour lifetime); Log out is in the drawer.
• Each signed-in user gets their own isolated live map — one person's layers, selection, and saved-map edits never leak into another's session.
• Self-service sign-up (/register.html) is disabled when require_login=true; admins provision accounts on the Users page instead.

Roles

Saved-map access (ACL). Every saved map has an owner and a visibility: private (owner only), shared (owner + named grants, each view or edit), or public (everyone can view). Owners set this in the map properties dialog; admins can view/edit anything. Legacy maps normalize to a public, admin-owned entry on first read.

Managing users

Open Settings → Users (/users.html). You can add a member (username, password, role), change a role, and remove an account. The store refuses deleting yourself or the last remaining admin. Accounts persist to config/users.json; passwords are Argon2id-hashed (never plaintext), the file is git-ignored.

./strata-geoai hash-password 'the-new-password'

4. Signing in from an MCP client (OAuth 2.0)

Strata runs a small OAuth 2.0 authorization server for exactly one purpose: to let an MCP client — Claude Desktop — sign you in, so its tool calls run against your map. It is a sign-in mechanism, not an app platform.

How it works

1. The client discovers the server from GET /.well-known/oauth-protected-resource (advertised by the 401 WWW-Authenticate the MCP endpoint returns) and GET /.well-known/oauth-authorization-server.
2. It registers itself as a public PKCE client at POST /oauth/register (RFC 7591). No secret is issued.
3. It sends you to GET /oauth/authorize. You sign in with your normal account, then meet a consent screen naming the client and the access it wants. Every client sees this screen — the registration endpoint is open by necessity, so your explicit approval is what makes a client trusted.
4. It exchanges the one-time code at POST /oauth/token (PKCE S256 mandatory, code valid 60 s, single use) for an access token (1 hour) and a refresh token (30 days, rotated on use).
5. It sends Authorization: Bearer <token> to /mcp. Calls run against your session (user:<name>) and are logged with it to logs/mcp.log.

Endpoints & scopes

Scopes: maps:read, maps:write, mcp:tools (space-separated; omit to get all three). Deleting a user immediately invalidates their tokens.

First-party web UI vs. MCP clients

The bundled web UI signs in with a session cookie, not an OAuth token — the standard first-party pattern. The cookie and OAuth tokens come from the same user store, so identity is unified; OAuth is the door for MCP clients only (Claude Desktop — §5).

Errors

5. Connect Claude Desktop

Claude Desktop can drive this map directly: it connects to the MCP server as a native custom connector and calls the map tools. Map-mutating tools (add a layer, render by a field, buffer…) render on the live web map you have open at /; data/query tools return answers in Desktop. It runs under the Desktop subscription — no API key.

Prerequisites — HTTPS

Custom connectors require an https:// URL. The app serves plain HTTP on 127.0.0.1:8767/mcp; the bundled Caddy front provides the TLS hostname https://stratageoaimcp.localhost/mcp. So before connecting:

• the app is running (./start.sh),
• Caddy is up on :443 — it needs sudo; if https://…localhost can't be reached but http://127.0.0.1:8766 works, Caddy just isn't running (sudo caddy start --config ./Caddyfile),
• the mkcert local CA is trusted (once: mkcert -install).

See the MCP Server page (/mcp.html) for the copy-paste connector URL and the local-HTTPS setup.

Add the connector

1. In Claude Desktop: Settings → Connectors → Add custom connector.
2. Paste https://stratageoaimcp.localhost/mcp and save, then fully quit (⌘Q) and reopen Claude Desktop.
3. Keep the map open at / and prompt Desktop — e.g. “add the traffic cameras layer and render by county.”

Sign-in happens automatically over OAuth. With require_login on, Desktop's first call to /mcp gets a 401 with a WWW-Authenticate header pointing at the protected-resource metadata; Desktop discovers the authorization server, registers itself (DCR), runs the auth-code sign-in against your Strata login, and then calls with the token. Each person's tools run against their own map.

Fallback — the mcp-remote stdio bridge (OAuth-free)

If the native connector won't take the URL or OAuth misbehaves, bridge the plain-HTTP port via a local process. ./start.sh --claude writes this into ~/Library/Application Support/Claude/claude_desktop_config.json for you (and backs up the old file):

{ "mcpServers": {
    "strata-geoai": { "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:8767/mcp", "--allow-http"] } } }

This runs locally so it bypasses OAuth entirely. With require_login on it must still pass a token (--header "Authorization: Bearer $TOKEN"); for pure-local dev, keep require_login=false and no token is needed. After editing the config, ⌘Q and relaunch Desktop.

6. Configuration files

All configuration is file-based. Edits to config.json take effect on the next server start (skills can hot-reload separately — see §8).

Key config.json sections

7. Models & modes

Users toggle Local ↔ Cloud from the chat ☰ menu. The mapping lives in llm.modes: local → ollama (qwen2.5:7b-instruct), cloud → anthropic (Claude). The embedding model bge-m3 is infrastructure — it stays local in both modes and is never a user choice.

• Change a chat model — edit the provider's model under llm.providers (e.g. ollama.model, anthropic.model).
• Add / switch providers — llm.providers holds anthropic, gemini, grok, ollama, ollama_qwen3. Point a mode at one via llm.modes.
• API keys — never stored in config; each cloud provider reads an env var (api_key_env, e.g. ANTHROPIC_API_KEY). Cloud mode returns 409 if the key is missing.
• Changing the embedding model or embedding_dim forces a full re-embed (different vector space). Run rebuild-embeddings + ingest-docs after.

Setting up Ollama (local models)

The local mode and all embeddings run on Ollama — a local model runner. Install it, start it, and pull the two models the app expects. Ollama serves on http://localhost:11434 (matches llm.providers.ollama.base_url).

# 1. install Ollama (macOS: `brew install ollama`, or download from ollama.com), then start it
#    with the recommended performance flags (see note below):
OLLAMA_FLASH_ATTENTION=1 OLLAMA_KV_CACHE_TYPE=q8_0 ollama serve   # (the desktop app starts the server automatically)

# 2. pull the two models the app uses:
ollama pull qwen2.5:7b-instruct     # local chat / agent model
ollama pull bge-m3                  # embedding model

# 3. verify:
ollama list             # both models should appear

Performance flags (recommended). OLLAMA_FLASH_ATTENTION=1 speeds up long-context prefill, and OLLAMA_KV_CACHE_TYPE=q8_0 halves the memory of the 16K-token KV cache (it requires flash attention) — together they free enough headroom to run a larger local model (e.g. qwen2.5:14b) comfortably on a 16 GB machine, with quicker prefill on every turn. Set them on the ollama serve process. With the macOS desktop app (which auto-starts the server) set them once with launchctl setenv OLLAMA_FLASH_ATTENTION 1 and launchctl setenv OLLAMA_KV_CACHE_TYPE q8_0, then restart Ollama.

8. Skills — the assistant's instructions

“Skills” are Markdown instruction packs. They are always injected (not retrieved), so this is where you put durable, authoritative guidance. Two parts compose per turn:

1. prompts/system.md — the base system prompt, split into XML-tagged sections (<Shared>, <Orchestrator>, <DataExploration>, <Geoprocessing>, <MapControl>, <Charts>, <Help>).
2. skills/<role>/SKILL.md — a detailed pack appended for that role.

How to edit a skill

1. Open the relevant skills/<role>/SKILL.md in a text editor.
2. Write senior-to-junior, concrete guidance: name the tool, give exact arg shapes, flag case-sensitive field names. Use placeholders (<layer_id>) and mark example field names as illustrative — the model fills real values from [MAP CONTEXT].
3. Keep claims accurate: only reference tools/parameters that exist. A wrong parameter teaches the model to emit a broken call.
4. Apply: set llm.hot_reload_skills: true in config.json to pick up edits live, or restart the server (the default).

9. Embeddings catalog

One local DuckDB table (./data/registry.duckdb) holds a semantic fingerprint of every layer, doc chunk, and tool. Each row carries:

• embed_text — the string the vector is computed from (tuned for retrieval).
• grounding_text — the string injected into the prompt (tuned for readability — placeholdered URLs, “fields are illustrative” notes).
• agent — which specialist(s) a doc/tool serves (so grounding routes by agent).
• lang — en / ar; bilingual layers/exemplars store one row per language (bge-m3 also bridges across languages).

Day-to-day curation happens on the Embeddings page (/embeddings.html): view, add, edit, delete entries, and export the whole catalog as Markdown (GET /geoai/admin/embeddings.md) for offline review. Most entries are created automatically when you register a layer or run the doc ingest; you add entries by hand to teach extra domain knowledge.

10. Catalog command-line tools

Run from the project root with the server stopped. (Dev form shown; the built binary is strata <subcommand>.) The local embedding service (Ollama + bge-m3) must be running for any command that embeds.

The routine “fine-tune” loop

“Fine-tuning” here means curating the catalog content (not retraining a model):

# 1. edit a source: config/services.json  or  config/rest_samples_mdsf311.json
# 2. stop the server, then (Ollama running):
cargo run -- build-rest-chunks      # only if you changed REST exemplars
cargo run -- rebuild-embeddings     # only if you changed layers
cargo run -- ingest-docs            # embed docs
cargo run -- catalog-lint           # expect 0 errors / 0 warnings
cargo run -- eval-retrieval         # confirm recall held

11. MCP servers & basemaps

• MCP servers — register external Model Context Protocol tool servers on /mcp.html (or via /geoai/admin/mcp-servers). Each adds tools the agents can call.
• Basemaps — manage the gallery on /basemaps.html, or edit config.json → basemap.library (supports xyz and tile_server sources). basemap.default sets the startup basemap.

12. Common tasks (cheat-sheet)

← User Help Back to the map