roam-research-mcp 2.19.1 → 2.22.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
@@ -160,30 +160,97 @@ Protected graphs require the `write_key` parameter matching `ROAM_SYSTEM_WRITE_K
 
 *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 for the HTTP MCP endpoint (**authentication**). Unset = open (fine for loopback). When set, every HTTP MCP request must send `Authorization: Bearer <token>` (`GET /health` stays open). Use it whenever you bind beyond `127.0.0.1`. This is separate from `ROAM_SYSTEM_WRITE_KEY` (per-graph write authorization).
 
 ### 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.
 
-**2. HTTP Stream Mode**
-Best for remote access or web clients.
+```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>" }
+    }
+  }
+}
+```
+
+These are two **distinct** layers — keep both:
+- **`HTTP_AUTH_TOKEN`** = *authentication* (who may connect). Gates **all** requests — reads and writes, every graph.
+- **`ROAM_SYSTEM_WRITE_KEY`** = *authorization* (what a connected caller may do). Gates only **writes** to `protected` graphs; it does **not** protect reads.
+
+> ⚠️ `write_key` is **not** transport auth. On an exposed server without `HTTP_AUTH_TOKEN`, anyone on the network can still **read every graph** and write non-protected graphs. For anything beyond loopback, set `HTTP_AUTH_TOKEN`.
+
+**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

@@ -243,8 +243,6 @@ Server returns `{"uid_map": {"parent": "Xk7mN2pQ9"}}`.
 **Open question:** `{{[[TODO]]}} Research: <question> #[[open questions]]`
 
 ---
-<personalization_layer>
-
 # Roam Preferences — Personalization Layer
 
 > This section contains YOUR specific conventions, tagging philosophy, and graph-specific rules. Customize to match your workflow.
@@ -253,21 +251,199 @@ Server returns `{"uid_map": {"parent": "Xk7mN2pQ9"}}`.
 
 ## Graph-Level Behaviors
 
+### On Creating New Pages
+<!-- CUSTOMIZE: What should happen when a new page is created? -->
+- After creating a new page, add a reference block on today's daily page: `Created page: [[New Page Name]]`
+- <!-- Add any naming conventions, required metadata, etc. -->
+
+### On Adding Content
+<!-- CUSTOMIZE: Any rules about where/how content gets added? -->
+- Default location for quick captures: Daily page
+- Long-form content: Create dedicated page, link from daily page
+- <!-- Your preferences here -->
+
+---
 
 ## Tagging Philosophy
 
+### Core Principle
+> Tag for **intellectual collision** and **future discovery**, not just categorization. Every tag should maximize potential for unexpected connections.
+
+### The Serendipity Test
+Before tagging, ask: *"Could this concept surprise me by connecting to something completely unrelated?"*
+
+### What To Tag — Decision Framework
+
+```
+ASK YOURSELF:
+┌─ How will Future Me find this?
+│   └─ Tag by retrieval context, not just content
+│
+├─ What domain does this belong to?
+│   └─ Use broad category tags: #[[knowledge management]], #[[decision-making]]
+│
+├─ Is this a proper noun?
+│   └─ YES → Wrap name (no titles): [[Werner Erhard]], [[NASA]]
+│   └─ For abbreviations: [NASA]([[National Aeronautics and Space Administration (NASA)]])
+│
+├─ Could this alias to existing page?
+│   └─ YES → [displayed phrase]([[existing page name]])
+│   └─ Example: [frameworks for decisions]([[decision-making frameworks]])
+│
+└─ Parent block with children?
+    └─ Tag parent when category applies to all children
+    └─ Tag individual children for specific categorization
+```
+
+### Tag Type Selection
+
+| Use This | When |
+|----------|------|
+| `[[Page Reference]]` | Concept deserves its own page, will be expanded |
+| `#[[hashtag]]` | Categorization, filtering, won't be a standalone page |
+| `#single-word` | Simple, unambiguous category |
+| Attribute `Type::` | Structured metadata for queries |
+
+### WHEN creating Endnotes/Footnotes:
+- Find/Create the block with heading "Footnotes::" and nest footnote item below. (Footnotes do not need to be on the same page as the block to which it references. Typically on the same page unless instructed otherwise.)
+- If not known, retrieve the block_uid reference for this footnote item.
+- In the block referencing the footnote, append the reference with footnote-item-block_id, example: "- <block_text> #ref ((block_uid))"
+
+### Structural Tagging (Beyond Content)
+
+Tag by **patterns and mechanisms**, not just subjects:
+
+| Structural Tag | Connects |
+|----------------|----------|
+| `#[[has feedback loops]]` | Systems, habits, markets, conversations |
+| `#[[requires calibration]]` | Instruments, relationships, AI prompts |
+| `#[[exhibits emergence]]` | Complexity, culture, creativity |
+| `#[[perspective switching]]` | Photography, negotiation, analysis |
+| `#[[flow dynamics]]` | Fluids, music, conversation, sequences |
+
+### Problem-Oriented Tagging
+
+Tag by problems solved, not methods used:
+
+- `#[[breaking cognitive constraints]]`
+- `#[[expanding solution spaces]]`
+- `#[[preventing expert blindness]]`
+
+### Temporal & State-Based Tags
+
+| Tag Type | Examples |
+|----------|----------|
+| Future relevance | `#[[will be relevant in 5 years]]`, `#[[connects to unborn projects]]` |
+| Mental state triggers | `#[[feeling stuck in patterns]]`, `#[[needing fresh perspective]]` |
+| Review scheduling | `[[For review]]: [[August 12th, 2026]]` |
+
+---
 
 ## Formatting Conventions
 
