---

📌 目录

1. 概述与项目理由
2. 系统架构
3. 工具目录（9个定制MCP工具）
4. 项目结构
5. 多智能体切换协议
6. 全新设备设置与迁移指南
7. 测试与验证

---

概述与项目理由

Caoile MCP 文件服务器是一款生产级沙箱文件系统连接器，基于 Anthropic 官方的 Model Context 协议（MCP） 规范构建。

为什么要建造这个？

自主LLM代理（如Claude、光标或自定义代理）在直接与主机交互时面临两个基本的工程挑战：

1. 安全漏洞（任意文件访问）：授予自主代理无限制的文件系统访问，会使主机系统暴露于破坏性行为和目录遍历利用（../../etc/passwd、C:\Windows\System32、个人目录、凭据或SSH密钥）。
2. 上下文退化与令牌预算耗尽：大型语言模型的上下文窗口是有限的。读取完整的数千行文件会立即耗尽令牌预算，并在代码重构过程中增加幻觉率。

这个项目如何解决这些问题：

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)        │