zerogterm 0.9.0-alpha.1 → 0.9.1-alpha.1

package/README.md

@@ -38,7 +38,7 @@ See the project walkthrough on [YouTube](https://youtu.be/4aJZCxLHD14).
 
 ## Release status
 
-ZeroG Terminal is currently a public alpha. The current release is `0.9.0-alpha.1`; the version history is tracked in [versions.txt](versions.txt). The running version is shown beside the wordmark in the title bar, read from the app itself rather than written into the interface, so it is accurate in a packaged build too.
+ZeroG Terminal is currently a public alpha. The current release is `0.9.1-alpha.1`; the version history is tracked in [versions.txt](versions.txt). The running version is shown beside the wordmark in the title bar, read from the app itself rather than written into the interface, so it is accurate in a packaged build too.
 
 The GitHub Releases page provides a Windows x64 installer and portable executable for each desktop release. These alpha builds are intended for early adopters and testing rather than production use. The npm package remains available for developers who prefer to launch ZeroG from Node.js.
 
@@ -396,6 +396,59 @@ npm install --global zerogterm
 zerogterm
 ```
 
+## Connecting an AI agent through MCP
+
+ZeroG Terminal can expose the running desktop instance as a local MCP server. This
+lets an MCP-capable AI agent inspect workspaces and sessions, restore or create
+project workspaces, open SSH sessions, and request commands for your approval.
+
+1. Start ZeroG Terminal with MCP enabled:
+
+   ```bash
+   ZEROG_MCP_ENABLED=1 npx zerogterm
+   ```
+
+   On Windows PowerShell, use:
+
+   ```powershell
+   $env:ZEROG_MCP_ENABLED = "1"
+   npx zerogterm
+   ```
+
+2. Open **Settings → AI & voice → MCP** in ZeroG Terminal. Copy the displayed
+   endpoint and bearer token into your MCP client. The default endpoint is
+   `http://127.0.0.1:60056/mcp`.
+
+   MCP clients that support Streamable HTTP generally need the equivalent of:
+
+   ```json
+   {
+     "url": "http://127.0.0.1:60056/mcp",
+     "headers": {
+       "Authorization": "Bearer <token-from-zero-g-settings>"
+     }
+   }
+   ```
+
+   The exact configuration key differs between clients; use its Streamable HTTP
+   or remote MCP server setting rather than a stdio command. The token belongs to
+   the current ZeroG process, is held only in memory, and must be copied again
+   after ZeroG restarts. Never put it in source control, prompts, issue reports,
+   or shared configuration.
+
+3. Ask the agent to call `zerog_get_connection_status`, then
+   `zerog_acquire_control` with a client ID and the capabilities it needs. Read
+   capabilities require no write access; workspace changes and command requests
+   require the corresponding lease capabilities. The lease is single-client and
+   expires unless renewed.
+
+Every command request is shown in ZeroG Terminal for exact user approval before
+anything is written to a shell. Rejection, cancellation, takeover, credential
+prompts, uncertain prompts, and unsupported command shapes fail closed. MCP does
+not receive terminal output, credentials, or keystroke-level control. See the
+[full MCP protocol and security guide](docs/mcp.md) for tools, limits, and
+troubleshooting.
+
 ## Development
 
 ```bash

package/dist/main/main/main.js

@@ -381,61 +381,64 @@ ipcMain.handle('mcp:execution:cancel', (_event, requestId) => {
     win?.webContents.send('mcp:execution', result);
     return result;
 });
-ipcMain.handle('mcp:start', async () => {
-    mcpHost ??= new McpServerHost({
-        control: mcpControl,
-        providers: {
-            listWorkspaces: () => workspaceStore.load(),
-            listSessions: () => service.list(),
-            createWorkspace,
-            restoreWorkspace,
-            createSshSession: async (request) => {
-                const session = await service.createSsh(request.target, request.name);
-                const attached = service.attach(session.id, (data) => {
-                    const requestId = mcpActiveExecutions.get(session.id);
-                    if (requestId) {
-                        const output = `${mcpExecutionOutput.get(requestId) ?? ''}${data}`.slice(0, 16 * 1024);
-                        mcpExecutionOutput.set(requestId, output);
-                        if ((output.match(/ExitCode=\d+/g) ?? []).length >= 2) {
-                            const result = mcpExecutions.finishRunning(requestId, 'completed', output, false, 'Command completed.');
-                            clearMcpExecution(requestId, session.id);
-                            win?.webContents.send('mcp:execution', result);
-                        }
+function createMcpProviders() {
+    return {
+        listWorkspaces: () => workspaceStore.load(),
+        listSessions: () => service.list(),
+        createWorkspace,
+        restoreWorkspace,
+        createSshSession: async (request) => {
+            const session = await service.createSsh(request.target, request.name);
+            const attached = service.attach(session.id, (data) => {
+                const requestId = mcpActiveExecutions.get(session.id);
+                if (requestId) {
+                    const output = `${mcpExecutionOutput.get(requestId) ?? ''}${data}`.slice(0, 16 * 1024);
+                    mcpExecutionOutput.set(requestId, output);
+                    if ((output.match(/ExitCode=\d+/g) ?? []).length >= 2) {
+                        const result = mcpExecutions.finishRunning(requestId, 'completed', output, false, 'Command completed.');
+                        clearMcpExecution(requestId, session.id);
+                        win?.webContents.send('mcp:execution', result);
                     }
-                    win?.webContents.send('terminal:data', session.id, data);
-                }, (message) => win?.webContents.send('terminal:status', session.id, message));
-                win?.webContents.send('mcp:ssh-session-created', { session: attached });
-                return attached;
-            },
-            createProjectWorkspace,
-            requestCommand: async (request) => {
-                const sessions = await service.list();
-                const session = sessions.find((item) => item.id === request.sessionId);
-                if (!session)
-                    throw new Error('Unknown session.');
-                const result = mcpExecutions.create({ clientId: request.clientId, sessionId: request.sessionId, sessionKind: session.kind, command: request.command, policy: { allowRemoteSessions: session.kind === 'ssh', ...(request.timeoutMs === undefined ? {} : { maxRuntimeMs: request.timeoutMs }), ...(request.outputBytes === undefined ? {} : { maxOutputBytes: request.outputBytes }) } });
-                const safeRemote = session.kind === 'ssh' && isSafeRemoteCommand(result.command);
-                if (safeRemote) {
-                    const approved = mcpExecutions.approveAutomatically(result.requestId);
-                    mcpAudit.record({ at: Date.now(), requestId: approved.requestId, clientId: approved.clientId, capability: 'session:execute', sessionId: approved.sessionId, state: 'approved', command: approved.displayCommand });
-                    await runMcpExecution(approved.requestId);
-                    return mcpExecutions.get(approved.requestId, request.clientId);
                 }
-                mcpAudit.record({ at: Date.now(), requestId: result.requestId, clientId: result.clientId, capability: 'session:execute', sessionId: result.sessionId, state: 'requested', command: result.displayCommand });
-                win?.webContents.send('mcp:execution', result);
-                return result;
-            },
-            getCommandResult: async (request) => mcpExecutions.get(request.requestId, request.clientId),
-            cancelCommand: async (request) => {
-                const current = mcpExecutions.get(request.requestId, request.clientId);
-                const result = mcpExecutions.cancel(request.requestId, request.clientId);
-                const session = 'sessionId' in current ? (await service.list()).find((item) => item.id === current.sessionId) : undefined;
-                if (session?.kind === 'local')
-                    service.write(session.id, '\u0003');
-                clearMcpExecution(request.requestId);
-                return result;
+                win?.webContents.send('terminal:data', session.id, data);
+            }, (message) => win?.webContents.send('terminal:status', session.id, message));
+            win?.webContents.send('mcp:ssh-session-created', { session: attached });
+            return attached;
+        },
+        createProjectWorkspace,
+        requestCommand: async (request) => {
+            const sessions = await service.list();
+            const session = sessions.find((item) => item.id === request.sessionId);
+            if (!session)
+                throw new Error('Unknown session.');
+            const result = mcpExecutions.create({ clientId: request.clientId, sessionId: request.sessionId, sessionKind: session.kind, command: request.command, policy: { allowRemoteSessions: session.kind === 'ssh', ...(request.timeoutMs === undefined ? {} : { maxRuntimeMs: request.timeoutMs }), ...(request.outputBytes === undefined ? {} : { maxOutputBytes: request.outputBytes }) } });
+            const safeRemote = session.kind === 'ssh' && isSafeRemoteCommand(result.command);
+            if (safeRemote) {
+                const approved = mcpExecutions.approveAutomatically(result.requestId);
+                mcpAudit.record({ at: Date.now(), requestId: approved.requestId, clientId: approved.clientId, capability: 'session:execute', sessionId: approved.sessionId, state: 'approved', command: approved.displayCommand });
+                await runMcpExecution(approved.requestId);
+                return mcpExecutions.get(approved.requestId, request.clientId);
             }
+            mcpAudit.record({ at: Date.now(), requestId: result.requestId, clientId: result.clientId, capability: 'session:execute', sessionId: result.sessionId, state: 'requested', command: result.displayCommand });
+            win?.webContents.send('mcp:execution', result);
+            return result;
         },
+        getCommandResult: async (request) => mcpExecutions.get(request.requestId, request.clientId),
+        cancelCommand: async (request) => {
+            const current = mcpExecutions.get(request.requestId, request.clientId);
+            const result = mcpExecutions.cancel(request.requestId, request.clientId);
+            const session = 'sessionId' in current ? (await service.list()).find((item) => item.id === current.sessionId) : undefined;
+            if (session?.kind === 'local')
+                service.write(session.id, '\u0003');
+            clearMcpExecution(request.requestId);
+            return result;
+        }
+    };
+}
+ipcMain.handle('mcp:start', async () => {
+    mcpHost ??= new McpServerHost({
+        control: mcpControl,
+        providers: createMcpProviders(),
         version: app.getVersion()
     });
     return mcpHost.start();
@@ -707,58 +710,7 @@ app.whenReady().then(() => {
     if (process.env.ZEROG_MCP_ENABLED === '1') {
         mcpHost ??= new McpServerHost({
             control: mcpControl,
-            providers: {
-                listWorkspaces: () => workspaceStore.load(),
-                listSessions: () => service.list(),
-                createWorkspace,
-                restoreWorkspace,
-                createSshSession: async (request) => {
-                    const session = await service.createSsh(request.target, request.name);
-                    const attached = service.attach(session.id, (data) => {
-                        const requestId = mcpActiveExecutions.get(session.id);
-                        if (requestId) {
-                            const output = `${mcpExecutionOutput.get(requestId) ?? ''}${data}`.slice(0, 16 * 1024);
-                            mcpExecutionOutput.set(requestId, output);
-                            if ((output.match(/ExitCode=\d+/g) ?? []).length >= 2) {
-                                const result = mcpExecutions.finishRunning(requestId, 'completed', output, false, 'Command completed.');
-                                clearMcpExecution(requestId, session.id);
-                                win?.webContents.send('mcp:execution', result);
-                            }
-                        }
-                        win?.webContents.send('terminal:data', session.id, data);
-                    }, (message) => win?.webContents.send('terminal:status', session.id, message));
-                    win?.webContents.send('mcp:ssh-session-created', { session: attached });
-                    return attached;
-                },
-                createProjectWorkspace,
-                requestCommand: async (request) => {
-                    const sessions = await service.list();
-                    const session = sessions.find((item) => item.id === request.sessionId);
-                    if (!session)
-                        throw new Error('Unknown session.');
-                    const result = mcpExecutions.create({ clientId: request.clientId, sessionId: request.sessionId, sessionKind: session.kind, command: request.command, policy: { allowRemoteSessions: session.kind === 'ssh', ...(request.timeoutMs === undefined ? {} : { maxRuntimeMs: request.timeoutMs }), ...(request.outputBytes === undefined ? {} : { maxOutputBytes: request.outputBytes }) } });
-                    const safeRemote = session.kind === 'ssh' && isSafeRemoteCommand(result.command);
-                    if (safeRemote) {
-                        const approved = mcpExecutions.approveAutomatically(result.requestId);
-                        mcpAudit.record({ at: Date.now(), requestId: approved.requestId, clientId: approved.clientId, capability: 'session:execute', sessionId: approved.sessionId, state: 'approved', command: approved.displayCommand });
-                        await runMcpExecution(approved.requestId);
-                        return mcpExecutions.get(approved.requestId, request.clientId);
-                    }
-                    mcpAudit.record({ at: Date.now(), requestId: result.requestId, clientId: result.clientId, capability: 'session:execute', sessionId: result.sessionId, state: 'requested', command: result.displayCommand });
-                    win?.webContents.send('mcp:execution', result);
-                    return result;
-                },
-                getCommandResult: async (request) => mcpExecutions.get(request.requestId, request.clientId),
-                cancelCommand: async (request) => {
-                    const current = mcpExecutions.get(request.requestId, request.clientId);
-                    const result = mcpExecutions.cancel(request.requestId, request.clientId);
-                    const session = 'sessionId' in current ? (await service.list()).find((item) => item.id === current.sessionId) : undefined;
-                    if (session?.kind === 'local')
-                        service.write(session.id, '\u0003');
-                    clearMcpExecution(request.requestId);
-                    return result;
-                }
-            },
+            providers: createMcpProviders(),
             version: app.getVersion()
         });
         void mcpHost.start();