[{"_1":2,"_339":-5,"_340":-5},"loaderData",{"_3":4,"_22":23,"_274":275},"root",{"_5":6,"_7":8},"toasts",[],"visitor",{"_9":10,"_11":12},"viewportWidth",1280,"visitorSession",{"_13":14,"_16":17,"_18":-5,"_19":20,"_21":-5},"attributes",[15],"bot","id",16419384,"membership","referenceId","019973c7-087b-708a-81cf-05fe85a3a946","userAccount","routes/_public/mcp/servers/~namespace/~slug/_pages/_layout",{"_24":25,"_66":-5,"_67":26,"_27":68,"_190":191,"_272":273},"availableLocales",[26,38,45,52,59],{"_27":28,"_31":35,"_36":37},"mcpServer",{"_29":30,"_31":32,"_33":34},"description","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.","name","Roam Research","readme","# Roam Research MCP Server\n\n[![npm version](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp)\n[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)\n\nA 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)\n\n $\"Roam$ \n\n## Installation\n\nYou can install the package globally:\n\n```bash\nnpm install -g roam-research-mcp\n```\n\nOr clone the repository and build from source:\n\n```bash\ngit clone https://github.com/2b3pro/roam-research-mcp.git\ncd roam-research-mcp\nnpm install\nnpm run build\n```\n\n## To Test\n\nRun [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build…\n\n```\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n## Features\n\nThe server provides powerful tools for interacting with Roam Research:\n\n- Environment variable handling with .env support\n- Comprehensive input validation\n- Case-insensitive page title matching\n- Recursive block reference resolution\n- Markdown parsing and conversion\n- Daily page integration\n- Detailed debug logging\n- Efficient batch operations\n- Hierarchical outline creation\n\n1. `roam_fetch_page_by_title`: Fetch and read a page's content by title, recursively resolving block references up to 4 levels deep\n2. `roam_create_page`: Create new pages with optional content\n3. `roam_create_block`: Create new blocks in a page (defaults to today's daily page)\n4. `roam_import_markdown`: Import nested markdown content under specific blocks\n5. `roam_add_todo`: Add multiple todo items to today's daily page with checkbox syntax\n6. `roam_create_outline`: Create hierarchical outlines with proper nesting and structure\n7. `roam_search_block_refs`: Search for block references within pages or across the graph\n8. `roam_search_hierarchy`: Navigate and search through block parent-child relationships\n9. `roam_find_pages_modified_today`: Find all pages that have been modified since midnight today\n10. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page\n11. `roam_update_block`: Update block content with direct text or pattern-based transformations\n12. `roam_search_by_date`: Search for blocks and pages based on creation or modification dates\n13. `roam_search_for_tag`: Search for blocks containing specific tags with optional filtering by nearby tags\n14. `roam_remember`: Store and categorize memories or information with automatic tagging\n15. `roam_recall`: Recall memories of blocks marked with tag MEMORIES_TAG (see below) or blocks on page title of the same name\n16. `roam_datomic_query`: Execute custom Datalog queries on the Roam graph for advanced data retrieval and analysis\n\n## Setup\n\n1. Create a [Roam Research API token](https://x.com/RoamResearch/status/1789358175474327881):\n\n - Go to your graph settings\n - Navigate to the \"API tokens\" section (Settings > \"Graph\" tab > \"API Tokens\" section and click on the \"+ New API Token\" button)\n - Create a new token\n\n2. Configure the environment variables:\n You have two options for configuring the required environment variables:\n\n Option 1: Using a .env file (Recommended for development)\n Create a `.env` file in the roam-research directory:\n\n ```\n ROAM_API_TOKEN=your-api-token\n ROAM_GRAPH_NAME=your-graph-name\n MEMORIES_TAG='#[[LLM/Memories]]'\n ```\n\n Option 2: Using MCP settings (Alternative method)\n Add the configuration to your MCP settings file:\n\n - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):\n - For Claude desktop app (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n ```json\n {\n \"mcpServers\": {\n \"roam-research\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/roam-research-mcp/build/index.js\"],\n \"env\": {\n \"ROAM_API_TOKEN\": \"your-api-token\",\n \"ROAM_GRAPH_NAME\": \"your-graph-name\",\n \"MEMORIES_TAG\": \"#[[LLM/Memories]]\"\n }\n }\n }\n }\n ```\n\n Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.\n\n3. Build the server (make sure you're in the root directory of the MCP):\n ```bash\n cd roam-research-mcp\n npm install\n npm run build\n ```\n\n## Usage\n\n### Fetch Page By Title\n\nFetch and read a page's content with resolved block references:\n\n```typescript\nuse_mcp_tool roam-research roam_fetch_page_by_title {\n \"title\": \"Example Page\"\n}\n```\n\nReturns the page content as markdown with:\n\n- Complete hierarchical structure\n- Block references recursively resolved (up to 4 levels deep)\n- Proper indentation for nesting levels\n- Full markdown formatting\n\n### Create Page\n\nCreate a new page with optional content:\n\n```typescript\nuse_mcp_tool roam-research roam_create_page {\n \"title\": \"New Page\",\n \"content\": \"Initial content for the page\"\n}\n```\n\nReturns the created page's UID on success.\n\n### Create Block\n\nAdd a new block to a page (defaults to today's daily page if neither page_uid nor title provided):\n\n```typescript\nuse_mcp_tool roam-research roam_create_block {\n \"content\": \"Block content\",\n \"page_uid\": \"optional-target-page-uid\",\n \"title\": \"optional-target-page-title\"\n}\n```\n\nYou can specify either:\n\n- `page_uid`: Direct reference to target page\n- `title`: Name of target page (will be created if it doesn't exist)\n- Neither: Block will be added to today's daily page\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"parent_uid\": \"parent-page-uid\"\n}\n```\n\n### Create Outline\n\nCreate a hierarchical outline with proper nesting and structure:\n\n```typescript\nuse_mcp_tool roam-research roam_create_outline {\n \"outline\": [\n {\n \"text\": \"I. Top Level\",\n \"level\": 1\n },\n {\n \"text\": \"A. Second Level\",\n \"level\": 2\n },\n {\n \"text\": \"1. Third Level\",\n \"level\": 3\n }\n ],\n \"page_title_uid\": \"optional-target-page\",\n \"block_text_uid\": \"optional-header-text\"\n}\n```\n\nFeatures:\n\n- Create complex outlines with up to 10 levels of nesting\n- Validate outline structure and content\n- Maintain proper parent-child relationships\n- Optional header block for the outline\n- Defaults to today's daily page if no page specified\n- Efficient batch operations for creating blocks\n\nParameters:\n\n- `outline`: Array of outline items, each with:\n - `text`: Content of the outline item (required)\n - `level`: Nesting level (1-10, required)\n- `page_title_uid`: Target page title or UID (optional, defaults to today's page)\n- `block_text_uid`: Header text for the outline (optional)\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"header-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n}\n```\n\n### Add Todo Items\n\nAdd one or more todo items to today's daily page:\n\n```typescript\nuse_mcp_tool roam-research roam_add_todo {\n \"todos\": [\n \"First todo item\",\n \"Second todo item\",\n \"Third todo item\"\n ]\n}\n```\n\nFeatures:\n\n- Adds todos with Roam checkbox syntax (`{{TODO}} todo text`)\n- Supports adding multiple todos in a single operation\n- Uses batch actions for efficiency when adding >10 todos\n- Automatically creates today's page if it doesn't exist\n- Adds todos as top-level blocks in sequential order\n\n### Import Nested Markdown\n\nImport nested markdown content under a specific block:\n\n```typescript\nuse_mcp_tool roam-research roam_import_markdown {\n \"content\": \"- Item 1\\n - Subitem A\\n - Subitem B\\n- Item 2\",\n \"page_uid\": \"optional-page-uid\",\n \"page_title\": \"optional-page-title\",\n \"parent_uid\": \"optional-parent-block-uid\",\n \"parent_string\": \"optional-exact-block-content\",\n \"order\": \"first\"\n}\n```\n\nFeatures:\n\n- Import content under specific blocks:\n - Find parent block by UID or exact string match\n - Locate blocks within specific pages by title or UID\n - Defaults to today's page if no page specified\n- Control content placement:\n - Add as first or last child of parent block\n - Preserve hierarchical structure\n - Efficient batch operations for nested content\n- Comprehensive return value:\n ```json\n {\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"parent-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n }\n ```\n\nParameters:\n\n- `content`: Nested markdown content to import\n- `page_uid`: UID of the page containing the parent block\n- `page_title`: Title of the page containing the parent block (ignored if page_uid provided)\n- `parent_uid`: UID of the parent block to add content under\n- `parent_string`: Exact string content of the parent block (must provide either page_uid or page_title)\n- `order`: Where to add the content (\"first\" or \"last\", defaults to \"first\")\n\n### Search Block References\n\nSearch for block references within pages or across the entire graph:\n\n```typescript\nuse_mcp_tool roam-research roam_search_block_refs {\n \"block_uid\": \"optional-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\"\n}\n```\n\nFeatures:\n\n- Find all references to a specific block\n- Search for any block references within a page\n- Search across the entire graph\n- Supports both direct and indirect references\n- Includes block content and location context\n\nParameters:\n\n- `block_uid`: UID of the block to find references to (optional)\n- `page_title_uid`: Title or UID of the page to search in (optional)\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"referenced-block-uid\",\n \"content\": \"Block content with ((reference))\",\n \"page_title\": \"Page containing reference\"\n }\n ],\n \"message\": \"Found N block(s) referencing...\"\n}\n```\n\n### Search By Text\n\nSearch for blocks containing specific text across all pages or within a specific page:\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_text {\n \"text\": \"search text\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"case_sensitive\": true\n}\n```\n\nFeatures:\n\n- Search for any text across all blocks in the graph\n- Optional page-scoped search\n- Case-sensitive or case-insensitive search\n- Returns block content with page context\n- Efficient text matching using Datalog queries\n\nParameters:\n\n- `text`: The text to search for (required)\n- `page_title_uid`: Title or UID of the page to search in (optional)\n- `case_sensitive`: Whether to perform a case-sensitive search (optional, default: true to match Roam's native behavior)\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing search text\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) containing \\\"search text\\\"\"\n}\n```\n\n### Update Block Content\n\nUpdate a block's content using either direct text replacement or pattern-based transformations:\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"content\": \"New block content\"\n}\n```\n\nOr use pattern-based transformation:\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"transform_pattern\": {\n \"find\": \"\\\\bPython\\\\b\",\n \"replace\": \"[[Python]]\",\n \"global\": true\n }\n}\n```\n\nFeatures:\n\n- Two update modes:\n - Direct content replacement\n - Pattern-based transformation using regex\n- Verify block existence before updating\n- Return updated content in response\n- Support for global or single-match replacements\n- Preserve block relationships and metadata\n\nParameters:\n\n- `block_uid`: UID of the block to update (required)\n- `content`: New content for the block (if using direct replacement)\n- `transform_pattern`: Pattern for transforming existing content:\n - `find`: Text or regex pattern to find\n - `replace`: Text to replace with\n - `global`: Whether to replace all occurrences (default: true)\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"content\": \"Updated block content\"\n}\n```\n\n### Search For Tags\n\nSearch for blocks containing specific tags with optional filtering by nearby tags:\n\n```typescript\nuse_mcp_tool roam-research roam_search_for_tag {\n \"primary_tag\": \"Project/Tasks\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"near_tag\": \"optional-secondary-tag\",\n \"case_sensitive\": true\n}\n```\n\nFeatures:\n\n- Search for blocks containing specific tags\n- Optional filtering by presence of another tag\n- Page-scoped or graph-wide search\n- Case-sensitive or case-insensitive search\n- Returns block content with page context\n- Efficient tag matching using Datalog queries\n\nParameters:\n\n- `primary_tag`: The main tag to search for (required)\n- `page_title_uid`: Title or UID of the page to search in (optional)\n- `near_tag`: Another tag to filter results by (optional)\n- `case_sensitive`: Whether to perform case-sensitive search (optional, default: true to match Roam's native behavior)\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing #[[primary_tag]]\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) referencing \\\"primary_tag\\\"\"\n}\n```\n\n### Remember Information\n\nStore memories or important information with automatic tagging and categorization:\n\n```typescript\nuse_mcp_tool roam-research roam_remember {\n \"memory\": \"Important information to remember\",\n \"categories\": [\"Work\", \"Project/Alpha\"]\n}\n```\n\nFeatures:\n\n- Store information with #[[LLM/Memories]] tag\n- Add optional category tags for organization\n- Automatically adds to today's daily page\n- Supports multiple categories per memory\n- Easy retrieval using roam_search_for_tag\n- Maintains chronological order of memories\n\nParameters:\n\n- `memory`: The information to remember (required)\n- `categories`: Optional array of categories to tag the memory with\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"content\": \"Memory content with tags\"\n}\n```\n\n### Search By Date\n\nSearch for blocks and pages based on creation or modification dates:\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_date {\n \"start_date\": \"2025-01-01\",\n \"end_date\": \"2025-01-31\",\n \"type\": \"modified\",\n \"scope\": \"blocks\",\n \"include_content\": true\n}\n```\n\nFeatures:\n\n- Search by creation date, modification date, or both\n- Filter blocks, pages, or both\n- Optional date range with start and end dates\n- Include or exclude block/page content in results\n- Sort results by timestamp\n- Efficient date-based filtering using Datalog queries\n\nParameters:\n\n- `start_date`: Start date in ISO format (YYYY-MM-DD) (required)\n- `end_date`: End date in ISO format (YYYY-MM-DD) (optional)\n- `type`: Whether to search by 'created', 'modified', or 'both' (required)\n- `scope`: Whether to search 'blocks', 'pages', or 'both' (required)\n- `include_content`: Whether to include the content of matching blocks/pages (optional, default: true)\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"uid\": \"block-or-page-uid\",\n \"type\": \"block\",\n \"time\": 1704067200000,\n \"content\": \"Block or page content\",\n \"page_title\": \"Page title (for blocks)\"\n }\n ],\n \"message\": \"Found N matches for the given date range and criteria\"\n}\n```\n\n### Find Pages Modified Today\n\nFind all pages that have been modified since midnight today:\n\n```typescript\nuse_mcp_tool roam-research roam_find_pages_modified_today {}\n```\n\nFeatures:\n\n- Tracks all modifications made to pages since midnight\n- Detects changes at any level in the block hierarchy\n- Returns unique list of modified page titles\n- Includes count of modified pages\n- No parameters required\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"pages\": [\"Page 1\", \"Page 2\"],\n \"message\": \"Found 2 page(s) modified today\"\n}\n```\n\n### Execute Datomic Queries\n\nExecute custom Datalog queries on your Roam graph for advanced data retrieval and analysis:\n\n```typescript\nuse_mcp_tool roam-research roam_datomic_query {\n \"query\": \"[:find (count ?p)\\n :where [?p :node/title]]\",\n \"inputs\": []\n}\n```\n\nFeatures:\n\n- Direct access to Roam's query engine\n- Support for all Datalog query features:\n - Complex pattern matching\n - Aggregation functions (count, sum, max, min, avg, distinct)\n - String operations (includes?, starts-with?, ends-with?)\n - Logical operations (<, >, <=, >=, =, not=)\n - Rules for recursive queries\n- Case-sensitive and case-insensitive search capabilities\n- Efficient querying across the entire graph\n\nParameters:\n\n- `query`: The Datalog query to execute (required)\n- `inputs`: Optional array of input parameters for the query\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"content\": \"[result data]\",\n \"block_uid\": \"\",\n \"page_title\": \"\"\n }\n ],\n \"message\": \"Query executed successfully. Found N results.\"\n}\n```\n\nExample Queries:\n\n1. Count all pages:\n\n```clojure\n[:find (count ?p)\n :where [?p :node/title]]\n```\n\n2. Case-insensitive text search:\n\n```clojure\n[:find ?string ?title\n :where\n [?b :block/string ?string]\n [(clojure.string/lower-case ?string) ?lower]\n [(clojure.string/includes? ?lower \"search term\")]\n [?b :block/page ?p]\n [?p :node/title ?title]]\n```\n\n3. Find blocks modified after a date:\n\n```clojure\n[:find ?block_ref ?string\n :in $ ?start_of_day\n :where\n [?b :edit/time ?time]\n [(> ?time ?start_of_day)]\n [?b :block/uid ?block_ref]\n [?b :block/string ?string]]\n```\n\nSee Roam_Research_Datalog_Cheatsheet.md for more query examples and syntax documentation.\n\n### Search Block Hierarchy\n\nNavigate and search through block parent-child relationships:\n\n```typescript\nuse_mcp_tool roam-research roam_search_hierarchy {\n \"parent_uid\": \"optional-parent-block-uid\",\n \"child_uid\": \"optional-child-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"max_depth\": 3\n}\n```\n\nFeatures:\n\n- Search up or down the block hierarchy\n- Find children of a specific block\n- Find parents of a specific block\n- Configure search depth (1-10 levels)\n- Optional page scope filtering\n- Includes depth information for each result\n\nParameters:\n\n- `parent_uid`: UID of the block to find children of (required if searching down)\n- `child_uid`: UID of the block to find parents of (required if searching up)\n- `page_title_uid`: Title or UID of the page to search in (optional)\n- `max_depth`: How many levels deep to search (optional, default: 1, max: 10)\n\nReturns:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"related-block-uid\",\n \"content\": \"Block content\",\n \"depth\": 2,\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) as children/parents...\"\n}\n```\n\n## Error Handling\n\nThe server provides comprehensive error handling for common scenarios:\n\n- Configuration errors:\n - Missing API token or graph name\n - Invalid environment variables\n- API errors:\n - Authentication failures\n - Invalid requests\n - Failed operations\n- Tool-specific errors:\n - Page not found (with case-insensitive search)\n - Block not found by string match\n - Invalid markdown format\n - Missing required parameters\n - Invalid outline structure or content\n\nEach error response includes:\n\n- Standard MCP error code\n- Detailed error message\n- Suggestions for resolution when applicable\n\n## Development\n\n### Building\n\nTo build the server:\n\n```bash\nnpm install\nnpm run build\n```\n\nThis will:\n\n1. Install all required dependencies\n2. Compile TypeScript to JavaScript\n3. Make the output file executable\n\nYou can also use `npm run watch` during development to automatically recompile when files change.\n\n### Testing with MCP Inspector\n\nThe MCP Inspector is a tool that helps test and debug MCP servers. To test the server:\n\n```bash\n# Inspect with npx:\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\nThis will:\n\n1. Start the server in inspector mode\n2. Provide an interactive interface to:\n - List available tools and resources\n - Execute tools with custom parameters\n - View tool responses and error handling\n\n## License\n\nMIT License\n","English","tag","en-US",{"_27":39,"_31":43,"_36":44},{"_29":40,"_31":41,"_33":42},"Proporciona acceso completo a la funcionalidad API de Roam Research. Este servidor permite que asistentes de IA como Claude interactúen con su gráfico de Roam Research a través de una interfaz estandarizada.","Investigación de Roam","# Servidor MCP de Roam Research\n\n[![versión npm](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp) [![Estado del proyecto: WIP – El desarrollo inicial está en progreso, pero aún no hay una versión estable y utilizable adecuada para el público.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![Licencia: 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)\n\nUn servidor de Protocolo de Contexto de Modelo (MCP) que proporciona acceso completo a la funcionalidad de la API de Roam Research. Este servidor permite que asistentes de IA como Claude interactúen con su gráfico de Roam Research a través de una interfaz estandarizada. (Un proyecto personal en desarrollo, no avalado oficialmente por Roam Research).\n\n## Instalación\n\nPuede instalar el paquete globalmente:\n\n```bash\nnpm install -g roam-research-mcp\n```\n\nO clonar el repositorio y compilar desde la fuente:\n\n```bash\ngit clone https://github.com/2b3pro/roam-research-mcp.git\ncd roam-research-mcp\nnpm install\nnpm run build\n```\n\n## Para probar\n\nEjecutar [MCP Inspector](https://github.com/modelcontextprotocol/inspector) después de la compilación…\n\n```\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n## Características\n\nEl servidor proporciona herramientas potentes para interactuar con Roam Research:\n\n* Manejo de variables de entorno con soporte .env\n* Validación de entrada integral\n* Coincidencia de títulos de páginas sin distinción entre mayúsculas y minúsculas\n* Resolución de referencia de bloque recursiva\n* Análisis y conversión de Markdown\n* Integración de páginas diarias\n* Registro de depuración detallado\n* Operaciones por lotes eficientes\n* Creación de esquemas jerárquicos\n\n1. `roam_fetch_page_by_title` : recupera y lee el contenido de una página por título, resolviendo recursivamente referencias de bloque hasta 4 niveles de profundidad\n2. `roam_create_page` : Crea nuevas páginas con contenido opcional\n3. `roam_create_block` : Crea nuevos bloques en una página (por defecto, la página diaria de hoy)\n4. `roam_import_markdown` : Importa contenido de Markdown anidado bajo bloques específicos\n5. `roam_add_todo` : agrega múltiples elementos de tareas pendientes a la página diaria de hoy con sintaxis de casilla de verificación\n6. `roam_create_outline` : Crea esquemas jerárquicos con anidamiento y estructura adecuados\n7. `roam_search_block_refs` : busca referencias de bloques dentro de las páginas o en el gráfico\n8. `roam_search_hierarchy` : Navegar y buscar a través de las relaciones padre-hijo del bloque\n9. `roam_find_pages_modified_today` : Encuentra todas las páginas que han sido modificadas desde la medianoche de hoy\n10. `roam_search_by_text` : busca bloques que contengan texto específico en todas las páginas o dentro de una página específica\n11. `roam_update_block` : Actualiza el contenido del bloque con texto directo o transformaciones basadas en patrones\n12. `roam_search_by_date` : busca bloques y páginas según las fechas de creación o modificación\n13. `roam_search_for_tag` : busca bloques que contengan etiquetas específicas con filtrado opcional por etiquetas cercanas\n14. `roam_remember` : Almacena y categoriza recuerdos o información con etiquetado automático\n15. `roam_recall` : Recupera recuerdos de bloques marcados con la etiqueta MEMORIES\\_TAG (ver más abajo) o bloques en el título de la página del mismo nombre\n16. `roam_datomic_query` : Ejecuta consultas de registro de datos personalizadas en el gráfico de Roam para la recuperación y el análisis avanzados de datos\n\n## Configuración\n\n1. Crear un [token de API de Roam Research](https://x.com/RoamResearch/status/1789358175474327881) :\n\n * Vaya a la configuración de sus gráficos\n * Vaya a la sección \"Tokens de API\" (Configuración > pestaña \"Gráfico\" > sección \"Tokens de API\" y haga clic en el botón \"+ Nuevo token de API\").\n * Crear un nuevo token\n\n2. Configurar las variables de entorno: Tiene dos opciones para configurar las variables de entorno requeridas:\n\n Opción 1: Usar un archivo .env (recomendado para desarrollo) Cree un archivo `.env` en el directorio roam-research:\n\n ```\n ROAM_API_TOKEN=your-api-token\n ROAM_GRAPH_NAME=your-graph-name\n MEMORIES_TAG='#[[LLM/Memories]]'\n ```\n\n Opción 2: Usar la configuración de MCP (método alternativo) Agregue la configuración a su archivo de configuración de MCP:\n\n * Para Cline ( `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` ):\n * Para la aplicación de escritorio Claude ( `~/Library/Application Support/Claude/claude_desktop_config.json` ):\n\n ```json\n {\n \"mcpServers\": {\n \"roam-research\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/roam-research-mcp/build/index.js\"],\n \"env\": {\n \"ROAM_API_TOKEN\": \"your-api-token\",\n \"ROAM_GRAPH_NAME\": \"your-graph-name\",\n \"MEMORIES_TAG\": \"#[[LLM/Memories]]\"\n }\n }\n }\n }\n ```\n\n Nota: El servidor primero intentará cargar desde el archivo .env y luego recurrirá a las variables de entorno de la configuración de MCP.\n\n3. Construya el servidor (asegúrese de estar en el directorio raíz del MCP):\n\n ```bash\n cd roam-research-mcp\n npm install\n npm run build\n ```\n\n## Uso\n\n### Obtener página por título\n\nObtener y leer el contenido de una página con referencias de bloque resueltas:\n\n```typescript\nuse_mcp_tool roam-research roam_fetch_page_by_title {\n \"title\": \"Example Page\"\n}\n```\n\nDevuelve el contenido de la página como markdown con:\n\n* Estructura jerárquica completa\n* Referencias de bloque resueltas recursivamente (hasta 4 niveles de profundidad)\n* Sangría adecuada para niveles de anidamiento\n* Formato de rebajas completo\n\n### Crear página\n\nCrear una nueva página con contenido opcional:\n\n```typescript\nuse_mcp_tool roam-research roam_create_page {\n \"title\": \"New Page\",\n \"content\": \"Initial content for the page\"\n}\n```\n\nDevuelve el UID de la página creada en caso de éxito.\n\n### Crear bloque\n\nAgregar un nuevo bloque a una página (el valor predeterminado es la página diaria de hoy si no se proporciona ni page\\_uid ni title):\n\n```typescript\nuse_mcp_tool roam-research roam_create_block {\n \"content\": \"Block content\",\n \"page_uid\": \"optional-target-page-uid\",\n \"title\": \"optional-target-page-title\"\n}\n```\n\nPuede especificar:\n\n* `page_uid` : Referencia directa a la página de destino\n* `title` : Nombre de la página de destino (se creará si no existe)\n* Ninguno: Se agregará un bloque a la página diaria de hoy.\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"parent_uid\": \"parent-page-uid\"\n}\n```\n\n### Crear esquema\n\nCrear un esquema jerárquico con anidación y estructura adecuadas:\n\n```typescript\nuse_mcp_tool roam-research roam_create_outline {\n \"outline\": [\n {\n \"text\": \"I. Top Level\",\n \"level\": 1\n },\n {\n \"text\": \"A. Second Level\",\n \"level\": 2\n },\n {\n \"text\": \"1. Third Level\",\n \"level\": 3\n }\n ],\n \"page_title_uid\": \"optional-target-page\",\n \"block_text_uid\": \"optional-header-text\"\n}\n```\n\nCaracterísticas:\n\n* Cree contornos complejos con hasta 10 niveles de anidamiento\n* Validar la estructura y el contenido del esquema\n* Mantener relaciones adecuadas entre padres e hijos\n* Bloque de encabezado opcional para el esquema\n* El valor predeterminado es la página diaria de hoy si no se especifica ninguna página\n* Operaciones por lotes eficientes para crear bloques\n\nParámetros:\n\n* `outline` : Matriz de elementos de esquema, cada uno con:\n * `text` : Contenido del elemento del esquema (obligatorio)\n * `level` : Nivel de anidamiento (1-10, obligatorio)\n* `page_title_uid` : Título de la página de destino o UID (opcional, el valor predeterminado es la página de hoy)\n* `block_text_uid` : Texto de encabezado para el esquema (opcional)\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"header-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n}\n```\n\n### Agregar elementos de tareas pendientes\n\nAgregue uno o más elementos de tareas pendientes a la página diaria de hoy:\n\n```typescript\nuse_mcp_tool roam-research roam_add_todo {\n \"todos\": [\n \"First todo item\",\n \"Second todo item\",\n \"Third todo item\"\n ]\n}\n```\n\nCaracterísticas:\n\n* Agrega todos con sintaxis de casilla de verificación Roam ( `{{TODO}} todo text` )\n* Admite agregar varias tareas pendientes en una sola operación\n* Utiliza acciones por lotes para lograr eficiencia al agregar más de 10 tareas pendientes\n* Crea automáticamente la página de hoy si no existe\n* Agrega tareas pendientes como bloques de nivel superior en orden secuencial\n\n### Importar Markdown anidado\n\nImportar contenido de Markdown anidado bajo un bloque específico:\n\n```typescript\nuse_mcp_tool roam-research roam_import_markdown {\n \"content\": \"- Item 1\\n - Subitem A\\n - Subitem B\\n- Item 2\",\n \"page_uid\": \"optional-page-uid\",\n \"page_title\": \"optional-page-title\",\n \"parent_uid\": \"optional-parent-block-uid\",\n \"parent_string\": \"optional-exact-block-content\",\n \"order\": \"first\"\n}\n```\n\nCaracterísticas:\n\n* Importar contenido bajo bloques específicos:\n\n * Buscar bloque padre por UID o coincidencia exacta de cadena\n * Localizar bloques dentro de páginas específicas por título o UID\n * Se establece como predeterminado la página de hoy si no se especifica ninguna página\n\n* Controlar la ubicación del contenido:\n\n * Agregar como primer o último hijo del bloque padre\n * Preservar la estructura jerárquica\n * Operaciones por lotes eficientes para contenido anidado\n\n* Valor de retorno integral:\n\n ```json\n {\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"parent-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n }\n ```\n\nParámetros:\n\n* `content` : Contenido de rebajas anidado para importar\n* `page_uid` : UID de la página que contiene el bloque padre\n* `page_title` : Título de la página que contiene el bloque padre (se ignora si se proporciona page\\_uid)\n* `parent_uid` : UID del bloque padre bajo el cual se agregará contenido\n* `parent_string` : contenido exacto de la cadena del bloque padre (debe proporcionar page\\_uid o page\\_title)\n* `order` : Dónde agregar el contenido (\"primero\" o \"último\", predeterminado \"primero\")\n\n### Referencias del bloque de búsqueda\n\nBusque referencias de bloques dentro de las páginas o en todo el gráfico:\n\n```typescript\nuse_mcp_tool roam-research roam_search_block_refs {\n \"block_uid\": \"optional-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\"\n}\n```\n\nCaracterísticas:\n\n* Encuentra todas las referencias a un bloque específico\n* Busque cualquier referencia de bloque dentro de una página\n* Buscar en todo el gráfico\n* Admite referencias tanto directas como indirectas\n* Incluye contenido de bloque y contexto de ubicación.\n\nParámetros:\n\n* `block_uid` : UID del bloque al que se buscarán referencias (opcional)\n* `page_title_uid` : Título o UID de la página donde buscar (opcional)\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"referenced-block-uid\",\n \"content\": \"Block content with ((reference))\",\n \"page_title\": \"Page containing reference\"\n }\n ],\n \"message\": \"Found N block(s) referencing...\"\n}\n```\n\n### Buscar por texto\n\nBusque bloques que contengan texto específico en todas las páginas o dentro de una página específica:\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_text {\n \"text\": \"search text\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"case_sensitive\": true\n}\n```\n\nCaracterísticas:\n\n* Busque cualquier texto en todos los bloques del gráfico\n* Búsqueda opcional en el ámbito de la página\n* Búsqueda con o sin distinción entre mayúsculas y minúsculas\n* Devuelve el contenido del bloque con el contexto de la página.\n* Coincidencia de texto eficiente mediante consultas de registro de datos\n\nParámetros:\n\n* `text` : El texto a buscar (obligatorio)\n* `page_title_uid` : Título o UID de la página donde buscar (opcional)\n* `case_sensitive` : si se debe realizar una búsqueda que distinga entre mayúsculas y minúsculas (opcional, valor predeterminado: verdadero para que coincida con el comportamiento nativo de Roam)\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing search text\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) containing \\\"search text\\\"\"\n}\n```\n\n### Actualizar el contenido del bloque\n\nActualice el contenido de un bloque utilizando reemplazo de texto directo o transformaciones basadas en patrones:\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"content\": \"New block content\"\n}\n```\n\nO utilice la transformación basada en patrones:\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"transform_pattern\": {\n \"find\": \"\\\\bPython\\\\b\",\n \"replace\": \"[[Python]]\",\n \"global\": true\n }\n}\n```\n\nCaracterísticas:\n\n* Dos modos de actualización:\n * Reemplazo directo de contenido\n * Transformación basada en patrones usando expresiones regulares\n* Verificar la existencia del bloque antes de actualizar\n* Devolver contenido actualizado en respuesta\n* Soporte para reemplazos globales o de un solo partido\n* Preservar las relaciones de bloques y los metadatos\n\nParámetros:\n\n* `block_uid` : UID del bloque a actualizar (obligatorio)\n* `content` : Nuevo contenido para el bloque (si se usa reemplazo directo)\n* `transform_pattern` : Patrón para transformar contenido existente:\n * `find` : Texto o patrón de expresión regular para buscar\n * `replace` : Texto con el que reemplazar\n * `global` : si se deben reemplazar todas las ocurrencias (valor predeterminado: verdadero)\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"content\": \"Updated block content\"\n}\n```\n\n### Buscar etiquetas\n\nBusque bloques que contengan etiquetas específicas con filtrado opcional por etiquetas cercanas:\n\n```typescript\nuse_mcp_tool roam-research roam_search_for_tag {\n \"primary_tag\": \"Project/Tasks\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"near_tag\": \"optional-secondary-tag\",\n \"case_sensitive\": true\n}\n```\n\nCaracterísticas:\n\n* Buscar bloques que contengan etiquetas específicas\n* Filtrado opcional por presencia de otra etiqueta\n* Búsqueda en el ámbito de la página o en todo el gráfico\n* Búsqueda con o sin distinción entre mayúsculas y minúsculas\n* Devuelve el contenido del bloque con el contexto de la página.\n* Coincidencia eficiente de etiquetas mediante consultas de registro de datos\n\nParámetros:\n\n* `primary_tag` : La etiqueta principal a buscar (obligatorio)\n* `page_title_uid` : Título o UID de la página donde buscar (opcional)\n* `near_tag` : Otra etiqueta para filtrar los resultados (opcional)\n* `case_sensitive` : si se debe realizar una búsqueda que distinga entre mayúsculas y minúsculas (opcional, valor predeterminado: verdadero para que coincida con el comportamiento nativo de Roam)\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing #[[primary_tag]]\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) referencing \\\"primary_tag\\\"\"\n}\n```\n\n### Recordar información\n\nAlmacene recuerdos o información importante con etiquetado y categorización automáticos:\n\n```typescript\nuse_mcp_tool roam-research roam_remember {\n \"memory\": \"Important information to remember\",\n \"categories\": [\"Work\", \"Project/Alpha\"]\n}\n```\n\nCaracterísticas:\n\n* Almacenar información con la etiqueta #\\[\\[LLM/Memories]]\n* Agregar etiquetas de categoría opcionales para la organización\n* Se agrega automáticamente a la página diaria de hoy.\n* Admite múltiples categorías por memoria\n* Recuperación fácil usando roam\\_search\\_for\\_tag\n* Mantiene el orden cronológico de los recuerdos.\n\nParámetros:\n\n* `memory` : La información a recordar (obligatoria)\n* `categories` : Matriz opcional de categorías para etiquetar la memoria\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"content\": \"Memory content with tags\"\n}\n```\n\n### Buscar por fecha\n\nBuscar bloques y páginas según fechas de creación o modificación:\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_date {\n \"start_date\": \"2025-01-01\",\n \"end_date\": \"2025-01-31\",\n \"type\": \"modified\",\n \"scope\": \"blocks\",\n \"include_content\": true\n}\n```\n\nCaracterísticas:\n\n* Buscar por fecha de creación, fecha de modificación o ambas\n* Bloques de filtros, páginas o ambos\n* Rango de fechas opcional con fechas de inicio y finalización\n* Incluir o excluir contenido de bloque/página en los resultados\n* Ordenar resultados por marca de tiempo\n* Filtrado eficiente basado en fechas mediante consultas de registro de datos\n\nParámetros:\n\n* `start_date` : Fecha de inicio en formato ISO (AAAA-MM-DD) (obligatorio)\n* `end_date` : Fecha de finalización en formato ISO (AAAA-MM-DD) (opcional)\n* `type` : si desea buscar por 'creado', 'modificado' o 'ambos' (obligatorio)\n* `scope` : si se debe buscar 'bloques', 'páginas' o 'ambos' (obligatorio)\n* `include_content` : si se debe incluir el contenido de los bloques/páginas coincidentes (opcional, valor predeterminado: verdadero)\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"uid\": \"block-or-page-uid\",\n \"type\": \"block\",\n \"time\": 1704067200000,\n \"content\": \"Block or page content\",\n \"page_title\": \"Page title (for blocks)\"\n }\n ],\n \"message\": \"Found N matches for the given date range and criteria\"\n}\n```\n\n### Encuentra páginas modificadas hoy\n\nEncuentra todas las páginas que han sido modificadas desde la medianoche de hoy:\n\n```typescript\nuse_mcp_tool roam-research roam_find_pages_modified_today {}\n```\n\nCaracterísticas:\n\n* Realiza un seguimiento de todas las modificaciones realizadas en las páginas desde la medianoche.\n* Detecta cambios en cualquier nivel de la jerarquía de bloques.\n* Devuelve una lista única de títulos de páginas modificados\n* Incluye recuento de páginas modificadas\n* No se requieren parámetros\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"pages\": [\"Page 1\", \"Page 2\"],\n \"message\": \"Found 2 page(s) modified today\"\n}\n```\n\n### Ejecutar consultas Datomic\n\nEjecute consultas de registro de datos personalizadas en su gráfico Roam para recuperación y análisis de datos avanzados:\n\n```typescript\nuse_mcp_tool roam-research roam_datomic_query {\n \"query\": \"[:find (count ?p)\\n :where [?p :node/title]]\",\n \"inputs\": []\n}\n```\n\nCaracterísticas:\n\n* Acceso directo al motor de consultas de Roam\n* Compatibilidad con todas las funciones de consulta de Datalog:\n * Coincidencia de patrones complejos\n * Funciones de agregación (contar, suma, máximo, mínimo, promedio, distinto)\n * Operaciones con cadenas (¿incluye?, ¿empieza con?, ¿termina con?)\n * Operaciones lógicas (<, >, <=, >=, =, not=)\n * Reglas para consultas recursivas\n* Capacidades de búsqueda que distinguen entre mayúsculas y minúsculas y que no lo distinguen entre mayúsculas y minúsculas\n* Consultas eficientes en todo el gráfico\n\nParámetros:\n\n* `query` : La consulta del registro de datos que se ejecutará (obligatorio)\n* `inputs` : Matriz opcional de parámetros de entrada para la consulta\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"content\": \"[result data]\",\n \"block_uid\": \"\",\n \"page_title\": \"\"\n }\n ],\n \"message\": \"Query executed successfully. Found N results.\"\n}\n```\n\nConsultas de ejemplo:\n\n1. Contar todas las páginas:\n\n```clojure\n[:find (count ?p)\n :where [?p :node/title]]\n```\n\n2. Búsqueda de texto sin distinción entre mayúsculas y minúsculas:\n\n```clojure\n[:find ?string ?title\n :where\n [?b :block/string ?string]\n [(clojure.string/lower-case ?string) ?lower]\n [(clojure.string/includes? ?lower \"search term\")]\n [?b :block/page ?p]\n [?p :node/title ?title]]\n```\n\n3. Buscar bloques modificados después de una fecha:\n\n```clojure\n[:find ?block_ref ?string\n :in $ ?start_of_day\n :where\n [?b :edit/time ?time]\n [(> ?time ?start_of_day)]\n [?b :block/uid ?block_ref]\n [?b :block/string ?string]]\n```\n\nConsulte Roam\\_Research\\_Datalog\\_Cheatsheet.md para obtener más ejemplos de consultas y documentación de sintaxis.\n\n### Jerarquía del bloque de búsqueda\n\nNavegar y buscar a través de las relaciones padre-hijo del bloque:\n\n```typescript\nuse_mcp_tool roam-research roam_search_hierarchy {\n \"parent_uid\": \"optional-parent-block-uid\",\n \"child_uid\": \"optional-child-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"max_depth\": 3\n}\n```\n\nCaracterísticas:\n\n* Buscar hacia arriba o hacia abajo en la jerarquía de bloques\n* Buscar hijos de un bloque específico\n* Buscar padres de un bloque específico\n* Configurar la profundidad de búsqueda (1-10 niveles)\n* Filtrado de alcance de página opcional\n* Incluye información de profundidad para cada resultado.\n\nParámetros:\n\n* `parent_uid` : UID del bloque del que se buscarán los hijos (obligatorio si se busca hacia abajo)\n* `child_uid` : UID del bloque del que se buscarán los padres (obligatorio si se busca hacia arriba)\n* `page_title_uid` : Título o UID de la página donde buscar (opcional)\n* `max_depth` : Cuántos niveles de profundidad buscar (opcional, predeterminado: 1, máximo: 10)\n\nDevoluciones:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"related-block-uid\",\n \"content\": \"Block content\",\n \"depth\": 2,\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) as children/parents...\"\n}\n```\n\n## Manejo de errores\n\nEl servidor proporciona un manejo integral de errores para escenarios comunes:\n\n* Errores de configuración:\n * Falta el token de API o el nombre del gráfico\n * Variables de entorno no válidas\n* Errores de API:\n * Errores de autenticación\n * Solicitudes no válidas\n * Operaciones fallidas\n* Errores específicos de la herramienta:\n * Página no encontrada (con búsqueda que no distingue entre mayúsculas y minúsculas)\n * Bloque no encontrado por coincidencia de cadena\n * Formato de rebajas no válido\n * Faltan parámetros requeridos\n * Estructura o contenido del esquema no válido\n\nCada respuesta de error incluye:\n\n* Código de error MCP estándar\n* Mensaje de error detallado\n* Sugerencias de resolución cuando corresponda\n\n## Desarrollo\n\n### Edificio\n\nPara construir el servidor:\n\n```bash\nnpm install\nnpm run build\n```\n\nEsto hará lo siguiente:\n\n1. Instalar todas las dependencias necesarias\n2. Compilar TypeScript a JavaScript\n3. Hacer que el archivo de salida sea ejecutable\n\nTambién puede utilizar `npm run watch` durante el desarrollo para recompilar automáticamente cuando los archivos cambian.\n\n### Pruebas con MCP Inspector\n\nEl Inspector MCP es una herramienta que ayuda a probar y depurar servidores MCP. Para probar el servidor:\n\n```bash\n# Inspect with npx:\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\nEsto hará lo siguiente:\n\n1. Iniciar el servidor en modo inspector\n2. Proporcionar una interfaz interactiva para:\n * Enumere las herramientas y recursos disponibles\n * Ejecutar herramientas con parámetros personalizados\n * Ver las respuestas de la herramienta y el manejo de errores\n\n## Licencia\n\nLicencia MIT","Spanish","es-ES",{"_27":46,"_31":50,"_36":51},{"_29":47,"_31":48,"_33":49},"Roam ResearchのAPI機能への包括的なアクセスを提供します。このサーバーにより、ClaudeのようなAIアシスタントが標準化されたインターフェースを介してRoam Researchグラフと対話できるようになります。","ロームリサーチ","# Roam Research MCP サーバー\n\n[![npmバージョン](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp) [![プロジェクトの状態: WIP – 初期開発は進行中ですが、一般公開に適した安定した使用可能なリリースはまだありません。](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![ライセンス: 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)\n\nRoam ResearchのAPI機能への包括的なアクセスを提供するモデルコンテキストプロトコル（MCP）サーバー。このサーバーにより、ClaudeのようなAIアシスタントが、標準化されたインターフェースを介してRoam Researchのグラフと対話できるようになります。（Roam Researchによる公式承認を受けていない、現在進行中の個人プロジェクトです。）\n\n## インストール\n\nパッケージをグローバルにインストールできます。\n\n```bash\nnpm install -g roam-research-mcp\n```\n\nまたは、リポジトリをクローンしてソースからビルドします。\n\n```bash\ngit clone https://github.com/2b3pro/roam-research-mcp.git\ncd roam-research-mcp\nnpm install\nnpm run build\n```\n\n## テストするには\n\nビルド後に[MCP Inspector](https://github.com/modelcontextprotocol/inspector)を実行します…\n\n```\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n## 特徴\n\nサーバーは、Roam Research と対話するための強力なツールを提供します。\n\n* .env サポートによる環境変数の処理\n* 包括的な入力検証\n* 大文字と小文字を区別しないページタイトルの一致\n* 再帰ブロック参照解決\n* Markdownの解析と変換\n* 毎日のページ統合\n* 詳細なデバッグログ\n* 効率的なバッチ操作\n* 階層的なアウトラインの作成\n\n1. `roam_fetch_page_by_title` : ページのコンテンツをタイトルで取得して読み取り、最大 4 レベルのブロック参照を再帰的に解決します。\n2. `roam_create_page` : オプションコンテンツを含む新しいページを作成する\n3. `roam_create_block` : ページに新しいブロックを作成します（デフォルトは今日の毎日のページ）\n4. `roam_import_markdown` : 特定のブロックの下にネストされたマークダウンコンテンツをインポートする\n5. `roam_add_todo` : チェックボックス構文を使用して、今日の日次ページに複数のToDo項目を追加します。\n6. `roam_create_outline` : 適切なネストと構造を持つ階層的なアウトラインを作成する\n7. `roam_search_block_refs` : ページ内またはグラフ全体でブロック参照を検索します\n8. `roam_search_hierarchy` : ブロックの親子関係をナビゲートして検索する\n9. `roam_find_pages_modified_today` : 今日の深夜以降に変更されたすべてのページを検索します\n10. `roam_search_by_text` : すべてのページまたは特定のページ内で特定のテキストを含むブロックを検索します。\n11. `roam_update_block` : 直接テキストまたはパターンベースの変換でブロックコンテンツを更新します\n12. `roam_search_by_date` : 作成日または変更日に基づいてブロックとページを検索します\n13. `roam_search_for_tag` : 特定のタグを含むブロックを検索し、近くのタグでフィルタリングするオプションもあります。\n14. `roam_remember` : 自動タグ付けで思い出や情報を保存・分類する\n15. `roam_recall` : タグ MEMORIES\\_TAG (下記参照) でマークされたブロック、または同じ名前のページタイトルのブロックの記憶を呼び出します。\n16. `roam_datomic_query` : 高度なデータ取得と分析のために、Roam グラフでカスタム Datalog クエリを実行します。\n\n## 設定\n\n1. [Roam Research APIトークン](https://x.com/RoamResearch/status/1789358175474327881)を作成します:\n\n * グラフ設定に移動\n * 「APIトークン」セクションに移動します（設定 > 「グラフ」タブ > 「APIトークン」セクションで、「+新しいAPIトークン」ボタンをクリックします）\n * 新しいトークンを作成する\n\n2. 環境変数を構成する: 必要な環境変数を構成するには、次の 2 つのオプションがあります。\n\n オプション 1: .env ファイルの使用 (開発に推奨) roam-research ディレクトリに`.env`ファイルを作成します。\n\n ```\n ROAM_API_TOKEN=your-api-token\n ROAM_GRAPH_NAME=your-graph-name\n MEMORIES_TAG='#[[LLM/Memories]]'\n ```\n\n オプション 2: MCP 設定を使用する (代替方法) MCP 設定ファイルに構成を追加します。\n\n * Cline の場合 ( `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` ):\n * Claude デスクトップアプリの場合 ( `~/Library/Application Support/Claude/claude_desktop_config.json` ):\n\n ```json\n {\n \"mcpServers\": {\n \"roam-research\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/roam-research-mcp/build/index.js\"],\n \"env\": {\n \"ROAM_API_TOKEN\": \"your-api-token\",\n \"ROAM_GRAPH_NAME\": \"your-graph-name\",\n \"MEMORIES_TAG\": \"#[[LLM/Memories]]\"\n }\n }\n }\n }\n ```\n\n 注: サーバーは最初に .env ファイルからの読み込みを試み、次に MCP 設定からの環境変数にフォールバックします。\n\n3. サーバーを構築します (MCP のルートディレクトリにいることを確認してください)。\n\n ```bash\n cd roam-research-mcp\n npm install\n npm run build\n ```\n\n## 使用法\n\n### タイトルでページを取得\n\n解決されたブロック参照を使用してページのコンテンツを取得して読み取ります。\n\n```typescript\nuse_mcp_tool roam-research roam_fetch_page_by_title {\n \"title\": \"Example Page\"\n}\n```\n\n次の内容でページコンテンツをマークダウンとして返します。\n\n* 完全な階層構造\n* ブロック参照は再帰的に解決されます（最大 4 レベルの深さ）\n* ネストレベルの適切なインデント\n* 完全なマークダウンフォーマット\n\n### ページを作成\n\nオプションのコンテンツを含む新しいページを作成します。\n\n```typescript\nuse_mcp_tool roam-research roam_create_page {\n \"title\": \"New Page\",\n \"content\": \"Initial content for the page\"\n}\n```\n\n成功した場合、作成されたページの UID を返します。\n\n### ブロックを作成\n\nページに新しいブロックを追加します (page\\_uid も title も指定されていない場合は、デフォルトで今日の日次ページになります)。\n\n```typescript\nuse_mcp_tool roam-research roam_create_block {\n \"content\": \"Block content\",\n \"page_uid\": \"optional-target-page-uid\",\n \"title\": \"optional-target-page-title\"\n}\n```\n\n次のいずれかを指定できます。\n\n* `page_uid` : 対象ページへの直接参照\n* `title` : 対象ページの名前（存在しない場合は作成されます）\n* どちらでもない: ブロックは今日の日刊ページに追加されます\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"parent_uid\": \"parent-page-uid\"\n}\n```\n\n### アウトラインを作成\n\n適切なネストと構造を持つ階層的なアウトラインを作成します。\n\n```typescript\nuse_mcp_tool roam-research roam_create_outline {\n \"outline\": [\n {\n \"text\": \"I. Top Level\",\n \"level\": 1\n },\n {\n \"text\": \"A. Second Level\",\n \"level\": 2\n },\n {\n \"text\": \"1. Third Level\",\n \"level\": 3\n }\n ],\n \"page_title_uid\": \"optional-target-page\",\n \"block_text_uid\": \"optional-header-text\"\n}\n```\n\n特徴：\n\n* 最大10レベルのネストで複雑なアウトラインを作成\n* アウトラインの構造と内容を検証する\n* 適切な親子関係を維持する\n* アウトラインのオプションのヘッダーブロック\n* ページが指定されていない場合は、今日の日次ページがデフォルトになります\n* ブロックを作成するための効率的なバッチ操作\n\nパラメータ:\n\n* `outline` : アウトライン項目の配列。各項目は次のようになります。\n * `text` : アウトライン項目の内容（必須）\n * `level` : ネストレベル（1～10、必須）\n* `page_title_uid` : 対象ページのタイトルまたはUID（オプション、デフォルトは今日のページ）\n* `block_text_uid` : アウトラインのヘッダーテキスト（オプション）\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"header-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n}\n```\n\n### ToDo項目を追加する\n\n今日の毎日のページに 1 つ以上の ToDo 項目を追加します。\n\n```typescript\nuse_mcp_tool roam-research roam_add_todo {\n \"todos\": [\n \"First todo item\",\n \"Second todo item\",\n \"Third todo item\"\n ]\n}\n```\n\n特徴：\n\n* Roam チェックボックス構文を使用して todo を追加します ( `{{TODO}} todo text` )\n* 1 回の操作で複数の ToDo を追加できます\n* 10 件を超える ToDo を追加する場合は、効率化のためにバッチアクションを使用します。\n* 今日のページが存在しない場合は自動的に作成します\n* 最上位レベルのブロックとしてToDoを順番に追加します\n\n### ネストされたマークダウンをインポートする\n\n特定のブロックの下にネストされたマークダウンコンテンツをインポートします。\n\n```typescript\nuse_mcp_tool roam-research roam_import_markdown {\n \"content\": \"- Item 1\\n - Subitem A\\n - Subitem B\\n- Item 2\",\n \"page_uid\": \"optional-page-uid\",\n \"page_title\": \"optional-page-title\",\n \"parent_uid\": \"optional-parent-block-uid\",\n \"parent_string\": \"optional-exact-block-content\",\n \"order\": \"first\"\n}\n```\n\n特徴：\n\n* 特定のブロックのコンテンツをインポートします。\n\n * UIDまたは文字列の完全一致で親ブロックを検索\n * タイトルまたはUIDで特定のページ内のブロックを検索する\n * ページが指定されていない場合は、今日のページがデフォルトになります\n\n* コンテンツの配置を制御する:\n\n * 親ブロックの最初または最後の子として追加\n * 階層構造を維持する\n * ネストされたコンテンツに対する効率的なバッチ操作\n\n* 包括的な戻り値:\n\n ```json\n {\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"parent-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n }\n ```\n\nパラメータ:\n\n* `content` : インポートするネストされたマークダウンコンテンツ\n* `page_uid` : 親ブロックを含むページのUID\n* `page_title` : 親ブロックを含むページのタイトル（page\\_uidが指定されている場合は無視されます）\n* `parent_uid` : コンテンツを追加する親ブロックのUID\n* `parent_string` : 親ブロックの正確な文字列コンテンツ（page\\_uid または page\\_title のいずれかを指定する必要があります）\n* `order` : コンテンツを追加する場所（「first」または「last」、デフォルトは「first」）\n\n### ブロック参照を検索\n\nページ内またはグラフ全体でブロック参照を検索します。\n\n```typescript\nuse_mcp_tool roam-research roam_search_block_refs {\n \"block_uid\": \"optional-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\"\n}\n```\n\n特徴：\n\n* 特定のブロックへのすべての参照を検索する\n* ページ内のブロック参照を検索する\n* グラフ全体を検索\n* 直接参照と間接参照の両方をサポート\n* ブロックコンテンツと場所のコンテキストを含む\n\nパラメータ:\n\n* `block_uid` : 参照を検索するブロックのUID（オプション）\n* `page_title_uid` : 検索するページのタイトルまたはUID（オプション）\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"referenced-block-uid\",\n \"content\": \"Block content with ((reference))\",\n \"page_title\": \"Page containing reference\"\n }\n ],\n \"message\": \"Found N block(s) referencing...\"\n}\n```\n\n### テキストで検索\n\nすべてのページまたは特定のページ内で特定のテキストを含むブロックを検索します。\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_text {\n \"text\": \"search text\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"case_sensitive\": true\n}\n```\n\n特徴：\n\n* グラフ内のすべてのブロックで任意のテキストを検索します\n* オプションのページスコープ検索\n* 大文字と小文字を区別する検索または大文字と小文字を区別しない検索\n* ページコンテキストを含むブロックコンテンツを返します\n* Datalogクエリを使用した効率的なテキストマッチング\n\nパラメータ:\n\n* `text` : 検索するテキスト（必須）\n* `page_title_uid` : 検索するページのタイトルまたはUID（オプション）\n* `case_sensitive` : 大文字と小文字を区別した検索を実行するかどうか（オプション、デフォルト: Roam のネイティブ動作と一致するように true）\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing search text\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) containing \\\"search text\\\"\"\n}\n```\n\n### ブロックコンテンツの更新\n\n直接的なテキスト置換またはパターンベースの変換を使用してブロックのコンテンツを更新します。\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"content\": \"New block content\"\n}\n```\n\nまたは、パターンベースの変換を使用します。\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"transform_pattern\": {\n \"find\": \"\\\\bPython\\\\b\",\n \"replace\": \"[[Python]]\",\n \"global\": true\n }\n}\n```\n\n特徴：\n\n* 2 つの更新モード:\n * 直接的なコンテンツの置き換え\n * 正規表現を使用したパターンベースの変換\n* 更新前にブロックの存在を確認する\n* 応答として更新されたコンテンツを返す\n* グローバルまたは単一一致の置換のサポート\n* ブロックの関係とメタデータを保持する\n\nパラメータ:\n\n* `block_uid` : 更新するブロックのUID（必須）\n* `content` : ブロックの新しいコンテンツ（直接置換を使用する場合）\n* `transform_pattern` : 既存のコンテンツを変換するためのパターン:\n * `find` : 検索するテキストまたは正規表現パターン\n * `replace` : 置換するテキスト\n * `global` : すべての出現箇所を置き換えるかどうか（デフォルト: true）\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"content\": \"Updated block content\"\n}\n```\n\n### タグを検索\n\n特定のタグを含むブロックを検索し、近くのタグでオプションでフィルタリングします。\n\n```typescript\nuse_mcp_tool roam-research roam_search_for_tag {\n \"primary_tag\": \"Project/Tasks\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"near_tag\": \"optional-secondary-tag\",\n \"case_sensitive\": true\n}\n```\n\n特徴：\n\n* 特定のタグを含むブロックを検索する\n* 別のタグの存在によるフィルタリング（オプション）\n* ページスコープまたはグラフ全体の検索\n* 大文字と小文字を区別する検索または大文字と小文字を区別しない検索\n* ページコンテキストを含むブロックコンテンツを返します\n* Datalogクエリを使用した効率的なタグマッチング\n\nパラメータ:\n\n* `primary_tag` : 検索するメインタグ（必須）\n* `page_title_uid` : 検索するページのタイトルまたはUID（オプション）\n* `near_tag` : 結果をフィルタリングするための別のタグ（オプション）\n* `case_sensitive` : 大文字と小文字を区別した検索を実行するかどうか（オプション、デフォルト: Roam のネイティブ動作と一致するように true）\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing #[[primary_tag]]\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) referencing \\\"primary_tag\\\"\"\n}\n```\n\n### 情報を記憶する\n\n自動タグ付けと分類機能を使用して思い出や重要な情報を保存します。\n\n```typescript\nuse_mcp_tool roam-research roam_remember {\n \"memory\": \"Important information to remember\",\n \"categories\": [\"Work\", \"Project/Alpha\"]\n}\n```\n\n特徴：\n\n* \\#\\[\\[LLM/Memories]] タグで情報を保存する\n* 組織にオプションのカテゴリタグを追加する\n* 今日の毎日のページに自動的に追加されます\n* メモリごとに複数のカテゴリをサポート\n* roam\\_search\\_for\\_tagを使った簡単な検索\n* 記憶の時系列を維持する\n\nパラメータ:\n\n* `memory` : 記憶する情報（必須）\n* `categories` : メモリにタグ付けするカテゴリのオプション配列\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"content\": \"Memory content with tags\"\n}\n```\n\n### 日付で検索\n\n作成日または変更日に基づいてブロックとページを検索します。\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_date {\n \"start_date\": \"2025-01-01\",\n \"end_date\": \"2025-01-31\",\n \"type\": \"modified\",\n \"scope\": \"blocks\",\n \"include_content\": true\n}\n```\n\n特徴：\n\n* 作成日、変更日、またはその両方で検索\n* ブロック、ページ、またはその両方をフィルタリングする\n* 開始日と終了日を含むオプションの日付範囲\n* 結果にブロック/ページコンテンツを含めるか除外するか\n* タイムスタンプで結果を並べ替える\n* Datalogクエリを使用した効率的な日付ベースのフィルタリング\n\nパラメータ:\n\n* `start_date` : ISO形式（YYYY-MM-DD）での開始日（必須）\n* `end_date` : ISO形式の終了日（YYYY-MM-DD）（オプション）\n* `type` : 「作成日」、「変更日」、「両方」のどれで検索するか（必須）\n* `scope` : 「ブロック」、「ページ」、または「両方」を検索するかどうか（必須）\n* `include_content` : 一致するブロック/ページのコンテンツを含めるかどうか（オプション、デフォルト: true）\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"uid\": \"block-or-page-uid\",\n \"type\": \"block\",\n \"time\": 1704067200000,\n \"content\": \"Block or page content\",\n \"page_title\": \"Page title (for blocks)\"\n }\n ],\n \"message\": \"Found N matches for the given date range and criteria\"\n}\n```\n\n### 今日変更されたページを検索\n\n今日の深夜以降に変更されたすべてのページを検索します。\n\n```typescript\nuse_mcp_tool roam-research roam_find_pages_modified_today {}\n```\n\n特徴：\n\n* 深夜以降にページに加えられたすべての変更を追跡します\n* ブロック階層のあらゆるレベルでの変更を検出します\n* 変更されたページタイトルの一意のリストを返します\n* 変更されたページの数を含む\n* パラメータは必要ありません\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"pages\": [\"Page 1\", \"Page 2\"],\n \"message\": \"Found 2 page(s) modified today\"\n}\n```\n\n### Datomicクエリを実行する\n\n高度なデータ取得と分析のために、Roam グラフでカスタム Datalog クエリを実行します。\n\n```typescript\nuse_mcp_tool roam-research roam_datomic_query {\n \"query\": \"[:find (count ?p)\\n :where [?p :node/title]]\",\n \"inputs\": []\n}\n```\n\n特徴：\n\n* Roamのクエリエンジンへの直接アクセス\n* すべての Datalog クエリ機能のサポート:\n * 複雑なパターンマッチング\n * 集計関数（count、sum、max、min、avg、distinct）\n * 文字列操作 (含む?、始まる?、終わる?)\n * 論理演算 (<、>、<=、>=、=、not=)\n * 再帰クエリのルール\n* 大文字と小文字を区別する検索機能と大文字と小文字を区別しない検索機能\n* グラフ全体にわたる効率的なクエリ\n\nパラメータ:\n\n* `query` : 実行するデータログクエリ（必須）\n* `inputs` : クエリの入力パラメータのオプション配列\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"content\": \"[result data]\",\n \"block_uid\": \"\",\n \"page_title\": \"\"\n }\n ],\n \"message\": \"Query executed successfully. Found N results.\"\n}\n```\n\nクエリの例:\n\n1. すべてのページを数える:\n\n```clojure\n[:find (count ?p)\n :where [?p :node/title]]\n```\n\n2. 大文字と小文字を区別しないテキスト検索:\n\n```clojure\n[:find ?string ?title\n :where\n [?b :block/string ?string]\n [(clojure.string/lower-case ?string) ?lower]\n [(clojure.string/includes? ?lower \"search term\")]\n [?b :block/page ?p]\n [?p :node/title ?title]]\n```\n\n3. 特定の日付以降に変更されたブロックを検索します。\n\n```clojure\n[:find ?block_ref ?string\n :in $ ?start_of_day\n :where\n [?b :edit/time ?time]\n [(> ?time ?start_of_day)]\n [?b :block/uid ?block_ref]\n [?b :block/string ?string]]\n```\n\n詳細なクエリ例と構文ドキュメントについては、Roam\\_Research\\_Datalog\\_Cheatsheet.md を参照してください。\n\n### 検索ブロック階層\n\nブロックの親子関係をナビゲートして検索します。\n\n```typescript\nuse_mcp_tool roam-research roam_search_hierarchy {\n \"parent_uid\": \"optional-parent-block-uid\",\n \"child_uid\": \"optional-child-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"max_depth\": 3\n}\n```\n\n特徴：\n\n* ブロック階層を上または下で検索\n* 特定のブロックの子を見つける\n* 特定のブロックの親を見つける\n* 検索の深さを設定する（1～10レベル）\n* オプションのページスコープフィルタリング\n* 各結果の深度情報が含まれます\n\nパラメータ:\n\n* `parent_uid` : 子を検索するブロックのUID（下方向に検索する場合は必須）\n* `child_uid` : 親を検索するブロックのUID（上方向を検索する場合は必須）\n* `page_title_uid` : 検索するページのタイトルまたはUID（オプション）\n* `max_depth` : 検索する深さのレベル数（オプション、デフォルト: 1、最大: 10）\n\n戻り値:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"related-block-uid\",\n \"content\": \"Block content\",\n \"depth\": 2,\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) as children/parents...\"\n}\n```\n\n## エラー処理\n\nサーバーは、一般的なシナリオに対して包括的なエラー処理を提供します。\n\n* 構成エラー:\n * APIトークンまたはグラフ名がありません\n * 無効な環境変数\n* API エラー:\n * 認証失敗\n * 無効なリクエスト\n * 失敗した操作\n* ツール固有のエラー:\n * ページが見つかりません（大文字と小文字を区別しない検索）\n * 文字列一致でブロックが見つかりません\n * 無効なマークダウン形式\n * 必要なパラメータが不足しています\n * アウトライン構造またはコンテンツが無効です\n\n各エラー応答には次の内容が含まれます。\n\n* 標準MCPエラーコード\n* 詳細なエラーメッセージ\n* 該当する場合の解決策の提案\n\n## 発達\n\n### 建物\n\nサーバーを構築するには:\n\n```bash\nnpm install\nnpm run build\n```\n\nこれにより、次のようになります。\n\n1. 必要な依存関係をすべてインストールする\n2. TypeScriptをJavaScriptにコンパイルする\n3. 出力ファイルを実行可能にする\n\n開発中に`npm run watch`使用して、ファイルが変更されたときに自動的に再コンパイルすることもできます。\n\n### MCP Inspectorによるテスト\n\nMCP Inspectorは、MCPサーバーのテストとデバッグに役立つツールです。サーバーをテストするには、次の手順に従います。\n\n```bash\n# Inspect with npx:\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\nこれにより、次のようになります。\n\n1. インスペクターモードでサーバーを起動する\n2. 次のインタラクティブなインターフェースを提供します:\n * 利用可能なツールとリソースをリストする\n * カスタムパラメータでツールを実行する\n * ツールの応答とエラー処理を表示する\n\n## ライセンス\n\nMITライセンス","Japanese","ja-JP",{"_27":53,"_31":57,"_36":58},{"_29":54,"_31":55,"_33":56},"Roam Research의 API 기능에 대한 포괄적인 액세스를 제공합니다. 이 서버를 통해 Claude와 같은 AI 비서가 표준화된 인터페이스를 통해 Roam Research 그래프와 상호 작용할 수 있습니다.","로밍 리서치","# Roam Research MCP 서버\n\n[![npm 버전](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp) [![프로젝트 상태: 진행 중 – 초기 개발이 진행 중이지만, 아직 대중에게 적합하고 안정적이며 사용 가능한 릴리스가 나오지 않았습니다.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![라이센스: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![깃허브](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)\n\nRoam Research의 API 기능에 대한 포괄적인 접근을 제공하는 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버를 통해 Claude와 같은 AI 비서가 표준화된 인터페이스를 통해 Roam Research 그래프와 상호 작용할 수 있습니다. (현재 진행 중인 개인 프로젝트이며 Roam Research의 공식 승인을 받지 않았습니다.)\n\n## 설치\n\n패키지를 글로벌하게 설치할 수 있습니다:\n\n지엑스피1\n\n또는 저장소를 복제하고 소스에서 빌드합니다.\n\n```bash\ngit clone https://github.com/2b3pro/roam-research-mcp.git\ncd roam-research-mcp\nnpm install\nnpm run build\n```\n\n## 테스트하려면\n\n빌드 후 [MCP Inspector를](https://github.com/modelcontextprotocol/inspector) 실행합니다.\n\n```\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n## 특징\n\n이 서버는 Roam Research와 상호 작용하기 위한 강력한 도구를 제공합니다.\n\n* .env 지원을 통한 환경 변수 처리\n* 포괄적인 입력 검증\n* 대소문자 구분 없이 페이지 제목 일치\n* 재귀적 블록 참조 해결\n* 마크다운 구문 분석 및 변환\n* 일일 페이지 통합\n* 자세한 디버그 로깅\n* 효율적인 배치 작업\n* 계층적 개요 생성\n\n1. `roam_fetch_page_by_title` : 제목별로 페이지의 콘텐츠를 가져와서 읽고, 최대 4단계 깊이까지 블록 참조를 재귀적으로 확인합니다.\n2. `roam_create_page` : 선택적 콘텐츠로 새 페이지를 만듭니다.\n3. `roam_create_block` : 페이지에 새로운 블록을 생성합니다(기본값은 오늘의 일일 페이지입니다)\n4. `roam_import_markdown` : 특정 블록 아래에 중첩된 마크다운 콘텐츠를 가져옵니다.\n5. `roam_add_todo` : 체크박스 구문을 사용하여 오늘의 일일 페이지에 여러 개의 할 일 항목을 추가합니다.\n6. `roam_create_outline` : 적절한 중첩 및 구조를 사용하여 계층적 개요를 만듭니다.\n7. `roam_search_block_refs` : 페이지 내 또는 그래프 전체에서 블록 참조를 검색합니다.\n8. `roam_search_hierarchy` : 블록 부모-자식 관계를 탐색하고 검색합니다.\n9. `roam_find_pages_modified_today` : 오늘 자정 이후 수정된 모든 페이지를 찾습니다.\n10. `roam_search_by_text` : 모든 페이지 또는 특정 페이지 내에서 특정 텍스트가 포함된 블록을 검색합니다.\n11. `roam_update_block` : 직접 텍스트 또는 패턴 기반 변환으로 블록 콘텐츠 업데이트\n12. `roam_search_by_date` : 생성 또는 수정 날짜를 기준으로 블록 및 페이지 검색\n13. `roam_search_for_tag` : 근처 태그로 선택적으로 필터링하여 특정 태그가 포함된 블록을 검색합니다.\n14. `roam_remember` : 자동 태그 지정으로 기억이나 정보를 저장하고 분류합니다.\n15. `roam_recall` : MEMORIES\\_TAG 태그로 표시된 블록(아래 참조) 또는 같은 이름의 페이지 제목에 있는 블록의 메모리를 회수합니다.\n16. `roam_datomic_query` : 고급 데이터 검색 및 분석을 위해 Roam 그래프에서 사용자 정의 Datalog 쿼리를 실행합니다.\n\n## 설정\n\n1. [Roam Research API 토큰을](https://x.com/RoamResearch/status/1789358175474327881) 생성하세요:\n\n * 그래프 설정으로 이동하세요\n * \"API 토큰\" 섹션으로 이동합니다(설정 > \"그래프\" 탭 > \"API 토큰\" 섹션을 클릭하고 \"+ 새 API 토큰\" 버튼을 클릭합니다)\n * 새로운 토큰을 생성하세요\n\n2. 환경 변수 구성: 필요한 환경 변수를 구성하는 데는 두 가지 옵션이 있습니다.\n\n 옵션 1: .env 파일 사용(개발에 권장) roam-research 디렉터리에 `.env` 파일을 만듭니다.\n\n ```\n ROAM_API_TOKEN=your-api-token\n ROAM_GRAPH_NAME=your-graph-name\n MEMORIES_TAG='#[[LLM/Memories]]'\n ```\n\n 옵션 2: MCP 설정 사용(대체 방법) MCP 설정 파일에 구성을 추가합니다.\n\n * Cline의 경우( `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` ):\n * Claude 데스크톱 앱( `~/Library/Application Support/Claude/claude_desktop_config.json` ):\n\n ```json\n {\n \"mcpServers\": {\n \"roam-research\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/roam-research-mcp/build/index.js\"],\n \"env\": {\n \"ROAM_API_TOKEN\": \"your-api-token\",\n \"ROAM_GRAPH_NAME\": \"your-graph-name\",\n \"MEMORIES_TAG\": \"#[[LLM/Memories]]\"\n }\n }\n }\n }\n ```\n\n 참고: 서버는 먼저 .env 파일에서 로드를 시도한 다음 MCP 설정의 환경 변수를 사용합니다.\n\n3. 서버를 빌드합니다(MCP의 루트 디렉토리에 있는지 확인하세요):\n\n ```bash\n cd roam-research-mcp\n npm install\n npm run build\n ```\n\n## 용법\n\n### 제목으로 페이지 가져오기\n\n해결된 블록 참조로 페이지의 콘텐츠를 가져와서 읽습니다.\n\n```typescript\nuse_mcp_tool roam-research roam_fetch_page_by_title {\n \"title\": \"Example Page\"\n}\n```\n\n다음을 사용하여 페이지 내용을 마크다운으로 반환합니다.\n\n* 완전한 계층 구조\n* 블록 참조는 재귀적으로 해결됨(최대 4단계 깊이)\n* 중첩 수준에 대한 적절한 들여쓰기\n* 전체 마크다운 서식\n\n### 페이지 만들기\n\n선택적인 콘텐츠로 새 페이지를 만드세요:\n\n```typescript\nuse_mcp_tool roam-research roam_create_page {\n \"title\": \"New Page\",\n \"content\": \"Initial content for the page\"\n}\n```\n\n성공시 생성된 페이지의 UID를 반환합니다.\n\n### 블록 생성\n\n페이지에 새 블록을 추가합니다(page\\_uid나 title이 제공되지 않으면 오늘의 일일 페이지가 기본값으로 설정됨):\n\n```typescript\nuse_mcp_tool roam-research roam_create_block {\n \"content\": \"Block content\",\n \"page_uid\": \"optional-target-page-uid\",\n \"title\": \"optional-target-page-title\"\n}\n```\n\n다음 중 하나를 지정할 수 있습니다.\n\n* `page_uid` : 대상 페이지에 대한 직접 참조\n* `title` : 대상 페이지의 이름 (존재하지 않으면 생성됩니다)\n* 둘 다 아님: 블록이 오늘의 일일 페이지에 추가됩니다.\n\n보고:\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"parent_uid\": \"parent-page-uid\"\n}\n```\n\n### 개요 만들기\n\n적절한 중첩과 구조를 갖춘 계층적 개요를 만듭니다.\n\n```typescript\nuse_mcp_tool roam-research roam_create_outline {\n \"outline\": [\n {\n \"text\": \"I. Top Level\",\n \"level\": 1\n },\n {\n \"text\": \"A. Second Level\",\n \"level\": 2\n },\n {\n \"text\": \"1. Third Level\",\n \"level\": 3\n }\n ],\n \"page_title_uid\": \"optional-target-page\",\n \"block_text_uid\": \"optional-header-text\"\n}\n```\n\n특징:\n\n* 최대 10단계의 중첩으로 복잡한 윤곽선을 만듭니다.\n* 개요 구조와 내용 검증\n* 올바른 부모-자녀 관계 유지\n* 개요에 대한 선택적 헤더 블록\n* 페이지가 지정되지 않으면 오늘의 일일 페이지로 기본 설정됩니다.\n* 블록 생성을 위한 효율적인 일괄 작업\n\n매개변수:\n\n* `outline` : 개요 항목의 배열, 각 항목에는 다음이 포함됩니다.\n * `text` : 개요 항목의 내용(필수)\n * `level` : 중첩 레벨(1-10, 필수)\n* `page_title_uid` : 대상 페이지 제목 또는 UID(선택 사항, 기본값은 오늘 페이지)\n* `block_text_uid` : 개요의 헤더 텍스트(선택 사항)\n\n보고:\n\n```json\n{\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"header-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n}\n```\n\n### 할 일 항목 추가\n\n오늘의 일일 페이지에 하나 이상의 할 일 항목을 추가하세요.\n\n```typescript\nuse_mcp_tool roam-research roam_add_todo {\n \"todos\": [\n \"First todo item\",\n \"Second todo item\",\n \"Third todo item\"\n ]\n}\n```\n\n특징:\n\n* Roam 체크박스 구문을 사용하여 할 일을 추가합니다( `{{TODO}} todo text` ).\n* 단일 작업에서 여러 개의 할 일 추가 지원\n* 10개 이상의 할 일을 추가할 때 효율성을 위해 일괄 작업을 사용합니다.\n* 오늘의 페이지가 존재하지 않으면 자동으로 오늘의 페이지를 생성합니다.\n* 순차적으로 최상위 블록으로 할 일을 추가합니다.\n\n### 중첩된 마크다운 가져오기\n\n특정 블록 아래에 중첩된 마크다운 콘텐츠를 가져옵니다.\n\n```typescript\nuse_mcp_tool roam-research roam_import_markdown {\n \"content\": \"- Item 1\\n - Subitem A\\n - Subitem B\\n- Item 2\",\n \"page_uid\": \"optional-page-uid\",\n \"page_title\": \"optional-page-title\",\n \"parent_uid\": \"optional-parent-block-uid\",\n \"parent_string\": \"optional-exact-block-content\",\n \"order\": \"first\"\n}\n```\n\n특징:\n\n* 특정 블록 아래의 콘텐츠 가져오기:\n\n * UID 또는 정확한 문자열 일치로 부모 블록 찾기\n * 제목이나 UID로 특정 페이지 내 블록 찾기\n * 페이지가 지정되지 않으면 오늘 페이지로 기본 설정됩니다.\n\n* 콘텐츠 배치 제어:\n\n * 부모 블록의 첫 번째 또는 마지막 자식으로 추가\n * 계층 구조 유지\n * 중첩된 콘텐츠에 대한 효율적인 일괄 작업\n\n* 포괄적인 반환 값:\n\n ```json\n {\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"parent-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n }\n ```\n\n매개변수:\n\n* `content` : 가져올 중첩된 마크다운 콘텐츠\n* `page_uid` : 부모 블록이 포함된 페이지의 UID\n* `page_title` : 부모 블록이 포함된 페이지의 제목(page\\_uid가 제공된 경우 무시됨)\n* `parent_uid` : 콘텐츠를 추가할 부모 블록의 UID\n* `parent_string` : 부모 블록의 정확한 문자열 내용(page\\_uid 또는 page\\_title을 제공해야 함)\n* `order` : 콘텐츠를 추가할 위치(\"first\" 또는 \"last\", 기본값은 \"first\")\n\n### 블록 참조 검색\n\n페이지 내 또는 전체 그래프에서 블록 참조를 검색합니다.\n\n```typescript\nuse_mcp_tool roam-research roam_search_block_refs {\n \"block_uid\": \"optional-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\"\n}\n```\n\n특징:\n\n* 특정 블록에 대한 모든 참조 찾기\n* 페이지 내에서 블록 참조를 검색합니다.\n* 그래프 전체에서 검색\n* 직접 및 간접 참조를 모두 지원합니다.\n* 블록 콘텐츠와 위치 컨텍스트가 포함됩니다.\n\n매개변수:\n\n* `block_uid` : 참조를 찾을 블록의 UID(선택 사항)\n* `page_title_uid` : 검색할 페이지의 제목 또는 UID(선택 사항)\n\n보고:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"referenced-block-uid\",\n \"content\": \"Block content with ((reference))\",\n \"page_title\": \"Page containing reference\"\n }\n ],\n \"message\": \"Found N block(s) referencing...\"\n}\n```\n\n### 텍스트로 검색\n\n모든 페이지 또는 특정 페이지 내에서 특정 텍스트가 포함된 블록을 검색합니다.\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_text {\n \"text\": \"search text\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"case_sensitive\": true\n}\n```\n\n특징:\n\n* 그래프의 모든 블록에서 모든 텍스트를 검색합니다.\n* 선택적인 페이지 범위 검색\n* 대소문자 구분 또는 대소문자 구분 안 함 검색\n* 페이지 컨텍스트를 사용하여 블록 콘텐츠를 반환합니다.\n* Datalog 쿼리를 사용한 효율적인 텍스트 매칭\n\n매개변수:\n\n* `text` : 검색할 텍스트(필수)\n* `page_title_uid` : 검색할 페이지의 제목 또는 UID(선택 사항)\n* `case_sensitive` : 대소문자 구분 검색을 수행할지 여부(선택 사항, 기본값: Roam의 기본 동작과 일치하려면 true)\n\n보고:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing search text\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) containing \\\"search text\\\"\"\n}\n```\n\n### 블록 콘텐츠 업데이트\n\n직접 텍스트 교체나 패턴 기반 변환을 사용하여 블록의 콘텐츠를 업데이트합니다.\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"content\": \"New block content\"\n}\n```\n\n또는 패턴 기반 변환을 사용합니다.\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"transform_pattern\": {\n \"find\": \"\\\\bPython\\\\b\",\n \"replace\": \"[[Python]]\",\n \"global\": true\n }\n}\n```\n\n특징:\n\n* 두 가지 업데이트 모드:\n * 직접 콘텐츠 교체\n * 정규식을 사용한 패턴 기반 변환\n* 업데이트하기 전에 블록 존재 여부를 확인하세요\n* 업데이트된 콘텐츠를 응답으로 반환합니다.\n* 글로벌 또는 단일 매치 교체 지원\n* 블록 관계 및 메타데이터 보존\n\n매개변수:\n\n* `block_uid` : 업데이트할 블록의 UID(필수)\n* `content` : 블록에 대한 새 콘텐츠(직접 교체를 사용하는 경우)\n* `transform_pattern` : 기존 콘텐츠를 변환하기 위한 패턴:\n * `find` : 찾을 텍스트 또는 정규식 패턴\n * `replace` : 바꿀 텍스트\n * `global` : 모든 항목을 바꿀지 여부(기본값: true)\n\n보고:\n\n```json\n{\n \"success\": true,\n \"content\": \"Updated block content\"\n}\n```\n\n### 태그 검색\n\n근처 태그로 선택적으로 필터링하여 특정 태그가 포함된 블록을 검색하세요.\n\n```typescript\nuse_mcp_tool roam-research roam_search_for_tag {\n \"primary_tag\": \"Project/Tasks\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"near_tag\": \"optional-secondary-tag\",\n \"case_sensitive\": true\n}\n```\n\n특징:\n\n* 특정 태그가 포함된 블록 검색\n* 다른 태그의 존재 여부에 따른 선택적 필터링\n* 페이지 범위 또는 그래프 전체 검색\n* 대소문자 구분 또는 대소문자 구분 안 함 검색\n* 페이지 컨텍스트를 사용하여 블록 콘텐츠를 반환합니다.\n* Datalog 쿼리를 사용한 효율적인 태그 매칭\n\n매개변수:\n\n* `primary_tag` : 검색할 주요 태그(필수)\n* `page_title_uid` : 검색할 페이지의 제목 또는 UID(선택 사항)\n* `near_tag` : 결과를 필터링할 또 다른 태그(선택 사항)\n* `case_sensitive` : 대소문자 구분 검색을 수행할지 여부(선택 사항, 기본값: Roam의 기본 동작과 일치하려면 true)\n\n보고:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing #[[primary_tag]]\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) referencing \\\"primary_tag\\\"\"\n}\n```\n\n### 정보 기억하기\n\n자동 태그 지정 및 분류를 통해 추억이나 중요한 정보를 저장하세요.\n\n```typescript\nuse_mcp_tool roam-research roam_remember {\n \"memory\": \"Important information to remember\",\n \"categories\": [\"Work\", \"Project/Alpha\"]\n}\n```\n\n특징:\n\n* \\#\\[\\[LLM/Memories]] 태그로 정보를 저장합니다.\n* 조직을 위한 선택적 카테고리 태그 추가\n* 오늘의 일일 페이지에 자동으로 추가됩니다\n* 메모리당 여러 카테고리 지원\n* roam\\_search\\_for\\_tag를 사용하여 쉽게 검색\n* 기억의 연대순을 유지합니다\n\n매개변수:\n\n* `memory` : 기억할 정보 (필수)\n* `categories` : 메모리에 태그를 지정할 카테고리의 선택적 배열\n\n보고:\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"content\": \"Memory content with tags\"\n}\n```\n\n### 날짜로 검색\n\n생성 또는 수정 날짜를 기준으로 블록 및 페이지 검색:\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_date {\n \"start_date\": \"2025-01-01\",\n \"end_date\": \"2025-01-31\",\n \"type\": \"modified\",\n \"scope\": \"blocks\",\n \"include_content\": true\n}\n```\n\n특징:\n\n* 생성 날짜, 수정 날짜 또는 둘 다로 검색\n* 블록, 페이지 또는 둘 다 필터링\n* 시작 및 종료 날짜가 포함된 선택적 날짜 범위\n* 결과에 블록/페이지 콘텐츠 포함 또는 제외\n* 타임스탬프별로 결과 정렬\n* Datalog 쿼리를 사용한 효율적인 날짜 기반 필터링\n\n매개변수:\n\n* `start_date` : ISO 형식(YYYY-MM-DD)의 시작 날짜(필수)\n* `end_date` : ISO 형식(YYYY-MM-DD)의 종료 날짜(선택 사항)\n* `type` : '생성됨', '수정됨', '둘 다'로 검색할지 여부 (필수)\n* `scope` : '블록', '페이지' 또는 '둘 다'를 검색할지 여부(필수)\n* `include_content` : 일치하는 블록/페이지의 콘텐츠를 포함할지 여부(선택 사항, 기본값: true)\n\n보고:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"uid\": \"block-or-page-uid\",\n \"type\": \"block\",\n \"time\": 1704067200000,\n \"content\": \"Block or page content\",\n \"page_title\": \"Page title (for blocks)\"\n }\n ],\n \"message\": \"Found N matches for the given date range and criteria\"\n}\n```\n\n### 오늘 수정된 페이지 찾기\n\n오늘 자정 이후 수정된 모든 페이지를 찾으세요:\n\n```typescript\nuse_mcp_tool roam-research roam_find_pages_modified_today {}\n```\n\n특징:\n\n* 자정 이후 페이지에 적용된 모든 수정 사항을 추적합니다.\n* 블록 계층의 모든 레벨에서 변경 사항을 감지합니다.\n* 수정된 페이지 제목의 고유한 목록을 반환합니다.\n* 수정된 페이지 수 포함\n* 매개변수가 필요하지 않습니다\n\n보고:\n\n```json\n{\n \"success\": true,\n \"pages\": [\"Page 1\", \"Page 2\"],\n \"message\": \"Found 2 page(s) modified today\"\n}\n```\n\n### 데이터 쿼리 실행\n\n고급 데이터 검색 및 분석을 위해 Roam 그래프에서 사용자 정의 Datalog 쿼리를 실행하세요.\n\n```typescript\nuse_mcp_tool roam-research roam_datomic_query {\n \"query\": \"[:find (count ?p)\\n :where [?p :node/title]]\",\n \"inputs\": []\n}\n```\n\n특징:\n\n* Roam의 쿼리 엔진에 직접 액세스\n* 모든 Datalog 쿼리 기능 지원:\n * 복잡한 패턴 매칭\n * 집계 함수(count, sum, max, min, avg, distinct)\n * 문자열 연산(includes?, starts-with?, ends-with?)\n * 논리 연산(<, >, <=, >=, =, not=)\n * 재귀 쿼리에 대한 규칙\n* 대소문자 구분 및 대소문자 구분 안 함 검색 기능\n* 그래프 전체에 걸친 효율적인 쿼리\n\n매개변수:\n\n* `query` : 실행할 Datalog 쿼리(필수)\n* `inputs` : 쿼리에 대한 입력 매개변수의 선택적 배열\n\n보고:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"content\": \"[result data]\",\n \"block_uid\": \"\",\n \"page_title\": \"\"\n }\n ],\n \"message\": \"Query executed successfully. Found N results.\"\n}\n```\n\n예시 쿼리:\n\n1. 모든 페이지 수 세기:\n\n```clojure\n[:find (count ?p)\n :where [?p :node/title]]\n```\n\n2. 대소문자를 구분하지 않는 텍스트 검색:\n\n```clojure\n[:find ?string ?title\n :where\n [?b :block/string ?string]\n [(clojure.string/lower-case ?string) ?lower]\n [(clojure.string/includes? ?lower \"search term\")]\n [?b :block/page ?p]\n [?p :node/title ?title]]\n```\n\n3. 날짜 이후에 수정된 블록 찾기:\n\n```clojure\n[:find ?block_ref ?string\n :in $ ?start_of_day\n :where\n [?b :edit/time ?time]\n [(> ?time ?start_of_day)]\n [?b :block/uid ?block_ref]\n [?b :block/string ?string]]\n```\n\n더 많은 쿼리 예제와 구문 설명서는 Roam\\_Research\\_Datalog\\_Cheatsheet.md를 참조하세요.\n\n### 검색 블록 계층 구조\n\n블록 부모-자식 관계를 탐색하고 검색합니다.\n\n```typescript\nuse_mcp_tool roam-research roam_search_hierarchy {\n \"parent_uid\": \"optional-parent-block-uid\",\n \"child_uid\": \"optional-child-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"max_depth\": 3\n}\n```\n\n특징:\n\n* 블록 계층을 위아래로 검색\n* 특정 블록의 자식 찾기\n* 특정 블록의 부모 찾기\n* 검색 깊이 구성(1~10단계)\n* 선택적 페이지 범위 필터링\n* 각 결과에 대한 심층 정보가 포함되어 있습니다.\n\n매개변수:\n\n* `parent_uid` : 자식을 찾을 블록의 UID(아래로 검색하는 경우 필수)\n* `child_uid` : 부모를 찾을 블록의 UID(위로 검색하는 경우 필수)\n* `page_title_uid` : 검색할 페이지의 제목 또는 UID(선택 사항)\n* `max_depth` : 검색할 깊이 수준(선택 사항, 기본값: 1, 최대: 10)\n\n보고:\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"related-block-uid\",\n \"content\": \"Block content\",\n \"depth\": 2,\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) as children/parents...\"\n}\n```\n\n## 오류 처리\n\n서버는 일반적인 시나리오에 대한 포괄적인 오류 처리를 제공합니다.\n\n* 구성 오류:\n * API 토큰 또는 그래프 이름이 없습니다.\n * 잘못된 환경 변수\n* API 오류:\n * 인증 실패\n * 잘못된 요청\n * 실패한 작업\n* 도구별 오류:\n * 페이지를 찾을 수 없습니다(대소문자 구분 없이 검색)\n * 문자열 일치로 블록을 찾을 수 없습니다.\n * 잘못된 마크다운 형식\n * 필수 매개변수가 없습니다\n * 잘못된 개요 구조 또는 내용\n\n각 오류 응답에는 다음이 포함됩니다.\n\n* 표준 MCP 오류 코드\n* 자세한 오류 메시지\n* 해당되는 경우 해결을 위한 제안\n\n## 개발\n\n### 건물\n\n서버를 빌드하려면:\n\n```bash\nnpm install\nnpm run build\n```\n\n이렇게 하면:\n\n1. 필요한 모든 종속성을 설치하세요\n2. TypeScript를 JavaScript로 컴파일\n3. 출력 파일을 실행 가능하게 만들기\n\n개발 중에 `npm run watch` 사용하면 파일이 변경되면 자동으로 다시 컴파일할 수도 있습니다.\n\n### MCP Inspector로 테스트\n\nMCP Inspector는 MCP 서버를 테스트하고 디버깅하는 데 도움이 되는 도구입니다. 서버를 테스트하려면 다음을 수행하세요.\n\n```bash\n# Inspect with npx:\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n이렇게 하면:\n\n1. 서버를 검사기 모드로 시작합니다.\n2. 다음에 대한 대화형 인터페이스를 제공합니다.\n * 사용 가능한 도구 및 리소스 나열\n * 사용자 정의 매개변수로 도구 실행\n * 도구 응답 및 오류 처리 보기\n\n## 특허\n\nMIT 라이센스","Korean","ko-KR",{"_27":60,"_31":64,"_36":65},{"_29":61,"_31":62,"_33":63},"提供对 Roam Research API 功能的全面访问。该服务器使 Claude 等 AI 助手能够通过标准化接口与您的 Roam Research 图表进行交互。","漫游研究","# 漫游研究 MCP 服务器\n\n[![npm 版本](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp) [![项目状态：WIP – 初步开发正在进行中，但尚未有适合公众使用的稳定、可用的版本。](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) [![许可证：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)\n\n一个模型上下文协议 (MCP) 服务器，提供对 Roam Research API 功能的全面访问。该服务器使 Claude 等 AI 助手能够通过标准化接口与您的 Roam Research 图表进行交互。（正在进行中的个人项目，未经 Roam Research 官方认可）\n\n## 安装\n\n您可以全局安装该包：\n\n```bash\nnpm install -g roam-research-mcp\n```\n\n或者克隆存储库并从源代码构建：\n\n```bash\ngit clone https://github.com/2b3pro/roam-research-mcp.git\ncd roam-research-mcp\nnpm install\nnpm run build\n```\n\n## 测试\n\n构建后运行[MCP Inspector](https://github.com/modelcontextprotocol/inspector) ...\n\n```\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n## 特征\n\n该服务器提供了与 Roam Research 交互的强大工具：\n\n* 使用 .env 支持处理环境变量\n* 全面的输入验证\n* 不区分大小写的页面标题匹配\n* 递归块引用解析\n* Markdown 解析和转换\n* 每日页面整合\n* 详细的调试日志记录\n* 高效的批量操作\n* 分层大纲创建\n\n1. `roam_fetch_page_by_title` ：按标题获取并读取页面内容，递归解析最多 4 级深度的块引用\n2. `roam_create_page` ：创建包含可选内容的新页面\n3. `roam_create_block` ：在页面中创建新块（默认为今天的每日页面）\n4. `roam_import_markdown` ：导入特定块下的嵌套 markdown 内容\n5. `roam_add_todo` ：使用复选框语法将多个待办事项添加到今天的每日页面\n6. `roam_create_outline` ：创建具有适当嵌套和结构的分层轮廓\n7. `roam_search_block_refs` ：在页面内或图表中搜索块引用\n8. `roam_search_hierarchy` ：通过块父子关系进行导航和搜索\n9. `roam_find_pages_modified_today` ：查找自今天午夜以来修改过的所有页面\n10. `roam_search_by_text` ：在所有页面或特定页面内搜索包含特定文本的块\n11. `roam_update_block` ：使用直接文本或基于模式的转换来更新块内容\n12. `roam_search_by_date` ：根据创建或修改日期搜索块和页面\n13. `roam_search_for_tag` ：搜索包含特定标签的块，并可选择按附近标签进行过滤\n14. `roam_remember` ：使用自动标记存储和分类记忆或信息\n15. `roam_recall` ：回忆标有标签 MEMORIES\\_TAG 的区块（见下文）或同名页面标题上的区块\n16. `roam_datomic_query` ：在漫游图上执行自定义数据日志查询，以进行高级数据检索和分析\n\n## 设置\n\n1. 创建[Roam Research API 令牌](https://x.com/RoamResearch/status/1789358175474327881)：\n\n * 转到图表设置\n * 导航到“API 令牌”部分（设置 > “图表”选项卡 > “API 令牌”部分，然后单击“+ 新 API 令牌”按钮）\n * 创建新令牌\n\n2. 配置环境变量：您有两种选择来配置所需的环境变量：\n\n 选项 1：使用 .env 文件（推荐用于开发）在 roam-research 目录中创建一个`.env`文件：\n\n ```\n ROAM_API_TOKEN=your-api-token\n ROAM_GRAPH_NAME=your-graph-name\n MEMORIES_TAG='#[[LLM/Memories]]'\n ```\n\n 选项 2：使用 MCP 设置（替代方法）将配置添加到您的 MCP 设置文件：\n\n * 对于 Cline （ `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` ）：\n * 对于 Claude 桌面应用程序（ `~/Library/Application Support/Claude/claude_desktop_config.json` ）：\n\n ```json\n {\n \"mcpServers\": {\n \"roam-research\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/roam-research-mcp/build/index.js\"],\n \"env\": {\n \"ROAM_API_TOKEN\": \"your-api-token\",\n \"ROAM_GRAPH_NAME\": \"your-graph-name\",\n \"MEMORIES_TAG\": \"#[[LLM/Memories]]\"\n }\n }\n }\n }\n ```\n\n 注意：服务器将首先尝试从 .env 文件加载，然后回退到 MCP 设置中的环境变量。\n\n3. 构建服务器（确保您位于 MCP 的根目录中）：\n\n ```bash\n cd roam-research-mcp\n npm install\n npm run build\n ```\n\n## 用法\n\n### 按标题获取页面\n\n使用已解析的块引用获取并读取页面内容：\n\n```typescript\nuse_mcp_tool roam-research roam_fetch_page_by_title {\n \"title\": \"Example Page\"\n}\n```\n\n将页面内容以 markdown 形式返回：\n\n* 完整的层级结构\n* 块引用递归解析（最多 4 层深度）\n* 嵌套级别的适当缩进\n* 完整 markdown 格式\n\n### 创建页面\n\n创建具有可选内容的新页面：\n\n```typescript\nuse_mcp_tool roam-research roam_create_page {\n \"title\": \"New Page\",\n \"content\": \"Initial content for the page\"\n}\n```\n\n成功时返回创建页面的 UID。\n\n### 创建块\n\n向页面添加新区块（如果没有提供 page\\_uid 或 title，则默认为今天的每日页面）：\n\n```typescript\nuse_mcp_tool roam-research roam_create_block {\n \"content\": \"Block content\",\n \"page_uid\": \"optional-target-page-uid\",\n \"title\": \"optional-target-page-title\"\n}\n```\n\n您可以指定：\n\n* `page_uid` ：直接引用目标页面\n* `title` ：目标页面的名称（如果不存在则创建）\n* 两者都不是：今天的每日页面将添加屏蔽\n\n返回：\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"parent_uid\": \"parent-page-uid\"\n}\n```\n\n### 创建大纲\n\n创建具有适当嵌套和结构的分层轮廓：\n\n```typescript\nuse_mcp_tool roam-research roam_create_outline {\n \"outline\": [\n {\n \"text\": \"I. Top Level\",\n \"level\": 1\n },\n {\n \"text\": \"A. Second Level\",\n \"level\": 2\n },\n {\n \"text\": \"1. Third Level\",\n \"level\": 3\n }\n ],\n \"page_title_uid\": \"optional-target-page\",\n \"block_text_uid\": \"optional-header-text\"\n}\n```\n\n特征：\n\n* 创建最多 10 层嵌套的复杂轮廓\n* 验证大纲结构和内容\n* 维持适当的亲子关系\n* 大纲的可选标题块\n* 如果没有指定页面，则默认为今天的每日页面\n* 高效的批量创建区块操作\n\n参数：\n\n* `outline` ：轮廓项目数组，每个项目具有：\n * `text` ：大纲项目的内容（必需）\n * `level` ：嵌套级别（1-10，必需）\n* `page_title_uid` ：目标页面标题或UID（可选，默认为今天的页面）\n* `block_text_uid` ：轮廓的标题文本（可选）\n\n返回：\n\n```json\n{\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"header-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n}\n```\n\n### 添加待办事项\n\n向今天的每日页面添加一个或多个待办事项：\n\n```typescript\nuse_mcp_tool roam-research roam_add_todo {\n \"todos\": [\n \"First todo item\",\n \"Second todo item\",\n \"Third todo item\"\n ]\n}\n```\n\n特征：\n\n* 使用漫游复选框语法添加待办事项（ `{{TODO}} todo text` ）\n* 支持在一次操作中添加多个待办事项\n* 添加 10 个以上待办事项时使用批处理操作来提高效率\n* 如果今天的页面不存在则自动创建\n* 按顺序将待办事项添加为顶级块\n\n### 导入嵌套 Markdown\n\n导入特定块下的嵌套 markdown 内容：\n\n```typescript\nuse_mcp_tool roam-research roam_import_markdown {\n \"content\": \"- Item 1\\n - Subitem A\\n - Subitem B\\n- Item 2\",\n \"page_uid\": \"optional-page-uid\",\n \"page_title\": \"optional-page-title\",\n \"parent_uid\": \"optional-parent-block-uid\",\n \"parent_string\": \"optional-exact-block-content\",\n \"order\": \"first\"\n}\n```\n\n特征：\n\n* 导入特定块下的内容：\n\n * 通过 UID 或精确字符串匹配查找父块\n * 通过标题或 UID 定位特定页面内的区块\n * 如果没有指定页面，则默认为今天的页面\n\n* 控制内容放置：\n\n * 添加为父块的第一个或最后一个子块\n * 保留层次结构\n * 嵌套内容的高效批量操作\n\n* 综合返回值：\n\n ```json\n {\n \"success\": true,\n \"page_uid\": \"target-page-uid\",\n \"parent_uid\": \"parent-block-uid\",\n \"created_uids\": [\"uid1\", \"uid2\", ...]\n }\n ```\n\n参数：\n\n* `content` ：要导入的嵌套 markdown 内容\n* `page_uid` ：包含父块的页面的 UID\n* `page_title` ：包含父块的页面标题（如果提供了 page\\_uid 则忽略）\n* `parent_uid` ：要添加内容的父块的 UID\n* `parent_string` ：父块的精确字符串内容（必须提供 page\\_uid 或 page\\_title）\n* `order` ：添加内容的位置（“first”或“last”，默认为“first”）\n\n### 搜索块引用\n\n在页面内或整个图表中搜索块引用：\n\n```typescript\nuse_mcp_tool roam-research roam_search_block_refs {\n \"block_uid\": \"optional-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\"\n}\n```\n\n特征：\n\n* 查找对特定块的所有引用\n* 搜索页面内的任何块引用\n* 在整个图表中搜索\n* 支持直接和间接引用\n* 包括块内容和位置上下文\n\n参数：\n\n* `block_uid` ：要查找引用的块的 UID（可选）\n* `page_title_uid` ：要搜索的页面的标题或 UID（可选）\n\n返回：\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"referenced-block-uid\",\n \"content\": \"Block content with ((reference))\",\n \"page_title\": \"Page containing reference\"\n }\n ],\n \"message\": \"Found N block(s) referencing...\"\n}\n```\n\n### 按文本搜索\n\n在所有页面或特定页面内搜索包含特定文本的块：\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_text {\n \"text\": \"search text\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"case_sensitive\": true\n}\n```\n\n特征：\n\n* 在图表的所有块中搜索任意文本\n* 可选的页面范围搜索\n* 区分大小写或不区分大小写的搜索\n* 返回带有页面上下文的块内容\n* 使用 Datalog 查询进行高效的文本匹配\n\n参数：\n\n* `text` ：要搜索的文本（必需）\n* `page_title_uid` ：要搜索的页面的标题或 UID（可选）\n* `case_sensitive` ：是否执行区分大小写的搜索（可选，默认值：true，以匹配 Roam 的本机行为）\n\n返回：\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing search text\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) containing \\\"search text\\\"\"\n}\n```\n\n### 更新块内容\n\n使用直接文本替换或基于模式的转换来更新块的内容：\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"content\": \"New block content\"\n}\n```\n\n或者使用基于模式的转换：\n\n```typescript\nuse_mcp_tool roam-research roam_update_block {\n \"block_uid\": \"target-block-uid\",\n \"transform_pattern\": {\n \"find\": \"\\\\bPython\\\\b\",\n \"replace\": \"[[Python]]\",\n \"global\": true\n }\n}\n```\n\n特征：\n\n* 两种更新模式：\n * 直接内容替换\n * 使用正则表达式进行基于模式的转换\n* 更新之前验证块的存在\n* 返回更新后的内容作为响应\n* 支持全局或单场比赛替换\n* 保留块关系和元数据\n\n参数：\n\n* `block_uid` ：要更新的块的 UID（必需）\n* `content` ：块的新内容（如果使用直接替换）\n* `transform_pattern` ：转换现有内容的模式：\n * `find` ：要查找的文本或正则表达式模式\n * `replace` ：要替换的文本\n * `global` ：是否替换所有出现的内容（默认值：true）\n\n返回：\n\n```json\n{\n \"success\": true,\n \"content\": \"Updated block content\"\n}\n```\n\n### 搜索标签\n\n搜索包含特定标签的块，并可选择按附近标签进行过滤：\n\n```typescript\nuse_mcp_tool roam-research roam_search_for_tag {\n \"primary_tag\": \"Project/Tasks\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"near_tag\": \"optional-secondary-tag\",\n \"case_sensitive\": true\n}\n```\n\n特征：\n\n* 搜索包含特定标签的块\n* 可选的根据另一个标签的存在进行过滤\n* 页面范围或图形范围的搜索\n* 区分大小写或不区分大小写的搜索\n* 返回带有页面上下文的块内容\n* 使用 Datalog 查询进行高效的标签匹配\n\n参数：\n\n* `primary_tag` ：要搜索的主标签（必需）\n* `page_title_uid` ：要搜索的页面的标题或 UID（可选）\n* `near_tag` ：用于过滤结果的另一个标签（可选）\n* `case_sensitive` ：是否执行区分大小写的搜索（可选，默认值：true，以匹配 Roam 的本机行为）\n\n返回：\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"matching-block-uid\",\n \"content\": \"Block content containing #[[primary_tag]]\",\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) referencing \\\"primary_tag\\\"\"\n}\n```\n\n### 记住信息\n\n使用自动标记和分类来存储记忆或重要信息：\n\n```typescript\nuse_mcp_tool roam-research roam_remember {\n \"memory\": \"Important information to remember\",\n \"categories\": [\"Work\", \"Project/Alpha\"]\n}\n```\n\n特征：\n\n* 使用 #\\[\\[LLM/Memories]] 标签存储信息\n* 为组织添加可选的类别标签\n* 自动添加到今天的每日页面\n* 每个内存支持多个类别\n* 使用 roam\\_search\\_for\\_tag 轻松检索\n* 保持记忆的时间顺序\n\n参数：\n\n* `memory` ：需要记住的信息（必需）\n* `categories` ：用于标记内存的可选类别数组\n\n返回：\n\n```json\n{\n \"success\": true,\n \"block_uid\": \"created-block-uid\",\n \"content\": \"Memory content with tags\"\n}\n```\n\n### 按日期搜索\n\n根据创建或修改日期搜索块和页面：\n\n```typescript\nuse_mcp_tool roam-research roam_search_by_date {\n \"start_date\": \"2025-01-01\",\n \"end_date\": \"2025-01-31\",\n \"type\": \"modified\",\n \"scope\": \"blocks\",\n \"include_content\": true\n}\n```\n\n特征：\n\n* 按创建日期、修改日期或两者搜索\n* 过滤块、页面或两者\n* 可选日期范围，包括开始日期和结束日期\n* 在结果中包含或排除块/页面内容\n* 按时间戳对结果进行排序\n* 使用 Datalog 查询进行高效的基于日期的过滤\n\n参数：\n\n* `start_date` ：ISO 格式的开始日期 (YYYY-MM-DD)（必需）\n* `end_date` ：ISO 格式的结束日期 (YYYY-MM-DD)（可选）\n* `type` ：是否按“创建”、“修改”或“两者”进行搜索（必需）\n* `scope` ：是否搜索“块”、“页面”或“两者”（必需）\n* `include_content` ：是否包含匹配的块/页面的内容（可选，默认值：true）\n\n返回：\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"uid\": \"block-or-page-uid\",\n \"type\": \"block\",\n \"time\": 1704067200000,\n \"content\": \"Block or page content\",\n \"page_title\": \"Page title (for blocks)\"\n }\n ],\n \"message\": \"Found N matches for the given date range and criteria\"\n}\n```\n\n### 查找今天修改的页面\n\n查找今天午夜以来修改过的所有页面：\n\n```typescript\nuse_mcp_tool roam-research roam_find_pages_modified_today {}\n```\n\n特征：\n\n* 跟踪自午夜以来对页面所做的所有修改\n* 检测块层次结构中任何级别的变化\n* 返回已修改页面标题的唯一列表\n* 包括已修改页面的数量\n* 无需参数\n\n返回：\n\n```json\n{\n \"success\": true,\n \"pages\": [\"Page 1\", \"Page 2\"],\n \"message\": \"Found 2 page(s) modified today\"\n}\n```\n\n### 执行 Datomic 查询\n\n在漫游图上执行自定义数据日志查询以进行高级数据检索和分析：\n\n```typescript\nuse_mcp_tool roam-research roam_datomic_query {\n \"query\": \"[:find (count ?p)\\n :where [?p :node/title]]\",\n \"inputs\": []\n}\n```\n\n特征：\n\n* 直接访问 Roam 的查询引擎\n* 支持所有Datalog查询功能：\n * 复杂模式匹配\n * 聚合函数（计数、总和、最大值、最小值、平均值、不同）\n * 字符串操作（包括？、以...开头？、以...结尾？）\n * 逻辑运算（<、>、<=、>=、=、not=）\n * 递归查询规则\n* 区分大小写和不区分大小写的搜索功能\n* 跨整个图表的高效查询\n\n参数：\n\n* `query` ：要执行的 Datalog 查询（必需）\n* `inputs` ：查询的可选输入参数数组\n\n返回：\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"content\": \"[result data]\",\n \"block_uid\": \"\",\n \"page_title\": \"\"\n }\n ],\n \"message\": \"Query executed successfully. Found N results.\"\n}\n```\n\n示例查询：\n\n1. 统计所有页面：\n\n```clojure\n[:find (count ?p)\n :where [?p :node/title]]\n```\n\n2. 不区分大小写的文本搜索：\n\n```clojure\n[:find ?string ?title\n :where\n [?b :block/string ?string]\n [(clojure.string/lower-case ?string) ?lower]\n [(clojure.string/includes? ?lower \"search term\")]\n [?b :block/page ?p]\n [?p :node/title ?title]]\n```\n\n3. 查找在某个日期之后修改的块：\n\n```clojure\n[:find ?block_ref ?string\n :in $ ?start_of_day\n :where\n [?b :edit/time ?time]\n [(> ?time ?start_of_day)]\n [?b :block/uid ?block_ref]\n [?b :block/string ?string]]\n```\n\n有关更多查询示例和语法文档，请参阅 Roam\\_Research\\_Datalog\\_Cheatsheet.md。\n\n### 搜索块层次结构\n\n浏览并搜索块父子关系：\n\n```typescript\nuse_mcp_tool roam-research roam_search_hierarchy {\n \"parent_uid\": \"optional-parent-block-uid\",\n \"child_uid\": \"optional-child-block-uid\",\n \"page_title_uid\": \"optional-page-title-or-uid\",\n \"max_depth\": 3\n}\n```\n\n特征：\n\n* 向上或向下搜索块层次结构\n* 查找特定块的子块\n* 查找特定块的父块\n* 配置搜索深度（1-10 级）\n* 可选的页面范围过滤\n* 包含每个结果的深度信息\n\n参数：\n\n* `parent_uid` ：要查找子块的 UID（向下搜索时必需）\n* `child_uid` ：要查找父块的 UID（向上搜索时必需）\n* `page_title_uid` ：要搜索的页面的标题或 UID（可选）\n* `max_depth` ：搜索深度（可选，默认值：1，最大值：10）\n\n返回：\n\n```json\n{\n \"success\": true,\n \"matches\": [\n {\n \"block_uid\": \"related-block-uid\",\n \"content\": \"Block content\",\n \"depth\": 2,\n \"page_title\": \"Page containing block\"\n }\n ],\n \"message\": \"Found N block(s) as children/parents...\"\n}\n```\n\n## 错误处理\n\n服务器针对常见场景提供了全面的错误处理：\n\n* 配置错误：\n * 缺少 API 令牌或图表名称\n * 无效的环境变量\n* API 错误：\n * 身份验证失败\n * 无效请求\n * 失败的操作\n* 特定于工具的错误：\n * 未找到页面（不区分大小写的搜索）\n * 未通过字符串匹配找到块\n * Markdown 格式无效\n * 缺少必需参数\n * 大纲结构或内容无效\n\n每个错误响应包括：\n\n* 标准 MCP 错误代码\n* 详细错误消息\n* 适用时的解决方案建议\n\n## 发展\n\n### 建筑\n\n构建服务器：\n\n```bash\nnpm install\nnpm run build\n```\n\n这将：\n\n1. 安装所有必需的依赖项\n2. 将 TypeScript 编译为 JavaScript\n3. 使输出文件可执行\n\n您还可以在开发过程中使用`npm run watch`在文件发生更改时自动重新编译。\n\n### 使用 MCP Inspector 进行测试\n\nMCP 检查器是一款用于测试和调试 MCP 服务器的工具。要测试服务器，请执行以下操作：\n\n```bash\n# Inspect with npx:\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n这将：\n\n1. 以检查器模式启动服务器\n2. 提供交互式界面来：\n * 列出可用的工具和资源\n * 使用自定义参数执行工具\n * 查看工具响应和错误处理\n\n## 执照\n\nMIT 许可证","Chinese","zh-CN","githubUser","locale",{"_69":70,"_13":71,"_81":30,"_82":30,"_16":83,"_84":85,"_31":32,"_110":111,"_118":-5,"_119":120,"_178":179,"_184":-5,"_92":157,"_185":186,"_95":187,"_188":189},"addedAt","2024-12-20T13:37:36.962584Z",[72,73,74,75,76,77,78,79,80],"category:developer-tools","category:note-taking","category:content-management-systems","environment:network","hosting:remote-capable","language:typescript","security_grade:a","quality_grade:a","license_grade:a","descriptionMarkdown","descriptionPlainText",403,"integrations",[86,97,104],{"_87":88,"_29":94,"_95":96},"brand",{"_89":90,"_31":91,"_92":93},"logoSvgPath","M24 0v24H0V0h24ZM10.933 15.89H6.84v5.52h4.198v-.93H7.955v-1.503h2.77v-.93h-2.77v-1.224h2.978v-.934Zm2.146 0h-1.084v5.52h1.035v-3.6l2.226 3.6h1.118v-5.52h-1.036v3.686l-2.259-3.687Zm5.117 0h-1.208l1.973 5.52h1.19l1.976-5.52h-1.182l-1.352 4.085-1.397-4.086ZM5.4 19.68H3.72v1.68H5.4v-1.68Z",".ENV","slug","dotenv","Supports loading configuration from .env files for managing environment variables like API tokens and graph names.","uid","7pi2f198th",{"_87":98,"_29":102,"_95":103},{"_89":99,"_31":100,"_92":101},"M22.27 19.385H1.73A1.73 1.73 0 010 17.655V6.345a1.73 1.73 0 011.73-1.73h20.54A1.73 1.73 0 0124 6.345v11.308a1.73 1.73 0 01-1.73 1.731zM5.769 15.923v-4.5l2.308 2.885 2.307-2.885v4.5h2.308V8.078h-2.308l-2.307 2.885-2.308-2.885H3.46v7.847zM21.232 12h-2.309V8.077h-2.307V12h-2.308l3.461 4.039z","Markdown","markdown","Enables parsing and conversion of markdown content, with support for importing nested markdown structures into Roam Research with proper hierarchy preservation.","0hh195061i",{"_87":105,"_29":108,"_95":109},{"_89":106,"_31":32,"_92":107},"M11.14.028C7.315.36 4.072 2.263 1.98 5.411.487 7.646-.232 10.589.067 13.211c.32 2.772 1.4 5.124 3.242 7.049 4.643 4.852 12.252 5.001 17.038.343 1.085-1.057 1.738-1.959 2.407-3.303a11.943 11.943 0 0 0-2.429-13.925C18.372 1.495 16.015.388 13.27.078c-.68-.083-1.56-.1-2.13-.05zm4.814 2.567c1.112.437 2.086 1.068 3.032 1.986.62.598 1.323 1.46 1.3 1.599-.016.072-1.626.725-1.792.725-.056 0-.078-.072-.078-.25 0-.138-.011-.248-.028-.248-.01 0-.758.459-1.654 1.023-.897.565-1.666 1.024-1.71 1.024-.05 0-.133-.061-.194-.139-.127-.16-.216-.171-.354-.044-.066.056-.1.166-.1.316v.226l-.824.46c-.46.249-.89.453-.968.453h-.144V8.161c0-.863.016-2.025.038-2.573.034-.99.04-1.007.155-1.007.117 0 .128-.028.155-.514.067-1.107.25-1.284 1.362-1.323l.514-.016.16-.233c.156-.226.167-.226.366-.171.116.028.46.15.764.271zm-7.05.011l.122.183.641-.006c.604 0 .659.011.902.15.355.21.482.497.526 1.145l.033.498.172.016.171.017.017 2.716.011 2.722-.232.138a3.024 3.024 0 0 0-.936.875l-.177.27h-5.24v-.325l-.592-.017-.598-.017-.398-.586c-.332-.493-.454-.626-.758-.825-.415-.265-.404-.193-.139-1.023.659-2.025 2.203-3.945 4.1-5.107.67-.409 1.932-.995 2.159-1.001.055-.005.155.078.216.177zm12.163 4.902c.354.686.725 1.588.725 1.765 0 .071-.1.149-.327.26-.326.154-.393.237-.393.503 0 .155-.166.36-.564.692l-.327.27h-.99v.333h-2.767v-.886l-.332-.42c-.183-.227-.332-.432-.332-.454 0-.022 1.073-.68 2.39-1.46 2.17-1.29 2.402-1.417 2.485-1.34.05.045.244.377.432.737zm-5.556 3.087c.243.354.454.664.46.686.01.027-.394.05-.892.05h-.918l-.2-.332c-.11-.183-.193-.36-.182-.388.028-.083 1.167-.708 1.234-.68.033.011.254.31.498.664zm-7.282 2.567c.254.398.442.741.415.769-.111.1-5.163 3.32-5.213 3.32-.155 0-.813-1.317-1.024-2.048-.249-.863-.265-.769.188-1.045.178-.111.371-.321.637-.703l.387-.548.603-.027.609-.028.017-.21.016-.205H7.77l.459.725zm1.815-.476c.066.122.127.249.127.288 0 .077-.996.686-1.057.647-.05-.028-.714-1.1-.714-1.15 0-.023.343-.028.758-.023l.758.017.128.221zm9.158-.044l.016.21.554.028c.597.027.525 0 1.184.481.011.006.06.194.11.41.095.425.128.459.493.547.288.072.293.133.072.78-.57 1.682-1.787 3.425-3.287 4.686-.642.542-.603.542-.559-.055.045-.614-.027-.935-.254-1.162-.26-.255-.526-.221-1.3.177-.51.26-.698.332-.897.332-.327 0-.631-.094-.825-.255l-.16-.127.393-.36c.42-.381.62-.73.525-.907-.16-.298-.453-.37-1.045-.26-.498.1-.864.105-1.013.028-.188-.105-.288-.376-.26-.741.028-.332.022-.343-.216-.62l-.238-.282v-1.765l.393-.271c.216-.144.559-.448.758-.675l.37-.404h5.17l.017.205zm-7.814 2.157v.758l-.276.282-.277.283.083.238c.1.282.105.52.022.674-.1.194-.293.222-.896.133a8.212 8.212 0 0 0-.764-.083c-.68 0-.703.482-.06 1.256.31.37.31.365-.084.564-.553.277-.902.25-1.389-.116-.41-.304-.647-.393-.968-.36-.21.017-.31.061-.443.2l-.177.177.006.686c0 .382-.011.691-.023.691-.06 0-1.023-.846-1.45-1.272-.442-.448-.995-1.123-.995-1.217 0-.044 1.516-.72 1.615-.72.034 0 .045.084.034.194-.011.105-.006.194.01.194.017 0 1.362-.747 2.989-1.66a204.276 204.276 0 0 1 3.005-1.66c.022 0 .038.343.038.758z","roam-research","Provides comprehensive access to Roam Research's API functionality, allowing AI assistants to interact with Roam Research graphs through tools for fetching, creating, and updating pages and blocks, importing markdown, searching content, and executing Datalog queries.","zfexrbxtkd","namespace",{"_112":113,"_92":117},"owner",{"_114":115},"githubAccount",{"_116":117},"login","2b3pro","redditPostExternalId","repository",{"_121":122,"_141":142,"_146":147,"_167":-5,"_168":169,"_170":171,"_174":175},"argumentsJsonSchema",{"_123":124,"_138":139,"_130":140},"properties",{"_125":126,"_132":133,"_135":136},"MEMORIES_TAG",{"_127":128,"_29":129,"_130":131},"default","#[[LLM/Memories]]","The tag used for marking memories in Roam","type","string","ROAM_API_TOKEN",{"_29":134,"_130":131},"Your Roam Research API token from graph settings","ROAM_GRAPH_NAME",{"_29":137,"_130":131},"The name of your Roam Research graph","required",[132,135],"object","githubProject",{"_33":143,"_144":145},"![](./roam-research-mcp-image.jpeg)\n\n# Roam Research MCP Server\n\n[![npm version](https://badge.fury.io/js/roam-research-mcp.svg)](https://badge.fury.io/js/roam-research-mcp)\n[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub](https://img.shields.io/github/license/2b3pro/roam-research-mcp)](https://github.com/2b3pro/roam-research-mcp/blob/main/LICENSE)\n\nA 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)\n\n $\"Roam$ \n $\"MseeP.ai$ \n\n## Installation and Usage\n\nThis MCP server supports three primary communication methods:\n\n1. **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.\n2. **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.\n3. **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.)\n\n### Running with Stdio\n\nYou can install the package globally and run it:\n\n```bash\nnpm install -g roam-research-mcp\nroam-research-mcp\n```\n\nOr clone the repository and build from source:\n\n```bash\ngit clone https://github.com/2b3pro/roam-research-mcp.git\ncd roam-research-mcp\nnpm install\nnpm run build\nnpm start\n```\n\n### Running with HTTP Stream\n\nTo run the server with HTTP Stream or SSE support, you can either:\n\n1. **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.\n2. **Specify custom ports:** Set the `HTTP_STREAM_PORT` and/or `SSE_PORT` environment variables before starting the server.\n\n ```bash\n HTTP_STREAM_PORT=9000 SSE_PORT=9001 npm start\n ```\n\n Or, if using a `.env` file, add `HTTP_STREAM_PORT=9000` and/or `SSE_PORT=9001` to it.\n\n## Docker\n\nThis project can be easily containerized using Docker. A `Dockerfile` is provided at the root of the repository.\n\n### Build the Docker Image\n\nTo build the Docker image, navigate to the project root and run:\n\n```bash\ndocker build -t roam-research-mcp .\n```\n\n### Run the Docker Container\n\nTo 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`:\n\n```bash\ndocker run -p 3000:3000 -p 8088:8088 -p 8087:8087 \\\n -e ROAM_API_TOKEN=\"your-api-token\" \\\n -e ROAM_GRAPH_NAME=\"your-graph-name\" \\\n -e MEMORIES_TAG=\"#[[LLM/Memories]]\" \\\n -e CUSTOM_INSTRUCTIONS_PATH=\"/path/to/your/custom_instructions_file.md\" \\\n -e HTTP_STREAM_PORT=\"8088\" \\\n -e SSE_PORT=\"8087\" \\\n roam-research-mcp\n```\n\nAlternatively, 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:\n\n```bash\ndocker run -p 3000:3000 -p 8088:8088 --env-file .env roam-research-mcp\n```\n\n## To Test\n\nRun [MCP Inspector](https://github.com/modelcontextprotocol/inspector) after build using the provided npm script:\n\n```bash\nnpm run inspector\n```\n\n## Features\n\nThe server provides powerful tools for interacting with Roam Research:\n\n- Environment variable handling with .env support\n- Comprehensive input validation\n- Case-insensitive page title matching\n- Recursive block reference resolution\n- Markdown parsing and conversion\n- Daily page integration\n- Detailed debug logging\n- Efficient batch operations\n- Hierarchical outline creation\n- Enhanced documentation for Roam Tables in `Roam_Markdown_Cheatsheet.md` for clearer guidance on nesting.\n - Custom instruction appended to the cheat sheet about your specific Roam notes.\n\n1. `roam_fetch_page_by_title`: Fetch page content by title. Returns content in the specified format.\n2. `roam_fetch_block_with_children`: Fetch a block by its UID along with its hierarchical children down to a specified depth. Automatically handles `((UID))` formatting.\n3. `roam_create_page`: Create new pages with optional content and headings. Now creates a block on the daily page linking to the newly created page.\n4. `roam_import_markdown`: Import nested markdown content under a specific block. (Internally uses `roam_process_batch_actions`.)\n5. `roam_add_todo`: Add a list of todo items to today's daily page. (Internally uses `roam_process_batch_actions`.)\n6. `roam_create_outline`: Add a structured outline to an existing page or block, with support for `children_view_type`. Best for simpler, sequential outlines. For complex nesting (e.g., tables), consider `roam_process_batch_actions`. If `page_title_uid` and `block_text_uid` are both blank, content defaults to the daily page. (Internally uses `roam_process_batch_actions`.)\n7. `roam_search_block_refs`: Search for block references within a page or across the entire graph.\n8. `roam_search_hierarchy`: Search for parent or child blocks in the block hierarchy.\n9. `roam_find_pages_modified_today`: Find pages that have been modified today (since midnight), with pagination and sorting options.\n10. `roam_search_by_text`: Search for blocks containing specific text across all pages or within a specific page. This tool supports pagination via the `limit` and `offset` parameters.\n11. `roam_search_by_status`: Search for blocks with a specific status (TODO/DONE) across all pages or within a specific page.\n12. `roam_search_by_date`: Search for blocks or pages based on creation or modification dates.\n13. `roam_search_for_tag`: Search for blocks containing a specific tag and optionally filter by blocks that also contain another tag nearby or exclude blocks with a specific tag. This tool supports pagination via the `limit` and `offset` parameters.\n14. `roam_remember`: Add a memory or piece of information to remember. (Internally uses `roam_process_batch_actions`.)\n15. `roam_recall`: Retrieve all stored memories.\n16. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. Now supports client-side regex filtering for enhanced post-query processing. Optimal for complex filtering (including regex), highly complex boolean logic, arbitrary sorting criteria, and proximity search.\n17. `roam_markdown_cheatsheet`: Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions if `CUSTOM_INSTRUCTIONS_PATH` environment variable is set.\n18. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)\n\n**Deprecated Tools**:\nThe following tools have been deprecated as of `v0.36.2` in favor of the more powerful and flexible `roam_process_batch_actions`:\n\n- `roam_create_block`: Use `roam_process_batch_actions` with the `create-block` action.\n- `roam_update_block`: Use `roam_process_batch_actions` with the `update-block` action.\n- `roam_update_multiple_blocks`: Use `roam_process_batch_actions` with multiple `update-block` actions.\n\n---\n\n### Tool Usage Guidelines and Best Practices\n\n**Pre-computation and Context Loading:**\n✅ Before attempting any Roam operations, **it is highly recommended** to load the `Roam Markdown Cheatsheet` resource into your context. This ensures you have immediate access to the correct Roam-flavored Markdown syntax, including details for tables, block references, and other special formatting. Example prompt: \"Read the Roam cheatsheet first. Then, … \"\n\n- **Specific notes and preferences** concerning my Roam Research graph. Users can add their own specific notes and preferences for working with their own graph in the Cheatsheet.\n\n**Identifying Pages and Blocks for Manipulation:**\nTo ensure accurate operations, always strive to identify target pages and blocks using their Unique Identifiers (UIDs) whenever possible. While some tools accept case-sensitive text titles or content, UIDs provide unambiguous references, reducing the risk of errors due to ambiguity or changes in text.\n\n- **For Pages:** Use `roam_fetch_page_by_title` to retrieve a page's UID if you only have its title. Example: \"Read the page titled 'Trip to Las Vegas'\"\n- **For Blocks:** If you need to manipulate an existing block, first use search tools like `roam_search_by_text`, `roam_search_for_tag`, or `roam_fetch_page_by_title` (with raw format) to find the block and obtain its UID. If the block exists on a page that has already been read, then a search isn't necessary.\n\n**Case-Sensitivity:**\nBe aware that text-based inputs (e.g., page titles, block content for search) are generally case-sensitive in Roam. Always match the exact casing of the text as it appears in your graph.\n\n**Iterative Refinement and Verification:**\nFor complex operations, especially those involving nested structures or multiple changes, it is often beneficial to break down the task into smaller, verifiable steps. After each significant tool call, consider fetching the affected content to verify the changes before proceeding.\n\n**Understanding Tool Nuances:**\nFamiliarize yourself with the specific behaviors and limitations of each tool. For instance, `roam_create_outline` is best for sequential outlines, while `roam_process_batch_actions` offers granular control for complex structures like tables. Refer to the individual tool descriptions for detailed usage notes.\n\nWhen making changes to your Roam graph, precision in your requests is crucial for achieving desired outcomes.\n\n**Specificity in Requests:**\nSome tools allow for identifying blocks or pages by their text content (e.g., `parent_string`, `title`). While convenient, using **Unique Identifiers (UIDs)** is always preferred for accuracy and reliability. Text-based matching can be prone to errors if there are multiple blocks with similar content or if the content changes. Tools are designed to work best when provided with explicit UIDs where available.\n\n**Example of Specificity:**\nInstead of:\n`\"parent_string\": \"My project notes\"`\n\nPrefer:\n`\"parent_uid\": \"((some-unique-uid))\"`\n\n**Caveat Regarding Heading Formatting:**\nPlease note that while the `roam_process_batch_actions` tool can set block headings (H1, H2, H3), directly **removing** an existing heading (i.e., reverting a heading block to a plain text block) through this tool is not currently supported by the Roam API. The `heading` attribute persists its value once set, and attempting to remove it by setting `heading` to `0`, `null`, or omitting the property will not unset the heading.\n\n---\n\n## Example Prompts\n\nHere are some examples of how to creatively use the Roam tool in an LLM to interact with your Roam graph, particularly leveraging `roam_process_batch_actions` for complex operations.\n\n### Example 1: Creating a Project Outline\n\nThis prompt demonstrates creating a new page and populating it with a structured outline using a single `roam_process_batch_actions` call.\n\n```\n\"Create a new Roam page titled 'Project Alpha Planning' and add the following outline:\n- Overview\n - Goals\n - Scope\n- Team Members\n - John Doe\n - Jane Smith\n- Tasks\n - Task 1\n - Subtask 1.1\n - Subtask 1.2\n - Task 2\n- Deadlines\"\n```\n\n### Example 2: Updating Multiple To-Dos and Adding a New One\n\nThis example shows how to mark existing to-do items as `DONE` and add a new one, all within a single batch.\n\n```\n\"Mark 'Finish report' and 'Review presentation' as done on today's daily page, and add a new todo 'Prepare for meeting'.\"\n```\n\n### Example 3: Moving and Updating a Block\n\nThis demonstrates moving a block from one location to another and simultaneously updating its content.\n\n```\n\"Move the block 'Important note about client feedback' (from page 'Meeting Notes 2025-06-30') under the 'Action Items' section on the 'Project Alpha Planning' page, and change its content to 'Client feedback reviewed and incorporated'.\"\n```\n\n### Example 4: Making a Table\n\nThis demonstrates moving a block from one location to another and simultaneously updating its content.\n\n```\n\"In Roam, add a new table on the page \"Fruity Tables\" that compares four types of fruits: apples, oranges, grapes, and dates. Choose randomly four areas to compare.\"\n```\n\n---\n\n## Setup\n\n1. Create a [Roam Research API token](https://x.com/RoamResearch/status/1789358175474327881):\n\n - Go to your graph settings\n - Navigate to the \"API tokens\" section (Settings > \"Graph\" tab > \"API Tokens\" section and click on the \"+ New API Token\" button)\n - Create a new token\n\n2. Configure the environment variables:\n You have two options for configuring the required environment variables:\n\n Option 1: Using a .env file (Recommended for development)\n Create a `.env` file in the roam-research directory:\n\n ```\n ROAM_API_TOKEN=your-api-token\n ROAM_GRAPH_NAME=your-graph-name\n MEMORIES_TAG='#[[LLM/Memories]]'\n CUSTOM_INSTRUCTIONS_PATH='/path/to/your/custom_instructions_file.md'\n HTTP_STREAM_PORT=8088 # Or your desired port for HTTP Stream communication\n SSE_PORT=8087 # Or your desired port for SSE communication\n ```\n\n Option 2: Using MCP settings (Alternative method)\n 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.\n\n - For Cline (`~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`):\n - For Claude desktop app (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n ```json\n {\n \"mcpServers\": {\n \"roam-research\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/roam-research-mcp/build/index.js\"],\n \"env\": {\n \"ROAM_API_TOKEN\": \"your-api-token\",\n \"ROAM_GRAPH_NAME\": \"your-graph-name\",\n \"MEMORIES_TAG\": \"#[[LLM/Memories]]\",\n \"CUSTOM_INSTRUCTIONS_PATH\": \"/path/to/your/custom_instructions_file.md\",\n \"HTTP_STREAM_PORT\": \"8088\",\n \"SSE_PORT\": \"8087\"\n }\n }\n }\n }\n ```\n\n Note: The server will first try to load from .env file, then fall back to environment variables from MCP settings.\n\n3. Build the server (make sure you're in the root directory of the MCP):\n\n Note: Customize 'Roam_Markdown_Cheatsheet.md' with any notes and preferences specific to your graph BEFORE building.\n\n ```bash\n cd roam-research-mcp\n npm install\n npm run build\n ```\n\n## Error Handling\n\nThe server provides comprehensive error handling for common scenarios:\n\n- Configuration errors:\n - Missing API token or graph name\n - Invalid environment variables\n- API errors:\n - Authentication failures\n - Invalid requests\n - Failed operations\n- Tool-specific errors:\n - Page not found (with case-insensitive search)\n - Block not found by string match\n - Invalid markdown format\n - Missing required parameters\n - Invalid outline structure or content\n\nEach error response includes:\n\n- Standard MCP error code\n- Detailed error message\n- Suggestions for resolution when applicable\n\n---\n\n## Development\n\n### Building\n\nTo build the server:\n\n```bash\nnpm install\nnpm run build\n```\n\nThis will:\n\n1. Install all required dependencies\n2. Compile TypeScript to JavaScript\n3. Make the output file executable\n\nYou can also use `npm run watch` during development to automatically recompile when files change.\n\n### Testing with MCP Inspector\n\nThe MCP Inspector is a tool that helps test and debug MCP servers. To test the server:\n\n```bash\n# Inspect with npx:\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\nThis will:\n\n1. Start the server in inspector mode\n2. Provide an interactive interface to:\n - List available tools and resources\n - Execute tools with custom parameters\n - View tool responses and error handling\n\n## License\n\nMIT License\n\n---\n\n## About the Author\n\nThis project is maintained by [Ian Shen](https://github.com/2b3pro).\n","url","https://github.com/2b3pro/roam-research-mcp","githubRepository",{"_148":149,"_150":151,"_152":153,"_16":154,"_155":156,"_31":157,"_112":158,"_160":161,"_162":163,"_165":166},"defaultBranch","main","fullName","2b3pro/roam-research-mcp","githubTreeId",278798,171,"language","TypeScript","roam-research-mcp",{"_116":117,"_95":159},"g2b7ocbaam","recentStargazers",2,"spdxLicense",{"_31":164},"MIT License","stargazers",65,"glamaJson","inspectable",true,"npmPackage",{"_31":157,"_172":173},"weeklyDownloads",12,"supportedPlatforms",[176,177],"MACOS","WINDOWS","scores",{"_180":181,"_182":181,"_183":181},"license",100,"quality","security","simpleIcon","toolCount",0,"fzfznyaflu","updatedAt","2025-09-17T02:55:17.028253Z","meta",[192,195,197,204,207,209,212,215,218,221,224,226,229,232,234,236,238,240,242],{"_193":194},"title","Roam Research | Glama",{"_196":30,"_31":29},"content",{"_198":199,"_200":201,"_202":203},"href","https://glama.ai/mcp/servers/@2b3pro/roam-research-mcp","rel","canonical","tagName","link",{"_196":32,"_205":206},"property","og:title",{"_196":30,"_205":208},"og:description",{"_196":210,"_205":211},"https://glama.ai/logo.png","og:logo",{"_196":213,"_205":214},"https://glama.ai/mcp/servers/@2b3pro/roam-research-mcp/og-image","og:image",{"_196":216,"_205":217},"630","og:image:height",{"_196":219,"_205":220},"1200","og:image:width",{"_196":222,"_205":223},"website","og:type",{"_196":199,"_205":225},"og:url",{"_196":227,"_205":228},"Glama – MCP Hosting Platform","og:site_name",{"_196":230,"_31":231},"summary_large_image","twitter:card",{"_196":227,"_31":233},"twitter:title",{"_196":30,"_31":235},"twitter:description",{"_196":213,"_31":237},"twitter:image",{"_196":216,"_31":239},"twitter:image:height",{"_196":219,"_31":241},"twitter:image:width",{"_243":244},"script:ld+json",{"_245":246,"_247":248},"@context","http://schema.org","@graph",[249],{"_245":250,"_251":252,"_253":254},"https://schema.org","@type","BreadcrumbList","itemListElement",[255,262,265,269],{"_251":256,"_257":258,"_31":259,"_260":261},"ListItem","item","/","Glama","position",1,{"_251":256,"_257":263,"_31":264,"_260":161},"/mcp","MCP",{"_251":256,"_257":266,"_31":267,"_260":268},"/mcp/servers","Servers",3,{"_251":256,"_257":270,"_31":32,"_260":271},"/mcp/servers/@2b3pro/roam-research-mcp",4,"visitorIsMaintainer",false,"routes/_public/mcp/servers/~namespace/~slug/_pages/reviews/_route",{"_66":-5,"_27":276,"_190":302,"_338":-5},{"_69":70,"_13":277,"_81":30,"_82":30,"_16":83,"_84":278,"_31":32,"_110":285,"_118":-5,"_119":288,"_178":301,"_184":-5,"_92":157,"_185":186,"_95":187,"_188":189},[72,73,74,75,76,77,78,79,80],[279,281,283],{"_87":280,"_29":94,"_95":96},{"_89":90,"_31":91,"_92":93},{"_87":282,"_29":102,"_95":103},{"_89":99,"_31":100,"_92":101},{"_87":284,"_29":108,"_95":109},{"_89":106,"_31":32,"_92":107},{"_112":286,"_92":117},{"_114":287},{"_116":117},{"_121":289,"_141":295,"_146":296,"_167":-5,"_168":169,"_170":299,"_174":300},{"_123":290,"_138":294,"_130":140},{"_125":291,"_132":292,"_135":293},{"_127":128,"_29":129,"_130":131},{"_29":134,"_130":131},{"_29":137,"_130":131},[132,135],{"_33":143,"_144":145},{"_148":149,"_150":151,"_152":153,"_16":154,"_155":156,"_31":157,"_112":297,"_160":161,"_162":298,"_165":166},{"_116":117,"_95":159},{"_31":164},{"_31":157,"_172":173},[176,177],{"_180":181,"_182":181,"_183":181},[303,305,307,309,311,312,313,314,315,316,317,318,319,320,321,322,323,324,325],{"_193":304},"Reviews | Roam Research | Glama",{"_196":306,"_31":29},"Read community reviews and feedback for Roam Research. Discover user experiences, ratings, strengths, and potential limitations of this MCP implementation from actual users.",{"_198":308,"_200":201,"_202":203},"https://glama.ai/mcp/servers/@2b3pro/roam-research-mcp/reviews",{"_196":310,"_205":206},"Reviews | Roam Research",{"_196":306,"_205":208},{"_196":210,"_205":211},{"_196":213,"_205":214},{"_196":216,"_205":217},{"_196":219,"_205":220},{"_196":222,"_205":223},{"_196":308,"_205":225},{"_196":227,"_205":228},{"_196":230,"_31":231},{"_196":227,"_31":233},{"_196":306,"_31":235},{"_196":213,"_31":237},{"_196":216,"_31":239},{"_196":219,"_31":241},{"_243":326},{"_245":246,"_247":327},[328],{"_245":250,"_251":252,"_253":329},[330,331,332,333,334],{"_251":256,"_257":258,"_31":259,"_260":261},{"_251":256,"_257":263,"_31":264,"_260":161},{"_251":256,"_257":266,"_31":267,"_260":268},{"_251":256,"_257":270,"_31":32,"_260":271},{"_251":256,"_257":335,"_31":336,"_260":337},"/mcp/servers/@2b3pro/roam-research-mcp/reviews","Reviews",5,"review","actionData","errors"]

MCP directory API