# Filesystem MCP Server (HTTP Streaming)

An HTTP streaming port of the official [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) by Anthropic.

## About This Port

This is a port of [@modelcontextprotocol/server-filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) that replaces the **stdio** transport with **HTTP Streaming** (Streamable HTTP transport).

### Why HTTP Streaming?

The original MCP filesystem server uses stdio transport, which works well for local CLI integrations but has limitations:

- Requires spawning a subprocess for each connection
- Not suitable for remote/networked deployments
- Can't be accessed by web-based MCP clients

This port uses HTTP Streaming, enabling:

- **Remote access** - Connect over HTTP from anywhere
- **Multiple concurrent sessions** - Handle many clients simultaneously
- **Web client compatibility** - Works with browser-based MCP clients
- **Standalone deployment** - Run as a service without subprocess management

All filesystem functionality from the original is preserved.

---

## Features

- Read/write files
- Create/list/delete directories
- Move files/directories
- Search files
- Get file metadata
- Dynamic directory access control via [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots)
- **OAuth 2.1 authentication** with PKCE support
- **ChatGPT integration** via MCP connectors

## Installation

```bash
npm install -g mcpfs
```

Or for local development:

```bash
npm install
npm run build
```

## Quick Start

```bash
# Initialize credentials (creates .env with random values)
mcpfs --init

# Start the server
mcpfs /path/to/your/project
```

## Using with ChatGPT

ChatGPT requires a publicly accessible HTTPS URL. Use Cloudflare Tunnel (free) to expose your local server:

### Step 1: Install Cloudflare Tunnel

```bash
# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

# Mac
brew install cloudflared

# Windows - download from:
# https://github.com/cloudflare/cloudflared/releases
```

### Step 2: Start mcpfs

```bash
mcpfs --init  # First time only - creates credentials
mcpfs /path/to/your/project
```

### Step 3: Start the Tunnel

In a separate terminal:

```bash
cloudflared tunnel --url http://localhost:24024
```

You'll get a URL like `https://random-words.trycloudflare.com`

### Step 4: Connect in ChatGPT

1. Go to **ChatGPT → Settings → Connectors → Create**
2. **Name**: `mcpfs` (or any name you prefer)
3. **URL**: `https://random-words.trycloudflare.com/mcp` (use your tunnel URL + `/mcp`)
4. **Authentication**: OAuth
5. **Client ID**: Copy from your `.env` file
6. **Client Secret**: Copy from your `.env` file
7. Click **Create**

ChatGPT will redirect you to authorize. Once complete, you can use filesystem tools in ChatGPT!

### Note on Tunnel URLs

Quick tunnels generate a new URL each time. For a permanent URL:

- Create a free Cloudflare account
- Set up a named tunnel with your own domain

---

## Usage

### Default Directory Behavior

When no directories are specified, the server will serve the **current working directory** if it's considered safe. The server will refuse to auto-serve:

- Root directory (`/`)
- Home directory (`~`)
- System directories (`/usr`, `/etc`, `/var`, `/System`, etc.)

To serve these directories, you must specify them explicitly as command-line arguments.

### Command Line Options

| Option    | Description                                     |
| --------- | ----------------------------------------------- |
| `--init`  | Generate random credentials and save to `.env`  |
| `--force` | Used with `--init` to overwrite existing `.env` |

### Environment Variables

```bash
CLIENT_ID=myid CLIENT_SECRET=mysecret mcpfs /path/to/dir

# With custom port
PORT=8080 CLIENT_ID=myid CLIENT_SECRET=mysecret mcpfs /path/to/dir
```

| Variable        | Required | Default | Description         |
| --------------- | -------- | ------- | ------------------- |
| `CLIENT_ID`     | Yes      | -       | OAuth client ID     |
| `CLIENT_SECRET` | Yes      | -       | OAuth client secret |
| `PORT`          | No       | 24024   | Server port         |

---

## HTTP Endpoints

### OAuth 2.1 Discovery (RFC 9728, RFC 8414)

| Method | Path                                      | Description                   |
| ------ | ----------------------------------------- | ----------------------------- |
| GET    | `/.well-known/oauth-protected-resource`   | Protected resource metadata   |
| GET    | `/.well-known/oauth-authorization-server` | Authorization server metadata |

### OAuth 2.1 Endpoints

| Method | Path         | Description                            |
| ------ | ------------ | -------------------------------------- |
| POST   | `/register`  | Dynamic client registration (RFC 7591) |
| GET    | `/authorize` | Authorization endpoint with PKCE       |
| POST   | `/token`     | Token endpoint                         |

### MCP Endpoints

