roam-research-mcp 2.19.1 → 2.23.0

package/README.md

@@ -76,7 +76,7 @@ roam get "Page Title" -g work
 roam save "Note" -g work --write-key "$ROAM_SYSTEM_WRITE_KEY"
 ```
 
-**Available Commands:** `get`, `search`, `save`, `refs`, `update`, `batch`, `rename`, `status`.
+**Available Commands:** `get`, `search`, `save`, `refs`, `update`, `batch`, `rename`, `status`, `server`.
 Run `roam <command> --help` for details on any command.
 
 ### Installation
@@ -116,6 +116,47 @@ The MCP server exposes these tools to AI assistants (like Claude), enabling them
 | `roam_remember` / `roam_recall` | specialized tools for AI memory management within Roam. |
 | `roam_datomic_query` | Execute raw Datalog queries for advanced filtering. |
 | `roam_markdown_cheatsheet` | Retrieve the Roam-flavored markdown reference. |
+| `roam_get_guidelines` | Retrieve this graph's user-defined agent conventions. |
+
+---
+
+## Agent guidelines (per-graph)
+
+`roam_get_guidelines` reads a page **inside the graph** — `[[roam/agent guidelines]]` by default — holding your own conventions: how you tag, how you namespace pages, what an agent should never do. Roam's official MCP server reads the same page title, so one page serves both.
+
+This is distinct from `CUSTOM_INSTRUCTIONS_PATH`, and the two compose:
+
+| | `CUSTOM_INSTRUCTIONS_PATH` | `[[roam/agent guidelines]]` |
+|---|---|---|
+| Lives in | a file on disk | a page in the graph |
+| Scope | server-wide, all graphs | **per-graph** |
+| To change it | edit the file, restart the server | edit the page |
+| Answers | how to write Roam markdown | how *this user* wants *this graph* handled |
+
+Configure per graph, or disable with `false`:
+
+```bash
+ROAM_GRAPHS='{"personal": {"token": "...", "graph": "...", "guidelinesPage": "roam/agent guidelines"}, "work": {"token": "...", "graph": "...", "guidelinesPage": false}}'
+ROAM_GUIDELINES_PAGE='roam/agent guidelines'   # fallback when a graph sets none
+```
+
+If no such page exists the tool returns `exists: false` rather than failing, so it is safe to call unconditionally. Results are cached for 30 seconds — an edit to the page takes effect without a restart. A starter template lives at [`.roam/agent-guidelines.template.md`](.roam/agent-guidelines.template.md).
+
+Note that guidelines are read through the normal page path, so blocks tagged `#.rm-hide` / `#.rm-private` are withheld from them too — see below.
+
+---
+
+## Hiding content from the AI
+
+Blocks tagged `#.rm-hide` or `#.rm-private` — and everything nested under them — are omitted from the content these tools return. Both the hashtag (`#.rm-hide`, `#[[.rm-hide]]`) and link (`[[.rm-hide]]`) forms work. `.rm-private` is Roam's existing "hidden from other users" tag; `.rm-hide` hides from the AI specifically.
+
+This follows the same convention as Roam's official MCP server, so a block tagged for one is hidden from the other.
+
+Applied to: `roam_fetch_page_by_title`, `roam_fetch_block`, `roam_fetch_page_full_view`, `roam_get_subpages`, `roam_search_by_text`, `roam_search_for_tag`, `roam_search_by_status`, `roam_search_block_refs`, `roam_search_hierarchy`, `roam_search_by_date`.
+
+**This is a convenience filter, not a security guarantee.** `roam_datomic_query` reads the database directly and deliberately does **not** apply it, so a capable agent can still surface hidden blocks through raw Datalog. Treat these tags as "keep it out of the AI's way," not "keep it secret."
+
+Tag matching is case-insensitive, and only exact tags match — `#.rm-hidden` and `#.rm-highlight` are left alone. The set of hidden UIDs is cached for 30 seconds, so a block tagged just now may remain visible for up to that long.
 
 ---
 
@@ -155,35 +196,114 @@ ROAM_SYSTEM_WRITE_KEY=your-secret-key
 | `protected` | No | If `true`, writes require `ROAM_SYSTEM_WRITE_KEY` confirmation |
 | `memoriesTag` | No | Tag for `roam_remember`/`roam_recall` (overrides global default) |
 
