How do I use freebuff-bridge?

This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

freebuff-bridge

by toyro396133

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

freebuff-bridge

A communication server for Freebuff Desktop — a bridge between agents/scripts and Desktop sessions.

English · עברית (README.he.md)

Any tool or script (any language, any platform) can open a new session or talk to an existing agent session, watch live activity, and manage work — all over HTTP, MCP, or a Web UI.

   ┌─────────────────┐    HTTP + SSE     ┌────────────────────┐
   │  bridge (7777)  ├──────────────────►│ orchestrator (dynamic) │  ← Freebuff Desktop
   │  bun + Hono     │  /api/threads      └─────────┬──────────┘
   │  reads DB       │  /api/thread/:id/message
   │  writes via API │                                │
   │  streams SSE    │                                ▼
   └────────┬────────┘                  ┌────────────────────┐
            │ reads                     │   SQLite (.freebuff)│
            ▼                           └────────────────────┘
   ┌─────────────────┐
   │  <project>/     │
   │  desktop-v2.db  │  ← Freebuff's own DB per project
   └─────────────────┘

The bridge talks to both the orchestrator (live) and the SQLite audit log (offline), and keeps working even if one of them is unavailable (falls back to DB-only mode with a fallback flag).

Features

Area	What you get
REST API (`/v1/*`)	Threads CRUD, send prompts, stop/resume, switch model/harness live, queue control, SSE streams, wake
MCP server (stdio)	14 tools (`list_projects`, `send_prompt`, `resume_thread`, `set_agent`, `wake_freebuff`, queue tools…) for Claude Code / Cline / any MCP agent
Web UI (port 7778)	RTL Hebrew dashboard — projects, all threads, single-thread view with state + queue + action buttons
Wake on demand	`POST /v1/wake` launches `Freebuff.exe` if it's down; `send_prompt`/`enqueue_prompt` auto-wake the app instead of failing
Self-healing	Discovers the orchestrator's dynamic port from its log; re-resolves on port change mid-run; SSE streams reconnect automatically
Version compatibility	Reads the installed Freebuff version, checks it against a verified table, warns in banner + `/v1/info` + UI
Shape probe	Validates the live `/api/projects` schema at startup against the verified contract — catches drift even inside a "verified" version
Windows services	Runs 24/7 via nssm (`FreebuffBridge` on 7777, `FreebuffBridgeUi` on 7778)
Examples	Copy-paste recipes in 4 languages (Python, bash, PowerShell, make)

Related MCP server: libredesk-mcp

Quick install

# Prerequisite: Bun (https://bun.sh)
bun install
bun run init                 # creates ~/.config/freebuff-bridge/instances.json
bun run serve                # listens on 127.0.0.1:7777 (localhost-noauth)

# checks
bun run typecheck            # tsc --noEmit
bun run test                 # 175 tests across 10 files

That's it — the bridge is live. Open the Web UI:

bun run ui                   # Hono JSX + RTL Hebrew on 127.0.0.1:7778
# → open http://127.0.0.1:7778/

One-liner smoke test

curl -s http://127.0.0.1:7777/v1/info | jq .

curl examples

Reads

# health + self info (includes orchestrator, freebuff version, shape probe)
curl http://127.0.0.1:7777/v1/info

# all configured machines
curl http://127.0.0.1:7777/v1/instances

# all projects the orchestrator sees
curl http://127.0.0.1:7777/v1/projects

# threads of one project
curl "http://127.0.0.1:7777/v1/projects/C:/path/to/project/threads"

# a specific session (from the DB)
curl http://127.0.0.1:7777/v1/threads/<THREAD_ID>

# recent messages of a session
curl "http://127.0.0.1:7777/v1/threads/<THREAD_ID>/messages?limit=20"

Writes (go through the live orchestrator)

# open a new session in a chosen project
curl -X POST http://127.0.0.1:7777/v1/threads \
  -H 'content-type: application/json' \
  --data-raw '{"title":"[bridge] test","projectPath":"C:/my-project","harnessId":"codebuff","model":"deepseek/deepseek-v4-flash"}'

