<p align="center"><img src="assets/raccoon-128.png" width="72" height="72" alt="Raccoon icon"></p>

# Raccoon MCP / 浣熊 MCP

A local-first Model Context Protocol (MCP) server for AI-assisted development, files, processes, optional Windows desktop automation and Android tools.

面向开发者的独立本地 MCP 服务。**无需安装燕子 / OpenQuickHost，也无需云服务器或域名。**

## Windows quick start / Windows 快速安装

Prerequisites: Windows 10/11, **Node.js 22.16+**, npm, PowerShell 5.1+. Git is only needed for cloning; you can also download the ZIP.

~~~powershell
git clone https://github.com/luoluoluo22/raccoon-mcp-public.git
cd raccoon-mcp-public
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1
npm run doctor
~~~

The installer runs npm ci; creates a workspace under your user profile; generates a private 256-bit local token; writes a git-ignored .env; and starts a loopback-only HTTP MCP server on port 3766. Default settings are **read-only**, **Shell disabled**, and **restricted to the workspace**. It never overwrites an existing .env.

可指定工作区、端口，或仅安装而暂不启动：

~~~powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-windows.ps1 -Workspace 'D:\Workspace' -Port 3877 -NoStart
~~~

Start/stop and optional login auto-start:

~~~powershell
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\local.ps1 status
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\local.ps1 start
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\local.ps1 stop
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\local.ps1 install-autostart
~~~

The URL http://127.0.0.1:3766/mcp is **local-only**. Cloud-hosted ChatGPT cannot connect to it directly. For remote access use your own secure HTTPS tunnel and OAuth, explained in [部署文档](DEPLOYMENT.zh-CN.md).

## Linux / macOS

Core Node.js file, process, development and MCP transport tools can run on supported Node.js hosts; Windows PowerShell services, GUI automation and screenshots need Windows. Install dependencies using npm ci, copy the provided .env.example to a private .env, set RACCOON_ROOT to an existing isolated workspace and RACCOON_TOKEN to a random secret, then start:

~~~bash
npm ci
cp .env.example .env
# edit the private .env first
npm run start:http
# or use npm start for stdio
~~~

For Linux/macOS, check availability of any optional native components you intend to use. Windows task automation is not cross-platform.

## Features

- Scoped file access, reading/writing/patching, batch operations and rich document helpers
- Explicitly enabled Shell, build/test steps, persistent process sessions, Git automation and development pipelines
- Streamable HTTP and stdio MCP transports, local health checks and OAuth for optional remote ingress
- Optional ADB tools, Windows foreground/UI automation and visual inspection
- Optional outbound self-hosted relay with persistent queue and reconnect support

## Safety

The Windows installer defaults to RACCOON_READ_ONLY=1, RACCOON_ENABLE_SHELL=0, RACCOON_FILESYSTEM_UNRESTRICTED=0, RACCOON_HOST=127.0.0.1. Modify these only after reading [Security policy](SECURITY.md). RACCOON_ROOT is a file-tool boundary, not a Shell sandbox; enabling Shell grants the current Windows user privileges to commands. Never commit local .env, .raccoon-runtime, device tokens or personal data.

## Docs and verification

- [完整安装、依赖、ChatGPT / Cloudflare 接入与排错](DEPLOYMENT.zh-CN.md)
- [可选独立中继架构](RELIABILITY.zh-CN.md)
- [开发执行引擎](EXECUTION-ENGINE.zh-CN.md)
- [流水线](PIPELINES.zh-CN.md)
- [安全策略](SECURITY.md)

~~~bash
npm run check
npm test
npm run verify
~~~

The full verify suite can use extra optional native tools for smoke tests. The project currently reports package version 0.8.0 and runs GitHub Actions checks on Windows and Linux.

Old scripts named install-standalone.ps1 or handoff-yanzi-manager.ps1 are **migration utilities** for pre-existing local installations, not the default installation workflow.

MIT License.