-**Write Protection:**
-Protected graphs require the `write_key` parameter matching `ROAM_SYSTEM_WRITE_KEY` for any write operation. This prevents accidental writes to sensitive graphs.
+**Two kinds of access control (and how they differ)**
+
+The server has two independent locks. They're easy to mix up because both are "keys" — here's the plain version (both are **optional and off by default**):
+
+| | **Bearer token** — `HTTP_AUTH_TOKEN` | **Write key** — `ROAM_SYSTEM_WRITE_KEY` |
+|---|---|---|
+| In a phrase | The key to the **front door** | The latch on a **safe inside** |
+| Controls | *Who can reach the server at all* | *Whether a write to a `protected` graph is allowed* |
+| Covers | Everything — reads **and** writes, all graphs | Only **writes**, and only to graphs marked `protected` |
+| Protects reading? | **Yes** | **No** |
+| When you need it | Only if the server is reachable beyond your own machine (e.g. `-H 0.0.0.0`) | Whenever you want a guard against accidental edits to important graphs |
+| How it's sent | HTTP header: `Authorization: Bearer <token>` | A `write_key` argument on write tools / CLI commands |
+
+Think of a house: the **bearer token locks the front door** (keeps strangers out entirely), and the **write key locks a safe inside** (even someone already in the house needs it to change what's in the safe). On your own machine bound to `127.0.0.1`, the front door faces a wall — you don't need the bearer token there. The write key is still handy locally as an "are you sure?" guard, because **Roam has no undo**.
+
+So: to mark a graph as needing the write key, set `protected: true` on it and configure `ROAM_SYSTEM_WRITE_KEY`; callers then pass a matching `write_key` for any write to that graph.
 
 *Optional:*
 - `ROAM_MEMORIES_TAG`: Default tag for `roam_remember`/`roam_recall` (fallback when per-graph `memoriesTag` not set).
-- `HTTP_STREAM_PORT`: To enable HTTP Stream (defaults to 8088).
+- `HTTP_STREAM_PORT`: Port for the HTTP Stream transport (defaults to 8088).
+- `HTTP_STREAM_HOST`: Host to bind the HTTP transport to in `--server` mode (defaults to `127.0.0.1`, loopback-only). Set to `0.0.0.0` to expose on the LAN.
+- `HTTP_AUTH_TOKEN`: Optional bearer token that locks the **whole** HTTP endpoint. Unset = open (fine for loopback). When set, every MCP request must send `Authorization: Bearer <token>` (`GET /health` stays open). Use it whenever you bind beyond `127.0.0.1`. Different from `ROAM_SYSTEM_WRITE_KEY` — see [Two kinds of access control](#two-kinds-of-access-control-and-how-they-differ).
 
 ### Running the Server
 
-**1. Stdio Mode (Default)**
-Best for local integration (e.g., Claude Desktop, IDE extensions).
+**1. Default Mode (stdio + HTTP)**
+Best for local integration (e.g., Claude Desktop, IDE extensions). The MCP client launches the process per session over stdio; an HTTP Stream transport is also opened on an auto-discovered port near `HTTP_STREAM_PORT`.
 
 ```bash
 npx roam-research-mcp
 ```
 
-Note: Stdio mode does not use any network ports.
+**2. Shared Server Mode (`--server`)**
+Best for a single long-lived, HTTP-only daemon that **multiple MCP clients share** — instead of each session spawning its own subprocess. This saves memory and gives clients a stable URL.
+
+```bash
+HTTP_STREAM_PORT=8088 npx roam-research-mcp --server
+```
+
+Or manage it through the `roam` CLI, which adds start/stop/status/logs:
+
+```bash
+roam server start            # start the shared daemon in the background
+roam server start -H 0.0.0.0 # expose on the LAN (no transport auth!)
+roam server status           # is it up? version, graphs, active sessions
+roam server logs -f          # follow the log
+roam server stop             # stop a CLI-started daemon
+```
+
+`roam server status` works no matter how the daemon was launched (it probes `/health`), so it also reports a daemon started by a LaunchAgent/systemd unit. State (pidfile + log) lives in `~/.roam/` (override with `ROAM_HOME`).
+
+In `--server` mode the server:
+- runs **HTTP-only** (no stdio transport),
+- binds the **exact** `HTTP_STREAM_PORT` on `HTTP_STREAM_HOST` and **exits non-zero if the port is taken** (no silent drift — a shared daemon must keep a stable URL),
+- exposes `GET /health` → `{"status":"ok", ...}` for liveness checks.
+
+Point MCP clients at it with an HTTP transport config:
+
+```json
+{
+  "mcpServers": {
+    "roam-research-mcp": {
+      "type": "http",
+      "url": "http://127.0.0.1:8088/mcp"
+    }
+  }
+}
+```
+
+Env vars (tokens, graphs) live with the **server** process, not the client config.
+
+**Securing an exposed server (two layers):**
+If you bind beyond loopback (`-H 0.0.0.0`), add the perimeter lock:
+
+```bash
+HTTP_AUTH_TOKEN=$(openssl rand -hex 32) roam server start -H 0.0.0.0
+```
+
+Clients then send the token as a header:
+
+```json
+{
+  "mcpServers": {
+    "roam-research-mcp": {
+      "type": "http",
+      "url": "http://<host>:8088/mcp",
+      "headers": { "Authorization": "Bearer <token>" }
+    }
+  }
+}
+```
+
+Keep **both** — they do different jobs (see [Two kinds of access control](#two-kinds-of-access-control-and-how-they-differ) above): the bearer token controls **who can connect**, the write key only guards **writes to protected graphs**.
+
+> ⚠️ The write key is **not** a substitute for the bearer token. On an exposed server without `HTTP_AUTH_TOKEN`, anyone on the network can still **read every graph** (and write non-protected ones). For anything beyond loopback, set `HTTP_AUTH_TOKEN`.
 
-**2. HTTP Stream Mode**
-Best for remote access or web clients.
+**Keeping it running (macOS LaunchAgent):**
+Create `~/Library/LaunchAgents/com.example.roam-mcp.plist` with `RunAtLoad` + `KeepAlive`, your env vars under `EnvironmentVariables`, and `--server` as the last `ProgramArguments` entry. Keep `StandardOutPath`/`StandardErrorPath` on a **local** path (e.g. `~/Library/Logs/`), then:
 
 ```bash
-HTTP_STREAM_PORT=8088 npx roam-research-mcp
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.roam-mcp.plist
+curl -s http://127.0.0.1:8088/health   # verify
 ```
 
 **3. Docker**
 
 ```bash
-docker run -p 8088:8088 --env-file .env roam-research-mcp
+docker run -p 8088:8088 --env-file .env roam-research-mcp --server
 ```
 
 ### Configuring in LLMs

package/build/Roam_Markdown_Cheatsheet.md

@@ -23,6 +23,7 @@
 
 ⚠️ Never concatenate: `#knowledgemanagement` ≠ `#[[knowledge management]]`
 ⚠️ `#` always creates tags — write `Step 1` not `#1`
+⚠️ Because `#` creates tags, a bare `#N` silently creates a numbered page. When you must show the literal form, put it in quotes: `"#1"`, `"#2"` — otherwise rephrase (`Step 1`, `No. 1`, `item 1`)
 
 ### Dates
 Always ordinal format: `[[January 1st, 2025]]`, `[[December 23rd, 2024]]`
@@ -161,7 +162,7 @@ Theme via CSS: `:root { --mermaidjs-theme: dark; }` (in `roam/css`)
 | ❌ Wrong | ✅ Correct |
 |----------|-----------|
 | `#multiplewords` | `#[[multiple words]]` |
-| `#1`, `#2` | `Step 1`, `No. 1` |
+| `#1`, `#2` | `Step 1`, `No. 1`, or quoted: `"#1"` |
 | `[[january 1, 2025]]` | `[[January 1st, 2025]]` |
 | `[text](((uid)))` | `[text](<((uid))>)` |
 | `{{embed: ((uid))}}` | `{{[[embed]]: ((uid))}}` |

package/build/cli/commands/server.js

@@ -0,0 +1,240 @@
+import { Command } from 'commander';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, readFileSync, writeFileSync, unlinkSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { get as httpGet } from 'node:http';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Path to the MCP server entry (build/index.js) relative to this command
+// (build/cli/commands/server.js -> build/index.js).
+const SERVER_ENTRY = join(__dirname, '../../index.js');
+// State dir for the CLI-managed daemon (pidfile + logfile). Local path by
+// default — overridable via ROAM_HOME. Kept off external volumes so launchd /
+// the daemon never hits the macOS provenance-xattr EPERM trap.
+const STATE_DIR = process.env.ROAM_HOME || join(homedir(), '.roam');
+const PID_FILE = join(STATE_DIR, 'server.pid');
+const LOG_FILE = join(STATE_DIR, 'server.log');
+const DEFAULT_PORT = process.env.HTTP_STREAM_PORT || '8088';
+const DEFAULT_HOST = process.env.HTTP_STREAM_HOST || '127.0.0.1';
+/** Probe GET /health. Returns parsed info, or null if nothing is serving. */
+function checkHealth(host, port, timeoutMs = 2000) {
+    // 0.0.0.0 is a bind address, not a connect address — probe loopback instead.
+    const target = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host;
+    return new Promise((resolve) => {
+        const req = httpGet({ host: target, port, path: '/health', timeout: timeoutMs }, (res) => {
+            let body = '';
+            res.on('data', (c) => (body += c));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    resolve(null);
+                }
+            });
+        });
+        req.on('error', () => resolve(null));
+        req.on('timeout', () => {
+            req.destroy();
+            resolve(null);
+        });
+    });
+}
+function readPid() {
+    if (!existsSync(PID_FILE))
+        return null;
+    const raw = readFileSync(PID_FILE, 'utf8').trim();
+    const pid = parseInt(raw, 10);
+    return Number.isFinite(pid) ? pid : null;
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // EPERM means it exists but we can't signal it; ESRCH means gone.
+        return err.code === 'EPERM';
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function createStartCommand() {
+    return new Command('start')
+        .description('Start the shared HTTP MCP server (HTTP-only daemon)')
+        .option('-p, --port <port>', 'Port to bind', DEFAULT_PORT)
+        .option('-H, --host <host>', 'Host to bind (use 0.0.0.0 to expose on LAN)', DEFAULT_HOST)
+        .option('-f, --foreground', 'Run in the foreground instead of detaching', false)
+        .action(async (options) => {
+        const { port, host, foreground } = options;
+        // Don't start a second copy if one is already serving this address.
+        const existing = await checkHealth(host, port);
+        if (existing) {
+            console.log(`Already running on http://${host}:${port}/ (v${existing.version ?? '?'}, ${existing.activeSessions ?? 0} session(s)).`);
+            return;
+        }
+        if (!existsSync(SERVER_ENTRY)) {
+            console.error(`Error: server entry not found at ${SERVER_ENTRY}. Run "npm run build" first.`);
+            process.exit(1);
+        }
+        const env = { ...process.env, HTTP_STREAM_PORT: port, HTTP_STREAM_HOST: host };
+        if (foreground) {
+            const child = spawn(process.execPath, [SERVER_ENTRY, '--server'], { env, stdio: 'inherit' });
+            child.on('exit', (code) => process.exit(code ?? 0));
+            return;
+        }
+        // Detached background launch: logs to LOG_FILE, pid recorded in PID_FILE.
+        if (!existsSync(STATE_DIR))
+            mkdirSync(STATE_DIR, { recursive: true });
+        const out = openSync(LOG_FILE, 'a');
+        const child = spawn(process.execPath, [SERVER_ENTRY, '--server'], {
+            env,
+            detached: true,
+            stdio: ['ignore', out, out],
+        });
+        child.unref();
+        if (child.pid)
+            writeFileSync(PID_FILE, String(child.pid));
+        // Confirm it actually came up (port-in-use fails loudly and exits).
+        let health = null;
+        for (let i = 0; i < 10 && !health; i++) {
+            await sleep(300);
+            if (child.pid && !isAlive(child.pid))
+                break;
+            health = await checkHealth(host, port);
+        }
+        if (health) {
+            console.log(`Started (pid ${child.pid}) on http://${host}:${port}/`);
+            console.log(`  health: http://${host}:${port}/health`);
+            console.log(`  logs:   ${LOG_FILE}  (roam server logs -f)`);
+        }
+        else {
+            console.error(`Failed to confirm startup. Check logs: ${LOG_FILE}`);
+            if (existsSync(PID_FILE))
+                unlinkSync(PID_FILE);
+            process.exit(1);
+        }
+    });
+}
+function createStopCommand() {
+    return new Command('stop')
+        .description('Stop a CLI-started server (see notes for service-managed daemons)')
+        .option('-H, --host <host>', 'Host to probe', DEFAULT_HOST)
+        .option('-p, --port <port>', 'Port to probe', DEFAULT_PORT)
+        .action(async (options) => {
+        const pid = readPid();
+        if (pid && isAlive(pid)) {
+            process.kill(pid, 'SIGTERM');
+            for (let i = 0; i < 20 && isAlive(pid); i++)
+                await sleep(100);
+            if (isAlive(pid)) {
+                console.error(`Process ${pid} did not stop after SIGTERM.`);
+                process.exit(1);
+            }
+            if (existsSync(PID_FILE))
+                unlinkSync(PID_FILE);
+            console.log(`Stopped (pid ${pid}).`);
+            return;
+        }
+        if (existsSync(PID_FILE))
+            unlinkSync(PID_FILE);
+        // No CLI-managed process — but something may still be serving via a
+        // service manager (launchd/systemd). Don't pretend we stopped it.
+        const health = await checkHealth(options.host, options.port);
+        if (health) {
+            console.log(`Not started by this CLI, but a server is responding on http://${options.host}:${options.port}/.`);
+            console.log(`It is likely managed by a service manager (e.g. launchd/systemd) — stop it there.`);
+            return;
+        }
+        console.log('Not running.');
+    });
+}
+function createStatusCommand() {
+    return new Command('status')
+        .description('Check whether the shared HTTP server is running')
+        .option('-H, --host <host>', 'Host to probe', DEFAULT_HOST)
+        .option('-p, --port <port>', 'Port to probe', DEFAULT_PORT)
+        .option('--json', 'Output as JSON', false)
+        .action(async (options) => {
+        const { host, port } = options;
+        const health = await checkHealth(host, port);
+        const pid = readPid();
+        const pidAlive = pid !== null && isAlive(pid);
+        if (options.json) {
+            console.log(JSON.stringify({
+                running: !!health,
+                url: `http://${host}:${port}/mcp`,
+                managedPid: pidAlive ? pid : null,
+                health: health ?? null,
+            }, null, 2));
+            return;
+        }
+        if (health) {
+            console.log(`● running — http://${host}:${port}/`);
+            console.log(`  version:        ${health.version ?? '?'}`);
+            console.log(`  mode:           ${health.mode ?? '?'}`);
+            console.log(`  auth:           ${health.auth ?? 'none'}`);
+            console.log(`  graphs:         ${(health.graphs ?? []).join(', ')}`);
+            console.log(`  default graph:  ${health.defaultGraph ?? '?'}`);
+            console.log(`  active sessions:${' '}${health.activeSessions ?? 0}`);
+            console.log(`  endpoint:       http://${host}:${port}/mcp`);
+            console.log(pidAlive
+                ? `  managed by:     this CLI (pid ${pid})`
+                : `  managed by:     external supervisor (not this CLI)`);
+        }
+        else {
+            console.log(`○ not running on http://${host}:${port}/`);
+            if (pidAlive)
+                console.log(`  (stale pidfile process ${pid} alive but not serving — try: roam server stop)`);
+        }
+    });
+}
+function createLogsCommand() {
+    return new Command('logs')
+        .description('Tail the CLI-managed server log')
+        .option('-f, --follow', 'Follow the log (like tail -f)', false)
+        .option('-n, --lines <n>', 'Number of lines to show', '50')
+        .action((options) => {
+        if (!existsSync(LOG_FILE)) {
+            console.error(`No CLI log at ${LOG_FILE}.`);
+            console.error('The server may not have been started via "roam server start"');
+            console.error('(e.g. a launchd/systemd service logs to its own configured path).');
+            process.exit(1);
+        }
+        const args = ['-n', options.lines];
+        if (options.follow)
+            args.push('-f');
+        args.push(LOG_FILE);
+        const child = spawn('tail', args, { stdio: 'inherit' });
+        child.on('exit', (code) => process.exit(code ?? 0));
+    });
+}
+export function createServerCommand() {
+    const server = new Command('server')
+        .description('Run/manage the shared HTTP MCP server (start/stop/status/logs)')
+        .addHelpText('after', `
+The shared server is a single long-lived, HTTP-only MCP daemon that multiple
+clients connect to over HTTP — instead of each session spawning its own copy.
+Point clients at it with:  { "type": "http", "url": "http://${DEFAULT_HOST}:${DEFAULT_PORT}/mcp" }
+
+Examples:
+  roam server start                 # start in the background (port ${DEFAULT_PORT})
+  roam server start -p 9000 -f      # foreground on port 9000
+  roam server start -H 0.0.0.0      # expose on the LAN (no transport auth!)
+  roam server status                # is it up? version, graphs, sessions
+  roam server logs -f               # follow the log
+  roam server stop                  # stop a CLI-started daemon
+
+Config comes from the environment (ROAM_GRAPHS / ROAM_API_TOKEN, etc.), same
+as the rest of the CLI. State dir: ${STATE_DIR} (override with ROAM_HOME).
+For an always-on daemon, run "roam server start" from a launchd/systemd unit.
+`);
+    server.addCommand(createStartCommand());
+    server.addCommand(createStopCommand());
+    server.addCommand(createStatusCommand());
+    server.addCommand(createLogsCommand());
+    // No subcommand → show help rather than erroring.
+    server.action(() => server.help());
+    return server;
+}

package/build/cli/roam.js

@@ -11,6 +11,7 @@ import { createUpdateCommand } from './commands/update.js';
 import { createBatchCommand } from './commands/batch.js';
 import { createRenameCommand } from './commands/rename.js';
 import { createStatusCommand } from './commands/status.js';
+import { createServerCommand } from './commands/server.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Read package.json to get the version
@@ -31,5 +32,6 @@ program.addCommand(createUpdateCommand());
 program.addCommand(createBatchCommand());
 program.addCommand(createRenameCommand());
 program.addCommand(createStatusCommand());
+program.addCommand(createServerCommand());
 // Parse arguments
 program.parse();

package/build/cli/utils/graph.js

@@ -33,8 +33,10 @@ export function resolveGraph(options, isWriteOp = false) {
                 if (!systemWriteKey) {
                     throw new Error(`Write to protected graph "${graphKey}" failed: ROAM_SYSTEM_WRITE_KEY not configured.`);
                 }
-                throw new Error(`Write to "${graphKey}" graph requires --write-key confirmation.\n` +
-                    `Use: --write-key "${systemWriteKey}"`);
+                // Never echo the key itself — CLI output lands in scrollback, logs and
+                // transcripts. Name the variable so the shell can expand it instead.
+                throw new Error(`Write to protected graph "${graphKey}" requires --write-key confirmation.\n` +
+                    `Use: --write-key "$ROAM_SYSTEM_WRITE_KEY"`);
             }
         }
     }