# send a prompt to a session (endpoint is /message, not /prompt)
curl -X POST http://127.0.0.1:7777/v1/threads/<THREAD_ID>/message \
  -H 'content-type: application/json' \
  --data-raw '{"text":"Check my email"}'

# stop a running turn
curl -X POST http://127.0.0.1:7777/v1/threads/<THREAD_ID>/stop

Resume a stuck session & switch model in real time

# bring a session back from paused → running
curl -X POST http://127.0.0.1:7777/v1/threads/<THREAD_ID>/resume
# → {"ok":true,"thread":{...}}

# switch only the model (harnessId is auto-filled from current state)
curl -X PATCH http://127.0.0.1:7777/v1/threads/<THREAD_ID> \
  -H 'content-type: application/json' \
  --data-raw '{"model":"openai/gpt-5.6-luna"}'

# switch model + harness together
curl -X PATCH http://127.0.0.1:7777/v1/threads/<THREAD_ID> \
  -H 'content-type: application/json' \
  --data-raw '{"harnessId":"codebuff","model":"deepseek/deepseek-v4-flash"}'

# un-pause via PATCH (alias)
curl -X PATCH http://127.0.0.1:7777/v1/threads/<THREAD_ID> \
  -H 'content-type: application/json' \
  --data-raw '{"queuePaused":false}'

⚠️ PATCH gotchas:

When changing only model, the bridge reads current state first to fill in harnessId — the orchestrator requires both together.
If the model is rejected by your tier (rejected: true), the thread gets model: null and the previous value is lost. Always check thread.model in the response.
The orchestrator endpoint is /api/thread/<id>/agent, not /model (verified against the live bundle).

Wake Freebuff Desktop on demand

curl -X POST http://127.0.0.1:7777/v1/wake
# → {"ok":true,"alreadyRunning":false,"exePath":"C:/.../Freebuff.exe","port":53810,"elapsedMs":4210}

When the orchestrator is down and autoWake is on (default), send_prompt / enqueue_prompt launch Freebuff automatically and retry once instead of returning 502.

Queue control

# list a session's queue (pending + done, sorted by position)
curl http://127.0.0.1:7777/v1/threads/<THREAD_ID>/queue
# → {"thread":{...}, "items":[{id, state, prompt, position, ...}], "pending":N}

# enqueue a prompt (runs when the current turn finishes)
curl -X POST http://127.0.0.1:7777/v1/threads/<THREAD_ID>/queue \
  -H 'content-type: application/json' \
  --data-raw '{"text":"collect today's PRs","label":"pr-digest"}'

# reorder (lower position = runs earlier)
curl -X POST http://127.0.0.1:7777/v1/threads/<THREAD_ID>/reorder \
  -H 'content-type: application/json' \
  --data-raw '{"id":"<ITEM_ID>","position":-1}'

# edit a queued item's prompt before it runs
curl -X POST http://127.0.0.1:7777/v1/queue/<ITEM_ID>/edit \
  -H 'content-type: application/json' \
  --data-raw '{"prompt":"rewritten prompt text"}'

# delete from queue
curl -X POST http://127.0.0.1:7777/v1/queue/<ITEM_ID>/delete

# promote to the front (runs immediately)
curl -X POST http://127.0.0.1:7777/v1/queue/<ITEM_ID>/send-now

⚠️ Queue rules:

If queuePaused=true, items accumulate and don't run until you call resume_thread (or PATCH {"queuePaused":false}).
If queuePaused=false, items run as soon as the current turn finishes (auto-promote to running).
reorder can fail with 409 "item is not queued" once the item is already running/done.

Live events (SSE)

# all orchestrator events
curl -N -H 'accept: text/event-stream' http://127.0.0.1:7777/v1/events

# events for one session
curl -N -H 'accept: text/event-stream' http://127.0.0.1:7777/v1/threads/<THREAD_ID>/stream

Running as Windows services (24/7)

