Outline MCP Server

Servidor MCP para la herramienta de gestión de documentos y base de conocimiento Outline.

GitHub
17

Documentación

Outline MCP Server

Un servidor de Model Context Protocol (MCP) para Outline que permite leer y escribir documentos a través de la API de Outline.

Características

  • Leer documentos: Obtener documentos individuales, buscar y listar documentos
  • Escribir documentos: Crear, actualizar y eliminar documentos
  • Gestión de colecciones: Listar y recuperar información de colecciones
  • Búsqueda de texto completo: Buscar en todos los documentos de tu instancia de Outline
  • Soporte de Markdown: Crear y editar documentos con formato Markdown completo

Inicio rápido (npx)

La forma más fácil de usar este servidor es mediante npx — no se requiere clonar ni compilar. Apunta tu cliente MCP directamente a él:

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "getoutline-mcp-server"],
      "env": {
        "OUTLINE_API_KEY": "your-secret-api-token",
        "OUTLINE_BASE_URL": "https://your-outline-instance.com"
      }
    }
  }
}

Consulta Configuración para saber cómo obtener el token de API.

Instalación (desde el código fuente)

Para desarrollo local, o para ejecutar desde el código fuente en lugar de npm:

  1. Clona o descarga este repositorio
  2. Instala las dependencias: 
    npm install
  3. Compila el proyecto: 
    npm run build

Configuración

Antes de usar el servidor, necesitas configurar tus credenciales de la API de Outline:

  1. Obtén tu token de API de Outline:

    • Inicia sesión en tu instancia de Outline (p. ej., https://app.getoutline.com)
    • Ve a Configuración → Tokens de API
    • Crea un nuevo token

  2. Configura las variables de entorno:

    export OUTLINE_BASE_URL="https://your-outline-instance.com"
export OUTLINE_API_KEY="your-api-token-here"

Uso

Ejecutar el servidor

Inicia el servidor MCP:

npm start

El servidor se comunica a través de stdio y es compatible con cualquier cliente MCP.

Herramientas disponibles

Operaciones de documentos

  1. outline_get_document

    • Obtener un documento específico por ID
    • Parámetros: id (cadena, obligatorio)

  2. outline_search_documents

    • Buscar documentos en tu instancia de Outline
    • Parámetros: query (cadena, obligatorio), limit (número, opcional, valor predeterminado: 25)

  3. outline_list_documents

    • Listar documentos, opcionalmente filtrados por colección
    • Parámetros: collectionId (cadena, opcional), limit (número, opcional, valor predeterminado: 25)

  4. outline_create_document

    • Crear un nuevo documento
    • Parámetros:
      • title (cadena, obligatorio)
      • text (cadena, obligatorio) - Contenido Markdown
      • collectionId (cadena, opcional)
      • parentDocumentId (cadena, opcional)
      • publish (booleano, opcional, valor predeterminado: false)

  5. outline_update_document

    • Actualizar un documento existente
    • Parámetros:
      • id (cadena, obligatorio)
      • title (cadena, opcional)
      • text (cadena, opcional) - Contenido Markdown
      • publish (booleano, opcional)

  6. outline_delete_document

    • Eliminar un documento
    • Parámetros: id (cadena, obligatorio)

Operaciones de colecciones

  1. outline_list_collections

    • Listar todas las colecciones de tu instancia de Outline
    • Parámetros: ninguno

  2. outline_get_collection

    • Obtener información sobre una colección específica
    • Parámetros: id (cadena, obligatorio)

Ejemplo de uso

Aquí hay algunos ejemplos de llamadas a herramientas:

{
  "name": "outline_search_documents",
  "arguments": {
    "query": "project documentation",
    "limit": 10
  }
}

{
  "name": "outline_create_document",
  "arguments": {
    "title": "New Project Plan",
    "text": "# Project Overview\n\nThis document outlines...",
    "collectionId": "collection-id-here",
    "publish": true
  }
}

{
  "name": "outline_update_document",
  "arguments": {
    "id": "document-id-here",
    "title": "Updated Project Plan",
    "text": "# Updated Project Overview\n\nThis document has been updated..."
  }
}

Desarrollo

Estructura del proyecto

src/
├── index.ts           # Main MCP server implementation
├── outline-client.ts  # Outline API client

Scripts

  • npm run build - Compilar TypeScript a JavaScript
  • npm run dev - Compilar y ejecutar el servidor
  • npm run watch - Observar cambios y recompilar
  • npm start - Ejecutar el servidor compilado

Compilación

npm run build

El JavaScript compilado se generará en el directorio dist/.

Configuración con clientes MCP

Para usar este servidor con un cliente MCP, deberás configurarlo para que ejecute este servidor. La configuración exacta depende de tu cliente, pero en general necesitarás:

  1. Especificar el comando a ejecutar: node /path/to/outline-mcp-server/dist/index.js
  2. Configurar las variables de entorno para tu instancia de Outline
  3. Configurar el cliente para usar transporte stdio

Ejemplos de configuración de clientes

Claude

Para clientes como Claude que usan un archivo de configuración JSON, agrega lo siguiente a tu mcp-servers.json. El enfoque recomendado usa npx, por lo que no hay nada que clonar ni compilar:

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": ["-y", "getoutline-mcp-server"],
      "env": {
        "OUTLINE_API_KEY": "your-secret-api-token",
        "OUTLINE_BASE_URL": "https://your-outline-instance.com"
      }
    }
  }
}
Alternativa: ejecutar desde el código fuente

Si has clonado y compilado el proyecto localmente, apunta el cliente al dist/index.js compilado en su lugar:

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/your/projects/outline-mcp-server/dist/index.js"],
      "env": {
        "OUTLINE_API_KEY": "your-secret-api-token",
        "OUTLINE_BASE_URL": "https://your-outline-instance.com"
      }
    }
  }
}

Asegúrate de reemplazar la ruta args con la ruta absoluta al archivo index.js en tu proyecto, y completa tus credenciales reales en el bloque env.

Cursor

Para clientes como Cursor, normalmente puedes configurar las variables de entorno directamente en la configuración del cliente o iniciando el cliente desde una terminal donde ya hayas exportado las variables.

export OUTLINE_BASE_URL="https://your-outline-instance.com"
export OUTLINE_API_KEY="your-secret-api-token"

# Then launch Cursor from this terminal
/path/to/Cursor.app/Contents/MacOS/Cursor

Límites de velocidad de la API

Ten en cuenta que Outline puede tener límites de velocidad de API. El servidor no implementa limitación de velocidad internamente, por lo que es posible que debas gestionarlo a nivel del cliente si realizas muchas solicitudes.

Manejo de errores

El servidor incluye un manejo integral de errores y devolverá mensajes de error descriptivos para problemas comunes como:

  • Credenciales de API faltantes o no válidas
  • Problemas de conectividad de red
  • IDs de documentos no válidos
  • Errores de límite de velocidad de la API

Notas de seguridad

  • Almacena tu token de API de forma segura usando variables de entorno
  • Nunca subas tu token de API al control de versiones
  • Considera usar tokens de API restringidos con los permisos mínimos necesarios
  • Ten precaución al permitir que otros usen tu servidor MCP, ya que tiene acceso completo a tu instancia de Outline

Licencia

Licencia MIT: consulta el archivo LICENSE para obtener más detalles.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar problemas (issues) y solicitudes de extracción (pull requests).