roam-research-mcp 3.0.0 → 3.1.0

package/README.md

@@ -273,14 +273,16 @@ So: to mark a graph as needing the write key, set `protected: true` on it and co
 
 *Optional:*
 - `ROAM_MEMORIES_TAG`: Default tag for `roam_remember`/`roam_recall` (fallback when per-graph `memoriesTag` not set).
-- `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_STREAM_PORT`: Port for the HTTP Stream transport (defaults to 8088). **`--server` mode only** — stdio mode opens no socket, so this is ignored there.
+- `HTTP_STREAM_HOST`: Host to bind the HTTP transport to (defaults to `127.0.0.1`, loopback-only). **`--server` mode only.** Set to `0.0.0.0` to expose on the LAN, and set `HTTP_AUTH_TOKEN` when you do.
 - `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. 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`.
+**1. Default Mode (stdio)**
+Best for local integration (e.g., Claude Desktop, IDE extensions). The MCP client launches the process per session and talks to it over stdin/stdout. **No port is opened** — nothing about MCP over stdio needs one.
+
+> Before 3.1.0 this mode *also* opened an HTTP listener, and bound it to every interface. If you were using that endpoint, run a `--server` daemon instead; see below.
 
 ```bash
 npx roam-research-mcp
@@ -305,7 +307,7 @@ 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:
+The two modes are mutually exclusive, and each opens exactly one transport: stdio mode speaks stdio and binds nothing, `--server` speaks HTTP and reads no stdin. 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.

package/build/Roam_Markdown_Cheatsheet.md

@@ -244,8 +244,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.
@@ -254,21 +252,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/server/roam-server.js

@@ -12,7 +12,7 @@ import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
-import { findAvailablePort, isPortInUse } from '../utils/net.js';
+import { isPortInUse } from '../utils/net.js';
 import { CORS_ORIGINS } from '../config/environment.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -306,12 +306,18 @@ export class RoamServer {
     async run(options = {}) {
         const { serverMode = false } = options;
         try {
-            // In --server (daemon) mode we run HTTP-only: no client reads the stdio
-            // transport, so we skip it. Otherwise behavior is unchanged (stdio + HTTP).
+            // The two transports are mutually exclusive, and each mode opens exactly
+            // one. Stdio mode talks to the client that spawned it over stdin/stdout
+            // and returns here — it opens no socket at all. Nothing about MCP over
+            // stdio needs one, and a listener nobody asked for is pure attack
+            // surface: until 3.1.0 stdio mode also bound an HTTP port, which shipped
+            // a token-free MCP endpoint per spawned instance. Run `--server` when
+            // you want HTTP; that is what it is for.
             if (!serverMode) {
                 const stdioMcpServer = this.createMcpServer();
                 const stdioTransport = new StdioServerTransport();
                 await stdioMcpServer.connect(stdioTransport);
+                return;
             }
             // Track active transports by session ID for proper session management
             const activeSessions = new Map();
@@ -343,7 +349,11 @@ export class RoamServer {
                         status: 'ok',
                         name: 'roam-research-mcp',
                         version: serverVersion,
-                        mode: serverMode ? 'server' : 'stdio+http',
+                        // Always 'server' since 3.1.0: this handler is only reachable in
+                        // --server mode. Kept as a field because clients read it, and the
+                        // retired 'stdio+http' value is how they can tell they are talking
+                        // to an older build that still had the stdio-mode listener.
+                        mode: 'server',
                         auth: HTTP_AUTH_TOKEN ? 'required' : 'none',
                         graphs: this.registry.getAvailableGraphs(),
                         defaultGraph: this.registry.defaultKey,
@@ -436,24 +446,17 @@ export class RoamServer {
                 }
             });
             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, () => {
-                });
+            // 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)`);
+            });
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : String(error);

package/build/utils/net.js

@@ -3,10 +3,9 @@ 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.
+ *   (any interface). Pass the host you intend to bind — a wildcard probe and a
+ *   host-specific bind disagree in both directions, so the two must match or
+ *   the answer is about a port nobody is going to open.
  * @returns A promise that resolves to true if the port is in use, and false otherwise.
  */
 export function isPortInUse(port, host) {
@@ -33,16 +32,8 @@ export function isPortInUse(port, host) {
         }
     });
 }
-/**
- * Finds an available port, starting from a given port and incrementing by a specified amount.
- * @param startPort The port to start checking from.
- * @param incrementBy The amount to increment the port by if it's in use. Defaults to 2.
- * @returns A promise that resolves to an available port number.
- */
-export async function findAvailablePort(startPort, incrementBy = 2) {
-    let port = startPort;
-    while (await isPortInUse(port)) {
-        port += incrementBy;
-    }
-    return port;
-}
+// `findAvailablePort` lived here until 3.1.0. It existed so stdio mode could
+// drift to a free port when 8088 was taken, and it has no caller now that stdio
+// opens no socket: `--server` binds the exact configured port and fails loudly
+// rather than drifting, because a shared daemon must keep a stable URL.
+// Anything reaching for it again probably wants that failure instead.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "MCP server and CLI for Roam Research",
   "private": false,
   "repository": {