outiline-mcp/openspec/changes/split-main-into-files/proposal.md

Proposal: split-main-into-files

Why

Todo el código del servidor reside en un único archivo main.go (425 líneas) que mezcla tres responsabilidades sin relación entre sí: el cliente HTTP de Outline, los handlers de tools MCP y el mecanismo de auto-update. La decisión de diseño D2 (arquitectura de un solo archivo) se tomó para facilitar el bootstrap del proyecto; ese objetivo ya se cumplió y la pendiente de crecimiento (cada tool nueva agrega ~35-40 líneas) hará el archivo difícil de mantener y de testear a corto plazo.

What Changes

• Dividir main.go en varios archivos dentro del mismo paquete main (sin introducir paquetes internal/):
  • main.go: únicamente la función main() (wiring del servidor MCP y registro de tools) y las variables inyectadas por -ldflags.
  • client.go: tipo OutlineClient, constructor newOutlineClient y método post.
  • tools.go: los cuatro handlers de tools MCP (handleListCollections, handleSearch, handleGetDocument, handleCreateDocument).
  • updater.go: giteaRelease, parseVersion, versionNewer y doUpdate.
• Se trata de un refactor mecánico: se mueve código, no se modifica. No hay cambios de comportamiento, de API MCP ni de contrato de nombres de assets (outline-mcp_{GOOS}_{GOARCH}).

Capabilities

New Capabilities

• code-structure: Convención de organización del código fuente del proyecto: un paquete main distribuido en archivos por responsabilidad (cliente, tools, updater, entrypoint), manteniendo el carácter deliberado de monolito de paquete único.

Modified Capabilities

(ninguna — no hay cambios a nivel de requisitos de comportamiento)

Impact

• Código: único archivo afectado main.go, que se reparte en 4 archivos nuevos dentro de la raíz del módulo. go.mod y go.sum no cambian.
• Build/release: sin impacto. El pipeline de release (.gitea/workflows/release.yml) compila . y el contrato de nombres de assets no depende de la estructura de archivos.
• Auto-update: sin impacto funcional; doUpdate se traslada íntegro a updater.go.
• Dependencias: no se añaden ni eliminan dependencias.

No objetivos

• No se introducen paquetes internal/ (opción C descartada por ahora; queda como refactor futuro si el número de tools crece significativamente).
• No se añaden tests en este change (la estructura elegida los facilita, pero son alcance de un cambio posterior).
• No se modifica ningún comportamiento observable: protocolo MCP, manejo de errores, variables de entorno ni lógica de actualización.
• No se renombran funciones ni tipos; solo cambian de archivo.