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:

O clonar el repositorio y compilar desde la fuente:

Para probar

Ejecutar MCP Inspector después de la compilación…

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

1. 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

2. roam_create_page : Crea nuevas páginas con contenido opcional

3. roam_create_block : Crea nuevos bloques en una página (por defecto, la página diaria de hoy)

4. roam_import_markdown : Importa contenido de Markdown anidado bajo bloques específicos

5. roam_add_todo : agrega múltiples elementos de tareas pendientes a la página diaria de hoy con sintaxis de casilla de verificación

6. roam_create_outline : Crea esquemas jerárquicos con anidamiento y estructura adecuados

7. roam_search_block_refs : busca referencias de bloques dentro de las páginas o en el gráfico

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

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

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

11. roam_update_block : Actualiza el contenido del bloque con texto directo o transformaciones basadas en patrones

12. roam_search_by_date : busca bloques y páginas según las fechas de creación o modificación

13. roam_search_for_tag : busca bloques que contengan etiquetas específicas con filtrado opcional por etiquetas cercanas

14. roam_remember : Almacena y categoriza recuerdos o información con etiquetado automático

15. 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

16. 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

1. 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

2. 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.

3. 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:

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:

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

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:

Crear esquema

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

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:

Agregar elementos de tareas pendientes

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

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:

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:

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:

Buscar por texto

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

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:

Actualizar el contenido del bloque

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

O utilice la transformación basada en patrones:

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:

Buscar etiquetas

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

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:

Recordar información

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

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:

Buscar por fecha

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

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:

Encuentra páginas modificadas hoy

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

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:

Ejecutar consultas Datomic

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

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:

Consultas de ejemplo:

1. Contar todas las páginas:

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

3. Buscar bloques modificados después de una fecha:

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:

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:

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:

Esto hará lo siguiente:

1. Instalar todas las dependencias necesarias

2. Compilar TypeScript a JavaScript

3. 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:

Esto hará lo siguiente:

1. Iniciar el servidor en modo inspector

2. 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