package/build/config/environment.js

@@ -11,6 +11,14 @@ if (existsSync(envPath)) {
 }
 // HTTP server configuration
 const HTTP_STREAM_PORT = process.env.HTTP_STREAM_PORT || '8088';
+// Host to bind the HTTP transport to. Only applied in --server (daemon) mode.
+// Defaults to loopback so a shared server is not exposed beyond this machine.
+const HTTP_STREAM_HOST = process.env.HTTP_STREAM_HOST || '127.0.0.1';
+// Optional transport-level bearer token (authentication). When set, every HTTP
+// MCP request must send `Authorization: Bearer <token>` (the /health probe stays
+// open). Unset = open, i.e. unchanged. This is the perimeter lock; it is separate
+// from ROAM_SYSTEM_WRITE_KEY, which is per-graph write authorization.
+const HTTP_AUTH_TOKEN = process.env.HTTP_AUTH_TOKEN;
 const CORS_ORIGINS = (process.env.CORS_ORIGIN || 'http://localhost:5678,https://roamresearch.com')
     .split(',')
     .map(origin => origin.trim());
@@ -81,4 +89,4 @@ export function validateEnvironment() {
         }
     }
 }
-export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, CORS_ORIGINS, ROAM_GRAPHS, ROAM_DEFAULT_GRAPH };
+export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, HTTP_STREAM_HOST, HTTP_AUTH_TOKEN, CORS_ORIGINS, ROAM_GRAPHS, ROAM_DEFAULT_GRAPH };

