Servidor MCP de Roam Research

Un 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).

Instalación

Puede instalar el paquete globalmente:

npm install -g roam-research-mcp

O clonar el repositorio y compilar desde la fuente:

git clone https://github.com/2b3pro/roam-research-mcp.git
cd roam-research-mcp
npm install
npm run build

Características

El servidor proporciona herramientas potentes para interactuar con Roam Research:

Manejo de variables de entorno con soporte .env
Validación de entrada integral
Coincidencia de títulos de páginas sin distinción entre mayúsculas y minúsculas
Resolución de referencia de bloque recursiva
Análisis y conversión de Markdown
Integración de páginas diarias
Registro de depuración detallado
Operaciones por lotes eficientes
Creación de esquemas jerárquicos

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
roam_create_page : Crea nuevas páginas con contenido opcional
roam_create_block : Crea nuevos bloques en una página (por defecto, la página diaria de hoy)
roam_import_markdown : Importa contenido de Markdown anidado bajo bloques específicos
roam_add_todo : agrega múltiples elementos de tareas pendientes a la página diaria de hoy con sintaxis de casilla de verificación
roam_create_outline : Crea esquemas jerárquicos con anidamiento y estructura adecuados
roam_search_block_refs : busca referencias de bloques dentro de las páginas o en el gráfico
roam_search_hierarchy : Navegar y buscar a través de las relaciones padre-hijo del bloque
roam_find_pages_modified_today : Encuentra todas las páginas que han sido modificadas desde la medianoche de hoy
roam_search_by_text : busca bloques que contengan texto específico en todas las páginas o dentro de una página específica
roam_update_block : Actualiza el contenido del bloque con texto directo o transformaciones basadas en patrones
roam_search_by_date : busca bloques y páginas según las fechas de creación o modificación
roam_search_for_tag : busca bloques que contengan etiquetas específicas con filtrado opcional por etiquetas cercanas
roam_remember : Almacena y categoriza recuerdos o información con etiquetado automático
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
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

Configuración

Crear un token de API de Roam Research :
- Vaya a la configuración de sus gráficos
- 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").
- Crear un nuevo token
Configurar las variables de entorno: Tiene dos opciones para configurar las variables de entorno requeridas:Opción 1: Usar un archivo .env (recomendado para desarrollo) Cree un archivo .env en el directorio roam-research:
ROAM_API_TOKEN=your-api-token ROAM_GRAPH_NAME=your-graph-name MEMORIES_TAG='#[[LLM/Memories]]'
Opción 2: Usar la configuración de MCP (método alternativo) Agregue la configuración a su archivo de configuración de MCP:
- Para Cline ( ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ):
- Para la aplicación de escritorio Claude ( ~/Library/Application Support/Claude/claude_desktop_config.json ):
{ "mcpServers": { "roam-research": { "command": "node", "args": ["/path/to/roam-research-mcp/build/index.js"], "env": { "ROAM_API_TOKEN": "your-api-token", "ROAM_GRAPH_NAME": "your-graph-name", "MEMORIES_TAG": "#[[LLM/Memories]]" } } } }
Nota: El servidor primero intentará cargar desde el archivo .env y luego recurrirá a las variables de entorno de la configuración de MCP.
Construya el servidor (asegúrese de estar en el directorio raíz del MCP):
cd roam-research-mcp npm install npm run build

Uso

Obtener página por título

Obtener y leer el contenido de una página con referencias de bloque resueltas:

use_mcp_tool roam-research roam_fetch_page_by_title {
  "title": "Example Page"
}

Devuelve el contenido de la página como markdown con:

Estructura jerárquica completa
Referencias de bloque resueltas recursivamente (hasta 4 niveles de profundidad)
Sangría adecuada para niveles de anidamiento
Formato de rebajas completo

Crear página

Crear una nueva página con contenido opcional:

use_mcp_tool roam-research roam_create_page {
  "title": "New Page",
  "content": "Initial content for the page"
}

Devuelve el UID de la página creada en caso de éxito.

Crear bloque

Agregar 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):

