# projectfs-node

Server MCP TypeScript/Node.js per lettura sicura del filesystem di progetto. Il server e':

- read-only;
- vincolato a `allowedRoots`;
- coerente tra Windows e Linux;
- pensato come fallback sicuro quando IDE, `docs-node` o `git-node` non coprono la sola ispezione file.

## Setup locale

```bash
cd projectfs-node
npm install
npm run build
```

Avvio via stdio:

```bash
PROJECTFS_ALLOWED_ROOTS="/path/to/repo" node dist/index.js
```

Su Windows PowerShell:

```powershell
$env:PROJECTFS_ALLOWED_ROOTS="D:\mcp-servers"
node .\dist\index.js
```

## Configurazione

Il server legge `projectfs.config.json` nella cartella del package, con precedenza:

1. `.env` del `project_path` passato al tool, se presente
2. `.env` locale scoperto automaticamente (`cwd`, root repo, package/config root)
3. env `PROJECTFS_*` del launcher/host
4. file `projectfs.config.json`
5. default interni

`allowedRoots` e' obbligatorio dopo il merge finale; se manca, il bootstrap fallisce.

Ogni tool accetta inoltre `project_path` opzionale per allinearsi agli altri server MCP del workspace quando il progetto target ha un proprio `.env`.

### Campi supportati

- `allowedRoots`
- `blockedGlobs`
- `blockedDirs`
- `followLinks`: `allow-within-whitelist` | `deny` | `report-only`
- `maxFileBytes`
- `maxSearchResults`
- `maxDepth`
- `searchTimeoutMs`

### Esempio Windows

```json
{
  "allowedRoots": [
    "D:\\mcp-servers",
    "D:\\cfprojects\\envs\\dev\\website"
  ],
  "blockedDirs": [".git", "node_modules", "vendor", "dist", "build", "bin", "obj"],
  "followLinks": "allow-within-whitelist",
  "maxFileBytes": 262144,
  "maxSearchResults": 100,
  "maxDepth": 8,
  "searchTimeoutMs": 3000
}
```

### Esempio Linux

```json
{
  "allowedRoots": [
    "/home/user/mcp-servers",
    "/srv/app/current"
  ],
  "blockedDirs": [".git", "node_modules", "vendor", "dist", "build", "bin", "obj"],
  "followLinks": "allow-within-whitelist",
  "maxFileBytes": 262144,
  "maxSearchResults": 100,
  "maxDepth": 8,
  "searchTimeoutMs": 3000
}
```

## Tool

- `read_file(path, project_path?, startLine?, endLine?, maxBytes?)`
- `list_dir(path, project_path?, depth?, include?, exclude?, includeHidden?)`
- `grep_files(root, pattern, project_path?, include?, exclude?, caseSensitive?, maxResults?)`
- `stat(path, project_path?)`
- `read_many(paths[], project_path?, maxBytesPerFile?)`

## Limiti noti

- `grep_files` usa ricerca letterale, non regex.
- La lettura binaria e' rifiutata.
- Default: `followLinks=allow-within-whitelist`, quindi symlink e junction interni alla whitelist sono ammessi.
- Con `followLinks=deny`, symlink e junction vengono bloccati anche se restano dentro whitelist.
- `list_dir` e `grep_files` troncono i risultati quando raggiungono i limiti configurati.

## Verifica

```bash
npm run build
npm test
node ../tests/smoke/projectfs-node.smoke.mjs
```

Quando cambia codice MCP o configurazione del server, riavviare il processo host.