package/build/config/graph-registry.js

@@ -8,7 +8,7 @@
  * - Lazy graph initialization (connects only when first accessed)
  */
 import { initializeGraph } from '@roam-research/roam-api-sdk';
-import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { RoamError } from '../shared/errors.js';
 /** List of tool names that perform write operations */
 export const WRITE_OPERATIONS = [
     'roam_create_page',
@@ -69,6 +69,18 @@ export class GraphRegistry {
         // Priority: per-graph config > env var > default
         return config?.memoriesTag ?? process.env.ROAM_MEMORIES_TAG ?? 'Memories';
     }
+    /**
+     * Page holding a graph's agent conventions, or null when disabled.
+     * Same precedence as memoriesTag: per-graph config > env var > default.
+     */
+    getGuidelinesPage(key) {
+        const resolvedKey = key ?? this.defaultKey;
+        const config = this.configs.get(resolvedKey);
+        if (config?.guidelinesPage === false) {
+            return null;
+        }
+        return config?.guidelinesPage ?? process.env.ROAM_GUIDELINES_PAGE ?? 'roam/agent guidelines';
+    }
     /**
      * Get an initialized Graph instance, creating it lazily if needed
      * @param key - Graph key from config. Defaults to defaultKey if not specified.
@@ -83,7 +95,7 @@ export class GraphRegistry {
         // Get config
         const config = this.configs.get(resolvedKey);
         if (!config) {
-            throw new McpError(ErrorCode.InvalidParams, `Unknown graph: "${resolvedKey}". Available graphs: ${this.getAvailableGraphs().join(', ')}`);
+            throw new RoamError(`Unknown graph: "${resolvedKey}".`, 'UNKNOWN_GRAPH', { requested_graph: resolvedKey, available_graphs: this.getAvailableGraphs() });
         }
         // Initialize the graph
         const graph = initializeGraph({
@@ -131,15 +143,19 @@ export class GraphRegistry {
         if (!this.isWriteAllowed(resolvedKey, providedWriteKey)) {
             const config = this.configs.get(resolvedKey);
             if (!config) {
-                throw new McpError(ErrorCode.InvalidParams, `Unknown graph: "${resolvedKey}". Available graphs: ${this.getAvailableGraphs().join(', ')}`);
+                throw new RoamError(`Unknown graph: "${resolvedKey}".`, 'UNKNOWN_GRAPH', { requested_graph: resolvedKey, available_graphs: this.getAvailableGraphs() });
             }
             const systemWriteKey = process.env.ROAM_SYSTEM_WRITE_KEY;
             if (!systemWriteKey) {
-                throw new McpError(ErrorCode.InvalidParams, `Write to protected graph "${resolvedKey}" failed: ROAM_SYSTEM_WRITE_KEY not configured.`);
+                throw new RoamError(`Write to protected graph "${resolvedKey}" failed: ROAM_SYSTEM_WRITE_KEY is not configured on the server.`, 'WRITE_KEY_NOT_CONFIGURED', { graph: resolvedKey });
             }
-            // Provide informative error with the required key
-            throw new McpError(ErrorCode.InvalidParams, `Write to "${resolvedKey}" graph requires write_key confirmation.\n` +
-                `Provide write_key: "${systemWriteKey}" to proceed.`);
+            // Say what is required, never what the value is. Echoing the key here
+            // hands the caller the means to retry and get through, which makes the
+            // whole gate decorative — including for a caller that simply guessed
+            // wrong. A legitimate operator can read ROAM_SYSTEM_WRITE_KEY from their
+            // own environment; an agent that cannot is exactly who this stops.
+            throw new RoamError(`Write to protected graph "${resolvedKey}" requires write_key confirmation. ` +
+                `Pass the value of the ROAM_SYSTEM_WRITE_KEY environment variable as the write_key parameter.`, 'WRITE_KEY_REQUIRED', { graph: resolvedKey, required_parameter: 'write_key' });
         }
     }
     /**

package/build/config/graph-registry.test.js

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { GraphRegistry } from './graph-registry.js';
 describe('GraphRegistry', () => {
     describe('getMemoriesTag', () => {
@@ -65,3 +65,94 @@ describe('GraphRegistry', () => {
         });
     });
 });
+describe('getGuidelinesPage', () => {
+    const make = (configs, def = 'personal') => new GraphRegistry(configs, def);
+    it('defaults to the shared roam/agent guidelines convention', () => {
+        delete process.env.ROAM_GUIDELINES_PAGE;
+        const r = make({ personal: { token: 't', graph: 'g' } });
+        expect(r.getGuidelinesPage('personal')).toBe('roam/agent guidelines');
+    });
+    it('prefers per-graph config over the env var', () => {
+        process.env.ROAM_GUIDELINES_PAGE = 'env/page';
+        const r = make({ work: { token: 't', graph: 'g', guidelinesPage: 'work/rules' } }, 'work');
+        expect(r.getGuidelinesPage('work')).toBe('work/rules');
+        delete process.env.ROAM_GUIDELINES_PAGE;
+    });
+    it('falls back to the env var when a graph sets nothing', () => {
+        process.env.ROAM_GUIDELINES_PAGE = 'env/page';
+        const r = make({ personal: { token: 't', graph: 'g' } });
+        expect(r.getGuidelinesPage('personal')).toBe('env/page');
+        delete process.env.ROAM_GUIDELINES_PAGE;
+    });
+    it('returns null when a graph disables guidelines', () => {
+        const r = make({ personal: { token: 't', graph: 'g', guidelinesPage: false } });
+        expect(r.getGuidelinesPage('personal')).toBeNull();
+    });
+    it('resolves the default graph when no key is given', () => {
+        delete process.env.ROAM_GUIDELINES_PAGE;
+        const r = make({ personal: { token: 't', graph: 'g', guidelinesPage: 'p/rules' } });
+        expect(r.getGuidelinesPage()).toBe('p/rules');
+    });
+});
+describe('write-key denial does not disclose the key', () => {
+    /**
+     * The write key is the whole gate on protected graphs. An error that tells
+     * the caller what the key is hands the agent the means to retry and get
+     * through — the protection becomes decorative.
+     */
+    const SECRET = 'super-secret-write-key';
+    const original = process.env.ROAM_SYSTEM_WRITE_KEY;
+    beforeEach(() => {
+        process.env.ROAM_SYSTEM_WRITE_KEY = SECRET;
+    });
+    afterEach(() => {
+        if (original !== undefined)
+            process.env.ROAM_SYSTEM_WRITE_KEY = original;
+        else
+            delete process.env.ROAM_SYSTEM_WRITE_KEY;
+    });
+    // 'work' must be NON-default: writes to the default graph bypass protection
+    // by design, so a protected default graph never reaches the denial path.
+    const protectedRegistry = () => new GraphRegistry({
+        personal: { token: 't', graph: 'p' },
+        work: { token: 't', graph: 'g', protected: true },
+    }, 'personal');
+    it('never puts the key in the denial message', () => {
+        let message = '';
+        try {
+            protectedRegistry().validateWriteAccess('roam_create_page', 'work', undefined);
+        }
+        catch (e) {
+            message = e.message;
+        }
+        expect(message, 'denial message must not be empty').not.toBe('');
+        expect(message).not.toContain(SECRET);
+    });
+    it('never discloses the key when a wrong one is supplied', () => {
+        let message = '';
+        try {
+            protectedRegistry().validateWriteAccess('roam_create_page', 'work', 'wrong-guess');
+        }
+        catch (e) {
+            message = e.message;
+        }
+        expect(message).not.toContain(SECRET);
+    });
+    it('still explains what is required, so a legitimate caller can proceed', () => {
+        let message = '';
+        try {
+            protectedRegistry().validateWriteAccess('roam_create_page', 'work', undefined);
+        }
+        catch (e) {
+            message = e.message;
+        }
+        expect(message).toMatch(/write_key/);
+        expect(message).toMatch(/work/);
+    });
+    it('lets a correct key through', () => {
+        expect(() => protectedRegistry().validateWriteAccess('roam_create_page', 'work', SECRET)).not.toThrow();
+    });
+    it('does not gate reads on protected graphs', () => {
+        expect(() => protectedRegistry().validateWriteAccess('roam_search_by_text', 'work', undefined)).not.toThrow();
+    });
+});