use_mcp_tool roam-research roam_create_block {
  "content": "Block content",
  "page_uid": "optional-target-page-uid",
  "title": "optional-target-page-title"
}

Puede especificar:

page_uid : Referencia directa a la página de destino
title : Nombre de la página de destino (se creará si no existe)
Ninguno: Se agregará un bloque a la página diaria de hoy.

Devoluciones:

{
  "success": true,
  "block_uid": "created-block-uid",
  "parent_uid": "parent-page-uid"
}

Crear esquema

Crear un esquema jerárquico con anidación y estructura adecuadas:

use_mcp_tool roam-research roam_create_outline {
  "outline": [
    {
      "text": "I. Top Level",
      "level": 1
    },
    {
      "text": "A. Second Level",
      "level": 2
    },
    {
      "text": "1. Third Level",
      "level": 3
    }
  ],
  "page_title_uid": "optional-target-page",
  "block_text_uid": "optional-header-text"
}

Características:

Cree contornos complejos con hasta 10 niveles de anidamiento
Validar la estructura y el contenido del esquema
Mantener relaciones adecuadas entre padres e hijos
Bloque de encabezado opcional para el esquema
El valor predeterminado es la página diaria de hoy si no se especifica ninguna página
Operaciones por lotes eficientes para crear bloques

Parámetros:

outline : Matriz de elementos de esquema, cada uno con:
- text : Contenido del elemento del esquema (obligatorio)
- level : Nivel de anidamiento (1-10, obligatorio)
page_title_uid : Título de la página de destino o UID (opcional, el valor predeterminado es la página de hoy)
block_text_uid : Texto de encabezado para el esquema (opcional)

Devoluciones:

{
  "success": true,
  "page_uid": "target-page-uid",
  "parent_uid": "header-block-uid",
  "created_uids": ["uid1", "uid2", ...]
}

Agregar elementos de tareas pendientes

Agregue uno o más elementos de tareas pendientes a la página diaria de hoy:

use_mcp_tool roam-research roam_add_todo {
  "todos": [
    "First todo item",
    "Second todo item",
    "Third todo item"
  ]
}

Características:

Agrega todos con sintaxis de casilla de verificación Roam ( {{TODO}} todo text )
Admite agregar varias tareas pendientes en una sola operación
Utiliza acciones por lotes para lograr eficiencia al agregar más de 10 tareas pendientes
Crea automáticamente la página de hoy si no existe
Agrega tareas pendientes como bloques de nivel superior en orden secuencial

Importar Markdown anidado

Importar contenido de Markdown anidado bajo un bloque específico:

use_mcp_tool roam-research roam_import_markdown {
  "content": "- Item 1\n  - Subitem A\n  - Subitem B\n- Item 2",
  "page_uid": "optional-page-uid",
  "page_title": "optional-page-title",
  "parent_uid": "optional-parent-block-uid",
  "parent_string": "optional-exact-block-content",
  "order": "first"
}

Características:

Importar contenido bajo bloques específicos:
- Buscar bloque padre por UID o coincidencia exacta de cadena
- Localizar bloques dentro de páginas específicas por título o UID
- Se establece como predeterminado la página de hoy si no se especifica ninguna página
Controlar la ubicación del contenido:
- Agregar como primer o último hijo del bloque padre
- Preservar la estructura jerárquica
- Operaciones por lotes eficientes para contenido anidado
Valor de retorno integral:
{ "success": true, "page_uid": "target-page-uid", "parent_uid": "parent-block-uid", "created_uids": ["uid1", "uid2", ...] }

Parámetros:

content : Contenido de rebajas anidado para importar
page_uid : UID de la página que contiene el bloque padre
page_title : Título de la página que contiene el bloque padre (se ignora si se proporciona page_uid)
parent_uid : UID del bloque padre bajo el cual se agregará contenido
parent_string : contenido exacto de la cadena del bloque padre (debe proporcionar page_uid o page_title)
order : Dónde agregar el contenido ("primero" o "último", predeterminado "primero")

Referencias del bloque de búsqueda

Busque referencias de bloques dentro de las páginas o en todo el gráfico:

