roam-research-mcp 0.25.5 → 0.27.0

package/README.md

@@ -5,16 +5,25 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![GitHub](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)
 
-A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
+A Model Context Protocol (MCP) server that provides comprehensive access to Roam Research's API functionality. This server enables AI assistants like Claude to interact with your Roam Research graph through a standardized interface. It supports standard input/output (stdio), HTTP Stream, and Server-Sent Events (SSE) communication. (A WORK-IN-PROGRESS, personal project not officially endorsed by Roam Research)
 
 <a href="https://glama.ai/mcp/servers/fzfznyaflu"><img width="380" height="200" src="https://glama.ai/mcp/servers/fzfznyaflu/badge" alt="Roam Research MCP server" /></a>
 
-## Installation
+## Installation and Usage
 
-You can install the package globally:
+This MCP server supports three primary communication methods:
+
+1.  **Stdio (Standard Input/Output):** Ideal for local inter-process communication, command-line tools, and direct integration with applications running on the same machine. This is the default communication method when running the server directly.
+2.  **HTTP Stream:** Provides network-based communication, suitable for web-based clients, remote applications, or scenarios requiring real-time updates over HTTP. The HTTP Stream endpoint runs on port `8088` by default.
+3.  **SSE (Server-Sent Events):** A transport for legacy clients that require SSE. The SSE endpoint runs on port `8087` by default. (NOTE: ⚠️ DEPRECATED: The SSE Transport has been deprecated as of MCP specification version 2025-03-26. HTTP Stream Transport preferred.)
+
+### Running with Stdio
+
+You can install the package globally and run it:
 
 ```bash
 npm install -g roam-research-mcp
+roam-research-mcp
 ```
 
 Or clone the repository and build from source:
@@ -24,14 +33,60 @@ git clone https://github.com/2b3pro/roam-research-mcp.git
 cd roam-research-mcp
 npm install
 npm run build
