@mindfullabai/onda-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mindfull AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @mindfullabai/onda-mcp
+
+MCP server to control [Onda](https://onda.dev) terminal from AI agents (Claude Code, Cursor, Windsurf, etc.)
+
+21 tools across 5 categories let AI agents split panes, run commands, manage tabs and workspaces, and orchestrate multi-agent workflows -- all through the standard [Model Context Protocol](https://modelcontextprotocol.io/).
+
+## Requirements
+
+- **Onda terminal** running with IPC server active (automatic since v1.6)
+- Node.js 18+
+
+## Quick Start
+
+### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "onda": {
+      "command": "npx",
+      "args": ["-y", "@mindfullabai/onda-mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "onda": {
+      "command": "npx",
+      "args": ["-y", "@mindfullabai/onda-mcp"]
+    }
+  }
+}
+```
+
+### Cursor / Windsurf
+
+Same MCP config format as above.
+
+## Available Tools
+
+### Pane Management
+
+| Tool | Description |
+|------|-------------|
+| `onda_pane_split` | Split the active pane. Creates a new terminal beside (`right`) or below (`down`) the current one. |
+| `onda_pane_list` | List all panes in the active tab. Returns pane IDs, terminal IDs, and content types. |
+| `onda_pane_close` | Close a specific pane by ID. If no ID given, closes the active pane. |
+| `onda_pane_focus` | Focus (activate) a specific pane by its ID. |
+
+### Terminal Control
+
+| Tool | Description |
+|------|-------------|
+| `onda_terminal_run` | Run a command in a specific terminal (sends command + newline). |
+| `onda_terminal_send` | Send raw text to a terminal without appending a newline. Use for interactive input or key sequences. |
+| `onda_terminal_list` | List all active terminals with their IDs, PIDs, working directories, and alive status. |
+| `onda_terminal_kill` | Kill a terminal process by ID. |
+
+### Tab Management
+
+| Tool | Description |
+|------|-------------|
+| `onda_tab_new` | Create a new tab. Each tab has its own layout of panes. |
+| `onda_tab_list` | List all tabs with their IDs, titles, active state, and workspace. |
+| `onda_tab_close` | Close a tab by ID. If no ID given, closes the active tab. |
+| `onda_tab_focus` | Switch to (focus) a specific tab by ID. |
+
+### Workspace Management
+
+| Tool | Description |
+|------|-------------|
+| `onda_workspace_list` | List all workspaces with their IDs, names, root paths, and which is active. |
+| `onda_workspace_create` | Create a new workspace. Workspaces group tabs by project. |
+| `onda_workspace_focus` | Switch to a workspace by ID. |
+| `onda_workspace_add_terminal` | Add a new terminal pane to a workspace (tiled mode). |
+| `onda_workspace_tile` | Set the workspace tiling layout: `single`, `split-h`, `split-v`, or `quad`. |
+
+### System
+
+| Tool | Description |
+|------|-------------|
+| `onda_context` | Get the Onda context for the current AI agent (paneId, tabId, workspaceId). Call this first. |
+| `onda_status` | Get current session state: active workspace, tab, pane, and their details. |
+| `onda_app_info` | Get Onda app info: version, process ID. |
+| `onda_ping` | Health check -- verify Onda is running and responsive. |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ONDA_SOCKET` | Path to Onda IPC socket | `~/.config/onda/onda.sock` |
+| `ONDA_PANE_ID` | Pane ID where agent is running | auto-detected |
+| `ONDA_TAB_ID` | Tab ID where agent is running | auto-detected |
+| `ONDA_WORKSPACE_ID` | Workspace ID | auto-detected |
+| `ONDA_TERMINAL` | Set to `"1"` when inside Onda | auto-detected |
+
+## Architecture
+
+- Communicates with Onda via **Unix domain socket**
+- Protocol: **JSON-RPC 2.0** over newline-delimited JSON
+- Socket path: `~/.config/onda/onda.sock`
+- Transport: **stdio** (standard MCP transport)
+
+```
+AI Agent  <--stdio-->  onda-mcp  <--Unix socket-->  Onda Terminal
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Onda MCP Server
+ *
+ * Exposes Onda terminal emulator controls as MCP tools.
+ * Connects to Onda's Unix domain socket (JSON-RPC 2.0).
+ *
+ * AI agents (Claude Code, Cursor, etc.) can use these tools to:
+ * - Split panes and create tabs
+ * - Run commands in terminals
+ * - Orchestrate multi-agent workflows
+ * - Query terminal and workspace state
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,459 @@
+#!/usr/bin/env node
+/**
+ * Onda MCP Server
+ *
+ * Exposes Onda terminal emulator controls as MCP tools.
+ * Connects to Onda's Unix domain socket (JSON-RPC 2.0).
+ *
+ * AI agents (Claude Code, Cursor, etc.) can use these tools to:
+ * - Split panes and create tabs
+ * - Run commands in terminals
+ * - Orchestrate multi-agent workflows
+ * - Query terminal and workspace state
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { Socket } from 'net';
+import { join } from 'path';
+import { homedir } from 'os';
+// ─── JSON-RPC Client ─────────────────────────────────────────
+const DEFAULT_SOCKET = join(homedir(), '.config', 'onda', 'onda.sock');
+function getSocketPath() {
+    return process.env.ONDA_SOCKET || DEFAULT_SOCKET;
+}
+// Context from the terminal where this MCP server was launched
+const ONDA_CONTEXT = {
+    paneId: process.env.ONDA_PANE_ID || null,
+    tabId: process.env.ONDA_TAB_ID || null,
+    workspaceId: process.env.ONDA_WORKSPACE_ID || null,
+    isOnda: process.env.ONDA_TERMINAL === '1',
+};
+let requestId = 0;
+async function callOnda(method, params) {
+    return new Promise((resolve, reject) => {
+        const socket = new Socket();
+        let buffer = '';
+        let settled = false;
+        const id = ++requestId;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+            socket.destroy();
+        };
+        const request = {
+            jsonrpc: '2.0',
+            method,
+            params,
+            id,
+        };
+        socket.on('connect', () => {
+            socket.write(JSON.stringify(request) + '\n');
+        });
+        socket.on('data', (chunk) => {
+            buffer += chunk.toString('utf8');
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || ''; // Keep incomplete last line
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const response = JSON.parse(line);
+                    if (response.id !== id)
+                        continue; // Skip mismatched responses
+                    settle(() => {
+                        if (response.error) {
+                            reject(new Error(response.error.message));
+                        }
+                        else {
+                            resolve(response.result);
+                        }
+                    });
+                    return;
+                }
+                catch {
+                    // Incomplete JSON, wait for more data
+                }
+            }
+        });
+        socket.on('error', (err) => {
+            settle(() => {
+                if (err.code === 'ENOENT' || err.code === 'ECONNREFUSED') {
+                    reject(new Error('Onda is not running. Start Onda terminal first.'));
+                }
+                else {
+                    reject(err);
+                }
+            });
+        });
+        socket.on('timeout', () => {
+            settle(() => reject(new Error('Connection timeout')));
+        });
+        socket.connect(getSocketPath());
+        socket.setTimeout(5000);
+    });
+}
+// ─── Tool Definitions ────────────────────────────────────────
+const TOOLS = [
+    // --- Pane ---
+    {
+        name: 'onda_pane_split',
+        description: 'Split the active pane in Onda terminal. Creates a new terminal beside or below the current one. Use this to set up parallel workspaces for multi-agent workflows.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                direction: {
+                    type: 'string',
+                    enum: ['right', 'down'],
+                    description: 'Where to place the new pane. "right" = side-by-side columns. "down" = stacked rows.',
+                },
+                cwd: {
+                    type: 'string',
+                    description: 'Working directory for the new pane. Defaults to current directory.',
+                },
+                shell: {
+                    type: 'string',
+                    description: 'Shell to use (e.g., /bin/zsh, /bin/bash). Defaults to user default.',
+                },
+            },
+        },
+    },
+    {
+        name: 'onda_pane_list',
+        description: 'List all panes in the active tab. Returns pane IDs, terminal IDs, and content types. Use this to discover available terminals before sending commands.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'onda_pane_close',
+        description: 'Close a specific pane by ID. If no ID given, closes the active pane.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Pane ID to close. Omit to close active pane.' },
+            },
+        },
+    },
+    {
+        name: 'onda_pane_focus',
+        description: 'Focus (activate) a specific pane by its ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Pane ID to focus.' },
+            },
+            required: ['id'],
+        },
+    },
+    // --- Terminal ---
+    {
+        name: 'onda_terminal_run',
+        description: 'Run a command in a specific terminal (sends command + newline). Use this to execute shell commands, launch processes, or start other AI agents in separate terminals.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Terminal ID to run the command in.' },
+                command: { type: 'string', description: 'Shell command to execute.' },
+            },
+            required: ['id', 'command'],
+        },
+    },
+    {
+        name: 'onda_terminal_send',
+        description: 'Send raw text to a terminal without appending a newline. Use for interactive input, partial commands, or key sequences.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Terminal ID to send text to.' },
+                text: { type: 'string', description: 'Text to send (no trailing newline added).' },
+            },
+            required: ['id', 'text'],
+        },
+    },
+    {
+        name: 'onda_terminal_list',
+        description: 'List all active terminals with their IDs, PIDs, working directories, and alive status. Essential for discovering which terminals exist before running commands.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'onda_terminal_kill',
+        description: 'Kill a terminal process by ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Terminal ID to kill.' },
+            },
+            required: ['id'],
+        },
+    },
+    // --- Tab ---
+    {
+        name: 'onda_tab_new',
+        description: 'Create a new tab in Onda. Each tab has its own layout of panes. Use this to isolate different workstreams.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                cwd: { type: 'string', description: 'Working directory for the new tab.' },
+                shell: { type: 'string', description: 'Shell to use.' },
+            },
+        },
+    },
+    {
+        name: 'onda_tab_list',
+        description: 'List all tabs with their IDs, titles, active state, and workspace.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'onda_tab_close',
+        description: 'Close a tab by ID. If no ID given, closes the active tab.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Tab ID to close. Omit to close active tab.' },
+            },
+        },
+    },
+    {
+        name: 'onda_tab_focus',
+        description: 'Switch to (focus) a specific tab by ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Tab ID to focus.' },
+            },
+            required: ['id'],
+        },
+    },
+    // --- Workspace ---
+    {
+        name: 'onda_workspace_list',
+        description: 'List all workspaces with their IDs, names, root paths, and which is active.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'onda_workspace_create',
+        description: 'Create a new workspace. Workspaces group tabs by project.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Workspace name.' },
+                rootPath: { type: 'string', description: 'Root directory path for the workspace.' },
+                color: { type: 'string', description: 'Color hex code (e.g., #a78bfa).' },
+            },
+            required: ['name', 'rootPath'],
+        },
+    },
+    {
+        name: 'onda_workspace_focus',
+        description: 'Switch to a workspace by ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Workspace ID to switch to.' },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'onda_workspace_add_terminal',
+        description: 'Add a new terminal pane to a workspace. Works in tiled mode to create terminals within workspace layout.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string', description: 'Workspace ID. Omit to use active workspace.' },
+                cwd: { type: 'string', description: 'Working directory for the new terminal.' },
+                shell: { type: 'string', description: 'Shell to use (e.g., /bin/zsh).' },
+            },
+        },
+    },
+    {
+        name: 'onda_workspace_tile',
+        description: 'Set the workspace-level tiling layout. Controls how workspaces are arranged in the main window.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                workspaceId: { type: 'string', description: 'Workspace ID. Omit to use active workspace.' },
+                layout: {
+                    type: 'string',
+                    enum: ['single', 'split-h', 'split-v', 'quad'],
+                    description: 'Layout mode: single (one workspace), split-h (horizontal split), split-v (vertical split), quad (four quadrants).',
+                },
+            },
+            required: ['layout'],
+        },
+    },
+    // --- System ---
+    {
+        name: 'onda_context',
+        description: 'Get the Onda context for the terminal where this AI agent is running. Returns paneId, tabId, workspaceId. Use this FIRST to know which pane/tab you are in before splitting or sending commands.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'onda_status',
+        description: 'Get current Onda session state: active workspace, active tab, active pane, and their details. Use this to understand the current context before taking actions.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'onda_app_info',
+        description: 'Get Onda app info: version, process ID.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    {
+        name: 'onda_ping',
+        description: 'Health check - verify Onda is running and responsive.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+];
+// ─── Tool → Method mapping ───────────────────────────────────
+const TOOL_MAP = {
+    // Pane
+    onda_pane_split: {
+        method: 'pane.split',
+        mapParams: (args) => ({
+            // Onda IPC uses inverted naming: "vertical" = stacked (down), "horizontal" = side-by-side (right)
+            direction: args.direction === 'down' ? 'vertical' : 'horizontal',
+            cwd: args.cwd,
+            shell: args.shell,
+        }),
+    },
+    onda_pane_list: { method: 'pane.list' },
+    onda_pane_close: { method: 'pane.close' },
+    onda_pane_focus: { method: 'pane.focus' },
+    // Terminal
+    onda_terminal_run: { method: 'terminal.run' },
+    onda_terminal_send: { method: 'terminal.send' },
+    onda_terminal_list: { method: 'terminal.list' },
+    onda_terminal_kill: { method: 'terminal.kill' },
+    // Tab
+    onda_tab_new: {
+        method: 'tab.new',
+        mapParams: (args) => ({
+            ...args,
+            // Auto-inject workspaceId from agent context so tab is created
+            // in the agent's workspace, not the currently active one
+            workspaceId: args.workspaceId || ONDA_CONTEXT.workspaceId || undefined,
+        }),
+    },
+    onda_tab_list: { method: 'tab.list' },
+    onda_tab_close: { method: 'tab.close' },
+    onda_tab_focus: { method: 'tab.focus' },
+    // Workspace
+    onda_workspace_list: { method: 'workspace.list' },
+    onda_workspace_create: { method: 'workspace.create' },
+    onda_workspace_focus: { method: 'workspace.focus' },
+    onda_workspace_add_terminal: {
+        method: 'workspace.addTerminal',
+        mapParams: (args) => ({
+            workspaceId: args.workspaceId || ONDA_CONTEXT.workspaceId || undefined,
+            cwd: args.cwd,
+            shell: args.shell,
+        }),
+    },
+    onda_workspace_tile: { method: 'workspace.setLayout' },
+    // System (onda_context handled separately - it's local, not RPC)
+    onda_status: { method: 'session.current' },
+    onda_app_info: { method: 'app.info' },
+    onda_ping: { method: 'app.ping' },
+};
+// ─── MCP Server ──────────────────────────────────────────────
+const server = new Server({
+    name: 'onda',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS,
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    // onda_context: local env vars + live session info from app
+    if (name === 'onda_context') {
+        let sessionInfo = null;
+        try {
+            sessionInfo = await callOnda('session.current');
+        }
+        catch {
+            // App may not be reachable, return env-only context
+        }
+        const context = {
+            ...ONDA_CONTEXT,
+            uiMode: sessionInfo?.uiMode || process.env.ONDA_UI_MODE || null,
+        };
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(context, null, 2),
+                }],
+        };
+    }
+    const mapping = TOOL_MAP[name];
+    if (!mapping) {
+        return {
+            content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    }
+    try {
+        // Auto-focus our pane before split so it splits in the right place
+        if (name === 'onda_pane_split' && ONDA_CONTEXT.paneId) {
+            await callOnda('pane.focus', { id: ONDA_CONTEXT.paneId });
+        }
+        const params = mapping.mapParams
+            ? mapping.mapParams((args || {}))
+            : (args || {});
+        const result = await callOnda(mapping.method, params);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: 'text', text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// ─── Start ───────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[onda-mcp] Server started, socket: ${getSocketPath()}`);
+}
+main().catch((error) => {
+    console.error('[onda-mcp] Fatal error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mindfullabai/onda-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Onda terminal - control tabs, panes, terminals from AI agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "onda-mcp": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "homepage": "https://github.com/mindfullabai/onda-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mindfullabai/onda-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mindfullabai/onda-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "onda",
+    "terminal",
+    "ai-agent",
+    "model-context-protocol",
+    "claude"
+  ],
+  "author": "Mindfull AI <hello@mindfull.ai>",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && chmod +x dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}