The bridge and the Web UI can run as Windows services via nssm — auto-start with the machine, restart-on-crash, logs to .freebuff/, and wake Freebuff automatically when there is work.

# one-time: install nssm
winget install -e --id NSSM.NSSM

# install (elevated)
powershell -ExecutionPolicy Bypass -File .\install-service.ps1        # FreebuffBridge (API, 7777)
powershell -ExecutionPolicy Bypass -File .\install-ui-service.ps1     # FreebuffBridgeUi (UI, 7778)

# uninstall (elevated)
powershell -ExecutionPolicy Bypass -File .\uninstall-service.ps1
powershell -ExecutionPolicy Bypass -File .\uninstall-ui-service.ps1

Why nssm? sc create alone can't work here — bun.exe never registers with the Service Control Manager, so SCM kills the service after 30 seconds (error 1053). nssm is the standard wrapper that manages bun as a child process.

LocalSystem + paths: services run as SYSTEM, so env overrides (FREEBUFF_BRIDGE_APPDATA, FREEBUFF_BRIDGE_LOCALAPPDATA, FREEBUFF_BRIDGE_WAKE_EXE) are written to the service's Environment value (REG_MULTI_SZ — the official SCM mechanism). Note: do not use nssm AppEnvironmentExtra — any nssm set call replaces the whole list.

The tray icon (bun run tray) detects when the services already hold ports 7777/7778 and doesn't start duplicate copies.

MCP server for external agents (Claude Code / Cline)

The bridge exposes an MCP server on stdio that talks directly to Claude Code / Cline / any MCP-aware agent. 14 tools are defined:

Session control (7): list_projects · list_threads · get_thread · send_prompt · stop_thread · resume_thread · set_agent

Wake (1): wake_freebuff

Queue control (6): list_queue · enqueue_prompt · reorder_queue_item · edit_queue_item · delete_queue_item · send_queue_item_now

Use it from Claude Code (~/.claude/mcp.json):

{
  "mcpServers": {
    "freebuff-bridge": {
      "command": "bun",
      "args": ["run", "C:/path/to/freebuff-bridge/src/bridge/mcp.ts"]
    }
  }
}

Make sure the bridge is running first: bun run serve. The MCP server connects automatically to http://127.0.0.1:7777.

Security

Default bind: 127.0.0.1 (loopback only). The bridge does not expose itself to the network.
localhost-noauth mode (default): any local process can talk without a token.
strict mode: requires Authorization: Bearer <token>. Every instance in instances.json gets a unique token.
Admin token via env var (FREEBUFF_BRIDGE_ADMIN_TOKEN) grants access to every instance.
Per-alias env override: FREEBUFF_BRIDGE_TOKEN_<ALIAS_UPPER> takes priority over the file.

# strict + admin token
FREEBUFF_BRIDGE_HOST=0.0.0.0 FREEBUFF_BRIDGE_BIND_MODE=strict \
FREEBUFF_BRIDGE_ADMIN_TOKEN=$(openssl rand -hex 32) \
  bun run serve

Project structure

src/
  bridge/
    db.ts            # SQLite + WAL/NORMAL/busy_timeout + typed reads
    instances.ts     # config store (load/save/find/env-override)
    auth.ts          # bearer header regex + decideAuth()
    ratelimit.ts     # sliding-window in-memory limiter
    orchestrator.ts  # HTTP client to Freebuff's orchestrator (dynamic port discovery)
    projects.ts      # multi-project discovery (.../.freebuff scan)
    wake.ts          # find exe + discover port from log + spawn + poll
    compat.ts        # installed Freebuff version (asar/exe) + compat table
    shape.ts         # /api/projects schema probe (validate + HTTP)
    server.ts        # Hono REST API (/v1/*) — reads DB, writes via orchestrator
    mcp.ts           # MCP stdio server — 14 tools that proxy /v1/*
  web/
    ui.tsx           # Hono JSX server (7778) — SSR HTML + 9 POST actions + SSE
    views/           # layout, projects, threads, thread, queue views
  cli/
    serve.ts         # bun run serve (main entry — bridge on 7777)
    ui.ts            # bun run ui (Web UI on 7778)
    tray.ts          # bun run tray (Windows tray icon)
  tray/
    tray.ps1         # PowerShell NotifyIcon + context menu + health poller
