AGENTS.md

Ejecución de comandos Go — OBLIGATORIO vía Docker

No hay Go ni agentes instalados en el host (macOS). Todos los comandos Go/lint/build se ejecutan dentro del contenedor DevPod:

# Resolver el nombre del contenedor (es auto-generado, puede cambiar):
docker ps --filter ancestor=mcr.microsoft.com/devcontainers/go --format '{{.Names}}'

# Ejecutar comandos dentro (workspace montado en /workspaces/outline-mcp):
docker exec <container> sh -c "cd /workspaces/outline-mcp && go build -o outline-mcp ./src"

El nombre actual es great_jang, pero NO asumirlo: resolverlo con docker ps cada sesión.
Las ediciones de archivos se hacen en el host (ruta normal del repo); solo la ejecución va por docker exec.
openspec CLI se ejecuta en el host (no está en el contenedor).

Toolchain

Go 1.26 (imagen mcr.microsoft.com/devcontainers/go:1-trixie). NO bajar a 1.22: mcp-go v1.0.0 requiere Go ≥ 1.25.5.
golangci-lint v2 solo dentro del contenedor.
Módulo: outline-mcp. Código en src/ (package main): main.go (entrypoint + registro de tools), client.go, tools.go, updater.go.

Build y verificación

# Dentro del contenedor:
go build -o outline-mcp ./src
go build -ldflags "-X main.Version=v0.0.1-dev -X main.GiteaURL=https://gitea.example.com -X main.RepoOwner=owner -X main.RepoName=outline-mcp" -o outline-mcp ./src
golangci-lint run ./src/...
# Ver tools/list del servidor MCP (handshake + listing por stdio):
printf '{"jsonrpc":"2.0","id":1,"method":"initialize",...}' | ./outline-mcp

Sin tests aún; verificación = go build + golangci-lint run + prueba manual por stdio.

Contrato crítico: nombres de assets

El pipeline de release (.gitea/workflows/release.yml) y el auto-update (doUpdate en main.go) comparten un contrato implícito: los assets DEBEN llamarse outline-mcp_{GOOS}_{GOARCH} (con .exe para windows). Cambiar una parte rompe la otra.

Convenciones del repo

Artefactos OpenSpec (openspec/changes/*/) en español, tono formal; tasks con formato Given/When/Than (regla de openspec/config.yaml).
Flujo: openspec new change → proposal → specs → design → tasks → implementar marcando checkboxes en tasks.md.
Errores de configuración (OUTLINE_URL, OUTLINE_API_KEY) se devuelven como resultado MCP de error, nunca panic.
La API key de Outline nunca se loguea.

2.4 KiB Raw Permalink Blame History