use_mcp_tool roam-research roam_search_block_refs {
  "block_uid": "optional-block-uid",
  "page_title_uid": "optional-page-title-or-uid"
}

Características:

Encuentra todas las referencias a un bloque específico
Busque cualquier referencia de bloque dentro de una página
Buscar en todo el gráfico
Admite referencias tanto directas como indirectas
Incluye contenido de bloque y contexto de ubicación.

Parámetros:

block_uid : UID del bloque al que se buscarán referencias (opcional)
page_title_uid : Título o UID de la página donde buscar (opcional)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "block_uid": "referenced-block-uid",
      "content": "Block content with ((reference))",
      "page_title": "Page containing reference"
    }
  ],
  "message": "Found N block(s) referencing..."
}

Buscar por texto

Busque bloques que contengan texto específico en todas las páginas o dentro de una página específica:

use_mcp_tool roam-research roam_search_by_text {
  "text": "search text",
  "page_title_uid": "optional-page-title-or-uid",
  "case_sensitive": true
}

Características:

Busque cualquier texto en todos los bloques del gráfico
Búsqueda opcional en el ámbito de la página
Búsqueda con o sin distinción entre mayúsculas y minúsculas
Devuelve el contenido del bloque con el contexto de la página.
Coincidencia de texto eficiente mediante consultas de registro de datos

Parámetros:

text : El texto a buscar (obligatorio)
page_title_uid : Título o UID de la página donde buscar (opcional)
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)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing search text",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) containing \"search text\""
}

Actualizar el contenido del bloque

Actualice el contenido de un bloque utilizando reemplazo de texto directo o transformaciones basadas en patrones:

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "content": "New block content"
}

O utilice la transformación basada en patrones:

use_mcp_tool roam-research roam_update_block {
  "block_uid": "target-block-uid",
  "transform_pattern": {
    "find": "\\bPython\\b",
    "replace": "[[Python]]",
    "global": true
  }
}

Características:

Dos modos de actualización:
- Reemplazo directo de contenido
- Transformación basada en patrones usando expresiones regulares
Verificar la existencia del bloque antes de actualizar
Devolver contenido actualizado en respuesta
Soporte para reemplazos globales o de un solo partido
Preservar las relaciones de bloques y los metadatos

Parámetros:

block_uid : UID del bloque a actualizar (obligatorio)
content : Nuevo contenido para el bloque (si se usa reemplazo directo)
transform_pattern : Patrón para transformar contenido existente:
- find : Texto o patrón de expresión regular para buscar
- replace : Texto con el que reemplazar
- global : si se deben reemplazar todas las ocurrencias (valor predeterminado: verdadero)

Devoluciones:

{
  "success": true,
  "content": "Updated block content"
}

Buscar etiquetas

Busque bloques que contengan etiquetas específicas con filtrado opcional por etiquetas cercanas:

use_mcp_tool roam-research roam_search_for_tag {
  "primary_tag": "Project/Tasks",
  "page_title_uid": "optional-page-title-or-uid",
  "near_tag": "optional-secondary-tag",
  "case_sensitive": true
}

Características:

Buscar bloques que contengan etiquetas específicas
Filtrado opcional por presencia de otra etiqueta
Búsqueda en el ámbito de la página o en todo el gráfico
Búsqueda con o sin distinción entre mayúsculas y minúsculas
Devuelve el contenido del bloque con el contexto de la página.
Coincidencia eficiente de etiquetas mediante consultas de registro de datos

Parámetros:

primary_tag : La etiqueta principal a buscar (obligatorio)
page_title_uid : Título o UID de la página donde buscar (opcional)
near_tag : Otra etiqueta para filtrar los resultados (opcional)
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)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "block_uid": "matching-block-uid",
      "content": "Block content containing #[[primary_tag]]",
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) referencing \"primary_tag\""
}

Recordar información

Almacene recuerdos o información importante con etiquetado y categorización automáticos:

use_mcp_tool roam-research roam_remember {
  "memory": "Important information to remember",
  "categories": ["Work", "Project/Alpha"]
}

