roam-research-mcp 2.18.0 → 2.22.0

package/README.md

@@ -46,6 +46,12 @@ roam search --namespace "Convention"    # Finds all Convention/* pages
 # Fetch a page by title
 roam get "Roam Research"
 
+# Fetch daily pages using any date format (auto-normalized)
+roam get today                          # Today's daily page
+roam get 2026-03-21                     # ISO date → "March 21st, 2026"
+roam get "03/21/2026"                   # US date → "March 21st, 2026"
+roam get "March 21"                     # Named (assumes current year)
+
 # Fetch a block with ancestors (parent chain to page root)
 roam get abc123def -a              # Block + children + ancestors
 roam get abc123def -a -d 0         # Ancestors only, no children
@@ -70,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
@@ -154,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.
+
+```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`.
 
-**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

@@ -184,6 +184,12 @@ CREATING:
 ├─ Memory → roam_remember
 └─ Todos → roam_add_todo
 
+NESTING (roam_import_markdown): nests by BOTH indentation AND markdown heading
+level — content and deeper headings fold under their heading (## under #, ### under
+##). Use it for heading-structured docs. roam_create_page nests ONLY by explicit
+per-item `level` integers, so heading-structured markdown sent to create_page
+imports flat. Don't use `---` dividers; they become horizontal-rule blocks.
+
 SEARCHING:
 ├─ By tag → roam_search_for_tag
 ├─ By text → roam_search_by_text
@@ -237,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.
@@ -247,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/batch/resolver.js

@@ -45,6 +45,21 @@ export async function resolveDailyPageUid(graph) {
     const dailyTitle = getDailyPageTitle();
     return resolvePageUid(graph, dailyTitle);
 }
+/**
+ * Check if a string looks like a valid Roam UID (not a page title)
+ */
+export function isUidFormat(ref) {
+    // 9 alphanumeric characters (standard block UID)
+    if (/^[a-zA-Z0-9_-]{9}$/.test(ref))
+        return true;
+    // MM-DD-YYYY daily page UID
+    if (/^\d{2}-\d{2}-\d{4}$/.test(ref))
+        return true;
+    // Placeholder {{name}}
+    if (/^\{\{[^}]+\}\}$/.test(ref))
+        return true;
+    return false;
+}
 /**
  * Collect all unique page titles that need resolution from commands
  */
@@ -56,6 +71,13 @@ export function collectPageTitles(commands) {
         if ('page' in params && typeof params.page === 'string') {
             titles.add(params.page);
         }
+        // Commands that can have 'parent' param — if it looks like a page title, resolve it
+        if ('parent' in params && typeof params.parent === 'string') {
+            const parent = params.parent;
+            if (!isUidFormat(parent)) {
+                titles.add(parent);
+            }
+        }
         // Remember command can have heading that needs parent page resolution
         // But heading lookup is handled separately
         // Todo/remember without explicit page need daily page
@@ -126,8 +148,13 @@ export function resolveParentRef(ref, context) {
     if (context.pageUids.has(ref)) {
         return context.pageUids.get(ref);
     }
-    // Assume it's a direct UID
-    return ref;
+    // If it looks like a UID, return as-is
+    if (isUidFormat(ref)) {
+        return ref;
+    }
+    // Not a UID and not resolved — this is a page title that wasn't collected/resolved
+    // Return null so callers can handle it (should not happen if collectPageTitles is correct)
+    return null;
 }
 /**
  * Generate a placeholder UID for tracking

package/build/cli/batch/translator.js

@@ -39,7 +39,10 @@ export function translateCommand(command, context) {
 function getParentUid(params, context) {
     // Direct parent UID or placeholder
     if (params.parent) {
-        return resolveParentRef(params.parent, context) || params.parent;
+        const resolved = resolveParentRef(params.parent, context);
+        if (resolved)
+            return resolved;
+        throw new Error(`Parent "${params.parent}" could not be resolved to a UID. Page may not exist.`);
     }
     // Page UID
     if (params.pageUid) {

package/build/cli/commands/batch.js

@@ -227,7 +227,7 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                 return;
             }
             const graph = resolveGraph(options, true);
-            // Phase 1: Collect and resolve page titles
+            // Phase 1: Collect and resolve page titles (from 'page' AND 'parent' params)
             const context = createResolutionContext();
             const pageTitles = collectPageTitles(commands);
             if (pageTitles.size > 0) {
@@ -238,10 +238,25 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                 for (const [title, uid] of resolved) {
                     context.pageUids.set(title, uid);
                 }
-                // Check for unresolved pages
+                // Auto-create unresolved pages (e.g., parent: "Page Title" for a page that doesn't exist yet)
                 const unresolved = Array.from(pageTitles).filter(t => !context.pageUids.has(t));
                 if (unresolved.length > 0) {
-                    exitWithError(`Page(s) not found: ${unresolved.map(t => `"${t}"`).join(', ')}`);
+                    if (options.debug) {
+                        printDebug('Auto-creating pages', unresolved);
+                    }
+                    const pageOps = new PageOperations(graph);
+                    for (const title of unresolved) {
+                        const result = await pageOps.createPage(title);
+                        if (result.success && result.uid) {
+                            context.pageUids.set(title, result.uid);
+                            if (options.debug) {
+                                printDebug(`Auto-created "${title}"`, result.uid);
+                            }
+                        }
+                        else {
+                            exitWithError(`Failed to create page "${title}"`);
+                        }
+                    }
                 }
                 if (options.debug) {
                     printDebug('Resolved pages', Object.fromEntries(context.pageUids));