+npm start
 ```
 
-## To Test
+### Running with HTTP Stream
+
+To run the server with HTTP Stream or SSE support, you can either:
+
+1.  **Use the default ports:** Run `npm start` after building (as shown above). The server will automatically listen on port `8088` for HTTP Stream and `8087` for SSE.
+2.  **Specify custom ports:** Set the `HTTP_STREAM_PORT` and/or `SSE_PORT` environment variables before starting the server.
+
+    ```bash
+    HTTP_STREAM_PORT=9000 SSE_PORT=9001 npm start
+    ```
+
+    Or, if using a `.env` file, add `HTTP_STREAM_PORT=9000` and/or `SSE_PORT=9001` to it.
+
+## Docker
+
+This project can be easily containerized using Docker. A `Dockerfile` is provided at the root of the repository.
 
-Run [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build…
+### Build the Docker Image
 
+To build the Docker image, navigate to the project root and run:
+
+```bash
+docker build -t roam-research-mcp .
 ```
-npx @modelcontextprotocol/inspector node build/index.js
+
+### Run the Docker Container
+
+To run the Docker container and map the necessary ports, you must also provide the required environment variables. Use the `-e` flag to pass `ROAM_API_TOKEN`, `ROAM_GRAPH_NAME`, and optionally `MEMORIES_TAG`, `HTTP_STREAM_PORT`, and `SSE_PORT`:
+
+```bash
+docker run -p 3000:3000 -p 8088:8088 -p 8087:8087 \
+  -e ROAM_API_TOKEN="your-api-token" \
+  -e ROAM_GRAPH_NAME="your-graph-name" \
+  -e MEMORIES_TAG="#[[LLM/Memories]]" \
+  -e HTTP_STREAM_PORT="8088" \
+  -e SSE_PORT="8087" \
+  roam-research-mcp
+```
+
+Alternatively, if you have a `.env` file in the project root (which is copied into the Docker image during build), you can use the `--env-file` flag:
+
+```bash
+docker run -p 3000:3000 -p 8088:8088 --env-file .env roam-research-mcp
+```
+
+## To Test
+
+Run [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build using the provided npm script:
+
+```bash
+npm run inspector
 ```
 
 ## Features
@@ -48,22 +103,24 @@ The server provides powerful tools for interacting with Roam Research:
 - Efficient batch operations
 - Hierarchical outline creation
 
-1. `roam_fetch_page_by_title`: Fetch and read a page's content by title, recursively resolving block references up to 4 levels deep
-2. `roam_create_page`: Create new pages with optional content
-3. `roam_create_block`: Create new blocks in a page (defaults to today's daily page)
-4. `roam_import_markdown`: Import nested markdown content under specific blocks
-5. `roam_add_todo`: Add multiple todo items to today's daily page with checkbox syntax
-6. `roam_create_outline`: Create hierarchical outlines with proper nesting and structure
-7. `roam_search_block_refs`: Search for block references within pages or across the graph
-8. `roam_search_hierarchy`: Navigate and search through block parent-child relationships
-9. `roam_find_pages_modified_today`: Find all pages that have been modified since midnight today
-10. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page
-11. `roam_update_block`: Update block content with direct text or pattern-based transformations
-12. `roam_search_by_date`: Search for blocks and pages based on creation or modification dates
-13. `roam_search_for_tag`: Search for blocks containing specific tags with optional filtering by nearby tags
-14. `roam_remember`: Store and categorize memories or information with automatic tagging
-15. `roam_recall`: Recall memories of blocks marked with tag MEMORIES_TAG (see below) or blocks on page title of the same name
-16. `roam_datomic_query`: Execute custom Datalog queries on the Roam graph for advanced data retrieval and analysis
+1. `roam_fetch_page_by_title`: Fetch page content by title.
+2. `roam_create_page`: Create new pages with optional content and headings.
+3. `roam_create_block`: Add new blocks to an existing page or today's daily note.
+4. `roam_import_markdown`: Import nested markdown content under a specific block.
+5. `roam_add_todo`: Add a list of todo items to today's daily page.
+6. `roam_create_outline`: Add a structured outline to an existing page or block.
+7. `roam_search_block_refs`: Search for block references within a page or across the entire graph.
+8. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.
+9. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight).
+10. `roam_search_by_text`: Search for blocks containing specific text.
+11. `roam_update_block`: Update a single block identified by its UID.
+12. `roam_update_multiple_blocks`: Efficiently update multiple blocks in a single batch operation.
+13. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.
+14. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.
+15. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby.
+16. `roam_remember`: Add a memory or piece of information to remember.
+17. `roam_recall`: Retrieve all stored memories.
+18. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph beyond the available search tools.
 
 ## Setup
 
@@ -83,10 +140,12 @@ The server provides powerful tools for interacting with Roam Research:
    ROAM_API_TOKEN=your-api-token
    ROAM_GRAPH_NAME=your-graph-name
    MEMORIES_TAG='#[[LLM/Memories]]'
+   HTTP_STREAM_PORT=8088 # Or your desired port for HTTP Stream communication
+   SSE_PORT=8087 # Or your desired port for SSE communication
    ```
 
    Option 2: Using MCP settings (Alternative method)
-   Add the configuration to your MCP settings file:
+   Add the configuration to your MCP settings file. Note that you may need to update the `args` to `["/path/to/roam-research-mcp/build/index.js"]` if you are running the server directly.
 
    - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):
    - For Claude desktop app (`~/Library/Application Support/Claude/claude_desktop_config.json`):
@@ -100,7 +159,9 @@ The server provides powerful tools for interacting with Roam Research:
          "env": {
            "ROAM_API_TOKEN": "your-api-token",
            "ROAM_GRAPH_NAME": "your-graph-name",
-           "MEMORIES_TAG": "#[[LLM/Memories]]"
+           "MEMORIES_TAG": "#[[LLM/Memories]]",
+           "HTTP_STREAM_PORT": "8088",
+           "SSE_PORT": "8087"
          }
        }
      }
