<div align="center">

<img src="https://raw.githubusercontent.com/0xnurrabby/mcp-omni-context/master/assets/logo.svg" alt="mcp-omni-context" width="110">

# mcp-omni-context

**Give any AI chat real vision.**

Read **images**, **files**, and **zip archives** in any language, for any AI model.
Works everywhere MCP works. No Python, no servers. OCR runs locally by default.

[![npm](https://img.shields.io/npm/v/mcp-omni-context?color=7c3aed&logo=npm)](https://www.npmjs.com/package/mcp-omni-context)
[![License](https://img.shields.io/badge/license-MIT-22c55e)](#license)
[![Node](https://img.shields.io/badge/node-%3E%3D20.17-339933)](https://nodejs.org)
[![stars](https://img.shields.io/github/stars/0xnurrabby/mcp-omni-context?color=f59e0b&logo=github)](https://github.com/0xnurrabby/mcp-omni-context)

</div>

---

## ✨ Features

| | Feature | What it does |
|---|---|---|
| 🖼️ | Screenshot reading | Reads any screenshot, at any angle, in any language |
| 🤖 | Optional AI vision | Add a key in `.env` → images read by **GPT-4o-mini** or **Gemini** (≈ $0.001/image) |
| 🔁 | Auto fallback | If the AI API fails (or no key set), it silently uses local OCR instead |
| 🧲 | Auto-detection | Pasted/dropped screenshots are found automatically in the temp/clipboard folders — no copying files anywhere |
| 📄 | File & log reader | Code files and error traces, line by line |
| 📦 | Zip explorer | Visual file tree plus every code file inside |
| 🌍 | Any language | English, Bengali, Hindi, Arabic, Chinese and more |
| 🪄 | Zero setup for users | One command installs it for any AI tool |
| 🔒 | Privacy first | With no API key, OCR runs 100% locally |

---

## 🚀 Download & Run

Everything lives behind two tools: `read_context_data` and `find_images`.

**Step 1** · Check you have Node.js (20.17+)

```bash
node -v
```

**Step 2** · No command? Just ask your AI assistant

> "please setup mcp-omni-context"

**Step 3** · Or run it yourself

```bash
npx -y mcp-omni-context setup
```

Then **restart** your AI tool. Done. That's the whole setup.

It configures **opencode, Codex, Claude Desktop, Cursor, Windsurf, Cline, Roo,
and VS Code**, backs up your existing configs, and creates an uploads folder at
`~/.mcp-omni-context/uploads`.

> 💡 **Pasting a screenshot?** Send it straight to your assistant. If the path is
> not obvious, the assistant calls `find_images` to locate the freshest images in
> your temp, clipboard, Downloads, Desktop, Pictures, and uploads folders. You
> never have to save or copy a file manually.

---

## ⚙️ Optional: better accuracy with AI vision (~$0.001 / image)

By default every image is read by **local OCR** (tesseract.js) — free and private.

For noticeably better UI/error-screen reading, add **one** API key to a file named
`.env` in your project folder (the same folder you run the AI tool from).

<details>
<summary><b>Option A — OpenAI (recommended)</b></summary>

1. Create an API key at https://platform.openai.com/api-keys
2. Create a `.env` file in your project and paste:

```env
OPENAI_API_KEY=sk-your-key-here
```

That's it. Images are resized to max **1024px** with sharp, compressed to JPEG,
and sent with `detail: "low"` — keeping the cost at roughly **$0.001 per image**
with **GPT-4o-mini**.

</details>

<details>
<summary><b>Option B — Google Gemini</b></summary>

1. Get a free key at https://aistudio.google.com/app/apikey
2. Create a `.env` file in your project and paste:

```env
GEMINI_API_KEY=your-gemini-key
```

</details>

<details>
<summary><b>Where else can the key live?</b></summary>

Keys are read from (first match wins):

1. Your environment variables (e.g. `set OPENAI_API_KEY=...` on Windows,
   `export OPENAI_API_KEY=...` on macOS/Linux), or
2. a `.env` file in the current project folder, or
3. a `.env` file at `~/.mcp-omni-context/.env`.

Existing environment variables are always respected over `.env` values.
New keys take effect immediately; you only need to **restart** the AI tool.
</details>

> 🛡️ **Fail-safe:** if the vision API is down, returns an error, or the key is
> missing, the tool automatically falls back to local OCR — you always get a
> result, never a crash.

---

## 🛠️ Tools

### read_context_data

Reads images, files, logs, and zip archives and returns a strictly-ordered,
LLM-ready text dump. Accepts:

- a path: `{"items": ["C:/Users/you/Desktop/shot.png"]}`
- many paths in one call: `{"items": ["a.png", "b.png", "error.log", "src/"]}`
- a bare file name (auto-resolved from the system temp/clipboard folders)
- an in-memory buffer: `{"items": [{"name": "a.png", "base64": "..."}]}`

Each image is processed sequentially and wrapped in a clear delimiter:

```
--- [Image Index 1] Visual Analysis ---
[Source: C:/Users/you/Desktop/shot.png]
[Vision AI · gpt-4o-mini · detail=low · jpeg 181.2 KB · raster 2560x1440]
<the analysis / transcribed text>

--- [Image Index 2] Visual Analysis ---
...
```

### find_images

Locates the freshest screenshots across your temp, clipboard, Downloads,
Desktop, Pictures, Telegram Desktop, and uploads folders — newest first.

```
find_images                 → 10 newest images
find_images maxResults: 50  → up to 50
find_images query: "bug"    → only files whose name contains "bug"
find_images sinceMinutes: 10→ only images from the last 10 minutes
```

---

## 📦 Updating

Updates are **automatic**. Every client runs this via `npx -y`, so the newest
version loads on the next start. Zero clicks, zero reinstall.

<details>
<summary><b>Want to update right now?</b></summary>

Just tell your assistant:

> "update mcp-omni-context"

Or run the one-command update yourself:

```bash
npx -y mcp-omni-context update
```

It fetches the latest version and refreshes your configs and rules.

</details>

---

## ⚙️ Setup (manual)

The installer writes all of this for you. For the curious, here is how each
client is configured.

<details>
<summary><b>opencode</b> · <code>opencode.json</code></summary>

```json
{
  "mcp": {
    "omni-context": {
      "type": "local",
      "command": ["npx", "-y", "mcp-omni-context"],
      "enabled": true
    }
  }
}
```

</details>

<details>
<summary><b>Claude Desktop</b> · <code>claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "omni-context": {
      "command": "npx",
      "args": ["-y", "mcp-omni-context"]
    }
  }
}
```

</details>

<details>
<summary><b>Cline / Cursor / Windsurf / Roo</b> · <code>mcpServers</code></summary>

```json
{
  "mcpServers": {
    "omni-context": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-omni-context"]
    }
  }
}
```

</details>

<details>
<summary><b>Codex CLI</b> · <code>~/.codex/config.toml</code></summary>

```toml
[mcp_servers.omni-context]
command = "npx"
args = ["-y", "mcp-omni-context"]
```

</details>

---

## ⚙️ Environment variables

All of these can go in a `.env` file or your real environment.

| Variable | Default | What it does |
|---|---|---|
| `OPENAI_API_KEY` | — | Enables GPT-4o-mini vision (resized to 1024px, `detail: "low"`, ~$0.001/img) |
| `OPENAI_MODEL` | `gpt-4o-mini` | Override the OpenAI vision model |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | Use any OpenAI-compatible endpoint |
| `GEMINI_API_KEY` | — | Enables Google Gemini vision instead |
| `GEMINI_MODEL` | `gemini-2.0-flash` | Override the Gemini model |
| `MCP_OMNI_VISION` | `auto` | `auto` · `openai` · `gemini` · `tesseract` (force local OCR) |
| `MCP_OMNI_ENV_FILE` | — | Path to a specific `.env` file to read |
| `MCP_OMNI_VERBOSE` | off | `1` to log OCR/vision progress to stderr |
| `MCP_OMNI_PSM` | `3` | tesseract page-segmentation mode (0–13) |

---

## 🔍 How it reads

Your assistant reads context through `read_context_data`. It accepts any number
of images, files, logs, or zip archives in order, and returns a strictly ordered,
LLM-ready text dump.

<details>
<summary><b>Reading in any language</b></summary>

OCR defaults to **English + Bengali**. For other languages, just tell your
assistant the language (Hindi, Arabic, Chinese, Spanish, French, German, Russian,
Japanese, Korean, Urdu, and many more). The language data downloads itself, or
pre-download once:

```bash
npx -y mcp-omni-context --warmup eng,ben,hin,spa,fra,urd
```

</details>

<details>
<summary><b>Project structure</b></summary>

```
src/
└── index.ts          # the entire server (tool + vision + zip tree + setup + update)
dist/                 # compiled output (published)
README.md
package.json
```

</details>

---

## 🔐 Safety

| | Guard | What it means |
|---|---|---|
| 🚫 | Sensitive files | `.env`, `id_rsa`, `*.pem`, `secrets.*`, tokens are skipped |
| 📦 | Binary & heavy | ignore `node_modules`, media, and oversized blobs |
| 🛡️ | Zip-slip | blocks `..` and absolute paths inside archives |
| 🧼 | Auto-cleanup | temp files are purged after every run |
| 💸 | Low cost | AI vision resizes to 1024px and sends `detail: "low"` (~$0.001/img) |

---

## 🛠️ CLI reference

```
mcp-omni-context                      start the MCP server (stdio)
mcp-omni-context setup                configure all supported clients
mcp-omni-context update               fetch latest + refresh configs and rules
mcp-omni-context --check-update       check the latest published version
mcp-omni-context --warmup [langs]     pre-download OCR language data
mcp-omni-context --selftest           check OCR works on your machine
mcp-omni-context --help               show help
mcp-omni-context --version            show version
```

---

<div align="center">

**MIT License** · built by [@0xnurrabby](https://github.com/0xnurrabby)

</div>