reporter

A home for AI agent reports. Agents push Markdown reports over MCP (Streamable HTTP with token auth); humans browse, search, tag, update and share them through a React UI.

• Private by default — reports are visible to their owner (or team) and admins.
• Shareable — any report can be enabled for public access via a tokenized link (/share/<token>); everyone with the link can view it.
• Taggable & searchable — tags on upload or afterwards, full-text search over title/content/agent, time buckets (YYYY-MM-DD / YYYY-MM) for grouping.
• Agent-provided ids & revisions — agents key reports by a stable agent_id and update in place; every content change is stored as a revision (internal, not exposed via API in v1).

Architecture

reporter (single Go binary, PocketBase embedded)
├── REST API      /api/...        (UI auth: PocketBase email+password JWT)
├── MCP endpoint  POST /mcp       (agent auth: Bearer rpt_... tokens)
├── Share API     GET /api/share/{token}  (public)
├── SPA           /               (React build served with index fallback)
└── PocketBase    SQLite in DATA_DIR (users, teams, reports, revisions,
                     mcp_tokens; Go migrations; default admin & user seeded)

Piece	Tech
Backend	Go 1.27, PocketBase v0.40.x as a library (custom app), DDD layout (domain/, application/, infrastructure/, config/, utils/)
MCP	mark3labs/mcp-go v1, stateless Streamable HTTP
Frontend	React 19 + TypeScript + Vite + Tailwind v4, bun, DDD-ish layout
Auth (UI)	PocketBase users (email + password). Azure AD OAuth2 is a documented extension point, not yet implemented.
Auth (MCP)	rpt_ tokens in the mcp_tokens collection (SHA-256 stored); user- or team-scoped

Docs: docs/api.md (REST + MCP contract), docs/backend-spec.md, docs/frontend-spec.md.

MCP tools (for agents)

Tool	Purpose
create_report	Create a report keyed by agent-provided agent_id
update_report	Update the existing report with the same agent_id
get_report	Fetch one report by agent_id
list_reports	Search / filter / list visible reports

Client config (get a token under Agent access in the UI):

{
  "mcpServers": {
    "reporter": {
      "url": "https://reports.barbara8.de/mcp",
      "headers": { "Authorization": "Bearer rpt_..." }
    }
  }
}

Development

mise install                 # go 1.27.1 + bun 1.4.2
cd backend && go mod download && go test ./...
cd ../frontend && bun install && bun run dev   # proxies /api + /mcp to :8080

Run the backend locally:

cd backend
DATA_DIR=./pb_data WEB_DIR=../frontend/dist \
ADMIN_EMAIL=admin@local ADMIN_PASSWORD=changeme \
USER_EMAIL=user@local USER_PASSWORD=changeme \
go run ./cmd/server serve --http 0.0.0.0:8080

Deployment

Single image (docker/Dockerfile: Go build + bun SPA build → one binary serving everything) deployed as the Dockhand stack reporter on UM890 (env 3) by the Forgejo Actions pipeline (.forgejo/workflows/ci.yml): build & test on PR/push → image push on main/develop → Dockhand two-step deploy on main. Public at https://reports.barbara8.de (Caddy ingress, Pattern A labels).

Runtime secrets live as Dockhand stack secrets (never in git/CI): ADMIN_PASSWORD, USER_PASSWORD (seeded once out-of-band; the app seeds admin@barbara8.de / user@barbara8.de on first boot and never overwrites existing users).

Repos layout

backend/   Go service (DDD: domain/application/infrastructure/config/utils)
frontend/  React SPA (DDD-ish: domain/infrastructure/application/presentation)
docker/    Dockerfile, compose (Dockhand source of truth), deploy.ts
docs/      API contract + implementation specs