<div align="center">
  <img src="assets/mark.svg" width="96" alt="Chatbottool MCP mark" />

  # Chatbottool MCP

  **Give AI useful tools—not the keys to your machine.**

  A local-first MCP workspace bridge with guarded files, controlled execution,<br>
  recoverable changes, and a deliberately narrow trust boundary.

  [![Node 22+](https://img.shields.io/badge/node-22%2B-59d4c8?style=for-the-badge&logo=node.js&logoColor=white)](#quick-start)
  [![MCP](https://img.shields.io/badge/protocol-MCP-67e8f9?style=for-the-badge)](#how-it-works)
  [![TypeScript](https://img.shields.io/badge/built_with-TypeScript-8b7cf6?style=for-the-badge&logo=typescript&logoColor=white)](src)
  [![License: MIT](https://img.shields.io/badge/license-MIT-d9c58a?style=for-the-badge)](LICENSE)
</div>

<img src="assets/chatbottool-mcp-hero.png" width="100%" alt="A luminous guarded bridge between an AI client and a local code workspace" />

---

## The idea

Local agents are useful because they can touch real files, run real tests, and
make real changes. That is also exactly what makes a careless bridge dangerous.

Chatbottool MCP puts a small, inspectable capability layer between the client
and the workspace.

<table>
  <tr>
    <td width="25%" valign="top">
      <h3>◇ Guarded paths</h3>
      Every file operation stays inside an explicitly allowed and opened workspace.
    </td>
    <td width="25%" valign="top">
      <h3>⌘ Controlled work</h3>
      Commands, tests, Git helpers, and network access follow separate policies.
    </td>
    <td width="25%" valign="top">
      <h3>↺ Recoverable change</h3>
      Checkpoints, trash-backed deletion, diffs, and continuity notes make work inspectable.
    </td>
    <td width="25%" valign="top">
      <h3>⬡ Client-neutral</h3>
      Use stdio locally or HTTP + OAuth with any compatible MCP client.
    </td>
  </tr>
</table>

## How it works

<div align="center">
  <img src="assets/architecture.svg" width="100%" alt="MCP client passes through Chatbottool policy controls before reaching a workspace" />
</div>

The client never receives ambient authority. It sees only the tools exposed by
the selected mode, and each tool still passes through path, process, network,
secret, and workspace checks.

| Layer | Responsibility |
|---|---|
| Workspace registry | Opens only roots already permitted by the server policy |
| Path guard | Blocks escapes, secret globs, symlink traversal, and case-confused paths |
| Tool policy | Chooses the visible capability surface: minimal, standard, or full |
| Execution layer | Runs commands, tests, Git helpers, previews, and managed processes |
| Recovery layer | Records audit events, checkpoints changes, and preserves continuity notes |
| Transport | Serves local stdio or authenticated streamable HTTP |

> [!IMPORTANT]
> This is a capability boundary, not a sandbox against a compromised operating-
> system account. Run it as an unprivileged user and keep allowed roots narrow.

## Two practical surfaces

| Mode | Tools | Intended use |
|---|---:|---|
| `standard` | **37** | Everyday reading, editing, structured commands, tests, safe Git writes, checkpoints, and continuity |
| `full` | **53** | Adds 16 opt-in capabilities for trusted clients and tightly scoped workspaces |

Full mode adds full shell, recoverable deletion, background processes,
repository initialization and branch recovery, Python module execution, direct
file placement, and allowlisted network fetch.

Tool visibility and shell policy are independent. For a trusted client that
needs `git clone` and package installation while retaining the guarded
destructive-command patterns, use `bashMode: "install"`. The configurable
`commandPath` exposes the intended Node/npm/Git installation to child commands.
See [Installer mode](docs/INSTALL-MODE.md) and the
[installer profile example](examples/chatbottool.installer.example.json).

The public edition deliberately contains **no browser automation, desktop
control, computer-use bridge, private service integration, or Git push tool**.

## Quick start

Requires Node.js 22.19+ (below Node 27), Git, and macOS or Linux.

```bash
git clone https://github.com/tamvi-journal/chatbottool-mcp.git
cd chatbottool-mcp
npm install
npm run build
node dist/cli.js init
```

The initializer creates a local policy file and a private owner password under
`~/.chatbottool-mcp/`.

### Local MCP clients

```bash
node /absolute/path/to/chatbottool-mcp/dist/cli.js serve-stdio
```

```json
{
  "mcpServers": {
    "chatbottool-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/chatbottool-mcp/dist/cli.js", "serve-stdio"]
    }
  }
}
```

### HTTP + OAuth

```bash
node dist/cli.js serve
```

The server binds to localhost by default and exposes `/mcp`, `/healthz`, and a
small status dashboard. Remote clients need a public HTTPS origin that you
operate; place the server behind a trusted reverse proxy or tunnel and set
`CHATBOTTOOL_PUBLIC_BASE_URL` to that origin.

## Tool families

| Family | Examples |
|---|---|
| Workspace | `open_workspace`, `ls`, `read`, `read_many`, `grep`, `glob` |
| Editing | `write`, `edit`, `apply_patch_many`, `copy_path`, `move_path`, `rename_file` |
| Execution | `run_command`, `run_test`, `run_build`, `run_pytest`, `run_npm_script`, `run_lint` |
| Git | `git_status`, `git_diff`, `git_add`, `git_commit`, `git_log`, `show_changes` |
| Recovery | `checkpoint_create`, `checkpoint_diff`, `checkpoint_restore` |
| Continuity | `continuity_save`, `continuity_load`, `handoff_note` |
| Local preview | `preview_local_app`, `collect_artifact` |

## Security defaults

- Common secret paths such as `.env`, SSH keys, PEM files, and private keys are blocked.
- Symlink escapes and case-only path confusion are rejected.
- Network fetch is full-mode only and requires an explicit hostname allowlist.
- HTTP MCP uses OAuth and host-header validation.
- Audit events redact common secret-bearing input fields.
- Shell, writes, tools, widgets, network hosts, and secret names have independent policies.

Read the complete [security model and deployment checklist](docs/SECURITY.md).

## Verify

```bash
npm test
npm run typecheck
npm audit --omit=dev
node dist/cli.js doctor
```

The suite verifies both published surfaces: exactly 37 standard tools and 53
full-mode tools, alongside workspace confinement, OAuth, secret blocking,
checkpoint recovery, audit redaction, and controlled Git behavior.

## Project status

Chatbottool MCP is an early public extraction. Its security boundaries and tool
surfaces are tested, but configuration and public APIs may evolve before `1.0`.

## License

MIT. See [LICENSE](LICENSE) and [NOTICE.md](NOTICE.md).

---

<div align="center">
  <sub>Power where it helps. Boundaries where they matter.</sub>
</div>