roam-research-mcp 2.25.0 → 3.1.0

package/README.md

@@ -146,6 +146,24 @@ The MCP server exposes these tools to AI assistants (like Claude), enabling them
 | `roam_markdown_cheatsheet` | Retrieve the Roam-flavored markdown reference. |
 | `roam_get_guidelines` | Retrieve this graph's user-defined agent conventions. |
 
+### Structured results from write tools (v3.0.0+)
+
+The ten write tools declare an `outputSchema` and return `structuredContent` — a validated object — alongside the usual text. A client can read `page_uid`, `uid_map` or `success` directly instead of hunting for JSON inside a string, which makes chaining calls more reliable:
+
+```jsonc
+// roam_process_batch_actions
+{ "success": true, "uid_map": { "parent1": "Xk7mN2pQ9" },
+  "validation_passed": true, "actions_attempted": 4 }
+```
+
+Three things worth knowing:
+
+- **Nothing was taken away.** The text channel is unchanged, so a client that ignores `structuredContent` behaves exactly as before.
+- **Read tools deliberately have neither.** They already serialise their whole result into the text channel, so a schema would just double the payload.
+- **These fields are additive-only.** Some clients validate live responses against a cached tool list, so a field will be added or deprecated — never renamed or removed outside a major version.
+
+> **Upgrading from 2.x:** three write-result fields were renamed — `uid` → `page_uid` (`roam_create_page`), `created_uids` → `created_blocks` (`roam_create_outline`, `roam_import_markdown`) and `preservedUids` → `preserved_uids` (`roam_update_page_markdown`). This only affects code that reads those names; if you use the server through an AI assistant, nothing changes. See the [changelog](CHANGELOG.md) for why.
+
 ---
 
 ## Agent guidelines (per-graph)
@@ -231,7 +249,7 @@ ROAM_SYSTEM_WRITE_KEY=your-secret-key
 |----------|----------|-------------|
 | `token` | Yes | Roam API token for this graph |
 | `graph` | Yes | Graph name/database identifier |
-| `protected` | No | If `true`, writes require `ROAM_SYSTEM_WRITE_KEY` confirmation |
+| `protected` | No | If `true`, writes require `ROAM_SYSTEM_WRITE_KEY` confirmation — **except on the default graph**, see below |
 | `memoriesTag` | No | Tag for `roam_remember`/`roam_recall` (overrides global default) |
 
 **Two kinds of access control (and how they differ)**
