configuracion de entorno de desarrollo

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

@@ -0,0 +1,61 @@
+# 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`