outiline-mcp/openspec/changes/create-outline-mcp-server/proposal.md

Proposal: create-outline-mcp-server

Why

El equipo necesita que los asistentes de IA (clientes MCP) puedan consultar y crear contenido en nuestra instancia self-hosted de Outline de forma segura y estructurada. Actualmente no existe ningún servidor MCP para Outline en el ecosistema interno, por lo que es necesario construirlo desde cero en Go, con un entorno de desarrollo reproducible en contenedores y una cadena de distribución (releases binarios) basada en Gitea Actions.

What Changes

• Creación de un proyecto Go nuevo (outline-mcp) que implementa un servidor MCP con transporte stdio.
• CLI básica con comandos version y update; sin argumentos arranca el servidor MCP.
• Cliente HTTP (OutlineClient) para la API de Outline, autenticado mediante OUTLINE_URL y OUTLINE_API_KEY.
• Cuatro herramientas MCP: outline_list_collections, outline_search, outline_get_document y outline_create_document.
• Mecanismo de auto-actualización que consulta la última release de Gitea y aplica el binario correspondiente al SO/arquitectura actual.
• Entorno de desarrollo en contenedor (.devcontainer/devcontainer.json) con imagen oficial de Go 1.22, gopls y golangci-lint.
• Pipeline de CI/CD en Gitea Actions (.gitea/workflows/release.yml) que compila binarios estáticos para linux/amd64, darwin/arm64 y windows/amd64 y publica releases al pushear tags v*.

Capabilities

New Capabilities

• mcp-server: Servidor MCP en Go con transporte stdio, CLI básica (version, update) e inyección de metadatos de build mediante -ldflags.
• outline-api-client: Cliente HTTP para la API de Outline con autenticación Bearer y las cuatro herramientas MCP sobre colecciones y documentos.
• self-update: Actualización automática del binario comparando la versión actual con el último tag de release en Gitea y aplicando el asset compatible con GOOS/GOARCH.
• release-pipeline: Pipeline de Gitea Actions que compila binarios estáticos multi-plataforma y publica releases en Gitea.
• dev-environment: Entorno de desarrollo en contenedor (devcontainer) con tooling de Go preconfigurado.

Modified Capabilities

(ninguna — el proyecto se crea desde cero)

No objetivos

• No se implementará transporte HTTP/SSE para el servidor MCP; solo stdio.
• No se gestionarán operaciones avanzadas de Outline (eliminar/actualizar documentos, gestionar permisos, comentarios, attachments).
• No se implementará autenticación OAuth del servidor MCP hacia los clientes; la seguridad se apoya en la API key de Outline vía entorno.
• No se configurará firma de binarios ni notarización (macOS/Windows).
• No se incluirá despliegue continuo ni instalación automática en servidores; solo publicación de releases.
• No se desarrollará test suite de integración contra una instancia real de Outline.

Impact

• Código: archivos nuevos en la raíz del repo (main.go, go.mod, go.sum, .devcontainer/devcontainer.json, .gitea/workflows/release.yml).
• Dependencias Go: github.com/mark3labs/mcp-go (SDK MCP), github.com/minio/selfupdate (auto-update).
• APIs externas: API REST de Outline (/api/collections.list, /api/documents.search, /api/documents.info, /api/documents.create) y API de releases de Gitea (/api/v1/repos/{owner}/{repo}/releases/latest).
• Infraestructura: requiere Gitea con Actions habilitadas y un repositorio con registro de releases; el desarrollo no requiere Go local (contenedor).