Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
npx -y [email protected]Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
claude mcp add io.github.guobug-ferrycat -- npx -y ferrycat@0.5.0รันในเทอร์มินัล
{ "mcpServers": { "io.github.guobug-ferrycat": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดFerryCat (
ferrycat) is a lightweight, deterministic cross-host AI agent handoff and code review bus built on the Model Context Protocol (MCP) and Node.js built-innode:sqlite(WAL mode).
Purpose-built to safely bridge isolated desktop IDE agent hosts (such as Google Antigravity, WorkBuddy, Claude Code, and Cursor) across separate OS processes without context drift or blind reviews on stale files. 📖 Deep Dive: Why I Started Building FerryCat: When Two AI Coding Hosts Live on the Same Desktop
No IDE setup or config file edits required. Watch the entire deterministic loop execute inside an isolated sandbox in ~2 seconds:
npx ferrycat demo
⚡ FerryCat Zero-Config Sandbox Demo ⚡
✔ [1/4] Contract Dispatched Locked: src/calc.ts (sha256: ce3ba9a5...bc5d)
✔ [2/4] Contract Claimed Lease: 7424261d-9a3f-4a86-a7ff-de278c273e96
✔ [3/4] Execution & Check Heartbeat 1 renewal | CHANGES_REQUESTED (loose equality caught)
✔ [4/4] Contract Completed TOCTOU: 0 dirty files | Status: COMPLETED (elapsed: 2.1s)
🎉 End-to-end multi-agent handoff verified successfully!
💡 Real benchmark: spins up child process, triggers 1 real lease renewal, catches loose equality at
src/calc.ts:6. Options (--keep/--json/--no-color) detailed in Quickstart §0.
While the official MCP Tasks specification (2025-11 / 2026-07) addresses long-running operations within a single Client ↔ Server connection, it does not solve cross-host collaboration on a developer workstation:
stdio Process Isolation: Desktop IDEs spawn local MCP servers as independent child processes with isolated memory spaces and distinct Node.js runtimes.Stale Context): When handing off a task from Host A to Host B, unushed IDE buffers, branch switches, or mid-review edits cause the receiving agent to audit outdated code and produce plausible but invalid conclusions.FerryCat resolves these failure modes through a human-scheduled, contract-driven SQLite WAL bus:
[Developer] [Host A: Antigravity] [~/.ferrycat/mesh.db] [Host B: WorkBuddy]
| | | |
|-- 1. "Dispatch review" --->| | |
| |-- dispatch_contract() -------->| Write status = SUBMITTED |
| | (Full SHA-256 + Line Bounds) | Store size / sha256 snapshot |
| | | |
|-- 2. Switch IDE: "Poll" ---|--------------------------------|------------------------------>|
| | |<-- poll_next_task() ----------|
| | | (Atomic claim changes===1 |
| | | + Verify disk SHA-256) |
| | | |-- Read local files
| | |<-- fulfill_contract() --------|-- Re-verify SHA-256
| | | (Validate Ajv JSON Schema | & submit JSON
| | | -> status = COMPLETED) |
| | | |
|-- 3. Switch IDE: "Inspect" | | |
| |-- inspect_mesh_state() ------->| Read-only query of COMPLETED |
|<-- Present structured res -| | |
Every state transition is bound to an explicit SQL transaction with optimistic concurrency control (changes === 1), eliminating phantom or dangling states:
dispatch_contract()
│
▼
┌───────────┐
│ SUBMITTED │ (Queue TTL: default 1800s)
└─────┬─────┘
│
poll_next_task()
┌────────────────┼────────────────┐
│ (Queue TTL) │ (Hash Match) │ (Missing / Size Diff / SHA-256 Mismatch)
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────────┐
│ TIMED_OUT │ │ CLAIMED │ │ POINTER_STALE │ (Terminal: Rejects blind review)
└───────────┘ └─────┬─────┘ └───────────────┘
▲ │ (Exec TTL: default 300s)
│ fulfill_contract()
│ ┌────────────────┼────────────────┬────────────────┐
└──┤ (Exec TTL) │ (Schema Valid) │ (Retries > 2) │ (Mid-Review File Edit)
│ ▼ ▼ ▼
│ ┌───────────┐ ┌───────────────────┐ ┌───────────────┐
└──────────│ COMPLETED │ │ VALIDATION_FAILED │ │ POINTER_STALE │
└───────────┘ └───────────────────┘ └───────────────┘
Holder-side lifecycle controls on a CLAIMED contract (all require agent_id === target_agent):
dispatch_contract reads target files on disk, recording byte size, full-file sha256 (64 hex chars), first_line, and last_line. If a file was modified within the last 3 seconds, a warning is emitted to alert the requester of potential unsaved IDE buffers.poll_next_task verifies Existence -> Byte Size -> Full-File SHA-256 (never rejecting on mtime_ms alone to tolerate no-op IDE saves). On mismatch, it waits 150ms and retries once to rule out transient IDE flushes before marking the contract POINTER_STALE.verify_contract): A strictly read-only check allowing workers or scripts to audit pointer health (valid: true vs valid: false with dirty files list) before submitting.fulfill_contract checks on-disk pointer fingerprints. If dirty pointers are detected:
RETRY_NEEDED, leaves the contract CLAIMED, renews the execution window, and lists dirty files with recovery instructions (git stash / git checkout -- <file>).POINTER_STALE and saves the full submitted review payload into salvaged_result_json so review effort is never lost.poll and at fulfill) drastically narrows the TOCTOU window from minutes of blind review down to the sub-millisecond atomic SQL transition boundary.RETRY_NEEDED $\le 2$)["/passed: must be boolean"]).RETRY_NEEDED while keeping the contract CLAIMED for immediate self-correction (each rejection also renews the execution window); a 3rd failure transitions the contract to terminal VALIDATION_FAILED.queue_ttl_sec (default 1800s for SUBMITTED) from exec_ttl_sec (measured from claimed_at), preventing tasks claimed late in the queue window from timing out prematurely during execution.exec_ttl_sec defaults are tiered by task_type: code_review / architecture_audit → 1800s (deep reasoning or human-in-the-loop), implementation / test_generation → 300s. An explicit exec_ttl_sec always wins.poll_next_task executes a lock-free SELECT COUNT(*) probe before attempting any UPDATE on expired rows; inspect_mesh_state is strictly read-only.workspace_root and blocks sensitive file patterns (.env*, *.pem, *.key, id_rsa*, *credentials*, *secret*, .npmrc, .git/config) on both dispatch and worker verification paths.workspace_root is strongly recommended to be passed as an absolute path. If a relative path is provided, it is deterministically resolved against process.cwd() via path.resolve.workspace_root) and SQLite database (~/.ferrycat/mesh.db).assertSafePointerPath) and sensitive file pattern filters prevent unintentional workspace escapes, symlink traversals, or accidental leakage of credentials/secret files during handoffs.ferrycat-cli daemon), handler scripts are invoked directly via execFile. Write permissions to ferrycat.config.json or handler script paths are equivalent to host execution privileges (ADR-0005 §2.2). Keep configurations local and version-controlled.AGENT_NAME.workspace_root.ferrycat-cli daemon, ADR-0005) manages single-step contract dispatch and supervised worker lifecycles; for complex multi-step branching DAG orchestrations, use dedicated DAG workflow engines such as PatchCat.FerryCat provides a controlled daemon mode governed by SQLite microsecond CAS leases on daemon_locks and declarative scripts defined in ferrycat.config.json:
# Run a single dispatch cycle with declared handlers
ferrycat-cli daemon --config ./ferrycat.config.json --once
# Start continuous daemon loop
ferrycat-cli daemon --config ./ferrycat.config.json
Example ferrycat.config.json:
{
"version": 1,
"daemon": {
"poll_interval_ms": 1000,
"lease_ttl_sec": 30,
"heartbeat_interval_ms": 10000,
"notify": true
},
"agents": {
"workbuddy": {
"handlers": {
"code_review": {
"exec_file": "./scripts/review-handler.js",
"pass_env": ["CUSTOM_ANALYZER_PATH"]
}
}
}
}
}
ferrycat demo)Before configuring any MCP server, watch the whole loop in ~3 seconds:
npx ferrycat demo
(or npx -p ferrycat ferrycat-cli demo)
It spins up a fully isolated sandbox under the OS temp dir (dedicated SQLite database,
sample source file, sample handler), runs dispatch → claim → supervised execution → TOCTOU re-verification → COMPLETED, then deletes the sandbox.
Your real workspace and ~/.ferrycat/mesh.db are never read or written.
⚡ FerryCat Zero-Config Sandbox Demo ⚡
Sandbox: /tmp/ferrycat-demo-c5iK6V
✔ [1/4] Contract Dispatched
Locked src/calc.ts (sha256: ce3ba9a5...bc5d)
✔ [2/4] Contract Claimed
Lease 7424261d-9a3f-4a86-a7ff-de278c273e96
✔ [3/4] Execution & Schema Check
Heartbeat 1 lease renewal(s)
✔ [4/4] Contract Completed
TOCTOU fingerprints matched (0 dirty files)
🎉 End-to-end multi-agent handoff verified successfully!
No local clone or manual compilation required. Mount directly into your IDE's MCP configuration using npx -y ferrycat:
Edit %USERPROFILE%\.gemini\antigravity\mcp_config.json (or ~/.gemini/antigravity/mcp_config.json on macOS/Linux):
{
"mcpServers": {
"ferrycat": {
"command": "npx",
"args": ["-y", "ferrycat"],
"env": {
"AGENT_NAME": "antigravity"
}
}
}
}
Configure the target host's MCP settings with its respective AGENT_NAME:
{
"mcpServers": {
"ferrycat": {
"command": "npx",
"args": ["-y", "ferrycat"],
"env": {
"AGENT_NAME": "workbuddy"
}
}
}
}
npm install -g ferrycat
Then simply set "command": "ferrycat" in your MCP config.git clone https://github.com/GuoBug/FerryCat.git
cd FerryCat
npm install
npm run build
npm test
Mount using your local path:
"command": "node", "args": ["--experimental-sqlite", "/path/to/FerryCat/dist/index.js"].ferrycat-cli)Beyond serving as an in-IDE MCP Server, FerryCat provides a first-class CLI utility (ferrycat-cli). The single ferrycat executable dispatches on its first argument: no argv starts the MCP stdio server, a known subcommand routes to the CLI. So you can run npx ferrycat <command> with zero install (or ferrycat-cli <command> once installed globally). Sharing the same ~/.ferrycat/mesh.db SQLite WAL database and Zod validation contracts, the CLI allows developers to inspect mesh health, verify working tree safety, and hook into automated CI/Git scripts without leaving their terminal:
Inspect all cross-host handoffs and error reasons formatted as an ASCII table:
# View all contracts in an ASCII table
npx ferrycat inspect
# Filter by target agent (e.g., only tasks for antigravity)
npx ferrycat inspect --target antigravity
Audit on-disk pointer file integrity against the contract's baseline SHA-256 before committing review work (ADR-0004), eliminating false-positive deliveries:
npx ferrycat verify <CONTRACT_ID>
Poll the queue, claim tasks, and execute local review/test scripts with automatic failure closure:
# Safely run a script upon task arrival (no shell quotation hazards)
npx ferrycat worker --agent codex --mode=exec --exec-file ./scripts/review.sh
Run the self-contained multi-agent lifecycle simulation without configuring an MCP server:
npx ferrycat demo
Options (--keep to retain SQLite for manual inspection, --json for CI assertions) detailed in Quickstart §0.
Run the headless orchestration daemon coordinating background workers via atomic CAS leases and declarative script bindings:
# Launch daemon using project-local declarative configuration
npx ferrycat daemon --config ./ferrycat.config.json
# Run single poll/dispatch iteration for a targeted agent and exit
npx ferrycat daemon --agent workbuddy --once
💡 Architecture Decision Records & Engineering Verification:
- ADR-0001: Cross-Host SQLite WAL Bus & Human-Scheduled Poll Model (Why
node:sqliteWAL +poll_next_taskinstead of 60s Blocking Hold or single-connection MCP Tasks)- ADR-0002: Full-File SHA-256 Fingerprinting, TOCTOU Guard & Cross-Model Audit (Stale-context prevention and real-world cross-host verification records)
- ADR-0003: GUI Sandbox vs CLI Process Hybrid Layering Architecture & Wake-Up Boundaries (Desktop HITL approval vs in-house CLI dual-channel autonomy)
- ADR-0004: Separation of Review and Mutation (SRM), TOCTOU Soft-Failure Buffering & Immutable Baseline Protocol (How to prevent review abortion from concurrent or well-intended reviewer edits; live mesh case: contract
fc_1793098036393_aea8bb9b)- ADR-0005: Controlled Daemon, Atomic CAS Micro-Leases & Safe Execution Boundaries (Microsecond atomic CAS leases on
daemon_locksand declarative whitelist handler enforcement)- ADR-0006: Dual-Track TOCTOU Semantics & Post-Mutation SHA-256 Fulfillment (Why
implementation/test_generationtasks commit post-mutation SHA-256 intoverified_sha256while preserving pre-mutation baselines inpointers; live mesh case:fc_1793100801409_4eedf544)- FerryCat Requirements Backlog & Roadmap
About the Author
Guo Qiang (GuoBug), Product Engineer specializing in platform engineering and growth. Currently focused on AI workflow orchestration, DAG state machines, and deterministic system architectures.
Open Source & Homepage: https://github.com/GuoBug · https://guobug.github.io
Inquiries and discussions on workflow engine architecture, topological scheduling, and developer experience are warmly welcomed.
Contract-driven cross-host agent handoff, code review & verification harness via MCP & SQLite WAL
{ "mcpServers": { "io.github.guobug-ferrycat": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
FerryCat ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-11 Contract-driven cross-host agent handoff, code review & verification harness via MCP & SQLite WAL