feat(plugins): make CCAM installable straight from a Claude Code plugin
Adds a root `ccam` plugin (`.claude-plugin/plugin.json`, `"source": "./"`) so
`/plugin marketplace add` + `/plugin install ccam@...` is enough on a machine
with nothing but Claude Code: no clone, no npm run setup, no manual npm start.
- scripts/plugin-bootstrap.js: SessionStart hook. Fast-path exit, Node >=22.5
gate (node:sqlite), mkdir lock with stale reclaim, deps installed into
~/.claude/agent-dashboard/runtime/ (never the plugin cache), legacy
checkout-hook cleanup (backed up), ~/.local/bin/ccam launcher, eager UI
build so client routes like /run work immediately, detached server spawn.
- scripts/plugin-open.js, scripts/plugin-doctor.js: /ccam-open, /ccam-doctor.
- server/index.js: DASHBOARD_CLIENT_DIST override (plugin cache is read-only).
- mcp/build/ is committed (plugin MCP servers start before any bootstrap could
build them) and kept honest by scripts/check-mcp-build.js (content hash,
not mtime), enforced by pre-commit when mcp/src changes.
- plugins/ccam-dashboard/.mcp.json moved under plugins/ccam/ with a working
${CLAUDE_PLUGIN_ROOT} path (the old relative path never resolved from a
marketplace-cached subdir).
- Docs: README, INSTALL, SETUP, ARCHITECTURE, CLAUDE.md, docs/PLUGINS.md,
docs/MCP.md, docs/CLI.md, docs/HOOKS.md.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,158 @@
|
||||
/**
|
||||
* @file agent-tools.ts
|
||||
* @description Defines and registers tools for managing agents in the dashboard, including listing agents with filters, retrieving agent details, creating new agents, and updating existing agents. Each tool includes input validation using Zod schemas and interacts with the dashboard API to perform the necessary operations. The tools also check for mutation permissions before allowing changes to agent data, ensuring that the application configuration is respected.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
/* =============================================================================
|
||||
* MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
|
||||
* =============================================================================
|
||||
* **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
|
||||
*
|
||||
* ## Design constraints
|
||||
* - Local-first: no telemetry leaves the machine unless the user configures webhooks.
|
||||
* - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
|
||||
* philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
|
||||
* - Destructive flows stay behind explicit confirmation modals and server-side gates.
|
||||
* - Internationalization: user-visible strings belong in i18n JSON, not literals here.
|
||||
*
|
||||
* ## Remote data & SSH
|
||||
* Remote Data Sources let operators aggregate multiple machines. SSH entries describe
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../core/tool-registry.js`
|
||||
* - `../../policy/tool-guards.js`
|
||||
* - `../schemas.js`
|
||||
* - `../../types/tool-context.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `registerAgentTools` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
* ## Testing pointers
|
||||
* - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
|
||||
* - Server contract changes require `npm run test:server` and OpenAPI sync.
|
||||
* - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
|
||||
*
|
||||
* ## Related docs
|
||||
* - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
|
||||
* - `docs/API.md` — REST reference.
|
||||
* - `.claude/skills/file-headers/` — mandatory `@author` header policy.
|
||||
* ============================================================================= */
|
||||
/* -----------------------------------------------------------------------------
|
||||
* EXPORT CATALOG — quick index of symbols defined below (documentation only).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **registerAgentTools**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
import { z } from "zod";
|
||||
import { createToolRegistrar } from "../../core/tool-registry.js";
|
||||
import { assertMutationsEnabled } from "../../policy/tool-guards.js";
|
||||
import { AgentStatusSchema, JsonObjectSchema } from "../schemas.js";
|
||||
/**
|
||||
* Registers the four agent-management tools backing `/api/agents/*`. List/
|
||||
* get are unconditional reads; create/update call
|
||||
* {@link assertMutationsEnabled} first. Agents mirror Claude Code's own
|
||||
* main-agent/subagent model: one main agent plus zero or more subagents
|
||||
* (`type: "subagent"`, optional `subagent_type`, linked via `parent_agent_id`).
|
||||
*/
|
||||
export function registerAgentTools(context) {
|
||||
const { api, logger, server, config } = context;
|
||||
const register = createToolRegistrar(server, logger);
|
||||
// Policy: none. Input: limit (1-500, default 50), offset (default 0),
|
||||
// status/session_id (optional). Calls GET /api/agents?... — the dashboard
|
||||
// honors only ONE of status/session_id per call (session_id wins,
|
||||
// ignoring limit/offset), so passing both doesn't intersect-filter.
|
||||
// Output: { agents, limit, offset }, each agent's own cost attached (from
|
||||
// its metadata token buckets, not its session's total).
|
||||
register("dashboard_list_agents", "List agents with optional status/session filters and pagination.", {
|
||||
limit: z.number().int().min(1).max(500).optional(),
|
||||
offset: z.number().int().min(0).max(100_000).optional(),
|
||||
status: AgentStatusSchema.optional(),
|
||||
session_id: z.string().min(1).max(256).optional(),
|
||||
}, async (args) => {
|
||||
const limit = args.limit ?? 50;
|
||||
const offset = args.offset ?? 0;
|
||||
return api.get("/api/agents", {
|
||||
query: {
|
||||
limit,
|
||||
offset,
|
||||
status: args.status,
|
||||
session_id: args.session_id,
|
||||
},
|
||||
});
|
||||
});
|
||||
// Policy: none. Input: agent_id (required). Calls GET /api/agents/:id.
|
||||
// Output: { agent } — 404s (ApiError, NOT_FOUND) if missing; unlike
|
||||
// dashboard_list_agents, no per-agent cost is attached.
|
||||
register("dashboard_get_agent", "Get a single agent by ID.", {
|
||||
agent_id: z.string().min(1).max(256),
|
||||
}, async (args) => {
|
||||
const agentId = args.agent_id;
|
||||
return api.get(`/api/agents/${encodeURIComponent(agentId)}`);
|
||||
});
|
||||
// Policy: MUTATIONS required. Input: id/session_id/name (required); type
|
||||
// (default "main"), subagent_type, status (default "waiting"), task,
|
||||
// parent_agent_id, metadata (all optional). Calls POST /api/agents.
|
||||
// Output: { agent, created } — an existing id returns as-is (created: false).
|
||||
register("dashboard_create_agent", "Create a new agent in a session.", {
|
||||
id: z.string().min(1).max(256),
|
||||
session_id: z.string().min(1).max(256),
|
||||
name: z.string().min(1).max(500),
|
||||
type: z.enum(["main", "subagent"]).optional(),
|
||||
subagent_type: z.string().max(128).optional(),
|
||||
status: AgentStatusSchema.optional(),
|
||||
task: z.string().max(5000).optional(),
|
||||
parent_agent_id: z.string().max(256).optional(),
|
||||
metadata: JsonObjectSchema.optional(),
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.post("/api/agents", {
|
||||
body: {
|
||||
id: args.id,
|
||||
session_id: args.session_id,
|
||||
name: args.name,
|
||||
type: args.type,
|
||||
subagent_type: args.subagent_type,
|
||||
status: args.status,
|
||||
task: args.task,
|
||||
parent_agent_id: args.parent_agent_id,
|
||||
metadata: args.metadata,
|
||||
},
|
||||
});
|
||||
});
|
||||
// Policy: MUTATIONS required. Input: agent_id (required);
|
||||
// name/status/task/current_tool/ended_at/metadata optional — current_tool
|
||||
// is nullable (explicitly clearable) and preserved when omitted entirely.
|
||||
// Calls PATCH /api/agents/:id. Output: { agent } — 404s if missing.
|
||||
register("dashboard_update_agent", "Update an existing agent's lifecycle state and metadata.", {
|
||||
agent_id: z.string().min(1).max(256),
|
||||
name: z.string().max(500).optional(),
|
||||
status: AgentStatusSchema.optional(),
|
||||
task: z.string().max(5000).optional(),
|
||||
current_tool: z.string().max(256).nullable().optional(),
|
||||
ended_at: z.string().datetime().optional(),
|
||||
metadata: JsonObjectSchema.optional(),
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
const agentId = args.agent_id;
|
||||
return api.patch(`/api/agents/${encodeURIComponent(agentId)}`, {
|
||||
body: {
|
||||
name: args.name,
|
||||
status: args.status,
|
||||
task: args.task,
|
||||
current_tool: args.current_tool,
|
||||
ended_at: args.ended_at,
|
||||
metadata: args.metadata,
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,113 @@
|
||||
/**
|
||||
* @file event-tools.ts
|
||||
* @description Defines tools related to event management in the dashboard, including listing events with optional filters and ingesting hook events from Claude Code. The tools are registered with the tool registry and include input validation using Zod schemas. The event listing tool supports pagination and session filtering, while the hook event ingestion tool allows for adding new events into the dashboard pipeline, with a guard to ensure that mutations are enabled in the configuration.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
/* =============================================================================
|
||||
* MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
|
||||
* =============================================================================
|
||||
* **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
|
||||
*
|
||||
* ## Design constraints
|
||||
* - Local-first: no telemetry leaves the machine unless the user configures webhooks.
|
||||
* - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
|
||||
* philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
|
||||
* - Destructive flows stay behind explicit confirmation modals and server-side gates.
|
||||
* - Internationalization: user-visible strings belong in i18n JSON, not literals here.
|
||||
*
|
||||
* ## Remote data & SSH
|
||||
* Remote Data Sources let operators aggregate multiple machines. SSH entries describe
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../core/tool-registry.js`
|
||||
* - `../../policy/tool-guards.js`
|
||||
* - `../schemas.js`
|
||||
* - `../../types/tool-context.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `registerEventTools` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
* ## Testing pointers
|
||||
* - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
|
||||
* - Server contract changes require `npm run test:server` and OpenAPI sync.
|
||||
* - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
|
||||
*
|
||||
* ## Related docs
|
||||
* - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
|
||||
* - `docs/API.md` — REST reference.
|
||||
* - `.claude/skills/file-headers/` — mandatory `@author` header policy.
|
||||
* ============================================================================= */
|
||||
/* -----------------------------------------------------------------------------
|
||||
* EXPORT CATALOG — quick index of symbols defined below (documentation only).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **registerEventTools**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
import { z } from "zod";
|
||||
import { createToolRegistrar } from "../../core/tool-registry.js";
|
||||
import { assertMutationsEnabled } from "../../policy/tool-guards.js";
|
||||
import { HookTypeSchema, JsonObjectSchema } from "../schemas.js";
|
||||
/**
|
||||
* Registers the two event-related tools: a read-only list and a mutation
|
||||
* that feeds the same ingestion pipeline the installed Claude Code hooks
|
||||
* use (`scripts/hook-handler.js` → `POST /api/hooks/event`) — the one domain
|
||||
* where a tool can inject data into the dashboard's real-time pipeline
|
||||
* (websocket broadcast + alert evaluation), useful for testing hook
|
||||
* behavior without a live Claude Code session.
|
||||
*/
|
||||
export function registerEventTools(context) {
|
||||
const { api, logger, server, config } = context;
|
||||
const register = createToolRegistrar(server, logger);
|
||||
// Policy: none. Input: limit (1-200, default 50), offset (default 0),
|
||||
// session_id (optional). Calls GET /api/events?limit&offset&session_id.
|
||||
// Output: paginated event rows, most recent first.
|
||||
register("dashboard_list_events", "List events with optional session filter and pagination.", {
|
||||
limit: z.number().int().min(1).max(200).optional(),
|
||||
offset: z.number().int().min(0).max(100_000).optional(),
|
||||
session_id: z.string().min(1).max(256).optional(),
|
||||
}, async (args) => {
|
||||
const limit = args.limit ?? 50;
|
||||
const offset = args.offset ?? 0;
|
||||
return api.get("/api/events", {
|
||||
query: {
|
||||
limit,
|
||||
offset,
|
||||
session_id: args.session_id,
|
||||
},
|
||||
});
|
||||
});
|
||||
// Policy: MUTATIONS required. Input: hook_type (one of the seven Claude
|
||||
// Code hook names); data (arbitrary JSON — MUST include session_id, which
|
||||
// the dashboard uses to target the session). Calls POST /api/hooks/event,
|
||||
// the same endpoint scripts/hook-handler.js posts to on every real hook
|
||||
// firing. Output: { ok: true, event }. Side effects: bumps the session's
|
||||
// updated_at, broadcasts "new_event" over websocket, fire-and-forget
|
||||
// evaluates alert rules (failures swallowed), and — only for
|
||||
// "SubagentStop" with a transcript_path — scans that session's subagent
|
||||
// JSONL files for tool calls not yet recorded as events (the only path
|
||||
// that attributes subagent tool_use to the right agent_id, since those
|
||||
// never fire their own hooks). Throws (ApiError, MISSING_SESSION) if data
|
||||
// has no session_id.
|
||||
register("dashboard_ingest_hook_event", "Ingest one Claude Code hook event into the dashboard pipeline.", {
|
||||
hook_type: HookTypeSchema,
|
||||
data: JsonObjectSchema,
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.post("/api/hooks/event", {
|
||||
body: {
|
||||
hook_type: args.hook_type,
|
||||
data: args.data,
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,130 @@
|
||||
/**
|
||||
* @file maintenance-tools.ts
|
||||
* @description Defines a set of maintenance tools for the MCP dashboard, including functions to clean up stale sessions, re-import legacy data, reinstall hooks, and clear all data. These tools are registered with the MCP server and include appropriate guards to ensure that mutating and destructive actions are only performed when explicitly allowed in the configuration. The tools interact with the MCP server's API to perform the necessary maintenance tasks, providing a way for administrators to manage the dashboard's data and settings effectively.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
/* =============================================================================
|
||||
* MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
|
||||
* =============================================================================
|
||||
* **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
|
||||
*
|
||||
* ## Design constraints
|
||||
* - Local-first: no telemetry leaves the machine unless the user configures webhooks.
|
||||
* - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
|
||||
* philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
|
||||
* - Destructive flows stay behind explicit confirmation modals and server-side gates.
|
||||
* - Internationalization: user-visible strings belong in i18n JSON, not literals here.
|
||||
*
|
||||
* ## Remote data & SSH
|
||||
* Remote Data Sources let operators aggregate multiple machines. SSH entries describe
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../core/tool-registry.js`
|
||||
* - `../../policy/tool-guards.js`
|
||||
* - `../../types/tool-context.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `registerMaintenanceTools` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
* ## Testing pointers
|
||||
* - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
|
||||
* - Server contract changes require `npm run test:server` and OpenAPI sync.
|
||||
* - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
|
||||
*
|
||||
* ## Related docs
|
||||
* - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
|
||||
* - `docs/API.md` — REST reference.
|
||||
* - `.claude/skills/file-headers/` — mandatory `@author` header policy.
|
||||
* ============================================================================= */
|
||||
/* -----------------------------------------------------------------------------
|
||||
* EXPORT CATALOG — quick index of symbols defined below (documentation only).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **registerMaintenanceTools**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
import { z } from "zod";
|
||||
import { createToolRegistrar } from "../../core/tool-registry.js";
|
||||
import { assertDestructiveEnabled, assertMutationsEnabled } from "../../policy/tool-guards.js";
|
||||
/**
|
||||
* Registers four administrative tools against `/api/settings/*`. All four
|
||||
* require mutations; `dashboard_clear_all_data` additionally requires the
|
||||
* destructive tier plus an exact confirmation token, since it's the only
|
||||
* irreversible one (cleanup only touches stale/old rows; reimport and
|
||||
* reinstall-hooks are idempotent, repeatable operations).
|
||||
*/
|
||||
export function registerMaintenanceTools(context) {
|
||||
const { api, logger, server, config } = context;
|
||||
const register = createToolRegistrar(server, logger);
|
||||
// Policy: MUTATIONS required (checked before the "at least one field"
|
||||
// validation below). Input: abandon_hours (1 to 24*365) and/or purge_days
|
||||
// (1-3650) — at least one required. Calls POST /api/settings/cleanup.
|
||||
// abandon_hours marks "active" sessions with no recent events as
|
||||
// "abandoned" (completing lingering agents); purge_days permanently
|
||||
// deletes terminal sessions (+ agents/events) older than N days. Output:
|
||||
// { abandoned, purged_sessions, purged_events, purged_agents } counts.
|
||||
register("dashboard_cleanup_data", "Maintenance: abandon stale sessions and/or purge old completed data.", {
|
||||
abandon_hours: z
|
||||
.number()
|
||||
.int()
|
||||
.min(1)
|
||||
.max(24 * 365)
|
||||
.optional(),
|
||||
purge_days: z.number().int().min(1).max(3650).optional(),
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
const abandonHours = args.abandon_hours;
|
||||
const purgeDays = args.purge_days;
|
||||
if (abandonHours === undefined && purgeDays === undefined) {
|
||||
throw new Error("At least one field is required: abandon_hours or purge_days.");
|
||||
}
|
||||
return api.post("/api/settings/cleanup", {
|
||||
body: {
|
||||
abandon_hours: abandonHours,
|
||||
purge_days: purgeDays,
|
||||
},
|
||||
});
|
||||
});
|
||||
// Policy: MUTATIONS required. Calls POST /api/settings/reimport, invoking
|
||||
// scripts/import-history.js against ~/.claude session-history JSONL files
|
||||
// — useful for backfilling sessions that predate hook installation or
|
||||
// recovering after a reset. Output: { ok: true, ...result }. Throws
|
||||
// (ApiError, IMPORT_FAILED) if the import script itself throws.
|
||||
register("dashboard_reimport_history", "Re-import legacy Claude sessions from ~/.claude into the local dashboard database.", {}, async () => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.post("/api/settings/reimport");
|
||||
});
|
||||
// Policy: MUTATIONS required. Calls POST /api/settings/reinstall-hooks,
|
||||
// invoking scripts/install-hooks.js to (re)write the seven hook entries
|
||||
// (PreToolUse/PostToolUse/Stop/SubagentStop/Notification/SessionStart/
|
||||
// SessionEnd) into ~/.claude/settings.json, overwriting any existing
|
||||
// config. Output: { ok, hooks } — same shape as dashboard_get_system_info.
|
||||
register("dashboard_reinstall_hooks", "Reinstall Claude Code hooks in ~/.claude/settings.json.", {}, async () => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.post("/api/settings/reinstall-hooks");
|
||||
});
|
||||
// Policy: DESTRUCTIVE required — the strictest gate in the server. Input:
|
||||
// confirmation_token, must exactly equal "CLEAR_ALL_DATA". Calls
|
||||
// POST /api/settings/clear-data, irreversibly deleting every row from
|
||||
// sessions, agents, events, token_usage, alert_events, and
|
||||
// webhook_deliveries — but preserving alert rules, webhook targets, and
|
||||
// pricing rules (user configuration, not activity data). Output:
|
||||
// { ok: true, cleared } with pre-deletion row counts. No undo; the only
|
||||
// tool gated by MCP_DASHBOARD_ALLOW_DESTRUCTIVE.
|
||||
register("dashboard_clear_all_data", "Delete all tracked sessions, agents, events, and token usage. Highly destructive.", {
|
||||
confirmation_token: z.string().min(1),
|
||||
}, async (args) => {
|
||||
const confirmationToken = args.confirmation_token;
|
||||
assertDestructiveEnabled(config, confirmationToken);
|
||||
return api.post("/api/settings/clear-data");
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,126 @@
|
||||
/**
|
||||
* @file observability-tools.ts
|
||||
* @description Tool registration for observability-related tools in the MCP server. This module defines a set of tools that interact with the Agent Dashboard API to provide health checks, stats, analytics, system information, data export, and operational snapshots. These tools enable users to monitor and analyze the performance and usage of their agents and sessions through the dashboard. Each tool is registered with a name, description, input schema (if applicable), and an asynchronous handler function that makes API calls to retrieve the necessary data.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
/* =============================================================================
|
||||
* MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
|
||||
* =============================================================================
|
||||
* **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
|
||||
*
|
||||
* ## Design constraints
|
||||
* - Local-first: no telemetry leaves the machine unless the user configures webhooks.
|
||||
* - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
|
||||
* philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
|
||||
* - Destructive flows stay behind explicit confirmation modals and server-side gates.
|
||||
* - Internationalization: user-visible strings belong in i18n JSON, not literals here.
|
||||
*
|
||||
* ## Remote data & SSH
|
||||
* Remote Data Sources let operators aggregate multiple machines. SSH entries describe
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../types/tool-context.js`
|
||||
* - `../../core/tool-registry.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `registerObservabilityTools` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
* ## Testing pointers
|
||||
* - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
|
||||
* - Server contract changes require `npm run test:server` and OpenAPI sync.
|
||||
* - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
|
||||
*
|
||||
* ## Related docs
|
||||
* - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
|
||||
* - `docs/API.md` — REST reference.
|
||||
* - `.claude/skills/file-headers/` — mandatory `@author` header policy.
|
||||
* ============================================================================= */
|
||||
/* -----------------------------------------------------------------------------
|
||||
* EXPORT CATALOG — quick index of symbols defined below (documentation only).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **registerObservabilityTools**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
import { z } from "zod";
|
||||
import { createToolRegistrar } from "../../core/tool-registry.js";
|
||||
/**
|
||||
* Registers the six read-only observability tools. None call
|
||||
* {@link assertMutationsEnabled}/{@link assertDestructiveEnabled} — all are
|
||||
* plain GETs, always available regardless of policy flags.
|
||||
* `dashboard_get_operational_snapshot` is the only one fanning out to
|
||||
* multiple endpoints in parallel rather than proxying a single one.
|
||||
*/
|
||||
export function registerObservabilityTools(context) {
|
||||
const { api, logger, server } = context;
|
||||
const register = createToolRegistrar(server, logger);
|
||||
// Calls GET /api/health. Output: dashboard liveness payload — a fast
|
||||
// pre-flight check, since every other tool needs the dashboard running at
|
||||
// config.dashboardBaseUrl or it fails with an ApiError network/timeout.
|
||||
register("dashboard_health_check", "Check health of the local Agent Dashboard API.", {}, async () => api.get("/api/health"));
|
||||
// Calls GET /api/stats. Output: session/agent counts by status,
|
||||
// events-today, and live websocket connection count.
|
||||
register("dashboard_get_stats", "Get dashboard overview stats including session/agent counts and websocket connections.", {}, async () => api.get("/api/stats"));
|
||||
// Calls GET /api/analytics. Output: token totals/cost, per-tool usage
|
||||
// counts, daily event/session counts, agent type distribution, and
|
||||
// event-type breakdown — backs the dashboard's Analytics page.
|
||||
register("dashboard_get_analytics", "Get analytics summary including token totals, usage trends, and distributions.", {}, async () => api.get("/api/analytics"));
|
||||
// Calls GET /api/settings/info. Output: SQLite path/size/counts/pragmas,
|
||||
// recent ingestion load (5/15/60 min), Claude Code hook install status,
|
||||
// and Node/OS process info (uptime, memory, cpu, ws connections).
|
||||
register("dashboard_get_system_info", "Get system info, DB stats, and hook installation status.", {}, async () => api.get("/api/settings/info"));
|
||||
// Calls GET /api/settings/export. Output: the full dashboard dataset —
|
||||
// sessions, agents, events, token_usage, pricing rules — same payload the
|
||||
// UI's "Export Data" button downloads (its attachment header has no
|
||||
// effect on this client).
|
||||
register("dashboard_export_data", "Export complete dashboard data payload (sessions, agents, events, tokens, pricing).", {}, async () => api.get("/api/settings/export"));
|
||||
// Input: three optional per-section limits, each defaulted below. Fans
|
||||
// out via Promise.all to GET /api/stats, /api/analytics, /api/events,
|
||||
// /api/sessions?status=active, and /api/agents queried twice
|
||||
// (status=working, status=connected — the dashboard filters one status
|
||||
// per call). Output: one combined { stats, analytics, recent_events,
|
||||
// active_sessions, active_agents: {working, connected}, generated_at }.
|
||||
register("dashboard_get_operational_snapshot", "Get a high-signal operational snapshot combining stats, analytics, active sessions, active agents, and recent events.", {
|
||||
recent_events_limit: z.number().int().min(1).max(50).optional(),
|
||||
active_sessions_limit: z.number().int().min(1).max(100).optional(),
|
||||
active_agents_limit: z.number().int().min(1).max(200).optional(),
|
||||
}, async (args) => {
|
||||
const eventsLimit = args.recent_events_limit ?? 20;
|
||||
const sessionsLimit = args.active_sessions_limit ?? 25;
|
||||
const agentsLimit = args.active_agents_limit ?? 100;
|
||||
const [stats, analytics, recentEvents, activeSessions, workingAgents, connectedAgents] = await Promise.all([
|
||||
api.get("/api/stats"),
|
||||
api.get("/api/analytics"),
|
||||
api.get("/api/events", { query: { limit: eventsLimit, offset: 0 } }),
|
||||
api.get("/api/sessions", {
|
||||
query: { status: "active", limit: sessionsLimit, offset: 0 },
|
||||
}),
|
||||
api.get("/api/agents", {
|
||||
query: { status: "working", limit: agentsLimit, offset: 0 },
|
||||
}),
|
||||
api.get("/api/agents", {
|
||||
query: { status: "connected", limit: agentsLimit, offset: 0 },
|
||||
}),
|
||||
]);
|
||||
return {
|
||||
stats,
|
||||
analytics,
|
||||
recent_events: recentEvents,
|
||||
active_sessions: activeSessions,
|
||||
active_agents: {
|
||||
working: workingAgents,
|
||||
connected: connectedAgents,
|
||||
},
|
||||
generated_at: new Date().toISOString(),
|
||||
};
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,130 @@
|
||||
/**
|
||||
* @file pricing-tools.ts
|
||||
* @description Tool registration for pricing-related functionalities in the dashboard. This includes tools for retrieving pricing rules and calculating total costs based on usage. The tools interact with the backend API to fetch the necessary data and perform calculations as needed. The file also includes input validation using Zod schemas to ensure that the tool arguments are correctly formatted before processing. These tools are essential for providing users with insights into their costs and helping them manage their usage effectively.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
/* =============================================================================
|
||||
* MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
|
||||
* =============================================================================
|
||||
* **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
|
||||
*
|
||||
* ## Design constraints
|
||||
* - Local-first: no telemetry leaves the machine unless the user configures webhooks.
|
||||
* - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
|
||||
* philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
|
||||
* - Destructive flows stay behind explicit confirmation modals and server-side gates.
|
||||
* - Internationalization: user-visible strings belong in i18n JSON, not literals here.
|
||||
*
|
||||
* ## Remote data & SSH
|
||||
* Remote Data Sources let operators aggregate multiple machines. SSH entries describe
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../core/tool-registry.js`
|
||||
* - `../../policy/tool-guards.js`
|
||||
* - `../../types/tool-context.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `registerPricingTools` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
* ## Testing pointers
|
||||
* - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
|
||||
* - Server contract changes require `npm run test:server` and OpenAPI sync.
|
||||
* - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
|
||||
*
|
||||
* ## Related docs
|
||||
* - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
|
||||
* - `docs/API.md` — REST reference.
|
||||
* - `.claude/skills/file-headers/` — mandatory `@author` header policy.
|
||||
* ============================================================================= */
|
||||
/* -----------------------------------------------------------------------------
|
||||
* EXPORT CATALOG — quick index of symbols defined below (documentation only).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **registerPricingTools**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
import { z } from "zod";
|
||||
import { createToolRegistrar } from "../../core/tool-registry.js";
|
||||
import { assertMutationsEnabled } from "../../policy/tool-guards.js";
|
||||
/**
|
||||
* Registers six tools covering `/api/pricing/*` plus the pricing-adjacent
|
||||
* `/api/settings/reset-pricing`. Reads are always available; writes
|
||||
* (upsert/delete/reset) require {@link assertMutationsEnabled}. Costs are
|
||||
* priced as of the usage date (session start date), not today's rate, so
|
||||
* historical costs stay correct across a promotional-rate cutover.
|
||||
*/
|
||||
export function registerPricingTools(context) {
|
||||
const { api, logger, server, config } = context;
|
||||
const register = createToolRegistrar(server, logger);
|
||||
// Policy: none. Calls GET /api/pricing. Output: all model_pricing rows
|
||||
// (model_pattern, display_name, per-million-token rates).
|
||||
register("dashboard_get_pricing_rules", "List all model pricing rules used for cost calculations.", {}, async () => api.get("/api/pricing"));
|
||||
// Policy: none. Calls GET /api/pricing/cost. Output: aggregate cost/token
|
||||
// totals across all sessions plus a per-day daily_costs breakdown, each
|
||||
// day priced at the rate effective on that date.
|
||||
register("dashboard_get_total_cost", "Get total model usage cost across all tracked sessions.", {}, async () => api.get("/api/pricing/cost"));
|
||||
// Policy: none. Input: session_id (required). Calls
|
||||
// GET /api/pricing/cost/:sessionId. Output: cost/token breakdown for that
|
||||
// session, priced as of its start date.
|
||||
register("dashboard_get_session_cost", "Get model usage cost breakdown for one session.", {
|
||||
session_id: z.string().min(1).max(256),
|
||||
}, async (args) => {
|
||||
const sessionId = args.session_id;
|
||||
return api.get(`/api/pricing/cost/${encodeURIComponent(sessionId)}`);
|
||||
});
|
||||
// Policy: MUTATIONS required. Input: model_pattern + display_name
|
||||
// (required); input/output/cache_read/cache_write rates (optional,
|
||||
// defaulted to 0 here). Calls PUT /api/pricing — a true `INSERT ...
|
||||
// ON CONFLICT DO UPDATE` upsert (unlike sessions/agents' create-if-absent):
|
||||
// an existing rule is fully overwritten. CAUTION: cache_write_1h_per_mtok/
|
||||
// fast_input_per_mtok/fast_output_per_mtok aren't exposed here, so
|
||||
// upserting an existing rule silently zeroes those columns. Time-limited
|
||||
// intro_* rates are untouched (server only rewrites them when an intro_*
|
||||
// field is sent). Output: the upserted rule.
|
||||
register("dashboard_upsert_pricing_rule", "Create or update a pricing rule.", {
|
||||
model_pattern: z.string().min(1).max(256),
|
||||
display_name: z.string().min(1).max(256),
|
||||
input_per_mtok: z.number().min(0).max(1_000_000).optional(),
|
||||
output_per_mtok: z.number().min(0).max(1_000_000).optional(),
|
||||
cache_read_per_mtok: z.number().min(0).max(1_000_000).optional(),
|
||||
cache_write_per_mtok: z.number().min(0).max(1_000_000).optional(),
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.put("/api/pricing", {
|
||||
body: {
|
||||
model_pattern: args.model_pattern,
|
||||
display_name: args.display_name,
|
||||
input_per_mtok: args.input_per_mtok ?? 0,
|
||||
output_per_mtok: args.output_per_mtok ?? 0,
|
||||
cache_read_per_mtok: args.cache_read_per_mtok ?? 0,
|
||||
cache_write_per_mtok: args.cache_write_per_mtok ?? 0,
|
||||
},
|
||||
});
|
||||
});
|
||||
// Policy: MUTATIONS required. Input: model_pattern (exact match). Calls
|
||||
// DELETE /api/pricing/:model_pattern. Output: { ok: true }. Throws
|
||||
// (ApiError, NOT_FOUND) if no rule matches.
|
||||
register("dashboard_delete_pricing_rule", "Delete one pricing rule by exact model_pattern.", {
|
||||
model_pattern: z.string().min(1).max(256),
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.delete(`/api/pricing/${encodeURIComponent(args.model_pattern)}`);
|
||||
});
|
||||
// Policy: MUTATIONS required. Calls POST /api/settings/reset-pricing,
|
||||
// which deletes ALL rules (including custom ones) and reseeds the
|
||||
// built-in defaults, then re-applies any active intro-rate promos so they
|
||||
// aren't lost. Output: { ok: true, pricing: [...] } — the reseeded list.
|
||||
register("dashboard_reset_pricing_defaults", "Reset pricing rules to dashboard defaults.", {}, async () => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.post("/api/settings/reset-pricing");
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
/**
|
||||
* @file remote-tools.ts
|
||||
* @description MCP tools for Remote Data Sources — list configured SSH sources
|
||||
* and trigger on-demand syncs so agents can operate remotes without the UI/CLI.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
import { z } from "zod";
|
||||
import { createToolRegistrar } from "../../core/tool-registry.js";
|
||||
import { assertMutationsEnabled } from "../../policy/tool-guards.js";
|
||||
/**
|
||||
* Registers remote-source tools against `/api/remote-sources/*`.
|
||||
* List is read-only; sync tools require the mutations policy gate.
|
||||
*/
|
||||
export function registerRemoteTools(context) {
|
||||
const { api, logger, server, config } = context;
|
||||
const register = createToolRegistrar(server, logger);
|
||||
register("dashboard_list_remote_sources", "List configured Remote Data Sources (SSH machines) with status and last sync.", {}, async () => api.get("/api/remote-sources"));
|
||||
register("dashboard_sync_remote_source", "Trigger an immediate SSH pull+import for one Remote Data Source by id.", {
|
||||
source_id: z.string().min(1).describe("Remote source id (src_…)"),
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
const id = encodeURIComponent(args.source_id);
|
||||
return api.post(`/api/remote-sources/${id}/sync`);
|
||||
});
|
||||
register("dashboard_sync_all_remote_sources", "Trigger an immediate SSH pull+import for every enabled Remote Data Source.", {}, async () => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.post("/api/remote-sources/sync-all");
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,138 @@
|
||||
/**
|
||||
* @file session-tools.ts
|
||||
* @description Defines and registers tools for managing sessions in the dashboard, including listing sessions with optional filters, retrieving session details, creating new sessions, and updating existing sessions. Each tool includes input validation using Zod schemas and interacts with the dashboard API to perform the necessary operations. The tools also check for mutation permissions before allowing changes to session data, ensuring that the application configuration is respected.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
/* =============================================================================
|
||||
* MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
|
||||
* =============================================================================
|
||||
* **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
|
||||
*
|
||||
* ## Design constraints
|
||||
* - Local-first: no telemetry leaves the machine unless the user configures webhooks.
|
||||
* - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
|
||||
* philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
|
||||
* - Destructive flows stay behind explicit confirmation modals and server-side gates.
|
||||
* - Internationalization: user-visible strings belong in i18n JSON, not literals here.
|
||||
*
|
||||
* ## Remote data & SSH
|
||||
* Remote Data Sources let operators aggregate multiple machines. SSH entries describe
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../../core/tool-registry.js`
|
||||
* - `../../policy/tool-guards.js`
|
||||
* - `../schemas.js`
|
||||
* - `../../types/tool-context.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `registerSessionTools` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
* ## Testing pointers
|
||||
* - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
|
||||
* - Server contract changes require `npm run test:server` and OpenAPI sync.
|
||||
* - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
|
||||
*
|
||||
* ## Related docs
|
||||
* - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
|
||||
* - `docs/API.md` — REST reference.
|
||||
* - `.claude/skills/file-headers/` — mandatory `@author` header policy.
|
||||
* ============================================================================= */
|
||||
/* -----------------------------------------------------------------------------
|
||||
* EXPORT CATALOG — quick index of symbols defined below (documentation only).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **registerSessionTools**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
import { z } from "zod";
|
||||
import { createToolRegistrar } from "../../core/tool-registry.js";
|
||||
import { assertMutationsEnabled } from "../../policy/tool-guards.js";
|
||||
import { SessionStatusSchema, JsonObjectSchema } from "../schemas.js";
|
||||
/**
|
||||
* Registers the four session-management tools backing `/api/sessions/*`.
|
||||
* List/get are read-only; create/update both call
|
||||
* {@link assertMutationsEnabled} first. None are gated by the
|
||||
* destructive-tools flag.
|
||||
*/
|
||||
export function registerSessionTools(context) {
|
||||
const { api, logger, server, config } = context;
|
||||
const register = createToolRegistrar(server, logger);
|
||||
// Policy: none. Input: limit (1-200, default 50), offset (default 0),
|
||||
// status (optional; omitted means all). Calls
|
||||
// GET /api/sessions?limit&offset&status. Output: { sessions, total, limit,
|
||||
// offset }.
|
||||
register("dashboard_list_sessions", "List sessions with optional status filter and pagination.", {
|
||||
limit: z.number().int().min(1).max(200).optional(),
|
||||
offset: z.number().int().min(0).max(100_000).optional(),
|
||||
status: SessionStatusSchema.optional(),
|
||||
}, async (args) => {
|
||||
const limit = args.limit ?? 50;
|
||||
const offset = args.offset ?? 0;
|
||||
const status = args.status;
|
||||
return api.get("/api/sessions", { query: { limit, offset, status } });
|
||||
});
|
||||
// Policy: none. Input: session_id (required). Calls
|
||||
// GET /api/sessions/:id. Output: { session, agents, events, workflows } —
|
||||
// agents carry their own cost (from agent.metadata token buckets),
|
||||
// workflows are any Workflow-tool runs launched in this session. 404s
|
||||
// (ApiError, NOT_FOUND) if missing.
|
||||
register("dashboard_get_session", "Get one session with its full agents list and event timeline.", {
|
||||
session_id: z.string().min(1).max(256),
|
||||
}, async (args) => {
|
||||
const sessionId = args.session_id;
|
||||
return api.get(`/api/sessions/${encodeURIComponent(sessionId)}`);
|
||||
});
|
||||
// Policy: MUTATIONS required. Input: id (required); name/cwd/model/
|
||||
// metadata (optional). Calls POST /api/sessions. Output: { session,
|
||||
// created } — an existing id returns as-is (created: false), matching how
|
||||
// the hook pipeline lazily creates sessions without erroring on a
|
||||
// duplicate id; a new session starts as "active".
|
||||
register("dashboard_create_session", "Create a new session record if it does not already exist.", {
|
||||
id: z.string().min(1).max(256),
|
||||
name: z.string().max(500).optional(),
|
||||
cwd: z.string().max(2048).optional(),
|
||||
model: z.string().max(256).optional(),
|
||||
metadata: JsonObjectSchema.optional(),
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
return api.post("/api/sessions", {
|
||||
body: {
|
||||
id: args.id,
|
||||
name: args.name,
|
||||
cwd: args.cwd,
|
||||
model: args.model,
|
||||
metadata: args.metadata,
|
||||
},
|
||||
});
|
||||
});
|
||||
// Policy: MUTATIONS required. Input: session_id (required);
|
||||
// name/status/ended_at/metadata (optional; ended_at is ISO-8601). Calls
|
||||
// PATCH /api/sessions/:id. Output: the updated session record.
|
||||
register("dashboard_update_session", "Update session metadata or lifecycle status.", {
|
||||
session_id: z.string().min(1).max(256),
|
||||
name: z.string().max(500).optional(),
|
||||
status: SessionStatusSchema.optional(),
|
||||
ended_at: z.string().datetime().optional(),
|
||||
metadata: JsonObjectSchema.optional(),
|
||||
}, async (args) => {
|
||||
assertMutationsEnabled(config);
|
||||
const sessionId = args.session_id;
|
||||
return api.patch(`/api/sessions/${encodeURIComponent(sessionId)}`, {
|
||||
body: {
|
||||
name: args.name,
|
||||
status: args.status,
|
||||
ended_at: args.ended_at,
|
||||
metadata: args.metadata,
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,81 @@
|
||||
/**
|
||||
* @file index.ts
|
||||
* @description Main entry point for registering all tools in the MCP application. This module imports and registers tools from various domains, including observability, session management, agent management, event handling, pricing, and maintenance. The registerAllTools function takes a ToolContext as an argument and calls the respective registration functions for each domain to ensure that all tools are properly set up and available for use within the application.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
/* =============================================================================
|
||||
* MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
|
||||
* =============================================================================
|
||||
* **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
|
||||
*
|
||||
* ## Design constraints
|
||||
* - Local-first: no telemetry leaves the machine unless the user configures webhooks.
|
||||
* - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
|
||||
* philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
|
||||
* - Destructive flows stay behind explicit confirmation modals and server-side gates.
|
||||
* - Internationalization: user-visible strings belong in i18n JSON, not literals here.
|
||||
*
|
||||
* ## Remote data & SSH
|
||||
* Remote Data Sources let operators aggregate multiple machines. SSH entries describe
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Internal dependencies
|
||||
* - `../types/tool-context.js`
|
||||
* - `./domains/observability-tools.js`
|
||||
* - `./domains/session-tools.js`
|
||||
* - `./domains/agent-tools.js`
|
||||
* - `./domains/event-tools.js`
|
||||
* - `./domains/pricing-tools.js`
|
||||
* - `./domains/maintenance-tools.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `registerAllTools` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
* ## Testing pointers
|
||||
* - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
|
||||
* - Server contract changes require `npm run test:server` and OpenAPI sync.
|
||||
* - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
|
||||
*
|
||||
* ## Related docs
|
||||
* - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
|
||||
* - `docs/API.md` — REST reference.
|
||||
* - `.claude/skills/file-headers/` — mandatory `@author` header policy.
|
||||
* ============================================================================= */
|
||||
/* -----------------------------------------------------------------------------
|
||||
* EXPORT CATALOG — quick index of symbols defined below (documentation only).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **registerAllTools**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
import { registerObservabilityTools } from "./domains/observability-tools.js";
|
||||
import { registerSessionTools } from "./domains/session-tools.js";
|
||||
import { registerAgentTools } from "./domains/agent-tools.js";
|
||||
import { registerEventTools } from "./domains/event-tools.js";
|
||||
import { registerPricingTools } from "./domains/pricing-tools.js";
|
||||
import { registerMaintenanceTools } from "./domains/maintenance-tools.js";
|
||||
import { registerRemoteTools } from "./domains/remote-tools.js";
|
||||
/**
|
||||
* Registers all 29 `dashboard_*` tools with the given {@link ToolContext} in
|
||||
* one call. `server.ts`'s `buildServer` calls this per `McpServer` instance;
|
||||
* `transports/tool-collector.ts`'s `collectAllTools` independently
|
||||
* re-implements the same registrations for REPL mode (no live server), so
|
||||
* the two files must be kept in sync by hand when a tool changes.
|
||||
*/
|
||||
export function registerAllTools(context) {
|
||||
registerObservabilityTools(context);
|
||||
registerSessionTools(context);
|
||||
registerAgentTools(context);
|
||||
registerEventTools(context);
|
||||
registerPricingTools(context);
|
||||
registerMaintenanceTools(context);
|
||||
registerRemoteTools(context);
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
/**
|
||||
* @file schemas.ts
|
||||
* @description Defines common Zod schemas used across different tools in the MCP application, including enumerations for session status, agent status, and hook types, as well as a generic JSON object schema. These schemas are used for input validation in various tools that manage sessions, agents, events, and hooks within the dashboard. By centralizing these schemas, we ensure consistency and reusability across the codebase.
|
||||
* @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
|
||||
*/
|
||||
/* =============================================================================
|
||||
* MODULE_GUIDE — extended in-file reference (comments only; safe to read, never executed)
|
||||
* =============================================================================
|
||||
* **Purpose:** Dashboard module consumed by the React client, MCP tools, or desktop shell depending on deployment mode.
|
||||
*
|
||||
* ## Design constraints
|
||||
* - Local-first: no telemetry leaves the machine unless the user configures webhooks.
|
||||
* - Fail-safe hooks path on the server must never block Claude Code; UI mirrors that
|
||||
* philosophy by degrading gracefully (empty states, stale badges, reconnect loops).
|
||||
* - Destructive flows stay behind explicit confirmation modals and server-side gates.
|
||||
* - Internationalization: user-visible strings belong in i18n JSON, not literals here.
|
||||
*
|
||||
* ## Remote data & SSH
|
||||
* Remote Data Sources let operators aggregate multiple machines. SSH entries describe
|
||||
* how to reach a peer dashboard; the global data scope (`dataScope.ts`) narrows every
|
||||
* scoped GET via `?sources=`. Health checks and import history surface in Settings.
|
||||
*
|
||||
* ## Observability
|
||||
* Prometheus scrapes `GET /api/metrics` (see `monitoring/`). Grafana ships four
|
||||
* provisioned boards (overview, sessions, tools, alerts). Native npm scripts and
|
||||
* Docker Compose profiles are documented in `monitoring/README.md`.
|
||||
*
|
||||
* ## Public surface
|
||||
* - `SessionStatusSchema` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `AgentStatusSchema` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `HookTypeSchema` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `JsonObjectSchema` — exported API; see TSDoc on the symbol for behavior.
|
||||
*
|
||||
* ## Testing pointers
|
||||
* - Prefer colocated `__tests__` with Vitest + Testing Library for UI.
|
||||
* - Server contract changes require `npm run test:server` and OpenAPI sync.
|
||||
* - MCP edits: `npm run mcp:typecheck` and `npm run mcp:build`.
|
||||
*
|
||||
* ## Related docs
|
||||
* - `ARCHITECTURE.md` — hooks → API → SQLite → WebSocket → UI pipeline.
|
||||
* - `docs/API.md` — REST reference.
|
||||
* - `.claude/skills/file-headers/` — mandatory `@author` header policy.
|
||||
* ============================================================================= */
|
||||
/* -----------------------------------------------------------------------------
|
||||
* EXPORT CATALOG — quick index of symbols defined below (documentation only).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **SessionStatusSchema**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* **AgentStatusSchema**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* **HookTypeSchema**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* **JsonObjectSchema**
|
||||
* Part of this module's public contract. Downstream imports should treat
|
||||
* the signature and return type as stable unless release notes say otherwise.
|
||||
* When behavior changes, update the `@file` overview and relevant tests.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
import { z } from "zod";
|
||||
/** Session lifecycle states, mirroring the dashboard's `sessions.status`
|
||||
* column. Used by `dashboard_list_sessions`'s `status` filter and
|
||||
* `dashboard_update_session`'s `status` field. Only `"active"` sessions are
|
||||
* eligible for `dashboard_cleanup_data`'s `abandon_hours`; only terminal
|
||||
* states are eligible for its `purge_days`. */
|
||||
export const SessionStatusSchema = z.enum(["active", "completed", "error", "abandoned"]);
|
||||
/** Agent lifecycle states, mirroring `agents.status`. Used by
|
||||
* `dashboard_list_agents`'s `status` filter and `dashboard_create_agent`/
|
||||
* `dashboard_update_agent`'s `status` field; new agents default to
|
||||
* `"waiting"` server-side when omitted. */
|
||||
export const AgentStatusSchema = z.enum(["working", "waiting", "completed", "error"]);
|
||||
/** The seven Claude Code hook lifecycle events the dashboard's ingestion
|
||||
* pipeline understands, matching the hook names Claude Code invokes (wired
|
||||
* into `~/.claude/settings.json` by `scripts/install-hooks.js`). Used only
|
||||
* by `dashboard_ingest_hook_event`'s `hook_type` field — every real hook
|
||||
* firing posts one of these via `scripts/hook-handler.js`. */
|
||||
export const HookTypeSchema = z.enum([
|
||||
"PreToolUse",
|
||||
"PostToolUse",
|
||||
"Stop",
|
||||
"SubagentStop",
|
||||
"Notification",
|
||||
"SessionStart",
|
||||
"SessionEnd",
|
||||
]);
|
||||
/** Permissive arbitrary-JSON-object schema, used for the free-form
|
||||
* `metadata` field on session/agent tools and the hook `data` payload in
|
||||
* `dashboard_ingest_hook_event`, whose actual shape varies by `hook_type`
|
||||
* and is validated by the dashboard server itself, not this MCP layer. */
|
||||
export const JsonObjectSchema = z.record(z.unknown());
|
||||
Reference in New Issue
Block a user