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,105 @@
|
||||
/**
|
||||
* @file logger.ts
|
||||
* @description Logger class for the MCP application, responsible for logging messages in JSON format to stderr with different log levels (debug, info, warn, error). The logger respects a minimum log level configuration and includes timestamps in ISO format. Each log entry is a single line of JSON containing the timestamp, log level, message, and optional metadata. This structured logging approach allows for easy parsing and analysis of logs. The Logger class provides methods for each log level and a private method to handle the actual writing of log entries to stderr.
|
||||
* @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
|
||||
* - `../config/app-config.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `Logger` — 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).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **Logger**
|
||||
* 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.
|
||||
*
|
||||
* ----------------------------------------------------------------------------- */
|
||||
/** Numeric severity ranking; higher is more severe. */
|
||||
const LEVEL_ORDER = {
|
||||
debug: 10,
|
||||
info: 20,
|
||||
warn: 30,
|
||||
error: 40,
|
||||
};
|
||||
/**
|
||||
* Structured JSON logger for the MCP process. Every entry is one
|
||||
* newline-terminated JSON object written to **stderr**, never stdout — for
|
||||
* the stdio transport, stdout is the MCP JSON-RPC channel, so logging there
|
||||
* would corrupt the protocol stream. One instance is shared process-wide via
|
||||
* {@link ToolContext} and {@link DashboardApiClient}.
|
||||
*/
|
||||
export class Logger {
|
||||
minLevel;
|
||||
/** @param minLevel Minimum severity written; lower calls are dropped.
|
||||
* Sourced from `AppConfig.logLevel` (`MCP_LOG_LEVEL`, default `"info"`). */
|
||||
constructor(minLevel) {
|
||||
this.minLevel = minLevel;
|
||||
}
|
||||
/** Per-call tracing, e.g. tool invocation start/completion; silent unless
|
||||
* `MCP_LOG_LEVEL=debug`. */
|
||||
debug(message, meta) {
|
||||
this.write("debug", message, meta);
|
||||
}
|
||||
/** Default-visible lifecycle events (server started, new session opened). */
|
||||
info(message, meta) {
|
||||
this.write("info", message, meta);
|
||||
}
|
||||
/** Recoverable/transient issues, e.g. a retried dashboard API request. */
|
||||
warn(message, meta) {
|
||||
this.write("warn", message, meta);
|
||||
}
|
||||
/** Aborted operations, e.g. a thrown tool handler or unhandled rejection. */
|
||||
error(message, meta) {
|
||||
this.write("error", message, meta);
|
||||
}
|
||||
/** Writes one entry if `level` meets {@link minLevel}; `meta` is included
|
||||
* only when non-empty. */
|
||||
write(level, message, meta) {
|
||||
if (LEVEL_ORDER[level] < LEVEL_ORDER[this.minLevel]) {
|
||||
return;
|
||||
}
|
||||
const line = JSON.stringify({
|
||||
timestamp: new Date().toISOString(),
|
||||
level,
|
||||
message,
|
||||
...(meta && Object.keys(meta).length > 0 ? { meta } : {}),
|
||||
});
|
||||
process.stderr.write(`${line}\n`);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,135 @@
|
||||
/**
|
||||
* @file tool-registry.ts
|
||||
* @description Core functions for registering tools in the MCP server. This module defines the ToolRegistrar type, which is a function that can be used to register a tool with a name, description, input schema, and handler function. It also provides factory functions to create different types of registrars: one that registers tools directly with the MCP server and collects entries for REPL mode, and another that only collects entries without registering with the MCP server (for pure REPL mode). The registrars handle error logging and result formatting to ensure consistent behavior across different tool implementations.
|
||||
* @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
|
||||
* - `./logger.js`
|
||||
* - `./tool-result.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `ToolHandler` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `ToolRegistrar` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `ToolEntry` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `createToolRegistrar` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `createDualRegistrar` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `createCollectorRegistrar` — 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).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **ToolHandler**
|
||||
* 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.
|
||||
*
|
||||
* **ToolRegistrar**
|
||||
* 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.
|
||||
*
|
||||
* **ToolEntry**
|
||||
* 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.
|
||||
*
|
||||
* **createToolRegistrar**
|
||||
* 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.
|
||||
*
|
||||
* **createDualRegistrar**
|
||||
* 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.
|
||||
*
|
||||
* **createCollectorRegistrar**
|
||||
* 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 { errorResult, jsonResult } from "./tool-result.js";
|
||||
/**
|
||||
* Creates a {@link ToolRegistrar} that registers each tool directly with a
|
||||
* live `McpServer`. Its handler wrapper is the one place that logs
|
||||
* `debug`-level start/completion (or `error` on failure), converts a
|
||||
* success into a `CallToolResult` via {@link jsonResult}, and catches any
|
||||
* thrown error — converting it via {@link errorResult} — so a failing call
|
||||
* always resolves rather than rejects the MCP request.
|
||||
*/
|
||||
export function createToolRegistrar(server, logger) {
|
||||
return (name, description, inputSchema, handler) => {
|
||||
server.registerTool(name, { description, inputSchema }, async (args) => {
|
||||
try {
|
||||
logger.debug("Tool invocation started", { tool: name });
|
||||
const result = await handler(args);
|
||||
logger.debug("Tool invocation completed", { tool: name });
|
||||
return jsonResult(name, result);
|
||||
}
|
||||
catch (error) {
|
||||
logger.error("Tool invocation failed", {
|
||||
tool: name,
|
||||
error: error instanceof Error ? error.message : "Unknown error",
|
||||
});
|
||||
return errorResult(error);
|
||||
}
|
||||
});
|
||||
};
|
||||
}
|
||||
/**
|
||||
* Registrar that also collects tool entries for REPL mode. Delegates to
|
||||
* {@link createToolRegistrar} and additionally pushes a plain
|
||||
* {@link ToolEntry}, so one call would both register a tool AND make it
|
||||
* directly invokable. Not currently used — `index.ts` builds REPL entries
|
||||
* via {@link createCollectorRegistrar} instead.
|
||||
*/
|
||||
export function createDualRegistrar(server, logger, collector) {
|
||||
const mcpRegistrar = createToolRegistrar(server, logger);
|
||||
return (name, description, inputSchema, handler) => {
|
||||
mcpRegistrar(name, description, inputSchema, handler);
|
||||
collector.push({ name, description, handler });
|
||||
};
|
||||
}
|
||||
/**
|
||||
* Registrar that only collects (no MCP server, for pure REPL mode). Used by
|
||||
* `collectAllTools` to build the REPL tool list with no protocol overhead —
|
||||
* thrown errors propagate as real exceptions to the REPL's own try/catch.
|
||||
*/
|
||||
export function createCollectorRegistrar(collector) {
|
||||
return (name, description, _inputSchema, handler) => {
|
||||
collector.push({ name, description, handler });
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,116 @@
|
||||
/**
|
||||
* @file tool-result.ts
|
||||
* @description Utility functions for formatting tool results in the MCP server. This module provides helper functions to create standardized result objects for successful tool calls (jsonResult) and error cases (errorResult). The jsonResult function formats the output with a title and pretty-printed JSON payload, while the errorResult function handles both known API errors and generic errors, ensuring that error information is consistently structured for the MCP client to display. These utilities help maintain a clear contract for tool handlers when returning results or errors.
|
||||
* @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
|
||||
* - `../clients/dashboard-api-client.js`
|
||||
*
|
||||
* ## Public surface
|
||||
* - `jsonResult` — exported API; see TSDoc on the symbol for behavior.
|
||||
* - `errorResult` — 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).
|
||||
* -----------------------------------------------------------------------------
|
||||
* **jsonResult**
|
||||
* 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.
|
||||
*
|
||||
* **errorResult**
|
||||
* 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 { ApiError } from "../clients/dashboard-api-client.js";
|
||||
/**
|
||||
* Wraps a successful handler return value into the MCP `CallToolResult`
|
||||
* shape. Called only from {@link createToolRegistrar}'s handler wrapper.
|
||||
* The result is a single `text` block: the tool name as a title, then the
|
||||
* payload pretty-printed as JSON — a display convenience, not a
|
||||
* machine-readable envelope.
|
||||
*/
|
||||
export function jsonResult(title, payload) {
|
||||
return {
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: `${title}\n\n${JSON.stringify(payload, null, 2)}`,
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
/**
|
||||
* Converts a thrown error into an `isError: true` `CallToolResult`, called
|
||||
* only from {@link createToolRegistrar}'s catch block so a failing tool
|
||||
* always resolves rather than rejects. An {@link ApiError} (raised by
|
||||
* {@link DashboardApiClient} for any non-2xx response, timeout, or network
|
||||
* failure) surfaces its own `code`/`status`/`details`; any other error
|
||||
* (including policy-guard failures) collapses to a generic `INTERNAL_ERROR`
|
||||
* with just the message.
|
||||
*/
|
||||
export function errorResult(error) {
|
||||
if (error instanceof ApiError) {
|
||||
return {
|
||||
isError: true,
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify({
|
||||
error: error.message,
|
||||
code: error.code ?? null,
|
||||
status: error.status ?? null,
|
||||
details: error.details ?? null,
|
||||
}, null, 2),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
const message = error instanceof Error ? error.message : "Unknown error";
|
||||
return {
|
||||
isError: true,
|
||||
content: [
|
||||
{
|
||||
type: "text",
|
||||
text: JSON.stringify({
|
||||
error: message,
|
||||
code: "INTERNAL_ERROR",
|
||||
}, null, 2),
|
||||
},
|
||||
],
|
||||
};
|
||||
}
|
||||
Reference in New Issue
Block a user