asepharyana
1dd16ebcba
- Install rehype-slug (proper heading anchors) + github-slugger (matching TOC) - TOC component: auto-generated from h2/h3 headings, clickable anchors - Dark mode toggle: ThemeToggle (localStorage + system default), class-based - /docs index page (lists all docs by section) - Markdown.tsx uses rehype-slug for stable heading ids - globals.css: @custom-variant dark (.dark class) for class-based dark mode - layout.tsx: nav includes ThemeToggle Note: per user instruction, installed real deps (rehype-slug, github-slugger, @types/hast) instead of hacky inline any-cast hacks.
68 lines
3.7 KiB
Markdown
68 lines
3.7 KiB
Markdown
# MCPedia Phase 11 — CRUD + Auth + UI/UX Improvement
|
|
|
|
## Plan (spec BEFORE implementation, per user rule)
|
|
|
|
### Scope: 4 areas
|
|
1. **CRUD**: Create/Read/Update/Delete documents from web UI + MCP
|
|
2. **Auth**: Session-based auth for web edits; API key auth for MCP writes
|
|
3. **UI/UX**: Polish doc page, edit forms, search UX, dark mode
|
|
4. **Agent integration**: MCP tools for CRUD with auth
|
|
|
|
## Requirements:
|
|
1. **Source of truth is the filesystem** — each doc is a markdown file under `content/{section}/{slug}.md` with YAML frontmatter (parsed/striped by gray-matter).
|
|
2. **DB mirrors disk** — `documents` table has slug/title/section/body/status/tags/etc; `document_chunks` stores embeddings; `document_revisions` snapshots body+meta.
|
|
3. **Single indexing path** — `indexContentFile` in `@mcpedia/core` writes DB + revisions + chunks; CRUD ops call it (or its pieces) after writing the file.
|
|
4. **Auth** — MCP/API writes require `x-webhook-secret` matching `WEBHOOK_SECRET` (Phase 4 pattern). Web CRUD uses cookie-based auth (Phase 11 addition: `ADMIN_PASSWORD`).
|
|
5. **Slug rules** — `[a-z0-9][a-z0-9/_-]*`, no `//`, no path traversal (`..`). The slug in the URL is `<section>/<slug-parts>`.
|
|
6. **No breaking existing features** — read tools/routes unchanged; existing 32 tests still green.
|
|
7. **UI/UX** — edit button on doc pages (auth-gated), `?edit=1` inline form, `/create` page, login page, table of contents auto-generated from h2, dark mode toggle.
|
|
|
|
### Schema changes:
|
|
- Optional: `users` table if auth is user-based
|
|
- OR: simple `WEB_AUTH_TOKEN` env for admin access (simpler, fits single-author KB)
|
|
|
|
### Backend surface:
|
|
- **Web auth**: Cookie-based session OR single admin token in localStorage
|
|
- Simpler approach: `POST /api/auth/login` (checks `ADMIN_PASSWORD` env) → sets cookie
|
|
- Edit UI gated behind cookie check in server components
|
|
- **MCP auth**: `x-api-key` header for write tools (create/update/delete)
|
|
- Read tools (list, get, search) — public
|
|
- Write tools (create, update, delete, index_document, reindex_all, restore_revision) — require key
|
|
- `createMcpServer(authKey?)` threads the header, same pattern as `x-webhook-secret`
|
|
|
|
### CRUD operations:
|
|
- **Create**: `POST /trpc/createDocument` (title, slug, section, body, tags)
|
|
- Writes markdown file to `content/{section}/{slug}.md`
|
|
- Triggers indexer (enqueues job or calls directly)
|
|
- **Update**: `POST /trpc/updateDocument` (slug, body, title, tags, status)
|
|
- Updates file + creates revision + reindexes
|
|
- **Delete**: `POST /trpc/deleteDocument` (slug)
|
|
- Removes file, DB rows, chunks; creates revision tombstone
|
|
- All mutations require auth (web cookie OR webhook secret OR MCP api-key)
|
|
|
|
### UI improvements:
|
|
- Edit button on doc pages (auth-gated) → link to `/docs/{slug}/edit`
|
|
- Create page: `/docs/create` with form (section dropdown, slug, title, tags, markdown editor)
|
|
- Edit page: `/docs/{slug}/edit` pre-fills from getDocument
|
|
- Search page: live search results with keyboard nav, better empty states
|
|
- Doc page: table of contents (auto-generated from h2), dark mode toggle
|
|
|
|
### Verification steps:
|
|
1. TDD: write failing tests for each new API endpoint/method first
|
|
2. `bun run typecheck` — green
|
|
3. `bun run test` — 32 existing + new tests green
|
|
4. `bun run build` — green
|
|
5. CI + Deploy passes
|
|
6. Browser: create doc → search sees it → edit doc → changes reflect → delete doc → gone
|
|
7. MCP: create_document tool with key → doc appears; without key → unauthorized
|
|
|
|
### Acceptance criteria:
|
|
- [ ] createDocument tRPC + MCP
|
|
- [ ] updateDocument tRPC + MCP
|
|
- [ ] deleteDocument tRPC + MCP
|
|
- [ ] Web auth (cookie-based login)
|
|
- [ ] MCP write-tool auth (api-key)
|
|
- [ ] UI: edit/create pages
|
|
- [ ] UI: TOC + dark mode on doc pages
|
|
- [ ] All tests green, CI+Deploy passes
|