<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.

</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.

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.

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

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

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

HTTP + OAuth

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.

Verify

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 and NOTICE.md.

---

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