@buildifyx/desktop-agent 0.1.0

package/src/transport/mcp/manifest-store.js

@@ -0,0 +1,32 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export function defaultToolManifestPath() {
+  return path.join(os.homedir(), '.buildifyx', 'tool-manifest.json');
+}
+
+export async function loadPreviousToolManifest(filePath = defaultToolManifestPath()) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export async function saveToolManifest(manifest, filePath = defaultToolManifestPath()) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+  return filePath;
+}
+
+export async function inspectToolManifest(manifest, filePath = defaultToolManifestPath()) {
+  const previous = await loadPreviousToolManifest(filePath);
+  const changed = Boolean(previous?.hash && previous.hash !== manifest.hash);
+  await saveToolManifest(manifest, filePath);
+  return {
+    previousHash: previous?.hash ?? null,
+    changed,
+    filePath
+  };
+}

package/src/transport/mcp/response.js

@@ -0,0 +1,25 @@
+import { normalizeError } from '../../core/errors.js';
+
+export function successResult(structuredContent, { isError } = {}) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
+    structuredContent,
+    ...(isError ? { isError: true } : {})
+  };
+}
+
+export function errorResult(error) {
+  const normalized = normalizeError(error);
+  const structuredContent = {
+    error: {
+      code: normalized.code,
+      message: normalized.message,
+      ...(normalized.details !== undefined ? { details: normalized.details } : {})
+    }
+  };
+  return {
+    content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
+    structuredContent,
+    isError: true
+  };
+}

package/src/transport/mcp/server.js

@@ -0,0 +1,114 @@
+import { createServer } from 'node:http';
+import { createRequire } from 'node:module';
+import { toNodeHandler } from '@modelcontextprotocol/node';
+import { createMcpHandler, McpServer } from '@modelcontextprotocol/server';
+import { createRuntime } from '../../core/runtime.js';
+import { createToolManifest, registerMcpToolRegistry } from './tools/index.js';
+import { inspectToolManifest } from './manifest-store.js';
+
+const require = createRequire(import.meta.url);
+const { version: packageVersion } = require('../../../package.json');
+
+export function isAllowedOrigin(origin) {
+  if (!origin) return true;
+  try {
+    const url = new URL(origin);
+    return url.hostname === '127.0.0.1' || url.hostname === 'localhost' || url.hostname === '::1';
+  } catch {
+    return false;
+  }
+}
+
+export function buildMcpServer({ runtime, root, fullAccess = false, policy, manifest }) {
+  const activeRuntime = runtime ?? createRuntime({ root, fullAccess, policy });
+  const activeManifest = manifest ?? createToolManifest({ fullAccess: activeRuntime.fullAccess });
+  const server = new McpServer({ name: 'buildifyx-desktop-agent', version: packageVersion });
+  registerMcpToolRegistry(server, activeRuntime.dispatch, { fullAccess: activeRuntime.fullAccess });
+  return { server, runtime: activeRuntime, manifest: activeManifest };
+}
+
+export async function startMcpServer({ root, port, fullAccess = false, policy, runtime, quiet = false }) {
+  const activeRuntime = runtime ?? createRuntime({ root, fullAccess, policy });
+  const manifest = createToolManifest({ fullAccess: activeRuntime.fullAccess });
+  const manifestState = await inspectToolManifest(manifest);
+
+  const handler = createMcpHandler(() => buildMcpServer({ runtime: activeRuntime, manifest }).server, {
+    responseMode: 'json'
+  });
+  const nodeHandler = toNodeHandler(handler);
+
+  const httpServer = createServer((req, res) => {
+    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+
+    if (url.pathname === '/health' && req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({
+        ok: true,
+        version: packageVersion,
+        mode: activeRuntime.fullAccess ? 'full_access' : 'restricted',
+        tools: {
+          count: manifest.count,
+          hash: manifest.hash,
+          shortHash: manifest.shortHash,
+          changedSinceLastRun: manifestState.changed
+        }
+      }));
+      return;
+    }
+
+    if (url.pathname === '/tools' && req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({
+        version: packageVersion,
+        changedSinceLastRun: manifestState.changed,
+        previousHash: manifestState.previousHash,
+        ...manifest
+      }, null, 2));
+      return;
+    }
+
+    if (url.pathname !== '/mcp') {
+      res.writeHead(404, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Not found' }));
+      return;
+    }
+    if (!isAllowedOrigin(req.headers.origin)) {
+      res.writeHead(403, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Origin not allowed' }));
+      return;
+    }
+    void nodeHandler(req, res);
+  });
+
+  await new Promise((resolve, reject) => {
+    httpServer.once('error', reject);
+    httpServer.listen(port, '127.0.0.1', resolve);
+  });
+
+  if (!quiet) {
+    console.log('Buildifyx Desktop Agent');
+    console.log(`Version: ${packageVersion}`);
+    console.log(`Root:    ${root}`);
+    console.log(`MCP:     http://127.0.0.1:${port}/mcp`);
+    console.log(`Health:  http://127.0.0.1:${port}/health`);
+    console.log(`Tools:   ${manifest.count} (${manifest.shortHash})${manifestState.changed ? ' CHANGED' : ''}`);
+    console.log(`Mode:    ${activeRuntime.fullAccess ? 'FULL ACCESS (not sandboxed)' : 'restricted'}`);
+  }
+
+  async function close() {
+    await handler.close();
+    await new Promise((resolve) => httpServer.close(resolve));
+  }
+
+  return {
+    close,
+    httpServer,
+    runtime: activeRuntime,
+    version: packageVersion,
+    manifest,
+    manifestState,
+    mcpUrl: `http://127.0.0.1:${port}/mcp`,
+    healthUrl: `http://127.0.0.1:${port}/health`,
+    toolsUrl: `http://127.0.0.1:${port}/tools`
+  };
+}

