refactor: finish the AgentHub rename and drop the MCP server
Two leftovers from the rebrand, done together because they touch the same docs and manifests. **Data directory.** `agent-dashboard` could not simply be renamed in the source: it names a real directory holding the live SQLite database. Startup now moves it once, via `migrateLegacyDataDir()` in `server/lib/claude-home.js` — a same-filesystem rename, so it is instant even at multiple gigabytes and cannot leave two divergent copies. `getDataDir()` stays PURE and resolves to the legacy path until the move happens; the first version of this put the rename inside the getter, which meant `npm run test:server` relocated the developer's real database as a side effect. The call sits behind `require.main === module` and ahead of the router requires, because those pull in db.js, which opens SQLite at module load. A failed rename is silent and the old directory keeps being used: an unfashionable directory name beats a blank database beside an unreachable one. Same treatment for the port-discovery file (`.agent-dashboard.json` → `.agenthub.json`, old one dropped on write). Not renamed on purpose: the Sagi localStorage keys (renaming silently resets everyone's prefs) and the PWA manifest `id` (changing it orphans an installed app). **MCP server.** 4 tool calls in 46 days across 577,132 events, against 4,556 lines of TypeScript, a 2 MB committed build artifact, and a pre-commit guard that had already blocked commits twice. Deleted: `mcp/`, the maintainer skills and `mcp-reviewer` agent, the build check, `plugins/agenthub/.mcp.json`, `docs/MCP.md`, 12 npm scripts, 5 Makefile targets, and every doc section describing it. Kept, because they are unrelated things sharing the name: the Config Explorer's MCP tab and its API, per-lane Playwright MCP, the agenthub-config plugin's MCP audit, and the historical `mcp__plugin_agenthub_*` events that analytics must keep attributing. Verified: server 1432/1432, client 459/459, tsc clean, prettier clean. Both directions of the migration proven — a sandbox-HOME test run leaves the legacy directory untouched, and a real boot moves it with its contents intact.
This commit is contained in:
@@ -24,7 +24,7 @@ that is missing the header, add it as part of the same change.
|
||||
| -------- | -------- |
|
||||
| `*.js`, `*.ts`, `*.tsx`, `*.cjs`, `*.mjs` | anything under `node_modules/`, `dist/`, `build/`, `data/` |
|
||||
| `*.py`, `*.sh` | vendored/minified files (`*.min.js`) |
|
||||
| `*.css` | generated files (they carry their own AUTO-GENERATED banner), including the committed `mcp/build/` |
|
||||
| `*.css` | generated files (they carry their own AUTO-GENERATED banner) |
|
||||
| | snapshots (`__snapshots__/`), lockfiles, JSON/YAML/Markdown |
|
||||
| | anything **gitignored** — local runtime state that happens to live in the checkout (a lane's own `.agenthub/profile/hooks/*.sh`, a scratch venv) is not this repo's source and can never be made compliant here |
|
||||
|
||||
|
||||
@@ -10,8 +10,7 @@
|
||||
# differs per machine, and can never be made compliant here. Untracked files
|
||||
# are still audited, so a file an agent just wrote is caught before it is
|
||||
# staged. The extra excludes below are for paths git DOES track (or would list)
|
||||
# but the rule exempts — notably `mcp/build/`, which is committed on purpose
|
||||
# (plugin MCP servers start before anything could build them) yet is still
|
||||
# but the rule exempts — notably generated bundles, which are still
|
||||
# generated tsc output, and snapshots.
|
||||
# @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
|
||||
|
||||
@@ -1,27 +0,0 @@
|
||||
---
|
||||
name: mcp-operations
|
||||
description: Operate and maintain the local MCP server for this project. Use when creating MCP host config, troubleshooting tool connectivity, modifying tool domains, or adjusting safety policy flags.
|
||||
---
|
||||
|
||||
# MCP Operations
|
||||
|
||||
Use this skill whenever work touches `mcp/` behavior or MCP host integration.
|
||||
|
||||
## Core workflow
|
||||
- Confirm dashboard API is running (`/api/health`).
|
||||
- Confirm MCP server build status.
|
||||
- Validate env flags for mutation/destructive modes.
|
||||
- Verify host configuration path and command.
|
||||
|
||||
## Safe operations policy
|
||||
- Default to read-only mode (`MCP_DASHBOARD_ALLOW_MUTATIONS=false`).
|
||||
- Enable mutations only for explicit admin tasks.
|
||||
- Enable destructive mode only transiently and require explicit confirmation token.
|
||||
|
||||
## Required verification for code changes
|
||||
- `npm run mcp:typecheck`
|
||||
- `npm run mcp:build`
|
||||
|
||||
## References
|
||||
- Host config examples: `references/host-config.md`
|
||||
- Operations runbook: `references/runbook.md`
|
||||
@@ -1,18 +0,0 @@
|
||||
# MCP Host Config
|
||||
|
||||
## Command
|
||||
- `node`
|
||||
|
||||
## Args
|
||||
- Absolute path to `mcp/build/index.js`
|
||||
|
||||
## Example env
|
||||
- `MCP_DASHBOARD_BASE_URL=http://127.0.0.1:4820`
|
||||
- `MCP_DASHBOARD_ALLOW_MUTATIONS=false`
|
||||
- `MCP_DASHBOARD_ALLOW_DESTRUCTIVE=false`
|
||||
- `MCP_LOG_LEVEL=info`
|
||||
|
||||
## Common mistakes
|
||||
- Relative path to MCP build entry.
|
||||
- Dashboard not running while MCP starts.
|
||||
- Mutating tools used while mutation flag is false.
|
||||
@@ -1,19 +0,0 @@
|
||||
# MCP Runbook
|
||||
|
||||
## Read-only daily mode
|
||||
- Keep both mutation flags false.
|
||||
- Use read tools for observability and reporting.
|
||||
|
||||
## Admin mode
|
||||
- Set `MCP_DASHBOARD_ALLOW_MUTATIONS=true`.
|
||||
- Run maintenance/pricing operations.
|
||||
- Reset mutation flag to false after completion.
|
||||
|
||||
## Destructive mode
|
||||
- Set both mutation and destructive flags true.
|
||||
- Execute destructive command only with explicit confirmation token.
|
||||
- Immediately disable destructive flag after operation.
|
||||
|
||||
## Verification commands
|
||||
- `npm run mcp:typecheck`
|
||||
- `npm run mcp:build`
|
||||
@@ -12,14 +12,12 @@ Use this workflow when a task begins with discovery.
|
||||
- Identify target layer:
|
||||
- `server/` for API, hooks, DB, websocket
|
||||
- `client/` for UI and routing
|
||||
- `mcp/` for local MCP tools and policy gates
|
||||
- Select the smallest set of files required to answer the task.
|
||||
- Confirm verification commands before implementation.
|
||||
|
||||
## Verification defaults
|
||||
- Backend: `npm run test:server`
|
||||
- Frontend: `npm run test:client`
|
||||
- MCP: `npm run mcp:typecheck` and `npm run mcp:build`
|
||||
|
||||
## References
|
||||
- Module map: `references/module-map.md`
|
||||
|
||||
@@ -11,15 +11,3 @@
|
||||
- `npm run import-history`
|
||||
- `npm run clear-data`
|
||||
|
||||
## MCP helper commands (root)
|
||||
- `npm run mcp:install`
|
||||
- `npm run mcp:build`
|
||||
- `npm run mcp:start`
|
||||
- `npm run mcp:dev`
|
||||
- `npm run mcp:typecheck`
|
||||
|
||||
## Direct MCP package commands
|
||||
- `npm --prefix mcp install`
|
||||
- `npm --prefix mcp run build`
|
||||
- `npm --prefix mcp run start`
|
||||
- `npm --prefix mcp run typecheck`
|
||||
|
||||
@@ -13,8 +13,3 @@
|
||||
- `client/src/hooks/useWebSocket.ts`: live update pipeline.
|
||||
|
||||
## MCP
|
||||
- `mcp/src/index.ts`: runtime entrypoint.
|
||||
- `mcp/src/server.ts`: MCP assembly.
|
||||
- `mcp/src/tools/domains/`: domain tool registration.
|
||||
- `mcp/src/clients/dashboard-api-client.ts`: resilient API bridge.
|
||||
- `mcp/src/policy/tool-guards.ts`: mutation/destructive gates.
|
||||
|
||||
@@ -127,13 +127,12 @@ The e2e hook doesn't run migrations itself — it tests the already-running stac
|
||||
- `agenthub stage review --status running`, then launch a fresh-context reviewer agent (Agent tool, `subagent_type: Code Reviewer` — FOREGROUND, **never `fork`**; a reviewer who already watched you write the code is not a reviewer). Hand it ONLY: the lane's working directory, the lane spec path (requirement + acceptance criteria), the diff commands, and the brief below. Do NOT summarize your own implementation for it, and do NOT pre-empt findings — let it read the diff cold.
|
||||
- Run the **`code-review` skill at effort `high`** on the feature diff vs `origin/development` — the deterministic gate, not an ad-hoc read. No PR is open yet, so point it at the local diff: `git diff origin/development...feat/<slug>` (and `git log origin/development..feat/<slug>` for commits). ONLY if the `code-review` skill is unavailable in its session, fall back to a manual review of that diff (correctness, security, tests, migration/contract safety, this repo's `CLAUDE.md` + `.claude/rules/` boundaries).
|
||||
- Final line: `REVIEW: CLEAN` or `REVIEW: FINDINGS — <n>`, with the findings listed above it as `path:line — severity — problem — suggested fix`.
|
||||
- **Domain reviewers, in parallel with the above (same message, separate Agent calls).** Check `git diff --name-only origin/development...feat/<slug>` for touched layers and launch every matching one — FOREGROUND, fresh context, **never `fork`**, addressed as `agenthub:backend-reviewer` / `agenthub:frontend-reviewer` / `agenthub:mcp-reviewer` (plugin-qualified — no lane install needed, unlike `qc-local`/`senior-gate-reviewer`):
|
||||
- **Domain reviewers, in parallel with the above (same message, separate Agent calls).** Check `git diff --name-only origin/development...feat/<slug>` for touched layers and launch every matching one — FOREGROUND, fresh context, **never `fork`**, addressed as `agenthub:backend-reviewer` / `agenthub:frontend-reviewer` (plugin-qualified — no lane install needed, unlike `qc-local`/`senior-gate-reviewer`):
|
||||
- Any path under `server/` → `agenthub:backend-reviewer`.
|
||||
- Any path under `client/` → `agenthub:frontend-reviewer`.
|
||||
- Any path under `mcp/` → `agenthub:mcp-reviewer`.
|
||||
- None of those three touched (root/`skills/`/`agents/`/`scripts/`/docs-only change) → skip all three; the generic Code Reviewer above is the only gate.
|
||||
- Hand each ONLY the lane's working directory and the diff range `git diff origin/development...feat/<slug>` — each scopes itself to its own domain's files even though the diff range is the same for all.
|
||||
- Each ends with its own parseable line: `BACKEND-REVIEW:` / `FRONTEND-REVIEW:` / `MCP-REVIEW:` — `CLEAN` or `FINDINGS — <n>`.
|
||||
- Neither touched (root/`skills/`/`agents/`/`scripts/`/docs-only change) → skip both; the generic Code Reviewer above is the only gate.
|
||||
- Hand each ONLY the lane's working directory and the diff range `git diff origin/development...feat/<slug>` — each scopes itself to its own domain's files even though the diff range is the same for both.
|
||||
- Each ends with its own parseable line: `BACKEND-REVIEW:` / `FRONTEND-REVIEW:` — `CLEAN` or `FINDINGS — <n>`.
|
||||
- Triage ALL findings — the generic review plus every domain reviewer that ran — together with **receiving-code-review** judgment (verify each, neither blind agreement nor blind rejection) and apply what's worth applying on the feature branch. Changed source → re-run **from Stage 1b**; changed only tests → **from Stage 2**. Keep the findings + your resolutions — the senior gate reads them.
|
||||
- The Stage-6 `qc-local` report covers the user-flow review for the senior gate.
|
||||
- `agenthub stage review --evidence "<total findings count across all reviewers that ran> findings, resolved"`
|
||||
|
||||
@@ -43,7 +43,7 @@ you dropped back to.
|
||||
- `agenthub stage intake --status running`
|
||||
- Restate the requirement and its success criteria.
|
||||
- Explore the impacted modules: `Explore` agent for breadth, then read the key
|
||||
files yourself. Identify which layers are hit (server / client / mcp / docs /
|
||||
files yourself. Identify which layers are hit (server / client / docs /
|
||||
scripts) — `repo-onboarding` if the area is unfamiliar.
|
||||
- Requirement fuzzy or open to more than one reading? **superpowers:brainstorming**.
|
||||
|
||||
@@ -79,7 +79,7 @@ you dropped back to.
|
||||
weaken existing tests. Final line: `UNIT-TESTS: PASS — <n> added` or
|
||||
`UNIT-TESTS: FAIL — <test> :: <defect>`.
|
||||
- **Suite run.** Backend changed → `npm run test:server`. Frontend →
|
||||
`npm run test:client`. MCP → `npm run mcp:typecheck` + `npm run mcp:build`.
|
||||
`npm run test:client`.
|
||||
A UI snapshot diff is reported for review, **never blindly regenerated**
|
||||
(`cd client && npx vitest run -u` is yours to run, only after you read the
|
||||
diff).
|
||||
@@ -101,15 +101,14 @@ you dropped back to.
|
||||
Agent calls).** Check `git diff --name-only` (against the base this task
|
||||
started from) for touched layers and launch every matching one —
|
||||
FOREGROUND, fresh context, never `fork`, addressed as `agenthub:backend-reviewer`
|
||||
/ `agenthub:frontend-reviewer` / `agenthub:mcp-reviewer`:
|
||||
/ `agenthub:frontend-reviewer`:
|
||||
- Any path under `server/` → `agenthub:backend-reviewer`.
|
||||
- Any path under `client/` → `agenthub:frontend-reviewer`.
|
||||
- Any path under `mcp/` → `agenthub:mcp-reviewer`.
|
||||
- None of those three touched → skip all three; the generic Code Reviewer
|
||||
- Neither touched → skip both; the generic Code Reviewer
|
||||
above is the only gate.
|
||||
- Hand each ONLY the repo path and the working diff — each scopes itself to
|
||||
its own domain's files. Each ends with its own parseable line:
|
||||
`BACKEND-REVIEW:` / `FRONTEND-REVIEW:` / `MCP-REVIEW:` — `CLEAN` or
|
||||
`BACKEND-REVIEW:` / `FRONTEND-REVIEW:` — `CLEAN` or
|
||||
`FINDINGS — <n>`.
|
||||
- Apply what is worth applying — the generic review plus every domain
|
||||
reviewer that ran — with **superpowers:receiving-code-review** judgment:
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- Scope
|
||||
- Problem and success criteria are explicit.
|
||||
- Impacted layers identified (server/client/mcp/docs/scripts).
|
||||
- Impacted layers identified (server/client/docs/scripts).
|
||||
|
||||
- Implementation
|
||||
- Input validation and error handling are explicit.
|
||||
@@ -12,10 +12,9 @@
|
||||
- Verification
|
||||
- Backend: `npm run test:server` when backend changed.
|
||||
- Frontend: `npm run test:client` when UI changed.
|
||||
- MCP: `npm run mcp:typecheck` + `npm run mcp:build` when MCP changed.
|
||||
|
||||
- Documentation
|
||||
- `README.md`, `ARCHITECTURE.md`, `SETUP.md`, `INSTALL.md`, `mcp/README.md` updated as needed.
|
||||
- `README.md`, `ARCHITECTURE.md`, `SETUP.md`, `INSTALL.md` updated as needed.
|
||||
- Commands in docs match `package.json`.
|
||||
|
||||
- Delivery
|
||||
|
||||
@@ -35,7 +35,6 @@ Update docs **in the same change-set (PR/commit) as the code**, before claiming
|
||||
| **API route / response** | `docs/API.md`, `server/README.md` (routes), `ARCHITECTURE.md` (routes row), `server/openapi*.js` (code) |
|
||||
| **DB schema** | `docs/DATABASE.md`, `ARCHITECTURE.md` (ERD/schema) |
|
||||
| **WebSocket message** | `client/README.md` (Event Types), `server/README.md`, |
|
||||
| **MCP tool** | `mcp/README.md`, `docs/MCP.md` |
|
||||
| **Feature / page / background service** | `README.md` (feature table + data-flow list), `ARCHITECTURE.md` (module table), `server/README.md` or `client/README.md` |
|
||||
| **CLI command / script** | `README.md` commands, `CLAUDE.md` / `AGENTS.md`, `INSTALL.md` / `SETUP.md` |
|
||||
| **New language** | `docs/I18N.md`, `client/src/i18n/locales/<xx>/*`, `client/src/i18n/index.ts` (add to `supportedLngs` AND the `resources` map) |
|
||||
@@ -53,7 +52,7 @@ Update docs **in the same change-set (PR/commit) as the code**, before claiming
|
||||
- **Tables**: markdown tables stay pipe-balanced (header column count == every row).
|
||||
- **Mermaid**: each edited block still parses (valid `source --> target: label`).
|
||||
- **i18n**: every new English string has a `vi` entry in `client/src/i18n/locales/vi/`.
|
||||
- **Format/tests**: run `npm run format` (or `prettier --check` on touched files); for any code touched, run the verification from `CLAUDE.md` (`npm run test:server` / `test:client` / `mcp:typecheck`).
|
||||
- **Format/tests**: run `npm run format` (or `prettier --check` on touched files); for any code touched, run the verification from `CLAUDE.md` (`npm run test:server` / `test:client`).
|
||||
- State exactly which docs were updated and which were intentionally skipped (with reason), mirroring the repo's verification policy.
|
||||
|
||||
## Tips
|
||||
|
||||
@@ -43,9 +43,6 @@ REST API reference (endpoints, params, example responses). Update for route/resp
|
||||
### `docs/PLUGINS.md`
|
||||
Plugin/marketplace docs incl. an **Event Types** enumeration line — keep it in sync with the canonical event-type list.
|
||||
|
||||
### `docs/MCP.md` + `mcp/README.md`
|
||||
MCP server + tool reference. Update for new/changed MCP tools.
|
||||
|
||||
### `docs/I18N.md`
|
||||
i18n architecture: **Supported languages** list, `supportedLngs`, the 15 namespaces. Update when adding a language or namespace. Client UI strings live in `client/src/i18n/locales/{en,zh,vi}/*.json` (code).
|
||||
|
||||
|
||||
@@ -25,8 +25,6 @@ DOCS=(
|
||||
"docs/DATABASE.md"
|
||||
"docs/API.md"
|
||||
"docs/PLUGINS.md"
|
||||
"docs/MCP.md"
|
||||
"mcp/README.md"
|
||||
"docs/I18N.md"
|
||||
".env.example"
|
||||
)
|
||||
|
||||
Reference in New Issue
Block a user