# Cli Bridge

> MCP server for Claude Desktop and other Model Context Protocol clients — sandboxed filesystem access (read/write/edit/search) plus Dev Mode-gated shell command execution, scoped to a single workspace root. Local-first, no cloud dependency, full audit logging. Built in TypeScript.

- **Type:** MCP server
- **Install:** `agentstack add mcp-anshupriyan-cli-bridge`
- **Verified:** Pending review
- **Seller:** [anshupriyan](https://agentstack.voostack.com/s/anshupriyan)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [anshupriyan](https://github.com/anshupriyan)
- **Source:** https://github.com/anshupriyan/cli-bridge

## Install

```sh
agentstack add mcp-anshupriyan-cli-bridge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# cli-bridge

**A local Model Context Protocol (MCP) server that gives Claude Desktop — or any MCP-compatible client — sandboxed filesystem access and gated shell command execution, scoped entirely to a single workspace root directory.**

  
  
  
  

  
  
  
  
  

---

## What is this?

`cli-bridge` is a lightweight MCP server that plugs into Claude Desktop (or any MCP client) and gives it:

- 📂 **Filesystem tools** — read, write, edit, search, and grep files, all confined to one workspace root
- 💻 **Shell execution** — run real commands on your machine, gated behind an explicit **Dev Mode** toggle
- 📝 **Project memory** — an append-only journal (`PROJECT_LOG.md`) so an agent can pick up context across sessions
- 🔒 **Audit logging** — every tool call recorded to a local log file, nothing sent anywhere else

Everything runs **locally, on your machine** — no external API calls, no cloud dependency, no telemetry.

---

## ⚠️ Dev Mode — Read Before Enabling Shell Execution

> [!CAUTION]
> `execute_command` can run **any executable available on your system**, with the **same permissions as the app hosting the MCP client**. This is real shell execution, not a sandbox.

| | |
|---|---|
| **Default state** | Dev Mode is **OFF** every time the server starts. `execute_command` is blocked before anything spawns. |
| **Turning it on** | Requires an explicit `toggle_dev_mode({ enable_dev_mode: true })` call — nothing enables it silently. |
| **Your responsibility** | Once enabled, any command run — including destructive ones (deleting files, modifying system state, installing software, network calls) — executes for real. **There is no command allowlist, no confirmation beyond your MCP client's own approval settings, and no undo.** |
| **Liability** | This project's author/developer is **not responsible** for data loss, system damage, security incidents, or any other consequence of enabling Dev Mode or using `execute_command`. Enabling it is a decision you make, at your own risk. |

Everything else — reading, searching, editing files in the workspace — works fully with Dev Mode left off. If you're unsure, leave it off.

---

## Features

🔍 Read-Only Tools (click to expand)

| Tool | Description |
|---|---|
| `read_file(path, start_line?, end_line?)` | Reads UTF-8 file contents, optional line-range support |
| `list_directory(path, recursive?)` | Lists directory contents (names, sizes, dir flags) |
| `search_files(pattern, path?)` | Recursive glob search (e.g. `*.ts`, `**/*.js`) |
| `grep_content(pattern, path?, case_sensitive?, max_results?)` | Fast fixed-string search via bundled `@vscode/ripgrep`, capped at `max_results` (default 50) |
| `get_dev_mode_status()` | Reports whether shell execution is ENABLED or BLOCKED |
| `get_recent_journal_entries(count?, project?)` | Reads the last N entries from `PROJECT_LOG.md` |

All tools are strictly confined to the workspace root directory.

✍️ Write & Execution Tools (click to expand)

| Tool | Description |
|---|---|
| `write_file(path, content)` | Overwrites/creates a file, auto-creates parent directories |
| `edit_file(path, old_str, new_str)` | Targeted find-and-replace; errors on zero or multiple matches |
| `execute_command(command, args, cwd?, timeout?)` | Shell execution, **gated by Dev Mode** — see warning above |
| `toggle_dev_mode(enable_dev_mode)` | Enables/re-locks shell execution for the current session only |
| `log_journal_entry(summary, files_changed?, commit_hash?, project?)` | Appends a structured entry to `PROJECT_LOG.md` |

---

## Security Architecture

```
┌─────────────────────────────────────────────┐
│              MCP Client (Claude)             │
└────────────────────┬──────────────────────────┘
                      │ tool calls
┌────────────────────▼──────────────────────────┐
│                  cli-bridge                    │
│  ┌───────────────────────────────────────────┐ │
│  │ 1. Path Confinement (resolveSafePath)      │ │
│  │ 2. Symlink Resolution (fs.realpathSync)    │ │
│  │ 3. Dev Mode Gate (execute_command only)    │ │
│  │ 4. Shell Metacharacter Scan (Windows only) │ │
│  │ 5. Audit Log Write (.cli-bridge-audit.log) │ │
│  └───────────────────────────────────────────┘ │
└────────────────────┬──────────────────────────┘
                      │ confined to
              /
```

- **Path Confinement** — every path (including command `cwd`) resolves strictly relative to the workspace root; traversal attempts are rejected.
- **Symlink Protection** — symlinks pointing outside the workspace boundary are resolved and blocked.
- **Dev Mode Gating** — `execute_command` is hard-blocked at the handler entry point until explicitly toggled on.
- **No Command Allowlist** — once Dev Mode is on, any executable on the host can run. See the warning above.
- **Shell Metacharacter Scanning** — Windows build-tool wrappers (`npm`, `npx`, `yarn`, `pnpm`, `tsc`, `jest`, `eslint`, `prettier`) run with `shell: true`; arguments are scanned for `& | ; $ > /.cli-bridge-audit.log` (timestamp, arguments truncated to 200 chars, status: `success` / `error` / `blocked`).

---

## Compatibility

| Platform | Status |
|---|---|
| 🪟 Windows 11 (x64) | ✅ Tested and verified |
| 🍎 macOS (arm64 / x64) | ⚠️ Architecturally supported (pure ESM + auto-resolved `ripgrep` binary), not yet live-tested |
| 🐧 Linux (x64) | ⚠️ Architecturally supported, not yet live-tested |

Windows-specific handling (the `.cmd`/`.bat` wrapper allowlist and shell-metacharacter scan) only applies when `process.platform === 'win32'`. On macOS/Linux, all commands spawn directly with `shell: false`. If you run this on macOS or Linux, feedback/issues are welcome.

---

## Token-Efficient Workflows

1. Use `grep_content` to locate keywords/functions before reading full files.
2. Use `read_file` with `start_line`/`end_line` once you have coordinates.
3. Use `edit_file` for targeted changes instead of rewriting whole files.
4. Use `git diff` / `git log` / `git show` via `execute_command` (Dev Mode required) to verify changes on disk.

---

## Project Journal

An append-only development log at `/PROJECT_LOG.md`, meant to be read by an agent at the start of a new session to recover prior context. Agents call `log_journal_entry` after completing work, including file lists and commit hashes.

---

## Installation

**Prerequisites:** Node.js v18.17.0+ (v20 or v24 LTS recommended)

```bash
npm install
npm run build
```

---

## Configuration in Claude Desktop

### Finding your config file (Windows)

Depending on how Claude Desktop was installed (standard installer vs. MSIX/Microsoft Store package), its configuration file location differs. You can run this PowerShell command to locate your `claude_desktop_config.json` automatically:

```powershell
Get-ChildItem -Path "$env:APPDATA\Claude\claude_desktop_config.json", "$env:LOCALAPPDATA\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json" -ErrorAction SilentlyContinue | Select-Object FullName
```

> [!NOTE]
> If neither path returns a result, the configuration file has likely not been created yet (which happens after opening Claude Desktop for the first time) or is installed in a non-standard location.

#### Manual File Paths Reference
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` (or `%LOCALAPPDATA%\Packages\Claude_...\LocalCache\Roaming\Claude\claude_desktop_config.json` for Store/MSIX installs)
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

### Registering cli-bridge

Add `cli-bridge` to the `mcpServers` object inside your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cli-bridge": {
      "command": "node",
      "args": [
        "/build/index.js",
        ""
      ],
      "env": {
        "WORKSPACE_ROOT": ""
      }
    }
  }
}
```

- Replace `` with the folder where you cloned `cli-bridge` (e.g. `C:/Projects/cli-bridge` on Windows or `/Users/username/Projects/cli-bridge` on macOS/Linux).
- Replace `` with the target project workspace folder you want `cli-bridge` to manage.

---

## Testing and Debugging

```bash
npx @modelcontextprotocol/inspector node build/index.js 
```

---

  Built as a local-first MCP tool. No cloud dependency, no telemetry, no data leaves your machine.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [anshupriyan](https://github.com/anshupriyan)
- **Source:** [anshupriyan/cli-bridge](https://github.com/anshupriyan/cli-bridge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-anshupriyan-cli-bridge
- Seller: https://agentstack.voostack.com/s/anshupriyan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.