@@ -251,16 +269,20 @@ Think of a house: the **bearer token locks the front door** (keeps strangers out
 
 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.
 
+> ⚠️ **`protected` does nothing on your default graph.** Writes to whichever graph `ROAM_DEFAULT_GRAPH` names are always allowed, before `protected` is ever consulted — the flag guards the graphs you have to *ask* for by name, on the reasoning that reaching for a non-default graph is the deliberate act worth confirming. If you want a graph write-guarded, it must not be your default.
+
 *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
@@ -285,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.
@@ -350,6 +372,16 @@ docker run -p 8088:8088 --env-file .env roam-research-mcp --server
 
 Add to your MCP settings file (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json`):
 
+> **Pinning the version.** `npx -y roam-research-mcp` fetches the **latest** release every time your client starts the server, so a new major version arrives without warning. Pin the major to decide for yourself when to move:
+>
+> | `args` | You get |
+> | :--- | :--- |
+> | `["-y", "roam-research-mcp"]` | Latest, always — including the next major |
+> | `["-y", "roam-research-mcp@3"]` | 3.x only; majors need an edit here |
+> | `["-y", "roam-research-mcp@3.0.0"]` | Exactly this build |
+>
+> Pinning the major is the sensible default: you still get fixes and new tools, but a breaking change becomes something you opt into. The examples below stay unpinned to match what most people paste in first.
+
 *Single Graph:*
 ```json
 {

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/cli/commands/batch.js

@@ -247,10 +247,10 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                     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 (result.success && result.page_uid) {
+                            context.pageUids.set(title, result.page_uid);
                             if (options.debug) {
-                                printDebug(`Auto-created "${title}"`, result.uid);
+                                printDebug(`Auto-created "${title}"`, result.page_uid);
                             }
                         }
                         else {
@@ -313,12 +313,12 @@ Output (JSON): { success, pages_created, actions_executed, uid_map? }
                         // Report partial results before exiting
                         outputPartialResults(pageResults, pc.params.title);
                     }
-                    pageResults.push({ title: pc.params.title, uid: result.uid });
+                    pageResults.push({ title: pc.params.title, uid: result.page_uid });
                     if (pc.params.as) {
-                        context.placeholders.set(pc.params.as, result.uid);
+                        context.placeholders.set(pc.params.as, result.page_uid);
                     }
                     if (options.debug) {
-                        printDebug(`Created "${pc.params.title}"`, result.uid);
+                        printDebug(`Created "${pc.params.title}"`, result.page_uid);
                     }
                 }
             }

package/build/cli/commands/save.js

@@ -430,8 +430,8 @@ JSON format (--json):
                     if (result.success) {
                         console.log(`Updated page '${pageTitle}'`);
                         console.log(`  ${result.summary}`);
-                        if (result.preservedUids.length > 0) {
-                            console.log(`  Preserved ${result.preservedUids.length} block UID(s)`);
+                        if (result.preserved_uids.length > 0) {
+                            console.log(`  Preserved ${result.preserved_uids.length} block UID(s)`);
                         }
                     }
                     else {
@@ -441,7 +441,7 @@ JSON format (--json):
                 else {
                     const result = await pageOps.createPage(pageTitle, contentBlocks);
                     if (result.success) {
-                        console.log(`Created page '${pageTitle}' (uid: ${result.uid})`);
+                        console.log(`Created page '${pageTitle}' (uid: ${result.page_uid})`);
                     }
                     else {
                         exitWithError(`Failed to create page '${pageTitle}'`);

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);
@@ -20,6 +20,29 @@ const __dirname = dirname(__filename);
 const packageJsonPath = join(__dirname, '../../package.json');
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
 const serverVersion = packageJson.version;
+/**
+ * The single place a tool result is built, and the only place
+ * `structuredContent` may be attached.
+ *
+ * The wire invariant is **`structuredContent` is present iff the tool declares
+ * an `outputSchema`**. A schema-bearing tool that returns none, or a
+ * schema-less tool that returns some, is a protocol violation a strict client
+ * will reject. We use the low-level `Server` rather than `McpServer`, so the
+ * SDK does not enforce this for us — routing every result through here is what
+ * enforces it. Adding a schema in schemas.ts is therefore sufficient; no switch
+ * case needs touching.
+ *
+ * The text channel is unchanged either way, so clients that never look at
+ * structuredContent see exactly what they saw before.
+ */
+function toolResult(toolName, result) {
+    const declaresSchema = Boolean(toolSchemas[toolName]?.outputSchema);
+    const canStructure = declaresSchema && result !== null && typeof result === 'object';
+    return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        ...(canStructure ? { structuredContent: result } : {}),
+    };
+}
 export class RoamServer {
     constructor() {
         this.toolHandlersCache = new Map();
@@ -126,9 +149,7 @@ export class RoamServer {
                     case 'roam_remember': {
                         const { memory, categories, heading, parent_uid, include_memories_tag } = cleanedArgs;
                         const result = await toolHandlers.remember(memory, categories, heading, parent_uid, include_memories_tag);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_fetch_page_full_view': {
                         const { title, children_depth, max_references } = cleanedArgs;
@@ -146,9 +167,7 @@ export class RoamServer {
                     }
                     case 'roam_get_guidelines': {
                         const result = await toolHandlers.getGuidelines();
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_fetch_page_by_title': {
                         const { title, format } = cleanedArgs;
@@ -160,30 +179,22 @@ export class RoamServer {
                     case 'roam_create_page': {
                         const { title, content } = cleanedArgs;
                         const result = await toolHandlers.createPage(title, content);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_import_markdown': {
                         const { content, page_uid, page_title, parent_uid, parent_string, order = 'first' } = cleanedArgs;
                         const result = await toolHandlers.importMarkdown(content, page_uid, page_title, parent_uid, parent_string, order);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_add_todo': {
                         const { todos } = cleanedArgs;
                         const result = await toolHandlers.addTodos(todos);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_create_outline': {
                         const { outline, page_title_uid, block_text_uid, order } = cleanedArgs;
                         const result = await toolHandlers.createOutline(outline, page_title_uid, block_text_uid, order);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_for_tag': {
                         const { primary_tag, page_title_uid, near_tag } = cleanedArgs;
@@ -191,23 +202,17 @@ export class RoamServer {
                             throw new McpError(ErrorCode.InvalidParams, 'Missing required parameter: primary_tag (the tag to search for). Use page_title_uid to limit search to a specific page.');
                         }
                         const result = await toolHandlers.searchForTag(primary_tag, page_title_uid, near_tag);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_by_status': {
                         const { status, page_title_uid, include, exclude } = cleanedArgs;
                         const result = await toolHandlers.searchByStatus(status, page_title_uid, include, exclude);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_block_refs': {
                         const params = cleanedArgs;
                         const result = await toolHandlers.searchBlockRefs(params);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_hierarchy': {
                         const params = cleanedArgs;
@@ -216,58 +221,42 @@ export class RoamServer {
                             throw new McpError(ErrorCode.InvalidRequest, 'Either parent_uid or child_uid must be provided, but not both');
                         }
                         const result = await toolHandlers.searchHierarchy(params);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_find_pages_modified_today': {
                         const { max_num_pages } = cleanedArgs;
                         const result = await toolHandlers.findPagesModifiedToday(max_num_pages || 50);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_by_text': {
                         const params = cleanedArgs;
                         const result = await toolHandlers.searchByText(params);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_search_by_date': {
                         const params = cleanedArgs;
                         const result = await toolHandlers.searchByDate(params);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_recall': {
                         const { sort_by = 'newest', filter_tag } = cleanedArgs;
                         const result = await toolHandlers.recall(sort_by, filter_tag);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_datomic_query': {
                         const { query, inputs } = cleanedArgs;
                         const result = await toolHandlers.executeDatomicQuery({ query, inputs });
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_process_batch_actions': {
                         const { actions } = cleanedArgs;
                         const result = await toolHandlers.processBatch(actions);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_fetch_block': {
                         const { block_uid, depth, include_ancestors } = cleanedArgs;
                         const result = await toolHandlers.fetchBlock(block_uid, depth, include_ancestors);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_create_table': {
                         const { parent_uid, order, headers, rows } = cleanedArgs;
@@ -277,30 +266,22 @@ export class RoamServer {
                             headers,
                             rows
                         });
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_move_block': {
                         const { block_uid, parent_uid, order = 'last' } = cleanedArgs;
                         const result = await toolHandlers.moveBlock(block_uid, parent_uid, order);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_update_page_markdown': {
                         const { title, markdown, dry_run = false } = cleanedArgs;
                         const result = await toolHandlers.updatePageMarkdown(title, markdown, dry_run);
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     case 'roam_rename_page': {
                         const { old_title, uid, new_title } = cleanedArgs;
                         const result = await toolHandlers.renamePage({ old_title, uid, new_title });
-                        return {
-                            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                        };
+                        return toolResult(request.params.name, result);
                     }
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
@@ -325,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();
@@ -362,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,
@@ -455,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);