Caoile MCP File-Server Connector

---

📌 Table of Contents

1. Overview & Project Rationale
2. System Architecture
3. Tool Catalog (9 Custom MCP Tools)
4. Project Structure
5. Multi-Agent Handoff Protocol
6. Fresh Device Setup & Migration Guide
7. Testing & Verification

---

Overview & Project Rationale

The Caoile MCP File-Server is a production-grade, sandboxed filesystem connector built on the official Model Context Protocol (MCP) specification by Anthropic.

Why build this?

Autonomous LLM agents (such as Claude, Cursor, or custom agents) present two fundamental engineering challenges when interacting directly with a host machine:

1. Security Vulnerabilities (Arbitrary File Access): Granting an autonomous agent unrestricted filesystem access exposes the host system to destructive actions and directory traversal exploits (../../etc/passwd, C:\Windows\System32, personal directories, credentials, or SSH keys).
2. Context Degradation & Token Budget Depletion: LLMs have finite context windows. Reading full multi-thousand-line files exhausts token budgets immediately and increases hallucination rates during code refactoring.

How this project solves these problems:

• Strictly Sandboxed Workspace: All file operations resolve strictly inside the ./workspace directory. Any attempt to escape the root boundary via relative path traversal (../, ..\), poison null bytes (\0), or absolute drive paths is intercepted and rejected with a SecurityError.
• Token-Aware Line Chunking: The read_file tool supports 1-indexed pagination (startLine, maxLines capped at 500) to keep LLM context consumption minimal and purposeful.
• Persistent Disk-Based Shared Memory: Cross-session context is preserved using physical Markdown artifacts (PROJECT_STATE, PLAN_LOG, CHECKPOINTS, DECISIONS), allowing an Architect Agent and a Builder Agent to collaborate asynchronously across isolated operational sessions.

---

System Architecture

┌────────────────────────────────────────────────────────┐
│             CLAUDE (Web Browser / Desktop)             │
│            Client: Autonomous LLM Sessions             │
└──────────────────────────┬─────────────────────────────┘
                           │ (Streamable HTTP / SSE)
                           ▼
┌────────────────────────────────────────────────────────┐
│             CLOUDFLARE SECURE HTTPS TUNNEL             │
│    https://.trycloudflare.com/mcp           │
└──────────────────────────┬─────────────────────────────┘
                           │ (Local Proxy to Port 3000)
                           ▼
┌────────────────────────────────────────────────────────┐
│             CAOILE MCP SERVER (Node.js/Express)        │