[![M8ven Score](https://m8ven.ai/badge/mcp/roobak-1234-local-mcp-nuynzr)](https://m8ven.ai/mcp/roobak-1234-local-mcp-nuynzr)
# Remote Project File-System MCP for Claude Web

A production-grade, secure **Model Context Protocol (MCP)** server built with **Python** and **FastMCP**. It allows **Claude Web** (and Claude in Chrome) to securely inspect, search, and modify the files of a local project workspace being developed alongside **Antigravity IDE**.

---

## 1. Architecture Overview

### How Antigravity and Claude Work Together

Both **Antigravity IDE** and the **Project Files MCP server** operate on the **same local project directory** on your machine (e.g. `C:\Projects\NeuroScan`).

```text
                       My Windows PC
  ┌─────────────────────────────────────────────────────────┐
  │                                                         │
  │   Antigravity IDE                                       │
  │         │                                               │
  │         ▼                                               │
  │   Local Project Files  ◄───  Project Files MCP Server   │
  │   (e.g., C:\Projects\NeuroScan)         │               │
  └─────────────────────────────────────────┼───────────────┘
                                            │
                                 Secure HTTPS / SSE Tunnel
                                 (FastMCP / Cloudflare / ngrok)
                                            │
                                            ▼
                                       Claude Web
                                (Custom MCP Connector)
```

1. **Antigravity IDE** has your project directory open and active.
2. **Project Files MCP server** is configured with `PROJECT_ROOT` pointing to that same directory.
3. **Claude Web** calls the MCP tools to inspect file trees, search code, read functions, and make targeted file modifications.
4. Changes made by Claude immediately reflect in Antigravity and your local file system.

---

### Important Architecture Constraint: Local Files vs. FastMCP Cloud

> [!IMPORTANT]
> **Understanding Cloud vs. Local Filesystem Access**:
> An MCP server hosted purely in the cloud (such as directly on FastMCP Cloud containers) **cannot directly access paths like `C:\Projects\MyProject` on your local Windows PC** across the internet without an active network bridge or tunnel.
>
> To use this MCP with your **local files and Claude Web**, choose one of the following two deployment topologies:

#### Option A: Local FastMCP Server + Secure HTTPS Tunnel (Recommended for Local Projects)
1. Run the MCP server locally on your Windows machine pointing `PROJECT_ROOT` to your project directory.
2. Expose the server using **FastMCP SSE / HTTP** via a lightweight tunnel (e.g., Cloudflare Tunnel `cloudflared`, `ngrok`, or FastMCP local tunnel).
3. Provide the resulting HTTPS URL to Claude Web as a **Custom MCP Connector**.

#### Option B: FastMCP Cloud Direct Deployment (For Cloud/Container Repositories)
1. Deploy this repository to FastMCP Cloud.
2. Set `PROJECT_ROOT` to the mounted repository path inside the cloud environment.
3. Connect the FastMCP Cloud endpoint directly to Claude Web.

---

## 2. Key Features

- **Strict Sandbox Security**: Every path is normalized, verified against path traversal (`../`), symlink escapes, and absolute path injections. Operations are strictly restricted to `PROJECT_ROOT`.
- **Sensitive File Protection**: Automatic denylist blocks access to `.env`, private keys (`id_rsa`, `*.pem`, `*.key`), and secrets (while permitting safe templates like `.env.example`).
- **Targeted Code Search**: Fast recursive search with surrounding context lines and line numbers. Automatically ignores build directories (`.git`, `node_modules`, `.venv`, `dist`, `build`, etc.).
- **Atomic File Writing**: Modifications use temporary files and atomic replacement (`os.replace`) to prevent file corruption.
- **Safe Targeted Edits**: `edit_file` enforces unambiguous text matching and prevents accidental multi-location edits unless `replace_all=True`.
- **Large & Binary File Protection**: Binary files are safely detected and directed to metadata inspection without terminal corruption. Large files enforce chunked reading (`start_line` / `end_line`).
- **Server Audit Logging**: Server-side logs record actions, paths, and status without leaking file contents or secrets.

---

## 3. MCP Tools Reference

The server exposes **17 specialized tools** with detailed parameter schemas and safety indicators:

### Read & Inspection Tools (Safe / Read-Only)

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `get_project_root` | *none* | Returns workspace name and root identifier without leaking host machine paths. |
| `list_directory` | `path: str = "."` | Lists directory contents, separating files and subdirectories with sizes. |
| `get_project_tree` | `path: str = "."`, `max_depth: int = 5` | Generates a clean visual ASCII directory tree, skipping ignored folders. |
| `read_file` | `path: str`, `start_line: int \| None`, `end_line: int \| None` | Reads text files with line numbers. Supports partial range slicing. |
| `get_file_metadata` | `path: str` | Returns file size, modified timestamp (ISO 8601), extension, and readability. |
| `search_files` | `pattern: str`, `path: str = "."` | Searches for files matching glob patterns (`*.py`, `test_*`, `*.tsx`). |
| `search_code` | `query: str`, `path: str = "."`, `file_extensions: list[str] \| None`, `max_results: int = 100` | Searches code files for text, returning line numbers and surrounding context window. |
| `find_files_by_extension` | `extension: str`, `path: str = "."` | Finds all files matching a specific extension (e.g. `.py` or `tsx`). |
| `get_project_statistics` | *none* | Calculates file counts, directory counts, and breakdown by file extension. |
| `inspect_project_file` | `path: str` | Diagnoses file type, language, size, line count, binary status, and head/tail previews. |

### Modification Tools (Marked `[MODIFIES PROJECT FILES]` / `[DESTRUCTIVE OPERATION]`)

| Tool Name | Parameters | Description |
| :--- | :--- | :--- |
| `create_directory` | `path: str` | Creates a new directory (and parent directories) inside the project root. |
| `create_file` | `path: str`, `content: str` | Creates a new file. Fails if the file already exists to prevent accidental overwrites. |
| `write_file` | `path: str`, `content: str`, `overwrite: bool = False` | Writes complete file contents atomically. Overwrite requires `overwrite=True`. |
| `edit_file` | `path: str`, `old_text: str`, `new_text: str`, `replace_all: bool = False` | Replaces exact text match atomically. Refuses if ambiguous unless `replace_all=True`. |
| `rename_file` | `old_path: str`, `new_path: str` | Renames a file or folder inside the project. Fails if destination already exists. |
| `move_file` | `source: str`, `destination: str` | Moves files or directories to another path within the project workspace. |
| `delete_file` | `path: str`, `recursive: bool = False` | Permanently deletes a file or directory. **Project root deletion is strictly forbidden.** |

---

### Read-Only MCP Resources

- `project://tree` - Fast ASCII tree view of the active workspace.
- `project://statistics` - High-level project summary statistics (JSON).
- `project://README` - Content of the project's root `README.md` file.

---

## 4. Installation & Local Setup

### 1. Prerequisites
- Python 3.10+ (or Python 3.11+)
- Windows, macOS, or Linux

### 2. Clone and Setup Virtual Environment
```bash
# Clone the repository
git clone https://github.com/your-username/project-files-mcp.git
cd project-files-mcp

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows PowerShell:
.venv\Scripts\Activate.ps1
# On Windows Command Prompt:
.venv\Scripts\activate.bat
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

---

## 5. Configuration

Configure the server via environment variables or a `.env` file:

```bash
cp .env.example .env
```

| Variable | Default | Description |
| :--- | :--- | :--- |
| `PROJECT_ROOT` | `.` | Absolute or relative path to the project directory to serve. |
| `MAX_READ_BYTES` | `524288` (512 KB) | Maximum file size allowed for full `read_file` calls. |
| `MAX_READ_LINES` | `2000` | Maximum lines returned in a single `read_file` call. |
| `MAX_SEARCH_RESULTS` | `100` | Maximum matches returned by `search_code`. |
| `IGNORED_DIRECTORIES` | `.git,__pycache__,node_modules,...` | Comma-separated directory names to ignore. |
| `BLOCKED_FILE_PATTERNS` | `.env,.env.*,*.pem,*.key,id_rsa,...` | Comma-separated glob patterns for blocked secret files. |
| `LOG_LEVEL` | `INFO` | Server logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`). |

### Example for Antigravity Workspace:
```env
PROJECT_ROOT=C:\Projects\NeuroScan
LOG_LEVEL=INFO
```

---

## 6. Running and Testing Locally

### Run Unit Tests
Run the comprehensive pytest suite (43 automated tests covering security, filesystem, search, and MCP tools):

```bash
.venv\Scripts\pytest.exe -v
```

### Run End-to-End Verification
Execute the simulated Claude workflow test:

```bash
.venv\Scripts\python.exe scripts/e2e_verification.py
```

### Start the FastMCP Server Locally
```bash
# Run FastMCP in standard stdio mode
.venv\Scripts\python.exe src/server.py

# Or run with FastMCP CLI inspector for local interactive browser testing:
fastmcp dev src/server.py
```

---

## 7. Connecting to Claude Web

### Step 1: Start FastMCP HTTP/SSE Server with Local Project Files
To allow Claude Web to reach your local server, run FastMCP in HTTP/SSE mode on port `8000`:

```bash
# Set your target project root
$env:PROJECT_ROOT = "C:\Projects\NeuroScan"

# Start the FastMCP HTTP server
fastmcp run src/server.py --transport sse --port 8000
```

### Step 2: Expose via a Secure HTTPS Tunnel
In a second terminal, create a secure HTTPS tunnel to port 8000:

**Option 1: Using Cloudflare Tunnel (Free, no account required)**:
```bash
cloudflared tunnel --url http://localhost:8000
```

**Option 2: Using ngrok**:
```bash
ngrok http 8000
```

You will receive an HTTPS URL, for example:
```text
https://my-project-mcp.trycloudflare.com/sse
```

### Step 3: Add Custom Connector in Claude Web
1. Open [Claude.ai](https://claude.ai) in your browser.
2. Go to **Settings** > **Integrations** / **Connectors** (or **Add Custom MCP Server**).
3. Enter:
   - **Name**: `Project Files MCP`
   - **Endpoint URL**: `https://my-project-mcp.trycloudflare.com/sse`
4. Click **Save** and verify the green connected indicator.

### Step 4: Use in Project Conversations
1. Open your project conversation in Claude Web.
2. Ensure the `Project Files MCP` tool is enabled.
3. Ask Claude to inspect and work with your project files!

---

## 8. Claude Web Workflow Guidance & Example Prompts

The MCP is designed so Claude follows an efficient, targeted workflow:

```text
Understand Request  ──►  get_project_tree()  ──►  search_code()  ──►  read_file() (targeted)
                                                                            │
Report to User      ◄──  read_file() (verify) ◄──  edit_file()   ◄─────────┘
```

### Example Prompts for Claude:

#### 1. Inspecting Architecture
> *"Inspect my project structure and explain the key components in the src/ directory."*

#### 2. Locating Implementation
> *"Search the codebase for authentication and token validation functions."*

#### 3. Reading Specific Logic
> *"Read `src/auth/service.py` around the login function and explain how sessions are handled."*

#### 4. Safe Targeted Refactoring
> *"In `src/config.py`, change `TOKEN_EXPIRY_MINUTES = 30` to `TOKEN_EXPIRY_MINUTES = 60` and verify the change."*

#### 5. Creating New Modules
> *"Create a new utility file at `src/utils/formatting.py` with helper functions for formatting timestamps."*

#### 6. Safe Deletions & Renaming
> *"Rename `src/old_service.py` to `src/legacy_service.py`."*

---

## 9. Security Model

- **Filesystem Isolation**: All paths are resolved strictly against `settings.project_root`.
- **Traversal Prevention**: Relative paths containing `..` or leading slashes that resolve outside the project root are rejected with a `SecurityError`.
- **Sensitive Files Denylist**: Proactively blocks reading `.env`, `.env.local`, `.env.production`, `id_rsa`, `id_ed25519`, `*.pem`, `*.key`, `credentials.json`, and `secrets.json`. Safe templates (`.env.example`) are allowed.
- **Root Protection**: The root workspace directory itself can never be deleted or replaced.
- **No Arbitrary Code Execution**: The server exposes strictly filesystem and search operations. There is **no `run_command` or shell execution tool**, preventing remote command execution risks.
- **Atomic Operations**: All file writes and edits are performed using temporary files with atomic replacement to prevent file corruption during writes.

---

## 10. Limitations

- **No Remote Shell**: Arbitrary terminal commands (e.g. `npm install`, `python script.py`) cannot be executed through this MCP.
- **Antigravity State**: The MCP interacts directly with the filesystem on disk. It does not control Antigravity IDE UI or memory state directly; Antigravity will automatically detect and reload the modified files from disk.
- **Binary Content**: Binary files (images, audio, compiled binaries) cannot be read as text to avoid payload corruption; use `get_file_metadata` or `inspect_project_file` instead.
- **Direct Cloud to Local Limitation**: A cloud-hosted MCP container cannot reach a local Windows filesystem without a tunnel (like Cloudflare Tunnel or ngrok) or bridge.

---

## 11. Project Layout

```text
project-files-mcp/
│
├── src/
│   ├── __init__.py           # Package init
│   ├── config.py             # Configuration & environment variables
│   ├── exceptions.py         # Custom typed exceptions
│   ├── security.py           # Path sandboxing, traversal & sensitive file checks
│   ├── models.py             # Pydantic structured output models
│   ├── filesystem.py         # Core filesystem operations (atomic write, edit, tree, metadata)
│   ├── search.py             # File & code search with context windows
│   ├── audit.py              # Safe server-side audit logging
│   └── server.py             # FastMCP server instance, tools, and resources
│
├── tests/
│   ├── __init__.py
│   ├── conftest.py           # Test fixtures & mock project workspace
│   ├── test_security.py      # Traversal, symlink, absolute path & secret tests
│   ├── test_filesystem.py    # Read, partial slice, write, edit, rename, move, delete tests
│   ├── test_search.py        # Code search, file search & ignore filtering tests
│   └── test_server.py        # FastMCP tool interface & resource tests
│
├── scripts/
│   └── e2e_verification.py   # Complete end-to-end verification script
│
├── .env.example              # Sample environment configuration
├── .gitignore                # Git ignore rules
├── pyproject.toml            # Packaging configuration
├── requirements.txt          # Python dependencies
├── fastmcp.json              # FastMCP Cloud deployment configuration
└── README.md                 # Complete documentation
```

---

## 12. License

MIT License. Free for open-source and commercial use.