outiline-mcp/openspec/changes/create-outline-mcp-server/specs/outline-api-client/spec.md

Spec: outline-api-client

ADDED Requirements

Requirement: Configuración por variables de entorno

El sistema SHALL configurar el cliente de Outline a partir de las variables de entorno OUTLINE_URL (URL base de la instancia) y OUTLINE_API_KEY (token de API).

Scenario: Cliente configurado correctamente

• WHEN las variables OUTLINE_URL y OUTLINE_API_KEY están definidas en el entorno
• THEN el cliente construye las peticiones contra la URL base indicada y autentica con el token provisto

Scenario: Variables de entorno ausentes

• WHEN OUTLINE_URL o OUTLINE_API_KEY no están definidas al invocar una herramienta
• THEN el sistema responde con un mensaje de error descriptivo indicando la configuración faltante

Requirement: Petición POST genérica autenticada

El cliente HTTP SHALL implementar un método genérico para realizar peticiones POST a los endpoints de la API de Outline, incluyendo el header Authorization: Bearer <TOKEN> y el body en formato JSON.

Scenario: Petición autenticada

• WHEN el cliente envía una petición a cualquier endpoint de la API de Outline
• THEN la petición incluye el header Authorization: Bearer con el token configurado y el payload serializado como JSON

Scenario: Error de la API de Outline

• WHEN la API de Outline responde con un código HTTP de error
• THEN el sistema propaga un error descriptivo (incluyendo el código y el mensaje de la API) hacia el llamador

Requirement: Herramienta outline_list_collections

La herramienta outline_list_collections SHALL invocar el endpoint /api/collections.list y devolver el ID, el nombre y la descripción de cada colección.

Scenario: Listado de colecciones exitoso

• WHEN se invoca outline_list_collections sin parámetros
• THEN la herramienta devuelve la lista de colecciones con sus campos id, name y description

Requirement: Herramienta outline_search

La herramienta outline_search SHALL invocar el endpoint /api/documents.search recibiendo el parámetro query y devolver los resultados de la búsqueda.

Scenario: Búsqueda con resultados

• WHEN se invoca outline_search con un query válido
• THEN la herramienta devuelve los documentos coincidentes con su información relevante (título, id y extracto)

Scenario: Búsqueda sin resultados

• WHEN se invoca outline_search con un query que no coincide con ningún documento
• THEN la herramienta devuelve una lista vacía sin error

Requirement: Herramienta outline_get_document

La herramienta outline_get_document SHALL invocar el endpoint /api/documents.info recibiendo el parámetro id y devolver el título y el texto del documento en formato Markdown.

Scenario: Lectura de documento existente

• WHEN se invoca outline_get_document con el id de un documento existente
• THEN la herramienta devuelve el título del documento y su contenido en Markdown

Scenario: Documento inexistente

• WHEN se invoca outline_get_document con un id que no corresponde a ningún documento
• THEN la herramienta devuelve un error indicando que el documento no fue encontrado

Requirement: Herramienta outline_create_document

La herramienta outline_create_document SHALL invocar el endpoint /api/documents.create recibiendo los parámetros title, text (Markdown) y collection_id, y devolver la información del documento creado.

Scenario: Creación de documento exitosa

• WHEN se invoca outline_create_document con title, text y un collection_id válido
• THEN la herramienta crea el documento en la colección indicada y devuelve su id y title