一个用 Python（FastMCP）编写的沙箱 文件系统 MCP 服务器。它为 AI 代理提供安全文件、搜索、git-lite 和切换工具，集中在一个工作区文件夹内，并通过切换协议（PROJECT_STATE、PLAN_LOG、CHECKPOINTS、DECISIONS）作为会话间共享内存。

课程项目：期中考试第一部分 - 自己构建（模型情境协议）。

特色

• 沙箱工作区根节点。 每条路径都针对工作区解析;[..\ 遍历、绝对路径和前缀技巧（MCP-activity-evil）被拒绝。
• 14 个工具：文件操作、搜索、Git Lite 和 handoff 工具（下表）。
• 两种传输方式：stdio（Claude Desktop）和可流式 HTTP。
• 通过Cloudflare隧道实现HTTPS，由Windows服务（NSSM）维持。
• 令牌认证用于HTTP端点（MCP_TOKEN）。
• 版本锁定（if_version），使得一个会话无法覆盖另一个会话的更改。
• 切换协议，这样新会话可以仅从文件中恢复工作。

要求

• Windows 10/11
• Python 3.10+，带有mcp包：pip install mcp
• Windows版Git（适用于git-lite工具）
• Claude 桌面（MCP 客户端）

StartFilesystemMCP

A sandboxed filesystem MCP server written in Python (FastMCP). It gives an AI agent safe file, search, git-lite and handoff tools inside one workspace folder, and doubles as shared memory between sessions through a Handoff Protocol (PROJECT_STATE, PLAN_LOG, CHECKPOINTS, DECISIONS).

Course project: Midterms Pt 1 - Build Your Own (Model Context Protocol).

Features

• Sandboxed workspace root. Every path is resolved against the workspace; ..\ traversal, absolute paths and prefix tricks (MCP-activity-evil) are rejected.
• 14 tools: file ops, search, git-lite and handoff tools (table below).
• Two transports: stdio (Claude Desktop) and streamable HTTP.
• HTTPS through a Cloudflare tunnel, kept alive by Windows services (NSSM).
• Token auth for the HTTP endpoint (MCP_TOKEN).
• Version locking (if_version) so one session cannot overwrite another’s changes.
• Handoff Protocol so a new session can resume work from the files alone.

Requirements

• Windows 10/11
• Python 3.10+ with the mcp package: pip install mcp
• Git for Windows (for the git-lite tools)
• Claude Desktop (MCP client)
• For the HTTPS part: cloudflared and NSSM (winget install Cloudflare.cloudflared and winget install NSSM.NSSM)

Setup

1. Clone the repo into the workspace folder, or copy mcp_server.py there.
2. Set WORKSPACE_ROOT at the top of mcp_server.py to your folder (default: C:\Users\Colee\MCP-activity).
3. Make sure the four handoff files exist in that folder.

Run over stdio (Claude Desktop)

Add this to claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\PYTHON314\\PYTHON.EXE",
      "args": ["C:\\Users\\Colee\\MCP-activity\\mcp_server.py"]
    }
  }
}

Run over HTTP

$env:MCP_TOKEN = -join ((48..57)+(97..122) | Get-Random -Count 24 | % {[char]$_})
$env:MCP_TOKEN                      # copy this value
python mcp_server.py --http         # serves http://127.0.0.1:8000/mcp

Without a token the endpoint is open to anyone who has the URL, so always set one.

Expose it over HTTPS (Cloudflare quick tunnel)

cloudflared tunnel --url http://127.0.0.1:8000

The command prints an address like https://.trycloudflare.com. In Claude Desktop add a custom connector named filesystem-http with the URL:

https://.trycloudflare.com/mcp?token=

Quick tunnel addresses change every time the tunnel restarts.

Keep it alive (NSSM, run in an Administrator PowerShell)

nssm install McpServer "C:\PYTHON314\PYTHON.EXE" "C:\Users\Colee\MCP-activity\mcp_server.py --http"
nssm set McpServer AppDirectory "C:\Users\Colee\MCP-activity"
nssm set McpServer AppEnvironmentExtra "MCP_TOKEN=$env:MCP_TOKEN"
nssm set McpServer Start SERVICE_AUTO_START
nssm start McpServer

$cf = (Get-Command cloudflared).Source