+### Quotes
+```
+<quote text> —[[Author Name]] #quote #[[topic1]] #[[topic2]]
+```
+Always include 2-3 relevant hashtags after quotes.
+
+### TODOs and Follow-ups
+```
+{{[[TODO]]}} <action needed>
+{{[[TODO]]}} #researchThis : <topic to investigate> 
+```
+
+### Scheduled Reviews
+
+- Any block tagged with a date will show on that respective daily page.
+
+```
+[[For review]]: [[Date in ordinal format]]
+```
+Optional labels: "Deadline", "Approved", "Pending", "Deferred", "Postponed until"
+
+### Aliasing for Case Sensitivity
+When a tag would awkwardly affect sentence capitalization:
+```
+[Cognitive biases]([[cognitive biases]]) affect decision-making...
+```
+
+### Definitions (OVERRIDE)
+```
+#def [[<term>]] : <definition>
+```
+
+---
 
 ## Constraints & Guardrails
 
+### DON'T
+- **Overtag** — Quality over quantity; each tag should earn its place
+- **Tag obvious/redundant** — If parent block is tagged, children inherit context
+- **Use inconsistent capitalization** — Tags are lowercase unless proper nouns
+- **Create orphan tags** — Check if existing page/tag serves the purpose
+- **Bold Attributes** - ❌ `**Attribute**::`, ✅ `Attribute::` (Roam auto-formats)
+- **Separators** - `---` Don't use them.
+
+### DO
+- **Think retrieval-first** — How will you search for this later?
+- **Cross-pollinate domains** — Force unlikely intellectual meetings
+- **Update aging tags** — As interests evolve, so should tag vocabulary
+- **Track surprise discoveries** — When unexpected connections yield insights, engineer more of those patterns
+
+---
 
 ## Custom Rules
 
