@moon16u/dsh-plugin-mcp-console 0.1.0

package/lib/routes.js

@@ -0,0 +1,317 @@
+/**
+ * HTTP API (plan §5.4): everything under `/api/dsh-mcp-console/`, registered
+ * as one prefix route on the web profile's `webServer` service.
+ *
+ * | Method | Path                        | Semantics                          |
+ * |--------|-----------------------------|------------------------------------|
+ * | GET    | /health                     | liveness + store paths             |
+ * | GET    | /servers                    | full snapshot (secrets masked)     |
+ * | POST   | /servers                    | add (body = server config)         |
+ * | PATCH  | /servers/:name              | edit (masked secrets round-trip)   |
+ * | DELETE | /servers/:name              | remove                             |
+ * | POST   | /servers/:name/enable       | enable + assemble                  |
+ * | POST   | /servers/:name/disable      | dispose (config kept)              |
+ * | POST   | /servers/:name/reconnect    | fiber.restart()                    |
+ * | POST   | /import                     | mcpServers JSON import             |
+ * | GET    | /events                     | SSE status stream                  |
+ * | GET    | /config                     | UI config (non-secret)             |
+ * | PUT    | /config                     | persist UI config                  |
+ *
+ * Loopback fence: every mutating and secret-bearing route answers 403 to
+ * non-loopback callers; GET /config (UI placement only) is open so a LAN
+ * browser can at least read placement while the data routes stay local.
+ */
+import { computeSnapshot } from "./status.js";
+import { ConsoleError } from "./orchestrator.js";
+import { parseMcpServers } from "./import.js";
+import { exportStoreToProfileYaml } from "./yamlMigrator.js";
+
+export const ROUTE_PREFIX = "/api/dsh-mcp-console";
+
+/** Max accepted JSON body (mcpServers imports can be chunky but not huge). */
+const BODY_LIMIT = 1024 * 1024;
+
+const STATUS_BY_CODE = { invalid: 400, conflict: 409, not_found: 404, internal: 500 };
+
+const LOOPBACK_ADDRESSES = new Set(["127.0.0.1", "::1", "::ffff:127.0.0.1"]);
+
+/**
+ * Register the API on the webserver.
+ *
+ * @param {import("@deepseek-ai/cordis").Context} ctx
+ * @param {object} services
+ * @param {import("./orchestrator.js").Orchestrator} services.orchestrator
+ * @param {import("./store.js").Store} services.uiStore store holding the `ui` section
+ * @returns {{ dispose: () => void, notify: () => void }} route handle
+ */
+export function registerRoutes(ctx, { orchestrator, uiStore }) {
+  const sseClients = new Set();
+  let heartbeat = null;
+  let notifyTimer = null;
+  let dirty = false;
+
+  const disposeRoute = ctx.webServer.register({
+    kind: "prefix",
+    path: ROUTE_PREFIX,
+    handler: (req, res) => {
+      handle(req, res).catch((error) => {
+        if (res.headersSent) {
+          res.end();
+          return;
+        }
+        const code = error instanceof ConsoleError ? error.code : "internal";
+        respond(res, STATUS_BY_CODE[code] ?? 500, { error: { code, message: String(error?.message ?? error) } });
+      });
+    },
+  });
+
+  heartbeat = setInterval(() => {
+    for (const client of sseClients) {
+      try {
+        client(": ping\n\n");
+      } catch {
+        // broken pipe: close handler will reap the client
+      }
+    }
+  }, 25000);
+  if (typeof heartbeat.unref === "function") heartbeat.unref();
+
+  /**
+   * Broadcast a status_changed SSE frame (throttled 500ms, plan §5.3).
+   * Frames carry the full snapshot; identical consecutive snapshots are
+   * skipped, so polling and event storms never spam open panels.
+   */
+  let lastSent = null;
+  function notify() {
+    dirty = true;
+    if (notifyTimer) return;
+    notifyTimer = setTimeout(() => {
+      notifyTimer = null;
+      if (!dirty) return;
+      dirty = false;
+      const snapshot = JSON.stringify(computeSnapshot(orchestrator));
+      if (snapshot === lastSent) return;
+      lastSent = snapshot;
+      const frame = `event: status_changed\ndata: ${snapshot}\n\n`;
+      for (const client of sseClients) {
+        try {
+          client(frame);
+        } catch {
+          // reaped by close handler
+        }
+      }
+    }, 500);
+    if (typeof notifyTimer.unref === "function") notifyTimer.unref();
+  }
+
+  async function handle(req, res) {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const segments = url.pathname.slice(ROUTE_PREFIX.length).split("/").filter(Boolean).map(decodeURIComponent);
+    const method = req.method ?? "GET";
+
+    // loopback fence: everything except GET /config
+    const isConfigRead = method === "GET" && segments.length === 1 && segments[0] === "config";
+    if (!isConfigRead && !isLoopback(req)) {
+      respond(res, 403, { error: { code: "forbidden", message: "loopback only" } });
+      return;
+    }
+
+    if (segments[0] === "health" && method === "GET") {
+      respond(res, 200, {
+        ok: true,
+        plugin: "mcp-console",
+        globalStore: orchestrator.globalStore.path,
+        projectStore: orchestrator.projectStore?.path ?? null,
+        managed: [...orchestrator.ledger.keys()].sort(),
+        disabledTools: [...orchestrator.disabledToolSet].sort(),
+        profileYaml: orchestrator.profileYamlPath,
+        ingestError: orchestrator.ingestError,
+      });
+      return;
+    }
+
+    if (segments[0] === "refresh" && method === "POST") {
+      respond(res, 200, await orchestrator.refresh());
+      return;
+    }
+
+    if (segments[0] === "export-yaml" && method === "POST") {
+      const result = await exportStoreToProfileYaml({ store: orchestrator.globalStore });
+      respond(res, 200, result);
+      return;
+    }
+
+    if (segments[0] === "servers") {
+      await handleServers(req, res, method, segments.slice(1));
+      return;
+    }
+
+    if (segments[0] === "import" && method === "POST") {
+      const body = await readJson(req);
+      const text = typeof body?.json === "string" ? body.json : typeof body?.text === "string" ? body.text : "";
+      if (text.length === 0) {
+        respond(res, 400, { error: { code: "invalid", message: "body must be { json: \"<mcpServers JSON>\" }" } });
+        return;
+      }
+      const { servers, errors } = parseMcpServers(text);
+      const result = await orchestrator.importServers(servers);
+      respond(res, 200, { ...result, parseErrors: errors });
+      return;
+    }
+
+    if (segments[0] === "events" && method === "GET") {
+      handleSse(req, res);
+      return;
+    }
+
+    if (segments[0] === "config") {
+      if (method === "GET") {
+        respond(res, 200, { ui: sanitizeUi(uiStore.read().ui) });
+        return;
+      }
+      if (method === "PUT" || method === "POST") {
+        const body = await readJson(req);
+        respond(res, 200, { ui: sanitizeUi(uiStore.writeUi(sanitizeUi(body?.ui ?? {}))) });
+        return;
+      }
+      respond(res, 405, { error: { code: "method_not_allowed", message: "GET or PUT /config" } });
+      return;
+    }
+
+    respond(res, 404, { error: { code: "not_found", message: `unknown route ${method} ${url.pathname}` } });
+  }
+
+  async function handleServers(req, res, method, rest) {
+    if (rest.length === 0) {
+      if (method === "GET") {
+        respond(res, 200, computeSnapshot(orchestrator));
+        return;
+      }
+      if (method === "POST") {
+        const body = await readJson(req);
+        const result = await orchestrator.add(body ?? {});
+        respond(res, 201, result);
+        return;
+      }
+      respond(res, 405, { error: { code: "method_not_allowed", message: "GET or POST /servers" } });
+      return;
+    }
+
+    const [name, action] = rest;
+    if (action === undefined) {
+      if (method === "PATCH") {
+        const body = await readJson(req);
+        respond(res, 200, await orchestrator.update(name, body ?? {}));
+        return;
+      }
+      if (method === "DELETE") {
+        respond(res, 200, await orchestrator.remove(name));
+        return;
+      }
+      respond(res, 405, { error: { code: "method_not_allowed", message: "PATCH or DELETE /servers/:name" } });
+      return;
+    }
+
+    if (method !== "POST") {
+      respond(res, 405, { error: { code: "method_not_allowed", message: `POST /servers/:name/${action}` } });
+      return;
+    }
+    if (action === "enable") respond(res, 200, await orchestrator.setEnabled(name, true));
+    else if (action === "disable") respond(res, 200, await orchestrator.setEnabled(name, false));
+    else if (action === "reconnect") respond(res, 200, await orchestrator.reconnect(name));
+    else respond(res, 404, { error: { code: "not_found", message: `unknown action "${action}"` } });
+  }
+
+  function handleSse(req, res) {
+    res.writeHead(200, {
+      "content-type": "text/event-stream; charset=utf-8",
+      "cache-control": "no-cache, no-transform",
+      connection: "keep-alive",
+      "x-accel-buffering": "no",
+    });
+    res.write("retry: 3000\n\n");
+    const send = (frame) => res.write(frame);
+    sseClients.add(send);
+    // initial snapshot so a freshly opened panel renders immediately
+    send(`event: status_changed\ndata: ${JSON.stringify(computeSnapshot(orchestrator))}\n\n`);
+    req.on("close", () => {
+      sseClients.delete(send);
+    });
+  }
+
+  function dispose() {
+    disposeRoute();
+    if (heartbeat) clearInterval(heartbeat);
+    if (notifyTimer) clearTimeout(notifyTimer);
+    for (const client of sseClients) {
+      try {
+        client("event: bye\ndata: {}\n\n");
+      } catch {
+        // already gone
+      }
+    }
+    sseClients.clear();
+  }
+
+  return { dispose, notify };
+}
+
+function isLoopback(req) {
+  const address = req?.socket?.remoteAddress;
+  return typeof address === "string" && LOOPBACK_ADDRESSES.has(address);
+}
+
+function respond(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "cache-control": "no-store",
+  });
+  res.end(payload);
+}
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > BODY_LIMIT) {
+        reject(new ConsoleError("invalid", `body exceeds ${BODY_LIMIT} bytes`));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (chunks.length === 0) {
+        resolve(undefined);
+        return;
+      }
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+      } catch (error) {
+        reject(new ConsoleError("invalid", `invalid JSON body: ${String(error?.message ?? error)}`));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+const UI_POSITIONS = new Set(["top-right", "bottom-right"]);
+
+/** Only known, non-secret UI keys survive into the store. */
+export function sanitizeUi(ui) {
+  const out = { position: "top-right", offsetX: 8, offsetY: 8 };
+  if (ui === null || typeof ui !== "object") return out;
+  if (UI_POSITIONS.has(ui.position)) out.position = ui.position;
+  out.offsetX = clampInt(ui.offsetX, 0, 256, out.offsetX);
+  out.offsetY = clampInt(ui.offsetY, 0, 256, out.offsetY);
+  return out;
+}
+
+function clampInt(value, min, max, fallback) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < min || n > max) return fallback;
+  return n;
+}

