@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/control-plane/scripts/embedded-device.mjs

@@ -0,0 +1,149 @@
+import { createHash, randomBytes } from 'node:crypto';
+import os from 'node:os';
+
+/**
+ * The server's Device is claimed through the existing account/pairing store.
+ * This controller never assigns an owner itself and never creates a local auth bypass.
+ * Only the transport of the proven Device session is in-process.
+ */
+export async function createEmbeddedDeviceController({
+  broker, deviceStore, pairingStore, identity, core, baseUrl, deviceName,
+  onPairing = () => {}, pollIntervalMs = 2000
+}) {
+  if (!broker || !deviceStore || !pairingStore || !identity || !core) {
+    throw new Error('Embedded Device requires broker, stores, identity and shared Device Core.');
+  }
+  const record = await identity.loadOrCreate();
+  let endpoint = null;
+  let pairing = null;
+  let timer = null;
+  let closed = false;
+  let busy = false;
+  let fault = null;
+  let unsubscribeCapabilities = null;
+  const metadata = {
+    agentVersion: 'mcp-device', packageVersion: core.version || '1.0.12',
+    hostname: os.hostname(), platform: process.platform, arch: process.arch,
+    pathStyle: process.platform === 'win32' ? 'windows' : 'posix',
+    runtimeReady: true, executionRuntimeGeneration: core.runtimeInstanceId
+  };
+
+  function status() {
+    const stored = deviceStore.get(record.deviceId);
+    return {
+      device_id: record.deviceId,
+      state: closed ? 'closed' : endpoint?.isOpen() ? 'online' : fault ? 'faulted' : 'pairing_required',
+      owner_account_id: stored?.ownerAccountId || null,
+      ...(pairing ? {
+        user_code: pairing.userCode,
+        verification_uri_complete: baseUrl + '/device/verify?user_code=' + encodeURIComponent(pairing.userCode),
+        expires_at: pairing.expiresAt
+      } : {}),
+      ...(fault ? { error: fault } : {})
+    };
+  }
+
+  async function connect(enrollmentGrant) {
+    endpoint?.close();
+    endpoint = await broker.attachLocalDevice({
+      deviceId: record.deviceId, publicKeyPem: record.publicKeyPem,
+      signChallenge: nonce => identity.signChallenge(nonce),
+      invoke: (tool, args) => core.invoke(tool, args),
+      capabilities: core.capabilities, ...metadata,
+      ...(enrollmentGrant ? { enrollmentGrant } : {})
+    });
+    await identity.markEnrolled();
+    fault = null;
+    pairing = null;
+    clearTimeout(timer);
+    timer = null;
+    return status();
+  }
+
+  async function checkPairing() {
+    if (closed || !pairing || busy) return status();
+    busy = true;
+    try {
+      const current = pairingStore.getStatusByUserCode(pairing.userCode);
+      if (current.status === 'expired') {
+        fault = 'PAIRING_EXPIRED';
+        clearTimeout(timer);
+        return status();
+      }
+      if (current.status === 'approved') {
+        const result = pairingStore.poll({
+          deviceCode: pairing.deviceCode,
+          clientId: pairing.clientId,
+          codeVerifier: pairing.codeVerifier
+        });
+        await connect(result.enrollmentGrant);
+      }
+    } catch (error) {
+      fault = String(error?.code || error?.message || 'PAIRING_FAILED').slice(0, 180);
+    } finally {
+      busy = false;
+    }
+    return status();
+  }
+
+  function schedule() {
+    clearTimeout(timer);
+    if (closed || !pairing || fault) return;
+    timer = setTimeout(async () => {
+      await checkPairing();
+      schedule();
+    }, Math.max(100, pollIntervalMs));
+    timer.unref?.();
+  }
+
+  function beginPairing() {
+    if (closed) throw new Error('Embedded Device controller is closed.');
+    if (busy) throw new Error('Embedded Device pairing is busy.');
+    if (endpoint?.isOpen()) return status();
+    const codeVerifier = randomBytes(32).toString('base64url');
+    const clientId = 'mcp-device-embedded-v1';
+    const started = pairingStore.start({
+      clientId, deviceId: record.deviceId,
+      deviceName: deviceName || os.hostname(),
+      publicKeyPem: record.publicKeyPem,
+      codeChallenge: createHash('sha256').update(codeVerifier).digest('base64url')
+    });
+    pairing = { ...started, clientId, codeVerifier, expiresAt: Date.now() + started.expiresIn * 1000 };
+    fault = null;
+    schedule();
+    onPairing(status());
+    return status();
+  }
+
+  async function start() {
+    const stored = deviceStore.get(record.deviceId);
+    if (stored && !stored.revokedAt && stored.ownerAccountId) {
+      if (stored.publicKeyPem !== record.publicKeyPem) {
+        throw new Error('Embedded Device identity does not match enrolled public key.');
+      }
+      return await connect();
+    }
+    return beginPairing();
+  }
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    clearTimeout(timer);
+    unsubscribeCapabilities?.();
+    unsubscribeCapabilities = null;
+    endpoint?.close();
+    endpoint = null;
+    pairing = null;
+  }
+
+  await start();
+  if (typeof core.onCapabilitiesChanged === 'function') {
+    unsubscribeCapabilities = core.onCapabilitiesChanged(() => endpoint?.updateCapabilities(core.capabilities));
+  }
+  return {
+    status, beginPairing, checkPairing,
+    refreshCapabilities() { endpoint?.updateCapabilities(core.capabilities); },
+    close
+  };
+}