Características:

Almacenar información con la etiqueta #[[LLM/Memories]]
Agregar etiquetas de categoría opcionales para la organización
Se agrega automáticamente a la página diaria de hoy.
Admite múltiples categorías por memoria
Recuperación fácil usando roam_search_for_tag
Mantiene el orden cronológico de los recuerdos.

Parámetros:

memory : La información a recordar (obligatoria)
categories : Matriz opcional de categorías para etiquetar la memoria

Devoluciones:

{
  "success": true,
  "block_uid": "created-block-uid",
  "content": "Memory content with tags"
}

Buscar por fecha

Buscar bloques y páginas según fechas de creación o modificación:

use_mcp_tool roam-research roam_search_by_date {
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "type": "modified",
  "scope": "blocks",
  "include_content": true
}

Características:

Buscar por fecha de creación, fecha de modificación o ambas
Bloques de filtros, páginas o ambos
Rango de fechas opcional con fechas de inicio y finalización
Incluir o excluir contenido de bloque/página en los resultados
Ordenar resultados por marca de tiempo
Filtrado eficiente basado en fechas mediante consultas de registro de datos

Parámetros:

start_date : Fecha de inicio en formato ISO (AAAA-MM-DD) (obligatorio)
end_date : Fecha de finalización en formato ISO (AAAA-MM-DD) (opcional)
type : si desea buscar por 'creado', 'modificado' o 'ambos' (obligatorio)
scope : si se debe buscar 'bloques', 'páginas' o 'ambos' (obligatorio)
include_content : si se debe incluir el contenido de los bloques/páginas coincidentes (opcional, valor predeterminado: verdadero)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "uid": "block-or-page-uid",
      "type": "block",
      "time": 1704067200000,
      "content": "Block or page content",
      "page_title": "Page title (for blocks)"
    }
  ],
  "message": "Found N matches for the given date range and criteria"
}

Encuentra páginas modificadas hoy

Encuentra todas las páginas que han sido modificadas desde la medianoche de hoy:

use_mcp_tool roam-research roam_find_pages_modified_today {}

Características:

Realiza un seguimiento de todas las modificaciones realizadas en las páginas desde la medianoche.
Detecta cambios en cualquier nivel de la jerarquía de bloques.
Devuelve una lista única de títulos de páginas modificados
Incluye recuento de páginas modificadas
No se requieren parámetros

Devoluciones:

{
  "success": true,
  "pages": ["Page 1", "Page 2"],
  "message": "Found 2 page(s) modified today"
}

Ejecutar consultas Datomic

Ejecute consultas de registro de datos personalizadas en su gráfico Roam para recuperación y análisis de datos avanzados:

use_mcp_tool roam-research roam_datomic_query {
  "query": "[:find (count ?p)\n :where [?p :node/title]]",
  "inputs": []
}

Características:

Acceso directo al motor de consultas de Roam
Compatibilidad con todas las funciones de consulta de Datalog:
- Coincidencia de patrones complejos
- Funciones de agregación (contar, suma, máximo, mínimo, promedio, distinto)
- Operaciones con cadenas (¿incluye?, ¿empieza con?, ¿termina con?)
- Operaciones lógicas (<, >, <=, >=, =, not=)
- Reglas para consultas recursivas
Capacidades de búsqueda que distinguen entre mayúsculas y minúsculas y que no lo distinguen entre mayúsculas y minúsculas
Consultas eficientes en todo el gráfico

Parámetros:

query : La consulta del registro de datos que se ejecutará (obligatorio)
inputs : Matriz opcional de parámetros de entrada para la consulta

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "content": "[result data]",
      "block_uid": "",
      "page_title": ""
    }
  ],
  "message": "Query executed successfully. Found N results."
}

Consultas de ejemplo:

Contar todas las páginas:

[:find (count ?p)
 :where [?p :node/title]]

Búsqueda de texto sin distinción entre mayúsculas y minúsculas:

[:find ?string ?title
 :where
 [?b :block/string ?string]
 [(clojure.string/lower-case ?string) ?lower]
 [(clojure.string/includes? ?lower "search term")]
 [?b :block/page ?p]
 [?p :node/title ?title]]

