# FlexFS MCP 

A Model Context Protocol (MCP) that provides secure file system, web fetching, and Google Cloud Storage access for AI IDEs.

## Features

- **Local File Access** - Read, write, and list local files with path security
- **Web Fetching** - Fetch web articles and pages
- **Google Cloud Storage** - Read and list files in GCS buckets (requires credentials)

## Prerequisites

- Node.js 18+
- npm or yarn

## Installation

### 1. Clone and Install Dependencies

```bash
cd C:\Projects\flexfs-mcp
npm install
```

### 2. Build the Project

```bash
npm run build
```

This compiles TypeScript to JavaScript in the `dist/` folder.

### 3. Start the Server (Development)

```bash
npm run dev
```

This runs the server with hot-reload using nodemon.

### 4. Start the Server (Production)

```bash
npm start
```

This runs the compiled server from `dist/server.js`.

## IDE Setup

### Codex

Edit `C:\Users\<YourName>\.codex\config.toml`:

```toml
[mcp_servers.flexfs-mcp]
command = "node"
args = ["C:/Projects/flexfs-mcp/dist/server.js"]
```

### Cursor

Edit `C:\Users\<YourName>\.cursor\mcp.json`:

```json
{
  "mcpServers": {
    "flexfs-mcp": {
      "command": "node",
      "args": ["C:/Projects/flexfs-mcp/dist/server.js"]
    }
  }
}
```

### Kiro

Edit `C:\Users\<YourName>\.kiro\config\mcp.json`:

```json
{
  "servers": {
    "flexfs-mcp": {
      "command": "node",
      "args": ["C:/Projects/flexfs-mcp/dist/server.js"]
    }
  }
}
```

### Claude Desktop

Edit `C:\Users\<YourName>\AppData\Roaming\Claude\mcp_servers.json`:

```json
{
  "flexfs-mcp": {
    "command": "node",
    "args": ["C:/Projects/flexfs-mcp/dist/server.js"]
  }
}
```

### VS Code (with MCP Extension)

Edit `C:\Users\<YourName>\.vscode\extensions\modelcontextprotocol\mcp_servers.json`:

```json
{
  "flexfs-mcp": {
    "command": "node",
    "args": ["C:/Projects/flexfs-mcp/dist/server.js"]
  }
}
```

## Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `read_local_file` | Read a local file | `path: string` |
| `list_folder` | List files in a folder | `folder: string` |
| `write_local_file` | Write content to a file | `path: string, content: string` |
| `fetch_web_article` | Fetch a web page | `url: string` |
| `read_gcs_file` | Read a file from GCS | `bucketName: string, fileName: string` |
| `list_gcs_files` | List files in a GCS bucket | `bucketName: string, prefix?: string` |


## Project Structure

```
flexfs-mcp/
├── src/
│   ├── server.ts           # Main MCP server
│   ├── config/
│   │   └── env.ts          # Environment config
│   ├── services/
│   │   ├── fileService.ts  # Local file operations
│   │   ├── gcsService.ts   # GCS operations
│   │   └── webService.ts   # Web fetch operations
│   ├── tools/
│   │   ├── Local/          # Local file tools
│   │   ├── GCS/            # GCS tools
│   │   └── Web/            # Web tools
│   └── utils/
│       └── pathSecurity.ts # Path validation
├── dist/                   # Compiled JavaScript
├── package.json
└── tsconfig.json
```

## Security

- Path validation blocks access to system directories (Windows, macOS, Linux)
- Case-insensitive path matching on Windows
- File existence checks before access

## Troubleshooting

### "Access Denied" on Windows

Make sure you've rebuilt after any changes:
```bash
npm run build
```

Then restart the MCP server.

### IDE Not Recognizing MCP Server

Restart the IDE after updating the config file.