package/control-plane/scripts/enduser-ui.mjs

@@ -0,0 +1,45 @@
+export function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+export function pageShell({ title, body, wide = false }) {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)} · MCP Device</title>
+<style>
+:root{color-scheme:dark;--bg:#07090d;--panel:#0d1117;--line:#27303b;--text:#e6edf3;--muted:#8b949e;--accent:#5ba7ff;--good:#3fb950;--bad:#ff7b72}*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:15px ui-monospace,SFMono-Regular,Consolas,monospace}a{color:var(--accent)}.wrap{width:min(${wide ? '1500px' : '760px'},92vw);margin:0 auto;padding:28px 0 48px}.nav{display:flex;align-items:center;justify-content:space-between;gap:16px;flex-wrap:wrap;border-bottom:1px solid var(--line);padding-bottom:16px;margin-bottom:26px}.brand{font-weight:700;letter-spacing:.08em;color:var(--text);text-decoration:none}.links{display:flex;gap:14px;flex-wrap:wrap}.links a{color:var(--muted);text-decoration:none}.links a:hover{color:var(--text)}.card{background:var(--panel);border:1px solid var(--line);padding:20px;margin:16px 0}.stack{display:grid;gap:12px}h1{font-size:24px;margin:0 0 8px}h2{font-size:15px;margin:0 0 10px}p{line-height:1.55}.muted{color:var(--muted)}.error{color:#ffb4ad}.notice{border-left:3px solid var(--accent);padding-left:12px}.actions{display:flex;gap:10px;flex-wrap:wrap;align-items:center}form.stack{display:grid}.inline{display:flex;gap:10px;flex-wrap:wrap}input{min-width:0;background:#090c11;color:var(--text);border:1px solid var(--line);padding:11px 12px;font:inherit}input:focus{outline:none;border-color:var(--accent)}button,.button{display:inline-block;border:1px solid #3b4654;background:#18202b;color:var(--text);padding:10px 13px;text-decoration:none;font:inherit;cursor:pointer}button.primary,.button.primary{background:#1769aa;border-color:#2586d7}.danger{color:#ffb4ad;border-color:#613038}code,pre{font:inherit}pre{white-space:pre-wrap;overflow-wrap:anywhere;background:#090c11;border:1px solid var(--line);padding:12px}.footer{margin-top:28px;padding-top:16px;border-top:1px solid var(--line);color:var(--muted);font-size:12px}@media(max-width:640px){.wrap{width:min(94vw,760px);padding-top:18px}.inline{display:grid}.inline>*{width:100%}}
+</style></head><body><main class="wrap"><nav class="nav"><a class="brand" href="/">MCP Device</a><div class="links"><a href="/dashboard">Dashboard</a><a href="/pair">Pair device</a><a href="/help">Help</a></div></nav>${body}<div class="footer">Your account only exposes devices paired to it. Device private keys stay on the device.</div></main></body></html>`;
+}
+
+export function quickGuide(baseUrl) {
+  const base = String(baseUrl || '').replace(/\/+$/, '') || 'https://your-mcp-host.example';
+  const escaped = escapeHtml(base);
+  const dashboardUrl = escapeHtml(`${base}/dashboard`);
+  const pairUrl = escapeHtml(`${base}/pair`);
+  const helpUrl = escapeHtml(`${base}/help`);
+  return `<div class="card"><h2>Quick start</h2><p class="muted">Server: <code>${escaped}</code></p><div class="actions"><a href="${dashboardUrl}">Dashboard</a><a href="${pairUrl}">Pair device</a><a href="${helpUrl}">Help</a></div><pre># Clone the current MCP Device v12 branch
+git clone -b feat/v12-platform-20261022 https://github.com/Hiroshimeow/agent-mcp-device.git
+cd agent-mcp-device
+npm ci
+npm run build
+
+# Point this device at the LAN server
+# PowerShell:
+$env:MCP_GATEWAY_URL="${escaped}"
+# macOS / Linux:
+export MCP_GATEWAY_URL="${escaped}"
+
+# Run the Device CLI from this checkout
+node ./dist/mcp-device.js login
+node ./dist/mcp-device.js install
+node ./dist/mcp-device.js status
+
+# Stop or uninstall without deleting account/device identity
+node ./dist/mcp-device.js stop
+node ./dist/mcp-device.js uninstall</pre><p class="muted"><code>login</code> links this device to your account, <code>install</code> enables the background service, and <code>status</code> verifies the connection. The device connects outbound to the MCP Device server; no inbound port is required.</p></div>`;
+}

package/control-plane/scripts/external-tool-broker.mjs

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/server/validators/ajv";
+import { classifyExternalToolLane } from './catalog-budget.mjs';
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 50;
+const MAX_DESCRIPTION_CHARS = 240;
+const MAX_INPUT_SUMMARY = 20;
+
+function boundedLimit(value) {
+  if (value === undefined || value === null || value === '') return DEFAULT_LIMIT;
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit < 1 || limit > MAX_LIMIT) {
+    throw new Error(`Invalid limit: ${value}. Expected an integer from 1 to ${MAX_LIMIT}.`);
+  }
+  return limit;
+}
+
+function tokenize(value) {
+  return String(value || '').toLowerCase().match(/[\p{L}\p{N}_-]+/gu) || [];
+}
+
+function searchScore(tool, query) {
+  const normalizedQuery = String(query || '').trim().toLowerCase();
+  if (!normalizedQuery) return 0;
+  const name = String(tool.name || '').toLowerCase();
+  const description = String(tool.description || '').toLowerCase();
+  if (name === normalizedQuery) return 1_000_000;
+
+  let score = name.includes(normalizedQuery) ? 10_000 : 0;
+  for (const token of tokenize(normalizedQuery)) {
+    if (name === token) score += 2_000;
+    else if (name.includes(token)) score += 500;
+    if (description.includes(token)) score += 50;
+  }
+  return score;
+}
+
+function inputSummary(tool) {
+  const properties = Object.keys(tool?.inputSchema?.properties || {});
+  const required = Array.isArray(tool?.inputSchema?.required) ? tool.inputSchema.required : [];
+  const ordered = [...required, ...properties.filter(name => !required.includes(name))];
+  return [...new Set(ordered)].slice(0, MAX_INPUT_SUMMARY);
+}
+
+function publicSearchItem(tool) {
+  return {
+    name: tool.name,
+    description: String(tool.description || '').slice(0, MAX_DESCRIPTION_CHARS),
+    lane: classifyExternalToolLane(tool),
+    server: String(tool?._meta?.upstream?.upstreamId || ''),
+    inputSummary: inputSummary(tool)
+  };
+}
+
+export function isExternalToolAllowedForProfile(tool, runtimeProfile) {
+  const profile = runtimeProfile || {};
+  if (classifyExternalToolLane(tool) === 'read') return true;
+  if (!profile.exposeDestructiveTools) return false;
+
+  const annotations = tool?.annotations;
+  const openWorld = annotations?.openWorldHint !== false;
+  if (openWorld && !profile.exposeOpenWorldTools) return false;
+  return true;
+}
+
+function cursorSignature({ query, server, lane, runtimeProfile, tools }) {
+  return createHash('sha256').update(JSON.stringify({
+    query: String(query || '').trim().toLowerCase(),
+    server: String(server || '').trim(),
+    lane: String(lane || '').trim(),
+    profile: runtimeProfile?.name || '',
+    tools: tools.map(tool => tool.name)
+  })).digest('base64url').slice(0, 18);
+}
+
+function encodeCursor(offset, signature) {
+  return Buffer.from(JSON.stringify({ v: 1, offset, signature }), 'utf8').toString('base64url');
+}
+
+function decodeCursor(cursor, signature) {
+  if (!cursor) return 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(Buffer.from(String(cursor), 'base64url').toString('utf8'));
+  } catch {
+    throw new Error('Invalid cursor: expected an opaque cursor returned by external_tool_search.');
+  }
+  if (parsed?.v !== 1 || parsed?.signature !== signature || !Number.isInteger(parsed?.offset) || parsed.offset < 0) {
+    throw new Error('Invalid or stale cursor: search parameters or catalog changed.');
+  }
+  return parsed.offset;
+}
+
+function searchTools(tools, options, runtimeProfile) {
+  const query = String(options.query || '').trim();
+  const server = String(options.server || '').trim();
+  const lane = String(options.lane || '').trim();
+  if (lane && !['read', 'write'].includes(lane)) throw new Error(`Invalid lane: ${lane}. Expected read or write.`);
+  const limit = boundedLimit(options.limit);
+
+  const filtered = tools
+    .filter(tool => isExternalToolAllowedForProfile(tool, runtimeProfile))
+    .filter(tool => !server || tool?._meta?.upstream?.upstreamId === server)
+    .filter(tool => !lane || classifyExternalToolLane(tool) === lane)
+    .map(tool => ({ tool, score: searchScore(tool, query) }))
+    .filter(entry => !query || entry.score > 0)
+    .sort((left, right) => right.score - left.score || String(left.tool.name).localeCompare(String(right.tool.name)))
+    .map(entry => entry.tool);
+
+  const signature = cursorSignature({ query, server, lane, runtimeProfile, tools: filtered });
+  const offset = decodeCursor(options.cursor, signature);
+  if (offset > filtered.length) throw new Error('Invalid or stale cursor: offset is outside the current result set.');
+  const page = filtered.slice(offset, offset + limit);
+  const nextOffset = offset + page.length;
+  const truncated = nextOffset < filtered.length;
+  return {
+    items: page.map(publicSearchItem),
+    truncated,
+    nextCursor: truncated ? encodeCursor(nextOffset, signature) : null
+  };
+}
+
+export function createExternalToolBroker({ getTools, invokeTool }) {
+  if (typeof getTools !== 'function') throw new Error('createExternalToolBroker requires getTools().');
+  if (typeof invokeTool !== 'function') throw new Error('createExternalToolBroker requires invokeTool().');
+  const validatorProvider = new AjvJsonSchemaValidator();
+  const validatorCache = new Map();
+
+  function currentTools() {
+    const tools = getTools();
+    return Array.isArray(tools) ? tools : [];
+  }
+
+  function findTool(name) {
+    const tool = currentTools().find(item => item.name === name);
+    if (!tool) throw new Error(`Unknown external tool: ${name}`);
+    return tool;
+  }
+
+  function validateArguments(tool, args) {
+    const schema = tool.inputSchema || { type: 'object' };
+    const schemaKey = JSON.stringify(schema);
+    let cached = validatorCache.get(tool.name);
+    if (!cached || cached.schemaKey !== schemaKey) {
+      try {
+        cached = { schemaKey, validate: validatorProvider.getValidator(schema) };
+      } catch (error) {
+        throw new Error(`Unable to validate cached input schema for ${tool.name}: ${error.message}`);
+      }
+      validatorCache.set(tool.name, cached);
+    }
+    const result = cached.validate(args);
+    if (!result.valid) throw new Error(`Invalid arguments for ${tool.name}: ${result.errorMessage || 'schema validation failed'}`);
+  }
+
+  return {
+    search(options = {}, runtimeProfile = {}) {
+      return searchTools(currentTools(), options, runtimeProfile);
+    },
+    async call(expectedLane, options = {}, runtimeProfile = {}) {
+      if (!['read', 'write'].includes(expectedLane)) throw new Error(`Invalid external tool call lane: ${expectedLane}`);
+      const name = String(options.name || '').trim();
+      if (!name) throw new Error('External tool name is required.');
+      const tool = findTool(name);
+      const actualLane = classifyExternalToolLane(tool);
+      if (actualLane !== expectedLane) {
+        throw new Error(`External tool ${name} belongs to the ${actualLane} lane; use external_tool_call_${actualLane}.`);
+      }
+      if (!isExternalToolAllowedForProfile(tool, runtimeProfile)) {
+        throw new Error(`Tool ${name} is disabled by MCP_RUNTIME_PROFILE=${runtimeProfile?.name || 'unknown'}.`);
+      }
+      const args = options.arguments ?? {};
+      if (!args || typeof args !== 'object' || Array.isArray(args)) throw new Error(`Invalid arguments for ${name}: expected an object.`);
+      validateArguments(tool, args);
+      return await invokeTool(name, args);
+    }
+  };
+}