@@ -116,599 +177,6 @@ The server provides powerful tools for interacting with Roam Research:
    npm run build
    ```
 
-## Usage
-
-### Fetch Page By Title
-
-Fetch and read a page's content with resolved block references:
-
-```typescript
-use_mcp_tool roam-research roam_fetch_page_by_title {
-  "title": "Example Page"
-}
-```
-
-Returns the page content as markdown with:
-
-- Complete hierarchical structure
-- Block references recursively resolved (up to 4 levels deep)
-- Proper indentation for nesting levels
-- Full markdown formatting
-
-### Create Page
-
-Create a new page with optional content:
-
-```typescript
-use_mcp_tool roam-research roam_create_page {
-  "title": "New Page",
-  "content": "Initial content for the page"
-}
-```
-
-Returns the created page's UID on success.
-
-### Create Block
-
-Add a new block to a page (defaults to today's daily page if neither page_uid nor title provided):
-
-```typescript
-use_mcp_tool roam-research roam_create_block {
-  "content": "Block content",
-  "page_uid": "optional-target-page-uid",
-  "title": "optional-target-page-title"
-}
-```
-
-You can specify either:
-
-- `page_uid`: Direct reference to target page
-- `title`: Name of target page (will be created if it doesn't exist)
-- Neither: Block will be added to today's daily page
-
-Returns:
-
-```json
-{
-  "success": true,
-  "block_uid": "created-block-uid",
-  "parent_uid": "parent-page-uid"
-}
-```
-
-### Create Outline
-
-Create a hierarchical outline with proper nesting and structure:
-
-```typescript
-use_mcp_tool roam-research roam_create_outline {
-  "outline": [
-    {
-      "text": "I. Top Level",
-      "level": 1
-    },
-    {
-      "text": "A. Second Level",
-      "level": 2
-    },
-    {
-      "text": "1. Third Level",
-      "level": 3
-    }
-  ],
-  "page_title_uid": "optional-target-page",
-  "block_text_uid": "optional-header-text"
-}
-```
-
-Features:
-
-- Create complex outlines with up to 10 levels of nesting
-- Validate outline structure and content
-- Maintain proper parent-child relationships
-- Optional header block for the outline
-- Defaults to today's daily page if no page specified
-- Efficient batch operations for creating blocks
-
-Parameters:
-
-- `outline`: Array of outline items, each with:
-  - `text`: Content of the outline item (required)
-  - `level`: Nesting level (1-10, required)
-- `page_title_uid`: Target page title or UID (optional, defaults to today's page)
-- `block_text_uid`: Header text for the outline (optional)
-
-Returns:
-
-```json
-{
-  "success": true,
-  "page_uid": "target-page-uid",
-  "parent_uid": "header-block-uid",
-  "created_uids": ["uid1", "uid2", ...]
-}
-```
-
-### Add Todo Items
-
-Add one or more todo items to today's daily page:
-
-```typescript
-use_mcp_tool roam-research roam_add_todo {
-  "todos": [
-    "First todo item",
-    "Second todo item",
-    "Third todo item"
-  ]
-}
-```
-
-Features:
-
-- Adds todos with Roam checkbox syntax (`{{TODO}} todo text`)
-- Supports adding multiple todos in a single operation
-- Uses batch actions for efficiency when adding >10 todos
-- Automatically creates today's page if it doesn't exist
-- Adds todos as top-level blocks in sequential order
-
-### Import Nested Markdown
-
-Import nested markdown content under a specific block:
-
-```typescript
-use_mcp_tool roam-research roam_import_markdown {
-  "content": "- Item 1\n  - Subitem A\n  - Subitem B\n- Item 2",
-  "page_uid": "optional-page-uid",
-  "page_title": "optional-page-title",
-  "parent_uid": "optional-parent-block-uid",
-  "parent_string": "optional-exact-block-content",
-  "order": "first"
-}
-```
-
-Features:
-
-- Import content under specific blocks:
-  - Find parent block by UID or exact string match
-  - Locate blocks within specific pages by title or UID
-  - Defaults to today's page if no page specified
-- Control content placement:
-  - Add as first or last child of parent block
-  - Preserve hierarchical structure
-  - Efficient batch operations for nested content
-- Comprehensive return value:
-  ```json
-  {
-    "success": true,
-    "page_uid": "target-page-uid",
-    "parent_uid": "parent-block-uid",
-    "created_uids": ["uid1", "uid2", ...]
-  }
-  ```
-
-Parameters:
-
-- `content`: Nested markdown content to import
-- `page_uid`: UID of the page containing the parent block
-- `page_title`: Title of the page containing the parent block (ignored if page_uid provided)
-- `parent_uid`: UID of the parent block to add content under
-- `parent_string`: Exact string content of the parent block (must provide either page_uid or page_title)
-- `order`: Where to add the content ("first" or "last", defaults to "first")
-
-### Search Block References
-
-Search for block references within pages or across the entire graph:
-
-```typescript
-use_mcp_tool roam-research roam_search_block_refs {
-  "block_uid": "optional-block-uid",
-  "page_title_uid": "optional-page-title-or-uid"
-}
-```
-
-Features:
-
-- Find all references to a specific block
-- Search for any block references within a page
-- Search across the entire graph
-- Supports both direct and indirect references
-- Includes block content and location context
-
-Parameters:
-
-- `block_uid`: UID of the block to find references to (optional)
-- `page_title_uid`: Title or UID of the page to search in (optional)
-
-Returns:
-
-```json
-{
-  "success": true,
-  "matches": [
-    {
-      "block_uid": "referenced-block-uid",
-      "content": "Block content with ((reference))",
-      "page_title": "Page containing reference"
-    }
-  ],
-  "message": "Found N block(s) referencing..."
-}
-```
-
-### Search By Text
-
-Search for blocks containing specific text across all pages or within a specific page:
-
-```typescript
-use_mcp_tool roam-research roam_search_by_text {
-  "text": "search text",
-  "page_title_uid": "optional-page-title-or-uid",
-  "case_sensitive": true
-}
-```
-
-Features:
-
-- Search for any text across all blocks in the graph
-- Optional page-scoped search
-- Case-sensitive or case-insensitive search
-- Returns block content with page context
-- Efficient text matching using Datalog queries
-
-Parameters:
-
-- `text`: The text to search for (required)
-- `page_title_uid`: Title or UID of the page to search in (optional)
-- `case_sensitive`: Whether to perform a case-sensitive search (optional, default: true to match Roam's native behavior)
-
-Returns:
-
-```json
-{
-  "success": true,
-  "matches": [
-    {
-      "block_uid": "matching-block-uid",
-      "content": "Block content containing search text",
-      "page_title": "Page containing block"
-    }
-  ],
-  "message": "Found N block(s) containing \"search text\""
-}
-```
-
-### Update Block Content
-
-Update a block's content using either direct text replacement or pattern-based transformations:
-
-```typescript
-use_mcp_tool roam-research roam_update_block {
-  "block_uid": "target-block-uid",
-  "content": "New block content"
-}
-```
-
-Or use pattern-based transformation:
-
-```typescript
-use_mcp_tool roam-research roam_update_block {
-  "block_uid": "target-block-uid",
-  "transform_pattern": {
-    "find": "\\bPython\\b",
-    "replace": "[[Python]]",
-    "global": true
-  }
-}
-```
-
-Features:
-
-- Two update modes:
-  - Direct content replacement
-  - Pattern-based transformation using regex
-- Verify block existence before updating
-- Return updated content in response
-- Support for global or single-match replacements
-- Preserve block relationships and metadata
-
-Parameters:
-
-- `block_uid`: UID of the block to update (required)
-- `content`: New content for the block (if using direct replacement)
-- `transform_pattern`: Pattern for transforming existing content:
-  - `find`: Text or regex pattern to find
-  - `replace`: Text to replace with
-  - `global`: Whether to replace all occurrences (default: true)
-
-Returns:
-
-```json
-{
-  "success": true,
-  "content": "Updated block content"
-}
-```
-
-### Search For Tags
-
-Search for blocks containing specific tags with optional filtering by nearby tags:
-
-```typescript
-use_mcp_tool roam-research roam_search_for_tag {
-  "primary_tag": "Project/Tasks",
-  "page_title_uid": "optional-page-title-or-uid",
-  "near_tag": "optional-secondary-tag",
-  "case_sensitive": true
-}
-```
-
-Features:
-
-- Search for blocks containing specific tags
-- Optional filtering by presence of another tag
-- Page-scoped or graph-wide search
-- Case-sensitive or case-insensitive search
-- Returns block content with page context
-- Efficient tag matching using Datalog queries
-
-Parameters:
-
-- `primary_tag`: The main tag to search for (required)
-- `page_title_uid`: Title or UID of the page to search in (optional)
-- `near_tag`: Another tag to filter results by (optional)
-- `case_sensitive`: Whether to perform case-sensitive search (optional, default: true to match Roam's native behavior)
-
-Returns:
-
-```json
-{
-  "success": true,
-  "matches": [
-    {
-      "block_uid": "matching-block-uid",
-      "content": "Block content containing #[[primary_tag]]",
-      "page_title": "Page containing block"
-    }
-  ],
-  "message": "Found N block(s) referencing \"primary_tag\""
-}
-```
-
-### Remember Information
-
-Store memories or important information with automatic tagging and categorization:
-
-```typescript
-use_mcp_tool roam-research roam_remember {
-  "memory": "Important information to remember",
-  "categories": ["Work", "Project/Alpha"]
-}
-```
-
-Features:
-
-- Store information with #[[LLM/Memories]] tag
-- Add optional category tags for organization
-- Automatically adds to today's daily page
-- Supports multiple categories per memory
-- Easy retrieval using roam_search_for_tag
-- Maintains chronological order of memories
-
-Parameters:
-
-- `memory`: The information to remember (required)
-- `categories`: Optional array of categories to tag the memory with
-
-Returns:
-
-```json
-{
-  "success": true,
-  "block_uid": "created-block-uid",
-  "content": "Memory content with tags"
-}
-```
-
-### Search By Date
-
-Search for blocks and pages based on creation or modification dates:
-
-```typescript
-use_mcp_tool roam-research roam_search_by_date {
-  "start_date": "2025-01-01",
-  "end_date": "2025-01-31",
-  "type": "modified",
-  "scope": "blocks",
-  "include_content": true
-}
-```
-
-Features:
-
-- Search by creation date, modification date, or both
-- Filter blocks, pages, or both
-- Optional date range with start and end dates
-- Include or exclude block/page content in results
-- Sort results by timestamp
-- Efficient date-based filtering using Datalog queries
-
-Parameters:
-
-- `start_date`: Start date in ISO format (YYYY-MM-DD) (required)
-- `end_date`: End date in ISO format (YYYY-MM-DD) (optional)
-- `type`: Whether to search by 'created', 'modified', or 'both' (required)
-- `scope`: Whether to search 'blocks', 'pages', or 'both' (required)
-- `include_content`: Whether to include the content of matching blocks/pages (optional, default: true)
-
-Returns:
-
-```json
-{
-  "success": true,
-  "matches": [
-    {
-      "uid": "block-or-page-uid",
-      "type": "block",
-      "time": 1704067200000,
-      "content": "Block or page content",
-      "page_title": "Page title (for blocks)"
-    }
-  ],
-  "message": "Found N matches for the given date range and criteria"
-}
-```
-
-### Find Pages Modified Today
-
-Find all pages that have been modified since midnight today:
-
-```typescript
-use_mcp_tool roam-research roam_find_pages_modified_today {}
-```
-
-Features:
-
-- Tracks all modifications made to pages since midnight
-- Detects changes at any level in the block hierarchy
-- Returns unique list of modified page titles
-- Includes count of modified pages
-- No parameters required
-
-Returns:
-
-```json
-{
-  "success": true,
-  "pages": ["Page 1", "Page 2"],
-  "message": "Found 2 page(s) modified today"
-}
-```
-
-### Execute Datomic Queries
-
-Execute custom Datalog queries on your Roam graph for advanced data retrieval and analysis:
-
-```typescript
-use_mcp_tool roam-research roam_datomic_query {
-  "query": "[:find (count ?p)\n :where [?p :node/title]]",
-  "inputs": []
-}
-```
-
-Features:
-
-- Direct access to Roam's query engine
-- Support for all Datalog query features:
-  - Complex pattern matching
-  - Aggregation functions (count, sum, max, min, avg, distinct)
-  - String operations (includes?, starts-with?, ends-with?)
-  - Logical operations (<, >, <=, >=, =, not=)
-  - Rules for recursive queries
-- Case-sensitive and case-insensitive search capabilities
-- Efficient querying across the entire graph
-
-Parameters:
-
-- `query`: The Datalog query to execute (required)
-- `inputs`: Optional array of input parameters for the query
-
-Returns:
-
-```json
-{
-  "success": true,
-  "matches": [
-    {
-      "content": "[result data]",
-      "block_uid": "",
-      "page_title": ""
-    }
-  ],
-  "message": "Query executed successfully. Found N results."
-}
-```
-
-Example Queries:
-
-1. Count all pages:
-
-```clojure
-[:find (count ?p)
- :where [?p :node/title]]
-```
-
-2. Case-insensitive text search:
-
-```clojure
-[:find ?string ?title
- :where
- [?b :block/string ?string]
- [(clojure.string/lower-case ?string) ?lower]
- [(clojure.string/includes? ?lower "search term")]
- [?b :block/page ?p]
- [?p :node/title ?title]]
-```
-
-3. Find blocks modified after a date:
-
-```clojure
-[:find ?block_ref ?string
- :in $ ?start_of_day
- :where
- [?b :edit/time ?time]
- [(> ?time ?start_of_day)]
- [?b :block/uid ?block_ref]
- [?b :block/string ?string]]
-```
-
-See Roam_Research_Datalog_Cheatsheet.md for more query examples and syntax documentation.
-
-### Search Block Hierarchy
-
-Navigate and search through block parent-child relationships:
-
-```typescript
-use_mcp_tool roam-research roam_search_hierarchy {
-  "parent_uid": "optional-parent-block-uid",
-  "child_uid": "optional-child-block-uid",
-  "page_title_uid": "optional-page-title-or-uid",
-  "max_depth": 3
-}
-```
-
-Features:
-
-- Search up or down the block hierarchy
-- Find children of a specific block
-- Find parents of a specific block
-- Configure search depth (1-10 levels)
-- Optional page scope filtering
-- Includes depth information for each result
-
-Parameters:
-
-- `parent_uid`: UID of the block to find children of (required if searching down)
-- `child_uid`: UID of the block to find parents of (required if searching up)
-- `page_title_uid`: Title or UID of the page to search in (optional)
-- `max_depth`: How many levels deep to search (optional, default: 1, max: 10)
-
-Returns:
-
-```json
-{
-  "success": true,
-  "matches": [
-    {
-      "block_uid": "related-block-uid",
-      "content": "Block content",
-      "depth": 2,
-      "page_title": "Page containing block"
-    }
-  ],
-  "message": "Found N block(s) as children/parents..."
-}
-```
-
 ## Error Handling
 
 The server provides comprehensive error handling for common scenarios:

package/build/config/environment.js

@@ -41,4 +41,6 @@ if (!API_TOKEN || !GRAPH_NAME) {
         '   ROAM_API_TOKEN=your-api-token\n' +
         '   ROAM_GRAPH_NAME=your-graph-name');
 }
-export { API_TOKEN, GRAPH_NAME };
+const HTTP_STREAM_PORT = process.env.HTTP_STREAM_PORT || '8088'; // Default to 8080
+const SSE_PORT = process.env.SSE_PORT || '8087'; // Default to 8087
+export { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, SSE_PORT };

package/build/server/roam-server.js

@@ -1,59 +1,54 @@
 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 { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { initializeGraph } from '@roam-research/roam-api-sdk';
-import { API_TOKEN, GRAPH_NAME } from '../config/environment.js';
+import { API_TOKEN, GRAPH_NAME, HTTP_STREAM_PORT, SSE_PORT } from '../config/environment.js';
 import { toolSchemas } from '../tools/schemas.js';
 import { ToolHandlers } from '../tools/tool-handlers.js';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Read package.json to get the version
+const packageJsonPath = join(__dirname, '../../package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+const serverVersion = packageJson.version;
 export class RoamServer {
     constructor() {
-        this.graph = initializeGraph({
-            token: API_TOKEN,
-            graph: GRAPH_NAME,
-        });
-        this.toolHandlers = new ToolHandlers(this.graph);
-        this.server = new Server({
-            name: 'roam-research',
-            version: '0.25.5',
-        }, {
-            capabilities: {
-                tools: {
-                    roam_remember: {},
-                    roam_recall: {},
-                    roam_add_todo: {},
-                    roam_fetch_page_by_title: {},
-                    roam_create_page: {},
-                    roam_create_block: {},
-                    roam_import_markdown: {},
-                    roam_create_outline: {},
-                    roam_search_for_tag: {},
-                    roam_search_by_status: {},
-                    roam_search_block_refs: {},
-                    roam_search_hierarchy: {},
-                    roam_find_pages_modified_today: {},
-                    roam_search_by_text: {},
-                    roam_update_block: {},
-                    roam_update_multiple_blocks: {},
-                    roam_search_by_date: {},
-                    roam_datomic_query: {}
-                },
-            },
-        });
-        this.setupRequestHandlers();
-        // Error handling
-        this.server.onerror = (error) => { };
-        process.on('SIGINT', async () => {
-            await this.server.close();
-            process.exit(0);
-        });
+        try {
+            this.graph = initializeGraph({
+                token: API_TOKEN,
+                graph: GRAPH_NAME,
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InternalError, `Failed to initialize Roam graph: ${errorMessage}`);
+        }
+        try {
+            this.toolHandlers = new ToolHandlers(this.graph);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InternalError, `Failed to initialize tool handlers: ${errorMessage}`);
+        }
+        // Ensure toolSchemas is not empty before proceeding
+        if (Object.keys(toolSchemas).length === 0) {
+            throw new McpError(ErrorCode.InternalError, 'No tool schemas defined in src/tools/schemas.ts');
+        }
     }
-    setupRequestHandlers() {
+    // Refactored to accept a Server instance
+    setupRequestHandlers(mcpServer) {
         // List available tools
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: Object.values(toolSchemas),
         }));
         // Handle tool calls
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
             try {
                 switch (request.params.name) {
                     case 'roam_remember': {
@@ -220,7 +215,116 @@ export class RoamServer {
         });
     }
     async run() {
-        const transport = new StdioServerTransport();
-        await this.server.connect(transport);
+        try {
+            const stdioMcpServer = new Server({
+                name: 'roam-research',
+                version: serverVersion,
+            }, {
+                capabilities: {
+                    tools: {
+                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
+                    },
+                },
+            });
+            this.setupRequestHandlers(stdioMcpServer);
+            const stdioTransport = new StdioServerTransport();
+            await stdioMcpServer.connect(stdioTransport);
+            const httpMcpServer = new Server({
+                name: 'roam-research-http', // A distinct name for the HTTP server
+                version: serverVersion,
+            }, {
+                capabilities: {
+                    tools: {
+                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
+                    },
+                },
+            });
+            this.setupRequestHandlers(httpMcpServer);
+            const httpStreamTransport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => Math.random().toString(36).substring(2, 15) + Math.random().toString(36).substring(2, 15),
+            });
+            await httpMcpServer.connect(httpStreamTransport);
+            const httpServer = createServer(async (req, res) => {
+                try {
+                    await httpStreamTransport.handleRequest(req, res);
+                }
+                catch (error) {
+                    // console.error('HTTP Stream Server error:', error);
+                    if (!res.headersSent) {
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Internal Server Error' }));
+                    }
+                }
+            });
+            httpServer.listen(parseInt(HTTP_STREAM_PORT), () => {
+                // console.log(`MCP Roam Research server running HTTP Stream on port ${HTTP_STREAM_PORT}`);
+            });
+            // SSE Server setup
+            const sseMcpServer = new Server({
+                name: 'roam-research-sse', // Distinct name for SSE server
+                version: serverVersion,
+            }, {
+                capabilities: {
+                    tools: {
+                        ...Object.fromEntries(Object.keys(toolSchemas).map((toolName) => [toolName, {}])),
+                    },
+                },
+            });
+            this.setupRequestHandlers(sseMcpServer);
+            const sseHttpServer = createServer(async (req, res) => {
+                const parseBody = (request) => {
+                    return new Promise((resolve, reject) => {
+                        let body = '';
+                        request.on('data', (chunk) => {
+                            body += chunk.toString();
+                        });
+                        request.on('end', () => {
+                            try {
+                                resolve(body ? JSON.parse(body) : {});
+                            }
+                            catch (error) {
+                                reject(error);
+                            }
+                        });
+                        request.on('error', reject);
+                    });
+                };
+                try {
+                    if (req.url === '/sse') {
+                        const sseTransport = new SSEServerTransport('/sse', res);
+                        await sseMcpServer.connect(sseTransport);
+                        if (req.method === 'GET') {
+                            await sseTransport.start();
+                        }
+                        else if (req.method === 'POST') {
+                            const parsedBody = await parseBody(req);
+                            await sseTransport.handlePostMessage(req, res, parsedBody);
+                        }
+                        else {
+                            res.writeHead(405, { 'Content-Type': 'text/plain' });
+                            res.end('Method Not Allowed');
+                        }
+                    }
+                    else {
+                        res.writeHead(404, { 'Content-Type': 'text/plain' });
+                        res.end('Not Found');
+                    }
+                }
+                catch (error) {
+                    // console.error('SSE HTTP Server error:', error);
+                    if (!res.headersSent) {
+                        res.writeHead(500, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Internal Server Error' }));
+                    }
+                }
+            });
+            sseHttpServer.listen(parseInt(SSE_PORT), () => {
+                // console.log(`MCP Roam Research server running SSE on port ${SSE_PORT}`);
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new McpError(ErrorCode.InternalError, `Failed to connect MCP server: ${errorMessage}`);
+        }
     }
 }

package/build/tools/schemas.js

@@ -19,21 +19,24 @@ export const toolSchemas = {
         },
     },
     roam_fetch_page_by_title: {
+        name: 'roam_fetch_page_by_title',
         description: 'Fetch page by title, defaults to raw JSON string.',
-        type: 'object',
-        properties: {
-            title: {
-                type: 'string',
-                description: 'Title of the page. For date pages, use ordinal date formats such as January 2nd, 2025'
+        inputSchema: {
+            type: 'object',
+            properties: {
+                title: {
+                    type: 'string',
+                    description: 'Title of the page. For date pages, use ordinal date formats such as January 2nd, 2025'
+                },
+                format: {
+                    type: 'string',
+                    enum: ['markdown', 'raw'],
+                    default: 'raw',
+                    description: "Format output as markdown or JSON. 'markdown' returns as string; 'raw' returns JSON string of the page's blocks"
+                }
             },
-            format: {
-                type: 'string',
-                enum: ['markdown', 'raw'],
-                default: 'raw',
-                description: "Format output as markdown or JSON. 'markdown' returns as string; 'raw' returns JSON string of the page's blocks"
-            }
+            required: ['title']
         },
-        required: ['title']
     },
     roam_create_page: {
         name: 'roam_create_page',
@@ -149,7 +152,7 @@ export const toolSchemas = {
     },
     roam_import_markdown: {
         name: 'roam_import_markdown',
-        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID or by exact string match within a specific page.',
+        description: 'Import nested markdown content into Roam under a specific block. Can locate the parent block by UID (preferred) or by exact string match within a specific page.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -171,7 +174,7 @@ export const toolSchemas = {
                 },
                 parent_string: {
                     type: 'string',
-                    description: 'Optional: Exact string content of the parent block to add content under (must provide either page_uid or page_title)'
+                    description: 'Optional: Exact string content of the parent block to add content under (must provide either page_uid (preferred) or page_title)'
                 },
                 order: {
                     type: 'string',
@@ -311,7 +314,7 @@ export const toolSchemas = {
     },
     roam_update_block: {
         name: 'roam_update_block',
-        description: 'Update a single block identified by its UID. Use this for individual block updates when you need to either replace the entire content or apply a transform pattern to modify specific parts of the content.\nNOTE on Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
+        description: 'Update a single block identified by its UID. Use this for individual block updates when you need to either replace the entire content or apply a transform pattern to modify specific parts of the content.\nNOTE Roam-flavored markdown: For direct linking: use [[link]] syntax. For aliased linking, use [alias]([[link]]) syntax. Do not concatenate words in links/hashtags - correct: #[[multiple words]] #self-esteem (for typically hyphenated words).',
         inputSchema: {
             type: 'object',
             properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roam-research-mcp",
-  "version": "0.25.5",
+  "version": "0.27.0",
   "description": "A Model Context Protocol (MCP) server for Roam Research API integration",
   "private": false,
   "repository": {
@@ -29,12 +29,12 @@
   ],
   "scripts": {
     "build": "tsc && chmod 755 build/index.js",
-    "prepare": "npm run build",
     "watch": "tsc --watch",
-    "inspector": "npx @modelcontextprotocol/inspector build/index.js"
+    "inspector": "npx @modelcontextprotocol/inspector build/index.js",
+    "start": "node build/index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "0.6.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "@roam-research/roam-api-sdk": "^0.10.0",
     "dotenv": "^16.4.7"
   },