tests/               # 10 files, 175 tests
examples/            # copy-paste integrations in 4 languages

Windows notes

bun:sqlite opens with journal_mode=WAL, synchronous=NORMAL, busy_timeout=5000ms, and foreign_keys=ON so it never collides with the Desktop running in parallel.
Hebrew/UTF-8 paths are supported.
The orchestrator port is dynamic in current builds — the bridge reads it from %APPDATA%\Freebuff\logs\orchestrator-stderr.log (line listening on http://127.0.0.1:PORT). Manual check: curl http://127.0.0.1:<PORT>/api/projects should return JSON, or just GET /v1/info and look at the orchestrator field.

Git

bun.lockb is meant to be committed — don't add it to .gitignore.

This server cannot be deployed

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Related MCP Connectors

JiZhiMCP B
io.github.alanwang100
Host any HTTP API as a standard MCP server; auto-distribute to 12+ mainstream agent platforms.
Developer Tools Agent Orchestration
211
https://mcp.xn--5kvtwv52d.com/mcp/gateway
Flowra
io.github.flowradev
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Agent Orchestration Autonomous Agents
11
https://mcp.flowra.dev/mcp
OneSchema MCP Server
co.oneschema
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Data Platforms App Automation
1
https://api.oneschema.co/mcp
AgentMarketplace A
io.github.raditotev
MCP Server for an Agent Task Marketplace
Autonomous Agents Agent Orchestration
221
https://agent-marketplace.radi.pro/mcp

Related MCP Servers

ACP-MCP-Server
Agent Orchestration Communication
GongRzhe
A
license
B
quality
F
maintenance
A bridge server that connects Agent Communication Protocol (ACP) agents with Model Context Protocol (MCP) clients, enabling seamless integration between ACP-based AI agents and MCP-compatible tools like Claude Desktop.
Updated a year ago (2025-06-18 08:48 UTC)
16
92 PyPI
24
MIT
libredesk-mcp
Customer Support Communication
metanmai
A
license
C
quality
D
maintenance
MCP server that exposes the complete Libredesk REST API (54 endpoints) as tools, enabling natural language management of conversations, contacts, agents, teams, and more for the open-source customer support desk.
Updated 5 months ago (2026-06-06 08:28 UTC)
54
8 npm
4
MIT
genesys-mcp
Customer Support App Automation Communication
outboundani
A
license
Not graded
quality
B
maintenance
MCP server for Genesys Cloud that enables AI assistants to build and manage queues, skills, users, wrap-up codes, and Architect flows, including a flow builder that renders diagrams and publishes via Genesys' validation pipeline.
Updated 23 days ago (2026-10-12 21:04 UTC)
20
MIT
MCP Proxy Server
Agent Orchestration Developer Tools Networking & Infrastructure
zDaniels437
A
license
Not graded
quality
A
maintenance
Enables connecting and managing multiple backend MCP resource servers of Stdio, SSE, and Streamable HTTP types, then exposing their aggregated tools and resources through unified SSE/HTTP endpoints or as a single Stdio server. It routes requests to the appropriate backend and supports optional web admin management, authentication, and concurrent client connections.
Updated 18 days ago (2026-10-17 09:50 UTC)
104 npm
MIT

freebuff-bridge

Features

Quick install

One-liner smoke test

curl examples

Reads

Writes (go through the live orchestrator)

Resume a stuck session & switch model in real time

Wake Freebuff Desktop on demand

Queue control

Live events (SSE)

Running as Windows services (24/7)

MCP server for external agents (Claude Code / Cline)

Security

Project structure

Windows notes

Git

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

ACP-MCP-Server

libredesk-mcp

genesys-mcp

MCP Proxy Server