package/lib/status.js

@@ -0,0 +1,126 @@
+/**
+ * Status observation and aggregation (plan §5.3, MVP口径).
+ *
+ * State machine per server: `disabled` (configured, not enabled) → `loading`
+ * (fiber starting) → `running` (fiber live AND tools registered) /
+ * `connecting` (fiber live, zero tools, inside the grace window) → `failed`
+ * (fiber FAILED, startup error, or zero tools after the grace window).
+ *
+ * Honest MVP caveats (documented in README known-limitations):
+ * - "connecting" vs "reconnecting, attempt N" cannot be distinguished — the
+ *   official client does not expose structured connection-level events yet.
+ * - A connected server that legitimately exposes zero tools reads as
+ *   "failed" after the grace window.
+ *
+ * Change sources: the global `tools/change` event (tool registration or
+ * unregistration anywhere), fiber `internal/status` transitions for fibers
+ * in our ledger, and a fallback timer while anything is mid-connect.
+ */
+import { FiberState, CONNECT_GRACE_MS } from "./orchestrator.js";
+
+/**
+ * Derive one server's status string from its ledger entry and live tools.
+ * @param {object|undefined} entry ledger entry (undefined = not assembled)
+ * @param {string[]} tools live tool names attributed to the server
+ * @param {boolean} enabled whether the stored config has enabled !== false
+ */
+export function serverStatus(entry, tools, enabled) {
+  if (!enabled) return "disabled";
+  if (!entry) return "failed";
+  if (entry.pending) return "loading";
+  if (entry.error) return "failed";
+  const state = entry.fiber ? entry.fiber.state : FiberState.DISPOSED;
+  if (state === FiberState.FAILED) return "failed";
+  if (state === FiberState.PENDING || state === FiberState.LOADING || state === FiberState.UNLOADING) {
+    return "loading";
+  }
+  if (tools.length > 0) return "running";
+  if (state === FiberState.ACTIVE) {
+    return Date.now() - entry.loadedAt < CONNECT_GRACE_MS ? "connecting" : "failed";
+  }
+  return "failed";
+}
+
+/**
+ * Full API snapshot: every stored server with live status, masked secrets,
+ * tool lists, plus profile-declared (external) servers as read-only entries
+ * with their live tool lists (mcp-manager-v1-review §2-4: read-only servers
+ * render inline in the list with a badge, no delete, controls disabled).
+ *
+ * @param {import("./orchestrator.js").Orchestrator} orchestrator
+ */
+export function computeSnapshot(orchestrator) {
+  const stored = orchestrator.storedServers();
+  const currentTools = orchestrator.toolNamesSnapshot();
+  const servers = [];
+  for (const [name, config] of stored) {
+    const entry = orchestrator.ledger.get(name);
+    const liveTools = orchestrator.toolsOf(name, currentTools);
+    const disabled = new Set(Array.isArray(config.disabledTools) ? config.disabledTools : []);
+    const prefix = `mcp__${name}__`;
+    const enabled = config.enabled !== false;
+    const tools = liveTools.map((publicName) => ({
+      name: publicName,
+      label: publicName.startsWith(prefix) ? publicName.slice(prefix.length) : publicName,
+      enabled: !disabled.has(publicName),
+    }));
+    const status = serverStatus(entry, liveTools, enabled);
+    const view = orchestrator.publicConfig(config);
+    servers.push({
+      ...view,
+      status,
+      toolCount: liveTools.length,
+      enabledToolCount: enabled ? tools.filter((tool) => tool.enabled).length : 0,
+      tools,
+      error: entry?.error ?? null,
+    });
+  }
+  servers.sort((a, b) => a.name.localeCompare(b.name));
+
+  const externalServers = [];
+  for (const name of orchestrator.externalServerNames()) {
+    const prefix = `mcp__${name}__`;
+    const tools = [...currentTools]
+      .filter((toolName) => toolName.startsWith(prefix))
+      .sort()
+      .map((publicName) => ({
+        name: publicName,
+        label: publicName.startsWith(prefix) ? publicName.slice(prefix.length) : publicName,
+        enabled: true,
+      }));
+    externalServers.push({
+      name,
+      readOnly: true,
+      enabled: true,
+      status: tools.length > 0 ? "running" : "connecting",
+      toolCount: tools.length,
+      enabledToolCount: tools.length,
+      tools,
+      error: null,
+    });
+  }
+  externalServers.sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    version: 1,
+    servers,
+    externalServers,
+    hasProjectWorkspace: Boolean(orchestrator.projectStore),
+    projectWorkspaceRoot: orchestrator.projectRoot ?? null,
+    storeErrors: [
+      orchestrator.globalStore.lastError,
+      orchestrator.projectStore?.lastError ?? null,
+      orchestrator.ingestError,
+    ].filter(Boolean),
+    clientError: orchestrator.clientError ?? null,
+  };
+}
+
+/** Group servers by status for the panel's sectioned list. */
+export function groupByStatus(servers) {
+  const groups = { running: [], connecting: [], loading: [], disabled: [], failed: [] };
+  for (const server of servers) {
+    (groups[server.status] ?? groups.failed).push(server);
+  }
+  return groups;
+}