package/src/transport/mcp/tools/commands.js

@@ -0,0 +1,33 @@
+import * as z from 'zod/v4';
+import { MAX_OUTPUT_BYTES, MAX_TIMEOUT_MS } from '../../../services/commands.js';
+import { successResult } from '../response.js';
+
+const RunCommandInput = z.object({
+  command: z.string().min(1).describe('Allowed executable name. Paths and shell command strings are not accepted.'),
+  args: z.array(z.string().max(4096)).max(128).default([]),
+  cwd: z.string().default('.').describe('Working directory relative to the configured root directory.'),
+  timeoutMs: z.number().int().min(100).max(MAX_TIMEOUT_MS).default(15_000)
+});
+
+export function getCommandToolDefinitions({ fullAccess = false } = {}) {
+  return [
+    {
+      name: 'run_command',
+      title: 'Run command',
+      description: fullAccess
+        ? `Run a command in FULL ACCESS mode. Commands are not sandboxed. Timeout: ${MAX_TIMEOUT_MS} ms; output: ${MAX_OUTPUT_BYTES} bytes per stream.`
+        : `Run a restricted developer command without a shell. cwd must stay inside an allowed root unless approved. Timeout: ${MAX_TIMEOUT_MS} ms; output: ${MAX_OUTPUT_BYTES} bytes per stream.`,
+      permission: 'command',
+      inputSchema: RunCommandInput,
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      },
+      toMcpResult(result) {
+        return successResult(result, { isError: result.exitCode !== 0 || result.timedOut });
+      }
+    }
+  ];
+}

package/src/transport/mcp/tools/files.js

@@ -0,0 +1,55 @@
+import * as z from 'zod/v4';
+import { MAX_TEXT_FILE_BYTES } from '../../../services/files.js';
+
+const FilePath = z.string().min(1).describe('Path relative to the configured root directory.');
+
+const schemas = {
+  list_directory: z.object({
+    path: z.string().default('.').describe('Path relative to the configured root directory.'),
+    limit: z.number().int().min(1).max(500).default(200)
+  }),
+  read_file: z.object({ path: FilePath }),
+  write_file: z.object({ path: FilePath, content: z.string() }),
+  edit_file: z.discriminatedUnion('operation', [
+    z.object({ path: FilePath, operation: z.literal('overwrite'), content: z.string() }),
+    z.object({ path: FilePath, operation: z.literal('replace_lines'), startLine: z.number().int().min(1), endLine: z.number().int().min(1), lines: z.array(z.string()) }),
+    z.object({ path: FilePath, operation: z.literal('replace_characters'), start: z.object({ line: z.number().int().min(1), column: z.number().int().min(1) }), end: z.object({ line: z.number().int().min(1), column: z.number().int().min(1) }), content: z.string() })
+  ])
+};
+
+export function getFileToolDefinitions() {
+  return [
+    {
+      name: 'list_directory',
+      title: 'List directory',
+      description: 'List files and folders inside the configured root directory.',
+      permission: 'read',
+      inputSchema: schemas.list_directory,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    {
+      name: 'read_file',
+      title: 'Read file',
+      description: `Read one UTF-8 text file inside the configured root. Files are limited to ${MAX_TEXT_FILE_BYTES} bytes.`,
+      permission: 'read',
+      inputSchema: schemas.read_file,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    },
+    {
+      name: 'write_file',
+      title: 'Write file',
+      description: 'Create one new UTF-8 text file inside the configured root. Existing files are never overwritten.',
+      permission: 'write',
+      inputSchema: schemas.write_file,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }
+    },
+    {
+      name: 'edit_file',
+      title: 'Edit file',
+      description: 'Edit an existing UTF-8 text file inside the configured root.',
+      permission: 'write',
+      inputSchema: schemas.edit_file,
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    }
+  ];
+}