Buscar bloques modificados después de una fecha:

[:find ?block_ref ?string
 :in $ ?start_of_day
 :where
 [?b :edit/time ?time]
 [(> ?time ?start_of_day)]
 [?b :block/uid ?block_ref]
 [?b :block/string ?string]]

Consulte Roam_Research_Datalog_Cheatsheet.md para obtener más ejemplos de consultas y documentación de sintaxis.

Jerarquía del bloque de búsqueda

Navegar y buscar a través de las relaciones padre-hijo del bloque:

use_mcp_tool roam-research roam_search_hierarchy {
  "parent_uid": "optional-parent-block-uid",
  "child_uid": "optional-child-block-uid",
  "page_title_uid": "optional-page-title-or-uid",
  "max_depth": 3
}

Características:

Buscar hacia arriba o hacia abajo en la jerarquía de bloques
Buscar hijos de un bloque específico
Buscar padres de un bloque específico
Configurar la profundidad de búsqueda (1-10 niveles)
Filtrado de alcance de página opcional
Incluye información de profundidad para cada resultado.

Parámetros:

parent_uid : UID del bloque del que se buscarán los hijos (obligatorio si se busca hacia abajo)
child_uid : UID del bloque del que se buscarán los padres (obligatorio si se busca hacia arriba)
page_title_uid : Título o UID de la página donde buscar (opcional)
max_depth : Cuántos niveles de profundidad buscar (opcional, predeterminado: 1, máximo: 10)

Devoluciones:

{
  "success": true,
  "matches": [
    {
      "block_uid": "related-block-uid",
      "content": "Block content",
      "depth": 2,
      "page_title": "Page containing block"
    }
  ],
  "message": "Found N block(s) as children/parents..."
}

Manejo de errores

El servidor proporciona un manejo integral de errores para escenarios comunes:

Errores de configuración:
- Falta el token de API o el nombre del gráfico
- Variables de entorno no válidas
Errores de API:
- Errores de autenticación
- Solicitudes no válidas
- Operaciones fallidas
Errores específicos de la herramienta:
- Página no encontrada (con búsqueda que no distingue entre mayúsculas y minúsculas)
- Bloque no encontrado por coincidencia de cadena
- Formato de rebajas no válido
- Faltan parámetros requeridos
- Estructura o contenido del esquema no válido

Cada respuesta de error incluye:

Código de error MCP estándar
Mensaje de error detallado
Sugerencias de resolución cuando corresponda

Desarrollo

Edificio

Para construir el servidor:

npm install
npm run build

Esto hará lo siguiente:

Instalar todas las dependencias necesarias
Compilar TypeScript a JavaScript
Hacer que el archivo de salida sea ejecutable

También puede utilizar npm run watch durante el desarrollo para recompilar automáticamente cuando los archivos cambian.

Pruebas con MCP Inspector

El Inspector MCP es una herramienta que ayuda a probar y depurar servidores MCP. Para probar el servidor:

# Inspect with npx:
npx @modelcontextprotocol/inspector node build/index.js

Esto hará lo siguiente:

Iniciar el servidor en modo inspector
Proporcionar una interfaz interactiva para:
- Enumere las herramientas y recursos disponibles
- Ejecutar herramientas con parámetros personalizados
- Ver las respuestas de la herramienta y el manejo de errores

Licencia

Licencia MIT

Roam Research

Integrations

Servidor MCP de Roam Research

Instalación

Características

Configuración

Uso

Obtener página por título

Crear página

Crear bloque

Crear esquema

Agregar elementos de tareas pendientes

Importar Markdown anidado

Referencias del bloque de búsqueda

Buscar por texto

Actualizar el contenido del bloque

Buscar etiquetas

Recordar información

Buscar por fecha

Encuentra páginas modificadas hoy

Ejecutar consultas Datomic

Jerarquía del bloque de búsqueda

Manejo de errores

Desarrollo

Edificio

Pruebas con MCP Inspector

Licencia

Tools

Appeared in Searches