# ChatGPT Local Reader

[中文说明](README.zh-CN.md) · [Windows tutorial](docs/quickstart-windows.md) · [Security](SECURITY.md)

A self-hosted, **read-only** MCP server that lets ChatGPT's web interface search
and read explicitly approved local project files for analysis and planning.
No file writing, deletion, shell execution, or model API calls are implemented.
This is an independent community project, not an official OpenAI product.

```text
ChatGPT web → OpenAI Secure MCP Tunnel → loopback MCP server → approved folder
```

Files remain on your computer; **content returned by tools is sent to ChatGPT**.
Only share data you are authorized to disclose. Indexing a file does not mean
the model has read it, and indexing is not an upload of the whole directory.

## Scope

- Five tools: `project_overview`, `list_project`, `search`, `fetch`, `read_file`.
- Explicit root and reviewed path allowlist, or an explicit full-filtered-root opt-in.
- Text/code, Markdown, CSV/JSON/YAML, notebook JSON and DOCX main-body text.
- Bounded reads, secret-pattern filtering and path/link checks. These reduce risk;
  they are not a perfect data-loss-prevention system or an OS sandbox.
- No PDF, images/OCR, Excel/PowerPoint, media, archives or model weights.
- Windows-first scripts; the Python module can also be tested directly on Linux.
  See [validation results](docs/review-report.md) for what was actually tested.

## Quick start — Windows

Prerequisites: Python 3.11+ with `venv`/`pip`, PowerShell, and this source folder.
Run from the repository root. Git is optional if you downloaded a source ZIP.

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\install.ps1

$demoRoot = (Resolve-Path .\examples\demo-project).Path
$demoManifest = (Resolve-Path .\examples\demo-allowlist.txt).Path
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\start_local.ps1 -ProjectRoot $demoRoot -Manifest $demoManifest
```

Keep that terminal open. In a second terminal at the repository root:

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\doctor.ps1 -SmokeTest
```

Then follow [ChatGPT connection setup](docs/chatgpt-setup.md). This requires your
own eligible ChatGPT workspace, tunnel permissions, tunnel client and runtime
credential. Never use another person's tunnel or paste a credential into a chat.
Account eligibility and product usage limits are controlled by OpenAI, not this tool.

## Read your own folder

Start with a separate, reviewed share folder. Copy `examples/allowlist.example.txt`
to your own local configuration location and edit the paths. Paths in the allowlist
are relative to the **target folder**, not the allowlist file.

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\scripts\start_local.ps1 -ProjectRoot 'C:\Shared\MyProject' -Manifest 'C:\Shared\reader-allowlist.txt'
```

An explicit `-FullFilteredProject` may replace `-Manifest`; it permits all files
under that root that pass the filters, including matching files added later.
It is not recommended for a home folder, disk root or a mixed private workspace.
Switching folders/manifests requires a restart. File edits refresh lazily;
[configuration details](docs/configuration.md) explain the limits.

## Develop and verify

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe scripts\integration_test.py
.\.venv\Scripts\python.exe scripts\check_release.py
```

Tests use synthetic temporary data. `integration_test.py` uses its own loopback
port and server process, not a running production service. Dependencies are
version-pinned in `requirements.lock`; this is not a hash-verified lock file.
Do not interpret a passing test suite as a guarantee against every attack.

## Documentation

- [Step-by-step Windows guide](docs/quickstart-windows.md)
- [ChatGPT and official tunnel](docs/chatgpt-setup.md)
- [Configuration, coverage and file formats](docs/configuration.md)
- [Troubleshooting](docs/troubleshooting.md)
- [Threat model and security boundaries](SECURITY.md)
- [Review and test report](docs/review-report.md)
- [Publishing checklist](docs/publishing.md)
- [Related projects](docs/related-projects.md)

The optional [Codex integration](integrations/codex/README.md) is not required
for ChatGPT web. Publishing this code on GitHub for self-hosting is different
from submitting a public ChatGPT plugin. Secure MCP Tunnel supports private
connections, not public plugin distribution; see the [official guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels).

## License

MIT — see [LICENSE](LICENSE). Third-party packages and the separately downloaded
official tunnel client retain their own licenses.