+<!-- 
+CUSTOMIZE THIS SECTION with your specific conventions:
+- Naming patterns for certain page types
+- Required attributes for books/articles/people
+- Project-specific tagging schemes
+- Integration rules with other tools
+- etc.
+-->
+
+### Example Custom Rules (modify as needed):
+
+**Books:**
+```
+[[Book/<title> | <author>]]
+Type:: Book
+Author:: [[Author Name]]
+Status:: Reading | Completed | Abandoned
+Rating:: X/5
+```
+
+**People:**
+```
+[[Person Name]]
+Type:: Person
+Context:: How I know them
+```
+- When linking bibliographic references —>
+  Example: `McAdams, D.P. (2001) [The Psychology of Life Stories](https://journals.sagepub.com/doi/10.1037/1089-2680.5.2.100) — foundational paper`
+  - [McAdams, D.P.]([[Dan McAdams]]) - author's name in the graph
+  - If source URL, link to source: [The Psychology of Life Stories](https://journals.sagepub.com/doi/10.1037/1089-2680.5.2.100)
+  - If notes page exists or will exist in Roam: append ` | [Notes]([[Article/The Psychology of Life Stories]]), if not, just leave it without link.
+  
+**Projects:**
+```
+[[Project/<project anme>]]
+Status:: Active | Paused | Completed
+Start:: [[Date]]
+```
+---
 
 ## Integration Notes
 
 <!-- CUSTOMIZE: Any rules about how Roam integrates with your other tools/systems -->
 
-</personalization_layer>
+- Daily pages serve as: <!-- inbox / journal / task list / etc. -->
+- Weekly reviews occur on: <!-- day of week -->
+- Content flows from: <!-- capture tools, read-later apps, etc. -->
+- Content flows to: <!-- publishing, archives, etc. -->
+
+---
+
+*End of Personalization Layer*

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/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/index.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
 import { RoamServer } from './server/roam-server.js';
+// `--server` runs a long-lived, HTTP-only daemon (no stdio transport) bound to a
+// pinned host:port — meant to be kept running (e.g. by a LaunchAgent) and shared
+// by multiple MCP clients. Without the flag, behavior is unchanged: stdio + an
+// auto-discovered HTTP port.
+const serverMode = process.argv.includes('--server');
 const server = new RoamServer();
-server.run().catch((error) => {
+server.run({ serverMode }).catch((error) => {
     console.error("Fatal error running server:", error);
     process.exit(1);
 });

package/build/server/roam-server.js

@@ -2,7 +2,8 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { CallToolRequestSchema, ErrorCode, ListResourcesRequestSchema, ReadResourceRequestSchema, McpError, ListToolsRequestSchema, ListPromptsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { HTTP_STREAM_PORT, validateEnvironment } from '../config/environment.js';
+import { HTTP_STREAM_PORT, HTTP_STREAM_HOST, HTTP_AUTH_TOKEN, validateEnvironment } from '../config/environment.js';
+import { isBearerAuthorized } from '../utils/auth.js';
 import { createRegistryFromEnv } from '../config/graph-registry.js';
 import { toolSchemas } from '../tools/schemas.js';
 import { ToolHandlers } from '../tools/tool-handlers.js';
@@ -10,7 +11,7 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
-import { findAvailablePort } from '../utils/net.js';
+import { findAvailablePort, isPortInUse } from '../utils/net.js';
 import { CORS_ORIGINS } from '../config/environment.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -306,11 +307,16 @@ export class RoamServer {
             }
         });
     }
-    async run() {
+    async run(options = {}) {
+        const { serverMode = false } = options;
         try {
-            const stdioMcpServer = this.createMcpServer();
-            const stdioTransport = new StdioServerTransport();
-            await stdioMcpServer.connect(stdioTransport);
+            // In --server (daemon) mode we run HTTP-only: no client reads the stdio
+            // transport, so we skip it. Otherwise behavior is unchanged (stdio + HTTP).
+            if (!serverMode) {
+                const stdioMcpServer = this.createMcpServer();
+                const stdioTransport = new StdioServerTransport();
+                await stdioMcpServer.connect(stdioTransport);
+            }
             // Track active transports by session ID for proper session management
             const activeSessions = new Map();
             const httpServer = createServer(async (req, res) => {
@@ -332,6 +338,38 @@ export class RoamServer {
                     res.end();
                     return;
                 }
+                // Liveness probe — cheap, no MCP handshake required. Useful for the
+                // LaunchAgent/health checks (a bare GET on the MCP endpoint returns 406).
+                const requestPath = (req.url || '/').split('?')[0];
+                if (req.method === 'GET' && requestPath === '/health') {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({
+                        status: 'ok',
+                        name: 'roam-research-mcp',
+                        version: serverVersion,
+                        mode: serverMode ? 'server' : 'stdio+http',
+                        auth: HTTP_AUTH_TOKEN ? 'required' : 'none',
+                        graphs: this.registry.getAvailableGraphs(),
+                        defaultGraph: this.registry.defaultKey,
+                        activeSessions: activeSessions.size,
+                    }));
+                    return;
+                }
+                // Transport authentication (perimeter): when HTTP_AUTH_TOKEN is set,
+                // every MCP request must carry `Authorization: Bearer <token>`. /health
+                // and OPTIONS are intentionally exempt (handled above). Unset = open.
+                if (HTTP_AUTH_TOKEN && !isBearerAuthorized(req.headers['authorization'], HTTP_AUTH_TOKEN)) {
+                    res.writeHead(401, {
+                        'Content-Type': 'application/json',
+                        'WWW-Authenticate': 'Bearer',
+                    });
+                    res.end(JSON.stringify({
+                        jsonrpc: '2.0',
+                        error: { code: -32001, message: 'Unauthorized: missing or invalid bearer token' },
+                        id: null,
+                    }));
+                    return;
+                }
                 // Check for existing session ID in header
                 const sessionId = req.headers['mcp-session-id'];
                 // Handle session termination (DELETE request)
@@ -384,9 +422,25 @@ export class RoamServer {
                     }
                 }
             });
-            const availableHttpPort = await findAvailablePort(parseInt(HTTP_STREAM_PORT));
-            httpServer.listen(availableHttpPort, () => {
-            });
+            const desiredPort = parseInt(HTTP_STREAM_PORT);
+            if (serverMode) {
+                // A shared daemon must own a stable URL — never silently drift to another
+                // port. Fail loudly if the configured port is already taken on our bind
+                // host (a listener on a different interface is not our conflict).
+                if (await isPortInUse(desiredPort, HTTP_STREAM_HOST)) {
+                    throw new McpError(ErrorCode.InternalError, `--server: port ${desiredPort} (HTTP_STREAM_PORT) is already in use. ` +
+                        `Stop the process using it, or set HTTP_STREAM_PORT to a free port.`);
+                }
+                httpServer.listen(desiredPort, HTTP_STREAM_HOST, () => {
+                    console.error(`roam-research-mcp v${serverVersion} (--server) listening on ` +
+                        `http://${HTTP_STREAM_HOST}:${desiredPort}/  (health: /health)`);
+                });
+            }
+            else {
+                const availableHttpPort = await findAvailablePort(desiredPort);
+                httpServer.listen(availableHttpPort, () => {
+                });
+            }
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);

