# worker-mcp

`worker-mcp` is a Model Context Protocol (MCP) server that empowers a highly intelligent coordinator agent (like Claude 3.5 Sonnet or Gemini Pro) to spawn, control, and interactively guide lower-intelligence, locally hosted worker agents.

Instead of rolling a custom local LLM tool loop, `worker-mcp` delegates coding, bash, and filesystem operations to the **`pi` coding agent** (`@earendil-works/pi-coding-agent`) by running it in JSON-RPC mode. Since these small local models require significant supervision, `worker-mcp` acts as a gating and auditing harness.

---

## Features

- **Interactive Gating (Consent Hook)**: Automatically intercepts and blocks high-risk operations (e.g. executing shell commands or writing files) and prompts the coordinator for approval before execution.
- **MCP Tool Integration**: Standardized tools to spawn worker sessions, dispatch prompts, list active runners, and approve/deny pending commands.
- **Log and History Resources**: Message history and subprocess logs (including `stderr` feeds) are exposed as standard MCP resources.
- **Session Registry Persistence**: Session configurations and directory bindings survive server restarts via state files in `~/.config/worker-mcp/sessions.json`.
- **Automatic Extension Deployment**: Deploys its supervisor gate extension directly into `~/.config/worker-mcp/` and loads it explicitly when spawning the worker agent (leaving standalone `pi` agent runs unaffected).

---

## Installation & Usage

