Metadata-Version: 2.4
Name: snapsearch-mcp
Version: 0.1.0
Summary: Your Mac screenshots folder is a disaster. This fixes it — with vision, embeddings, and semantic search.
Author-email: Shantanu Kumar <shantanuk436@gmail.com>
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: chromadb>=1.5.0
Requires-Dist: mcp>=1.27.0
Requires-Dist: openai-agents>=0.17.0
Requires-Dist: openai>=1.109.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv
Description-Content-Type: text/markdown

# 🧠 snapsearch

> Your Mac screenshots folder is a disaster. This fixes it — with vision, embeddings, and semantic search.

An AI agent + custom MCP server that **sees** your screenshots, understands what's in them, organizes them into clean folders, and lets you find anything with natural language.

**Fully local. No cloud uploads. No subscriptions.**

---

## How it works

```
screenshot.png
      │
      ▼
GPT-4o vision         "React error about invalid hook call in App.js, line 23"
      │
      ▼
text-embedding-3-small  [0.021, -0.847, 0.334, ...]
      │
      ▼
ChromaDB (local)      stored permanently on disk
      │
      ▼
search("hooks problem") → finds it, even with a garbage filename
```

---

## The result

```
~/Screenshots/
├── code/
│   ├── errors/         react-hooks-invalid-call.png
│   │                   python-importerror-requests.png
│   └── snippets/       vim-config-lsp-setup.png
├── design/
│   ├── figma/          darkmode-mobile-v3.png
│   └── other/          canva-instagram-post.png
├── chats/              whatsapp-trip-planning-march.png
├── docs/               notion-q2-sprint-board.png
├── memes/              drake-hotline-bling-coding.png
└── web/                vercel-deployment-dashboard.png
```

---

## Architecture

```
snapsearch (Agent)
    │
    │   MCPServerStdio
    ▼
snapsearch-mcp (MCP server — 8 tools)
    ├── vision.py        GPT-4o vision → structured description
    ├── embeddings.py    OpenAI embeddings + ChromaDB
    └── models.py        Pydantic data models
```

**Why MCP and not just a script?**

A script renames blindly. This agent:
- Understands context across a conversation
- Lets you say "actually split design into figma vs other" and re-organizes
- Finds screenshots by meaning: "that slack message about the deploy" works
- Remembers decisions across sessions (ChromaDB persists to `~/.snapsearch/`)

---

## Setup (No Clone Needed!)

Using `uvx` (the modern Python alternative to `npx`), you can run `snapsearch` instantly without manual cloning or pip installs.

### 1. Set your Environment Variables

You need to provide your OpenAI API key and optionally your screenshots directory. You can set them in your environment:

```bash
export OPENAI_API_KEY=sk-...
export SCREENSHOTS_DIR="/Users/yourname/Desktop" # Optional, defaults to ~/Desktop/screenshots-demo
```

### 2. Run the Agent

You can trigger the autonomous organizer right away:

```bash
# Full auto-organize (scan → vision → embed → move → rename)
uvx snapsearch

# Semantic search
uvx snapsearch "find my react error screenshots"
uvx snapsearch "show me figma mockups from last month"
uvx snapsearch "that slack conversation about the deployment"

# Partial organize
uvx snapsearch "organize only the code screenshots"

# Index health
uvx snapsearch --stats
```

---

## MCP Tools

| Tool | What it does |
|------|-------------|
| `scan_screenshots` | List all images + metadata |
| `read_screenshot` | Return base64 image for direct visual inspection |
| `describe_and_index` | **Main tool** — GPT-4o vision + ChromaDB embedding |
| `search_screenshots` | Semantic search (meaning, not filenames) |
| `move_screenshot` | Move to category subfolder, updates index |
| `rename_screenshot` | Human-readable rename, updates index |
| `list_categories` | Folder structure + counts |
| `index_stats` | ChromaDB health check |

---

## Use in Claude Desktop (MCP server only)

Because it's distributed on PyPI, using it in Claude Desktop is extremely simple.

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "snapsearch": {
      "command": "uvx",
      "args": ["snapsearch-mcp"],
      "env": {
        "SCREENSHOTS_DIR": "/Users/yourname/Desktop",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}
```

---

## Where data lives

| What | Where |
|------|-------|
| ChromaDB index | `~/.snapsearch/chroma/` |
| Your screenshots | wherever `SCREENSHOTS_DIR` points |
| Nothing else | nothing is uploaded anywhere |

---

## Stack

- **MCP server** — [`mcp`](https://github.com/anthropics/mcp) Python SDK v1.27+
- **Agent** — [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) v0.17+
- **Vision** — `gpt-4o` (low detail mode — fast + cheap)
- **Embeddings** — `text-embedding-3-small`
- **Vector DB** — [ChromaDB](https://www.trychroma.com/) (local, persistent)
- **Validation** — Pydantic v2

---

## License

MIT