freebuff-mcp
# Freebuff MCP

Watch the [short video](docs/media/freebuff-mcp-explainer.mp4) to see the path from request to finished work.
Freebuff MCP lets Codex, Claude Code, plus other MCP apps work with Freebuff Desktop plus its command line app on your computer. It can find projects, read threads, send a request, show progress, read ordinary project files, plus stop work when the app asks.
MCP is a shared way AI apps connect to tools on your computer.
Your computer runs the bridge. Your Freebuff installation controls access to your projects. The bridge does not read process memory. It does not remove Freebuff approval steps. Text returned to an MCP app has common secret patterns masked. Pattern checks can miss unusual secrets. Do not treat them as a complete security boundary.
## Start here
Node.js 22 or newer is required. Install Freebuff Desktop. The command line app works too. Sign in before connecting an MCP app.
```sh
npm install --global freebuff-mcp
freebuff-mcp doctor
```
The doctor report shows whether Desktop is found, whether it allows changes, whether the command line app is available, plus whether its terminal component works. A found app can still be signed out. A missing terminal component can block command line sessions. Check the report before setting up an MCP app.
## Connect an MCP app
Codex setup prints its settings entry.
```sh
freebuff-mcp install codex
```
Claude Code setup prints its instructions.
```sh
freebuff-mcp install claude
```
The automatic write option adds the entry to your app settings. It preserves other settings. It refuses to replace a different Freebuff entry.
## What you can ask it to do
The bridge can find projects and threads, search visible thread metadata or one thread's messages, read thread messages in full or in pages, start a request, continue earlier work, show live progress, stop a turn, resume a paused thread, change model settings, inspect changed files, and read project files. Attachment metadata is available when the owning backend exposes it.
The tools are grouped around the work you can do:
- Find projects and threads with `list_projects`, `list_threads`, `list_threads_page`, `search_threads`, and `get_active_work`. Use `search_threads_page` when a metadata search has many matches. Search one conversation with `search_thread_messages`. Read a thread with `get_thread`, `get_thread_settings`, or `get_thread_messages`. Use `get_thread_messages_page` for bounded results and continue with its `nextOffset` while `hasMore` is true.
- Read files with `list_project_files` and `get_project_file`. The older `read_project_file` name remains available. Thread attachment metadata is available through `list_thread_attachments`.
- Start or attach to a session with `create_thread`. The older `start_thread` name remains available. Send a request with `send_message` and follow it with `get_turn` or `watch_turn`, or use `run_turn` to wait for its result.
- Follow work with `get_thread_progress`, `watch_thread`, `get_thread_progress_summary`, and `watch_active_threads`. Review changed paths and Desktop diffs with `get_changed_files`, `get_changes`, and `get_diff`.
- Stop work with `stop_turn` or `stop_thread`, resume with `resume_thread`, and request model or reasoning changes with `set_model` and `set_reasoning`. `get_freebuff_status` reports connection, authorization, and actions the bridge supports, including whether the selected backend can list attachment metadata. The older `freebuff_status` name remains available.
- `search_history` remains available as a compatibility name for `search_threads`. `list_models` remains available as a compatibility name for `get_model_catalog_status`. Current Freebuff backends do not provide a standalone model catalog, so use `get_thread_settings` for the model reported on a thread. Freebuff still controls which models your account can use.
The bridge keeps compatibility names for existing clients. New integrations should use `get_freebuff_status`, `get_project_file`, `create_thread`, `search_threads`, and `get_model_catalog_status` as the canonical names.
MCP tool definitions include parameter descriptions and explicit read, write, repeatability, and external-system hints. Agent-run tools are marked as potentially destructive because Freebuff may edit files or run commands. A backend may omit settings it cannot report; the settings tool lists those fields as unavailable instead of guessing. Project creation and thread deletion are not exposed because the supported Freebuff interfaces do not provide verified operations for them.
`get_diff` reports whether its paths came from a Desktop change summary, bridge progress events, or no available source. Event-derived paths may omit earlier changes; an unavailable source is reported instead of looking like an empty change list. A file-filtered request also says whether that path was found.
`run_turn` stays open while Freebuff works. It reports progress while the turn runs. When the MCP app cancels the request, the bridge asks the owning Freebuff backend to stop. A local cancel alone does not prove the work stopped.
Freebuff can ask you to approve a step. The turn stays marked as waiting. Resume checks the same thread. The bridge marks the turn complete only after Desktop confirms a finish. Use `stop_turn` to stop a waiting turn. Command line resume may not prove that the original work finished. The bridge keeps that turn open when its result is uncertain.
Progress arrives in pages. Each returned cursor points to the last event in that page. Use it to read the next page without skipping events. Page size is limited to keep replies manageable.
## Local connection plus remote connection
The default connection uses standard input plus output. This works well when your MCP app runs on the same computer.
An optional remote web connection is available through Streamable HTTP.
```sh
freebuff-mcp serve-http
```
It listens on `127.0.0.1` port `8788`. Requests need the token in `FREEBUFF_MCP_TOKEN`. Remote binding also needs `FREEBUFF_MCP_ALLOW_REMOTE=1`. Remote use needs trusted HTTPS. A private network also works. Keep the access token private. The remote server still needs access to Freebuff on the computer where the bridge runs.
ACP is another tool connection format. This project's ACP support is experimental. Use MCP to do normal work.
## When a connection fails
Run the doctor first. Desktop can be visible while change access remains unavailable. Restart Freebuff Desktop, reopen the project, then run the doctor again if its permission is missing. Check that the command line app is installed plus signed in if Desktop cannot accept changes. Managed command line sessions need the terminal component.
## Security plus privacy
File reads stay inside the selected project. Credential files are denied. Binary content is denied. Reads stop at one megabyte. Common passwords, access tokens, authorization headers, URLs, plus private key text are masked before they reach the AI app. Fields named password, token, secret, API key are masked too. No text pattern can find every possible secret. Review sensitive project data before sharing it with a model.
Read [the security notes](SECURITY.md) plus [the privacy notes](PRIVACY.md) before using the bridge with private work.
## Project health