package/lib/store.js

@@ -0,0 +1,136 @@
+/**
+ * Configuration persistence for the MCP console.
+ *
+ * One JSON document per scope, each shaped `{ version, servers, ui? }` where
+ * `servers` maps `serverName -> ServerConfig` (the console's own storage
+ * format — NOT the official client's config shape; see clientAdapter.js for
+ * the translation). Writes are atomic (temp file + rename) and every write
+ * first snapshots the previous file to `<file>.bak.<ts>` so deletions stay
+ * recoverable. A corrupt file is renamed aside (`.corrupt.<ts>`) and rebuilt
+ * empty — the corruption is surfaced through `lastError`, never silently
+ * dropped.
+ */
+import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { randomBytes } from "node:crypto";
+
+/** Current document schema version. */
+export const STORE_VERSION = 1;
+
+/** serverName contract, mirrored from the official mcp-client. */
+export const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
+
+/** Global-scope store path: `$DSH_HOME/dsh-mcp.json` (defaults to ~/.dsh). */
+export function globalStorePath(dshHome) {
+  const root = dshHome ?? process.env.DSH_HOME ?? join(homedir(), ".dsh");
+  return join(root, "dsh-mcp.json");
+}
+
+/** Project-scope store path: `<workspace>/.dsh/mcp.json`. */
+export function projectStorePath(workspaceRoot) {
+  return join(workspaceRoot, ".dsh", "mcp.json");
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+export function emptyDoc() {
+  return { version: STORE_VERSION, servers: {} };
+}
+
+/** Normalize one parsed document; returns `{ doc, error }`. */
+export function normalizeDoc(raw) {
+  if (raw === undefined || raw === null) return { doc: emptyDoc(), error: null };
+  if (!isPlainObject(raw)) return { doc: emptyDoc(), error: "store root must be a JSON object" };
+  const doc = {
+    version: typeof raw.version === "number" ? raw.version : STORE_VERSION,
+    servers: {},
+    ...(isPlainObject(raw.ui) ? { ui: raw.ui } : {}),
+  };
+  if (isPlainObject(raw.servers)) {
+    for (const [name, entry] of Object.entries(raw.servers)) {
+      if (isPlainObject(entry)) doc.servers[name] = entry;
+    }
+  }
+  const error = isPlainObject(raw.servers) ? null : "`servers` missing or not an object; rebuilt empty";
+  return { doc, error };
+}
+
+/**
+ * One persisted document with atomic writes (temp file + rename).
+ *
+ * Deletions are the user's explicit intent, so no backup files are kept:
+ * every write replaces the previous file directly. `read()` re-reads from
+ * disk, so external edits (a user fixing a config by hand) are not clobbered.
+ */
+export class Store {
+  /**
+   * @param {string} filePath absolute path of the JSON document
+   */
+  constructor(filePath) {
+    this.path = filePath;
+    /** Last read/write failure, surfaced in the panel (never silently dropped). */
+    this.lastError = null;
+  }
+
+  /** Read the document from disk; corrupt files are moved aside and rebuilt. */
+  read() {
+    let raw;
+    if (existsSync(this.path)) {
+      try {
+        raw = JSON.parse(readFileSync(this.path, "utf8"));
+      } catch (error) {
+        const aside = `${this.path}.corrupt.${timestamp()}`;
+        try {
+          renameSync(this.path, aside);
+          this.lastError = `config file was corrupt; moved to ${aside} and rebuilt empty (${String(error?.message ?? error)})`;
+        } catch (renameError) {
+          this.lastError = `config file is corrupt and could not be moved aside (${String(renameError?.message ?? renameError)})`;
+        }
+        raw = undefined;
+      }
+    }
+    const { doc, error } = normalizeDoc(raw);
+    if (error && !this.lastError) this.lastError = error;
+    return doc;
+  }
+
+  /**
+   * Mutate the servers map through `mutate(servers)` and persist atomically.
+   * `mutate` returning `false` cancels the write (validation failed).
+   * @returns the mutate() result
+   */
+  mutate(mutate) {
+    const doc = this.read();
+    const servers = { ...doc.servers };
+    const result = mutate(servers);
+    if (result === false) return result;
+    this._persist({ ...doc, servers });
+    return result;
+  }
+
+  /** Persist only the UI config section, keeping servers untouched. */
+  writeUi(ui) {
+    if (!isPlainObject(ui)) throw new Error("ui config must be an object");
+    const doc = this.read();
+    this._persist({ ...doc, ui });
+    return ui;
+  }
+
+  /** Atomically write the document (temp file + rename, no backups). */
+  _persist(doc) {
+    const body = JSON.stringify(doc, null, 2) + "\n";
+    const dir = dirname(this.path);
+    mkdirSync(dir, { recursive: true });
+    const temp = join(dir, `.${randomBytes(6).toString("hex")}.tmp`);
+    writeFileSync(temp, body, "utf8");
+    renameSync(temp, this.path);
+    this.lastError = null;
+  }
+}

package/lib/types/client/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Browser-side types for @moon16u/dsh-plugin-mcp-console (client bundle).
+ */
+import type * as React from "react";
+
+/** Props injected into the settings section component. */
+export interface McpSectionProps {
+  /** Locale-bound translator provided by the section registration. */
+  t: (key: string) => string;
+}
+
+/** The "MCP" settings section (mcp-manager-gui-spec.md). */
+export declare const McpSection: React.FC<McpSectionProps>;
+export declare function mcpConsoleApply(ctx: unknown): void;
+export declare const mcpInject: string[];