brief-desk

One-repo engineering briefing desk: Next.js + CopilotKit (AG-UI) + Python MCP.

Pick a source (auto, GitHub, docs URL, compare, corpus), run the agent, get a cited brief. Free-form chat can call the same MCP tools. Tool cards, a live plan board, and cancel are built into the UI.

Browser
    │
    ├─ Run agent / demos  →  POST /api/brief-run  →  MCP + Groq draft
    └─ Free-form chat     →  CopilotKit → MCP tools
                │
                ▼
         Python MCP (backend/)
           ├── brief_auto / brief_orchestrate
           ├── brief_eval
           ├── brief_fetch_url / brief_web_search
           ├── brief_github_trending / brief_github_search
           ├── brief_repo_* (ask/overview/file/releases/security)
           └── brief_corpus  →  mcp/corpus/*.md

Features

• Deterministic run path (/api/brief-run): gather → draft → eval → revise

• Autonomous auto mode (brief_auto): invents plan from a free-form goal

• Web search (brief_web_search): DuckDuckGo Instant Answer, no API key

• GitHub trending (brief_github_trending): live scrape of github.com/trending

• Repo search (brief_github_search): GitHub Search API shortlists

• Releases + security (brief_repo_releases, brief_repo_security)

• In-chat tool cards for MCP calls on the free-form path

• Live plan board (SSE step events) + Cancel run

• Brief history (reopen / copy / download .md)

• Optional GitHub sign-in (Supabase): syncs history + saved shortcuts across devices; guest mode stays localStorage

• Light / dark / system theme

• Bundled sample corpus under mcp/corpus/ (no separate packages)

Related MCP server: revibe-mcp

Setup

cd brief-desk
cp .env.example .env.local
# OPENAI_API_KEY = Groq key (https://console.groq.com)
npm install
# Python MCP (uv installs deps from backend/pyproject.toml)
cd backend && uv sync && cd ..

Requires uv and Python 3.11+. See CONTRIBUTING.md.

Run

npm run dev

• UI: http://localhost:3000

• Python MCP health: http://127.0.0.1:3108/health (runtime: python, version: 0.10.0)

Docker Compose

cp .env.example .env.local   # set OPENAI_API_KEY
docker compose up --build

Same ports: UI :3000, MCP :3108.

Legacy TypeScript MCP (optional): npm run dev:mcp:ts

Sources

Auto goals like “Brief the npm package zod” also invent source_kind: package. Release deltas use brief_repo_release_diff.

Verify

npm test
curl -s http://127.0.0.1:3108/health
curl -s -X POST http://localhost:3000/api/brief-run \
  -H 'content-type: application/json' \
  -d '{"source":"auto","goal":"Brief facebook/react risks","question":"Brief facebook/react risks"}'

CI runs the same suite on every push/PR (.github/workflows/ci.yml).

Render: deploy with the root Dockerfile (Python MCP). After deploy, /health should show "runtime":"python" and "version":"0.10.0".

Vercel: point MCP_URL at that Render /mcp endpoint.

Optional Supabase sync: create a free project, run supabase/schema.sql, enable the GitHub auth provider (callback URL https://<project>.supabase.co/auth/v1/callback), and set NEXT_PUBLIC_SUPABASE_URL + NEXT_PUBLIC_SUPABASE_ANON_KEY on Vercel. Without those env vars the desk stays guest-only.

Stack

License

MIT. See LICENSE.