The figures above come from the local suite run on this source revision. They describe automated checks. They do not prove live compatibility with every Freebuff version. The Desktop plus command line acceptance steps are in [the acceptance checklist](docs/acceptance_checklist.md).
## Build from source
CI covers the maintained Node.js LTS lines 22, 24, and 26 on Windows, macOS, and Linux.
```sh
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
```
The automated suite uses fake Desktop plus command line services. It checks protocol behavior, event paging, cancellation, redaction, setup, plus error handling. It cannot prove that a signed in installation works on your computer. Use the acceptance checklist to record that separately.
## Learn more
Read [the changelog](CHANGELOG.md) to see release history. Read [the license](LICENSE) before you share changes to this project.
TDQS
Scored across 14 tools
Each tool targets a distinct resource/action: status, projects, threads, messages, active work, files, models, and thread controls are clearly separated. get_thread vs get_thread_messages and send_message vs resume_thread are differentiated by metadata/content and new-prompt vs resume semantics.
Most tools follow a verb_noun snake_case pattern (list_*, get_*, send_message, set_model), which is predictable. The main outlier is freebuff_status, which lacks a verb, and read_project_file introduces a minor verb variation versus get_*.
At 14 tools, the surface is well-scoped for a Freebuff bridge: discovery/status, project/thread inspection, file access, model listing, messaging, and turn control each have a place. No tool feels redundant or bloated.
The set covers the main inspect-and-interact workflow: list/read threads and files, send messages, stop/resume turns, and configure model/reasoning. Obvious gaps are thread/project creation/deletion and explicit per-thread model/reasoning read-back, though these may be intentionally outside the bridge's scope.