package/src/transport/mcp/tools/index.js

@@ -0,0 +1 @@
+export { createToolManifest, getMcpToolDefinitions, notifyToolListChanged, registerMcpToolRegistry } from './registry.js';

package/src/transport/mcp/tools/registry.js

@@ -0,0 +1,92 @@
+import { createHash } from 'node:crypto';
+import * as z from 'zod/v4';
+import { getCommandToolDefinitions } from './commands.js';
+import { getFileToolDefinitions } from './files.js';
+import { getSystemToolDefinitions } from './system.js';
+import { errorResult, successResult } from '../response.js';
+
+const MANIFEST_VERSION = 1;
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.keys(value)
+        .sort()
+        .map((key) => [key, stableValue(value[key])])
+    );
+  }
+  return value;
+}
+
+function jsonSchema(inputSchema) {
+  return inputSchema ? z.toJSONSchema(inputSchema) : { type: 'object', properties: {}, additionalProperties: false };
+}
+
+export function getMcpToolDefinitions(options = {}) {
+  return [
+    ...getSystemToolDefinitions(options),
+    ...getFileToolDefinitions(options),
+    ...getCommandToolDefinitions(options)
+  ];
+}
+
+export function createToolManifest(options = {}) {
+  const tools = getMcpToolDefinitions(options)
+    .map((definition) => ({
+      name: definition.name,
+      title: definition.title,
+      description: definition.description,
+      permission: definition.permission,
+      annotations: stableValue(definition.annotations ?? {}),
+      inputSchema: stableValue(jsonSchema(definition.inputSchema))
+    }))
+    .sort((left, right) => left.name.localeCompare(right.name));
+
+  const fingerprintSource = stableValue({ manifestVersion: MANIFEST_VERSION, tools });
+  const hash = createHash('sha256').update(JSON.stringify(fingerprintSource)).digest('hex');
+
+  return {
+    manifestVersion: MANIFEST_VERSION,
+    count: tools.length,
+    hash,
+    shortHash: hash.slice(0, 8),
+    tools
+  };
+}
+
+export function registerMcpToolRegistry(server, dispatch, options = {}) {
+  const definitions = getMcpToolDefinitions(options);
+
+  for (const definition of definitions) {
+    const config = {
+      title: definition.title,
+      description: definition.description,
+      annotations: definition.annotations
+    };
+    if (definition.inputSchema) config.inputSchema = definition.inputSchema;
+
+    server.registerTool(definition.name, config, async (input = {}) => {
+      try {
+        const result = await dispatch(definition.name, input ?? {});
+        return definition.toMcpResult
+          ? definition.toMcpResult(result)
+          : successResult(result);
+      } catch (error) {
+        return errorResult(error);
+      }
+    });
+  }
+
+  return definitions;
+}
+
+export function notifyToolListChanged(server) {
+  if (!server || typeof server.sendToolListChanged !== 'function') return false;
+  try {
+    server.sendToolListChanged();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/transport/mcp/tools/system.js

@@ -0,0 +1,16 @@
+export function getSystemToolDefinitions() {
+  return [
+    {
+      name: 'get_system_info',
+      title: 'Get system info',
+      description: 'Return basic read-only information about the local machine running the Buildifyx agent.',
+      permission: 'read',
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    }
+  ];
+}