`worker-mcp` is published on npm as [@noosxe/worker-mcp](https://www.npmjs.com/package/@noosxe/worker-mcp). This is the recommended installation path for most users.

### 1. Install via npm (Recommended)

#### Option A: Global Installation

Install the package globally on your system:

```bash
npm install -g @noosxe/worker-mcp
# or using pnpm
pnpm add -g @noosxe/worker-mcp
```

Once installed globally, you can run the server using the `worker-mcp` command.

#### Option B: Run ad-hoc via npx

Alternatively, you can run the server on stdio immediately without installing it:

```bash
npx @noosxe/worker-mcp
```

---

### 2. Install via Nix

This project also provides a Nix flake to ensure consistent environments and easy installation.

#### Option A: Run Directly (Ad-hoc)

You can run the server on stdio immediately using Nix:

```bash
nix run github:noosxe/worker-mcp
```

#### Option B: Install to User Profile

Install the `worker-mcp` executable globally in your user profile:

```bash
nix profile install github:noosxe/worker-mcp
```

Once installed, run it with:

```bash
worker-mcp
```

---

### 3. Declarative Installation via Flake Overlay (System / Home Manager)

If you manage your operating system or user profile declaratively via NixOS or Home Manager, you can consume our default overlay.

#### Step 3.1: Add the Flake Input

Add `worker-mcp` to your system's `flake.nix` input section:

```nix
inputs = {
  nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";

  # Add worker-mcp input
  worker-mcp.url = "github:noosxe/worker-mcp";
};
```

#### Step 3.2: Configure the Overlay and Install

##### Option A: NixOS Configuration

Add the overlay to `nixpkgs` and include `worker-mcp` in your system packages:

```nix
outputs = { self, nixpkgs, worker-mcp, ... }@inputs: {
  nixosConfigurations.my-system = nixpkgs.lib.nixosSystem {
    system = "x86_64-linux"; # Or your system architecture
    modules = [
      ({ pkgs, ... }: {
        # Apply the overlay
        nixpkgs.overlays = [
          worker-mcp.overlays.default
        ];

        # Install the package
        environment.systemPackages = [
          pkgs.worker-mcp
        ];
      })
      ./configuration.nix
    ];
  };
};
```

##### Option B: Home Manager Configuration

Add the overlay to `nixpkgs` and install it in your user packages:

```nix
outputs = { self, nixpkgs, worker-mcp, ... }@inputs: {
  homeConfigurations.my-user = inputs.home-manager.lib.homeManagerConfiguration {
    pkgs = import nixpkgs {
      system = "x86_64-linux";
      overlays = [ worker-mcp.overlays.default ];
    };
    modules = [
      ({ pkgs, ... }: {
        # Install the package
        home.packages = [
          pkgs.worker-mcp
        ];
      })
      ./home.nix
    ];
  };
};
```

---

## Harness Integration (Antigravity CLI / `agy`)

To register the `worker-mcp` server with your Antigravity TUI/CLI (`agy`), follow these steps:

### Step 1: Register the Server via `mcp_config.json` (Declarative)

Antigravity CLI resolves MCP servers from dedicated configuration files (rather than the old `settings.json`). Add the configuration in one of the following locations:

- **Global Configuration**: `~/.gemini/config/mcp_config.json`
- **Project-local Configuration**: `.agents/mcp_config.json` (at the root of your project workspace)

#### Configuration file schemas:

##### Option A: If installed globally (via npm or Nix)

```json
{
	"mcpServers": {
		"worker-mcp": {
			"command": "worker-mcp",
			"args": []
		}
	}
}
```

##### Option B: If running ad-hoc via npx

```json
{
	"mcpServers": {
		"worker-mcp": {
			"command": "npx",
			"args": ["-y", "@noosxe/worker-mcp"]
		}
	}
}
```

##### Option C: If running ad-hoc via GitHub Flake

```json
{
	"mcpServers": {
		"worker-mcp": {
			"command": "nix",
			"args": ["run", "github:noosxe/worker-mcp?ref=main"]
		}
	}
}
```

##### Option D: Declarative Home Manager Configuration

If you manage your user configuration via Home Manager, you can declare the global `mcp_config.json` file in your `home.nix` using `home.file` combined with `builtins.toJSON`:

```nix
home.file.".gemini/config/mcp_config.json".text = builtins.toJSON {
  mcpServers = {
    worker-mcp = {
      # If installed via overlay in system/home packages or globally via npm:
      command = "worker-mcp";
      args = [];

      # Alternatively, if running ad-hoc via npx:
      # command = "npx";
      # args = [ "-y" "@noosxe/worker-mcp" ];

      # Alternatively, if running ad-hoc via Nix:
      # command = "nix";
      # args = [ "run" "github:noosxe/worker-mcp?ref=main" ];
    };
  };
};
```

### Step 2: Verify and Manage via TUI (`/mcp` command)

Once you have added the server configuration to `mcp_config.json`, you can manage it interactively inside the CLI:

1. Launch the Antigravity TUI:
   ```bash
   agy
   ```
2. Type the slash command `/mcp` in the prompt input and press `Enter`.
3. An interactive management overlay will open, showing `worker-mcp` in the list. You can inspect its status, trigger manual reloads, or verify that the tools/resources are successfully discovered by the coordinator agent.

---

## Operational Configuration

### Environment Variables

- **`WORKER_MCP_PI_PATH`**: Absolute path to the `pi` coding-agent binary (defaults to searching `PATH` for `pi`).

### Pre-requisites

Make sure you have the global `pi` coding-agent CLI installed in your local system:

```bash
npm install -g @earendil-works/pi-coding-agent
```

Configure your models in `pi` (e.g. using `pi --mode rpc` to set default models, or registering Ollama model definitions).

---

## MCP Reference

### Exposed Tools

- `spawn_pi_session`: Spawns a new supervisor-gated worker agent in the specified workspace directory.
- `send_pi_command`: Dispatches prompts to the worker session. Supports background MCP task execution (resolving asynchronously) or blocking mode with an optional timeout.
- `cancel_pi_command`: Aborts the currently running command in a session and cancels its background task.
- `list_pi_sessions`: Returns a list of active sessions, directory targets, and current states.
- `get_pending_actions`: Fetches the details of an intercepted command awaiting consent.
- `approve_action`: Approves execution of a gated tool call.
- `reject_action`: Blocks a gated tool call and forwards feedback to correct the agent's course.
- `set_risk_policy`: Updates the risk-based auto-approval policy for a session at runtime.
- `get_auto_approved_log`: Retrieves the audit log of actions that were auto-approved by the risk policy.

### Exposed Resources

- `worker-mcp://sessions/{sessionId}/history`: Returns the conversation log and internal message stream.
- `worker-mcp://sessions/{sessionId}/logs`: Returns the stdout/stderr trace logs of the subprocess.

---

## Local Development

If you are contributing to this codebase, you **must** enter the Nix development shell:

```bash
nix develop
```

This enters an environment pre-packaged with:

- **Node.js 24**
- **pnpm**
- **TypeScript**
- **Oxlint + Oxfmt (Oxc)**

### Dev Tasks

- **Code Quality (Check, Lint, Format)**: `pnpm run lint:fix`
- **Compile TypeScript**: `pnpm run build`
- **Run local server**: `pnpm run dev`
- **Build Nix Derivation**: `nix build`