package/build/utils/auth.js

@@ -0,0 +1,24 @@
+import { timingSafeEqual } from 'node:crypto';
+/**
+ * Validate an HTTP `Authorization` header against an expected bearer token.
+ *
+ * Uses a constant-time comparison so the token can't be recovered via response
+ * timing. Returns true only when the header is exactly `Bearer <token>` (scheme
+ * is case-insensitive; surrounding whitespace tolerated) and matches.
+ *
+ * This is transport-level AUTHENTICATION (who may talk to the server) — distinct
+ * from ROAM_SYSTEM_WRITE_KEY, which is per-graph write AUTHORIZATION.
+ */
+export function isBearerAuthorized(authHeader, expectedToken) {
+    if (!authHeader || !expectedToken)
+        return false;
+    const match = /^Bearer\s+(.+)$/i.exec(authHeader.trim());
+    if (!match)
+        return false;
+    const provided = Buffer.from(match[1]);
+    const expected = Buffer.from(expectedToken);
+    // Length is not secret; guard first because timingSafeEqual throws on mismatch.
+    if (provided.length !== expected.length)
+        return false;
+    return timingSafeEqual(provided, expected);
+}

package/build/utils/auth.test.js

@@ -0,0 +1,34 @@
+import { describe, it, expect } from 'vitest';
+import { isBearerAuthorized } from './auth.js';
+describe('isBearerAuthorized', () => {
+    const token = 'secret-token-123';
+    it('accepts a correct Bearer token', () => {
+        expect(isBearerAuthorized(`Bearer ${token}`, token)).toBe(true);
+    });
+    it('is case-insensitive on the scheme', () => {
+        expect(isBearerAuthorized(`bearer ${token}`, token)).toBe(true);
+        expect(isBearerAuthorized(`BEARER ${token}`, token)).toBe(true);
+    });
+    it('tolerates surrounding and inter-token whitespace', () => {
+        expect(isBearerAuthorized(`  Bearer    ${token}  `, token)).toBe(true);
+    });
+    it('rejects a wrong token of the same length', () => {
+        expect(isBearerAuthorized('Bearer secret-token-124', token)).toBe(false);
+    });
+    it('rejects a token of a different length', () => {
+        expect(isBearerAuthorized(`Bearer ${token}extra`, token)).toBe(false);
+    });
+    it('rejects a missing/empty header', () => {
+        expect(isBearerAuthorized(undefined, token)).toBe(false);
+        expect(isBearerAuthorized('', token)).toBe(false);
+    });
+    it('rejects a non-Bearer scheme', () => {
+        expect(isBearerAuthorized(`Basic ${token}`, token)).toBe(false);
+    });
+    it('rejects a bare token without the scheme', () => {
+        expect(isBearerAuthorized(token, token)).toBe(false);
+    });
+    it('rejects when no expected token is configured', () => {
+        expect(isBearerAuthorized(`Bearer ${token}`, '')).toBe(false);
+    });
+});

package/build/utils/net.js

@@ -2,9 +2,14 @@ import { createServer } from 'node:net';
 /**
  * Checks if a given port is currently in use.
  * @param port The port to check.
+ * @param host Optional host to probe. When omitted, probes the wildcard address
+ *   (any interface) — matching `findAvailablePort`'s "globally free" semantics.
+ *   Pass a specific host (e.g. `127.0.0.1`) to check only that interface, so a
+ *   listener bound to a different interface (e.g. wildcard) doesn't register as
+ *   a conflict for a host-specific bind.
  * @returns A promise that resolves to true if the port is in use, and false otherwise.
  */
-export function isPortInUse(port) {
+export function isPortInUse(port, host) {
     return new Promise((resolve) => {
         const server = createServer();
         server.once('error', (err) => {
@@ -20,7 +25,12 @@ export function isPortInUse(port) {
             server.close();
             resolve(false);
         });
-        server.listen(port);
+        if (host) {
+            server.listen(port, host);
+        }
+        else {
+            server.listen(port);
+        }
     });
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "2.19.1",
+  "version": "2.22.0",
   "description": "MCP server and CLI for Roam Research",
   "private": false,
   "repository": {
@@ -56,4 +56,4 @@
     "typescript": "^5.3.3",
     "vitest": "^3.2.4"
   }
-}
+}