| Method | Path   | Auth   | Description                                      |
| ------ | ------ | ------ | ------------------------------------------------ |
| POST   | `/mcp` | Bearer | Send MCP messages (initialize, tool calls, etc.) |
| GET    | `/mcp` | Bearer | SSE stream for server-to-client notifications    |
| DELETE | `/mcp` | Bearer | Terminate session                                |

---

## Authentication

This server supports OAuth 2.1 with multiple authentication flows:

### Authorization Code Flow with PKCE (Recommended)

Used by ChatGPT and other MCP clients. The flow is:

1. Client discovers OAuth endpoints via `/.well-known/oauth-authorization-server`
2. Client registers dynamically via `/register` (or uses static credentials)
3. Client redirects to `/authorize` with PKCE challenge
4. Server redirects back with authorization code
5. Client exchanges code for tokens at `/token`

### Client Credentials Flow (Machine-to-Machine)

For direct API access without user interaction:

```bash
curl -X POST http://localhost:24024/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

Response:

```json
{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

### Using the Token

```bash
curl -X POST http://localhost:24024/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'
```

---

## Directory Access Control

The server uses a flexible directory access control system.

### Method 1: Command-line Arguments

```bash
mcpfs /path/to/dir1 /path/to/dir2
```

### Method 2: MCP Roots (Recommended)

MCP clients that support [Roots](https://modelcontextprotocol.io/docs/learn/client-concepts#roots) can dynamically update the allowed directories.

### How It Works

1. **Server Startup** - Server starts with directories from command-line arguments
2. **Client Connection** - Client connects and sends `initialize` request
3. **Roots Protocol** - If client supports roots, server uses client's roots
4. **Fallback** - If client doesn't support roots, server uses command-line directories
5. **Access Control** - All filesystem operations are restricted to allowed directories

---

## API

### Tools

- **read_text_file**
  - Read complete contents of a file as text
  - Inputs:
    - `path` (string)
    - `head` (number, optional): First N lines
    - `tail` (number, optional): Last N lines

- **read_media_file**
  - Read an image or audio file as base64
  - Input: `path` (string)

- **read_multiple_files**
  - Read multiple files simultaneously
  - Input: `paths` (string[])

- **write_file**
  - Create new file or overwrite existing
  - Inputs: `path` (string), `content` (string)

- **edit_file**
  - Make selective edits with pattern matching
  - Inputs: `path`, `edits` (array of oldText/newText), `dryRun` (boolean)

- **create_directory**
  - Create new directory or ensure it exists
  - Input: `path` (string)

- **list_directory**
  - List directory contents with [FILE] or [DIR] prefixes
  - Input: `path` (string)

- **list_directory_with_sizes**
  - List directory with file sizes
  - Inputs: `path` (string), `sortBy` ("name" | "size")

- **move_file**
  - Move or rename files and directories
  - Inputs: `source` (string), `destination` (string)

- **search_files**
  - Recursively search for files matching patterns
  - Inputs: `path`, `pattern`, `excludePatterns`

- **directory_tree**
  - Get recursive JSON tree structure
  - Inputs: `path`, `excludePatterns`

- **get_file_info**
  - Get detailed file/directory metadata
  - Input: `path` (string)

- **list_allowed_directories**
  - List all accessible directories
  - No input required

### Tool Annotations

| Tool                        | readOnlyHint | idempotentHint | destructiveHint |
| --------------------------- | ------------ | -------------- | --------------- |
| `read_text_file`            | `true`       | –              | –               |
| `read_media_file`           | `true`       | –              | –               |
| `read_multiple_files`       | `true`       | –              | –               |
| `list_directory`            | `true`       | –              | –               |
| `list_directory_with_sizes` | `true`       | –              | –               |
| `directory_tree`            | `true`       | –              | –               |
| `search_files`              | `true`       | –              | –               |
| `get_file_info`             | `true`       | –              | –               |
| `list_allowed_directories`  | `true`       | –              | –               |
| `create_directory`          | `false`      | `true`         | `false`         |
| `write_file`                | `false`      | `true`         | `true`          |
| `edit_file`                 | `false`      | `false`        | `true`          |
| `move_file`                 | `false`      | `false`        | `false`         |

---

## Security

- **OAuth 2.1 authentication** with PKCE for authorization code flow
- **Token audience validation** - tokens are bound to the resource server
- **Refresh token rotation** - tokens are rotated on each refresh (OAuth 2.1 requirement)
- Only directories specified at startup (or via MCP Roots) are accessible
- Symlinks are resolved to prevent directory escape attacks

## License

MIT License. See LICENSE file for details.

## Credits

Based on the [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) by Anthropic, PBC.