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

Tasks: create-outline-mcp-server

1. Entorno de desarrollo (devcontainer)

• 1.1 Crear .devcontainer/devcontainer.json con la imagen mcr.microsoft.com/devcontainers/go:1-trixie
• 1.2 Configurar extensiones del editor (golang.go con gopls) y settings (go.useLanguageServer: true)
• 1.3 Añadir postCreateCommand que instale golangci-lint y ejecute go mod download cuando exista go.mod
• 1.4 Verificar: Given el proyecto abierto en DevPod/Dev Containers, When el contenedor se construye, Then dispone de Go 1.22, gopls y golangci-lint operativos

2. Inicialización del módulo Go

• 2.1 Ejecutar go mod init outline-mcp dentro del contenedor
• 2.2 Instalar dependencias: go get github.com/mark3labs/mcp-go/mcp github.com/mark3labs/mcp-go/server
• 2.3 Instalar la librería de auto-update: go get github.com/minio/selfupdate
• 2.4 Verificar: Given go.mod creado, When se ejecuta go mod tidy, Then no hay errores y go.sum queda generado

3. CLI y esqueleto del servidor MCP

• 3.1 Crear main.go con variables globales inyectables (Version, GiteaURL, RepoOwner, RepoName) y parsing de argumentos (version, update; sin argumentos → servidor MCP)
• 3.2 Implementar el comando version que imprime la versión compilada
• 3.3 Arrancar el servidor MCP con server.NewMCPServer y transporte stdio (ServeStdio)
• 3.4 Verificar: Given el binario compilado con -ldflags -X main.Version=v0.0.1-dev, When se ejecuta version, Then imprime v0.0.1-dev; When se ejecuta sin argumentos, Then el proceso queda a la espera en stdio

4. Cliente HTTP de Outline

• 4.1 Implementar el struct OutlineClient configurado desde OUTLINE_URL y OUTLINE_API_KEY
• 4.2 Implementar método genérico post(ctx, path, payload, result) que serialice JSON, incluya el header Authorization: Bearer <TOKEN> y propague errores HTTP con el mensaje de la API
• 4.3 Verificar: Given OUTLINE_URL/OUTLINE_API_KEY ausentes, When se invoca una herramienta, Then se responde con error descriptivo sin panic

5. Herramientas MCP

• 5.1 Implementar outline_list_collections contra /api/collections.list devolviendo id, name y description
• 5.2 Implementar outline_search contra /api/documents.search con parámetro query
• 5.3 Implementar outline_get_document contra /api/documents.info con parámetro id, devolviendo título y texto en Markdown
• 5.4 Implementar outline_create_document contra /api/documents.create con parámetros title, text y collection_id
• 5.5 Registrar las cuatro herramientas en el servidor MCP con sus esquemas de entrada (mcp.WithString, mcp.Required())
• 5.6 Verificar: Given un cliente MCP conectado por stdio, When se lista tools/list, Then aparecen las cuatro herramientas con sus esquemas; When se invoca outline_search con query sin coincidencias, Then devuelve lista vacía sin error

6. Auto-update

• 6.1 Implementar doUpdate: consulta a {GiteaURL}/api/v1/repos/{RepoOwner}/{RepoName}/releases/latest y manejo de errores de red
• 6.2 Implementar comparación de versiones (parseo de vX.Y.Z frente a Version; fail-safe si el tag no es parseable)
• 6.3 Implementar selección y descarga del asset por convención outline-mcp_{GOOS}_{GOARCH}[.exe] usando runtime.GOOS/runtime.GOARCH
• 6.4 Aplicar el binario descargado con selfupdate.Apply e informar el resultado
• 6.5 Verificar: Given Version igual o superior al tag de Gitea, When se ejecuta update, Then informa que no hay actualizaciones y no modifica el binario; Given la API de Gitea inaccesible, Then finaliza con error sin tocar el binario

7. Pipeline de release (Gitea Actions)

• 7.1 Crear .gitea/workflows/release.yml con trigger on: push: tags: ['v*'] y runner ubuntu-latest
• 7.2 Configurar Go 1.22 en el job (actions/setup-go@v5)
• 7.3 Implementar el build con CGO_ENABLED=0 para linux/amd64, darwin/arm64 y windows/amd64, nombrando los artefactos outline-mcp_{GOOS}_{GOARCH}[.exe] e inyectando -ldflags con Version (desde github.ref_name), GiteaURL, RepoOwner y RepoName (desde el contexto del repo)
• 7.4 Publicar el release en Gitea adjuntando los tres binarios (acción oficial de Gitea o CLI tea release create)
• 7.5 Verificar: Given un push de tag v0.1.0, When el workflow se ejecuta, Then el release queda publicado en Gitea con los tres assets y el comando version del binario publicado reporta v0.1.0