diff --git a/README.md b/README.md
index 0753697..a8a7883 100644
--- a/README.md
+++ b/README.md
@@ -1,66 +1,111 @@
-
+# PaperlessMCP
-# 📄 PaperlessMCP
-
-**Model Context Protocol Server for Paperless-ngx**
+**Stop manually organizing your documents. Let AI do it.**
[](https://ci.barrywalker.io/repos/3)
-[](https://dotnet.microsoft.com/)
-[](https://opensource.org/licenses/MIT)
-[](https://modelcontextprotocol.io/)
+[](https://github.com/barryw/PaperlessMCP/releases/latest)
+[](LICENSE)
-*Seamlessly integrate your Paperless-ngx document management system with Claude via the Model Context Protocol*
+You've got a Paperless-ngx instance. You've got hundreds (thousands?) of documents. You *know* you should tag them, set correspondents, organize them properly. But who has time for that?
-[Features](#-features) • [Installation](#-installation) • [Configuration](#-configuration) • [API Reference](docs/API_REFERENCE.md) • [Contributing](#-contributing)
+PaperlessMCP connects your Paperless-ngx to any MCP-compatible AI. Now instead of clicking through the UI, you just ask:
-
+> "Find all my tax documents from 2023"
+>
+> "Tag these 50 invoices as 'Business Expense' and set the correspondent to 'Acme Corp'"
+>
+> "Upload this receipt and figure out what it is"
+>
+> "What documents am I missing from my insurance folder?"
+
+It's Paperless-ngx on LLM steroids. An interface designed *specifically* for AI to manage your documents while you do literally anything else.
---
-## 🎯 Overview
+## What Can AI Do With Your Paperless?
-PaperlessMCP is a Model Context Protocol (MCP) server that bridges [Paperless-ngx](https://github.com/paperless-ngx/paperless-ngx) with AI assistants like Claude. It provides comprehensive document management capabilities through a modern, type-safe .NET implementation.
+Everything. Full CRUD on every entity type:
-### What is MCP?
+| You Say | AI Does |
+|---------|---------|
+| "Find receipts from Amazon over $100" | Searches documents with filters |
+| "Tag all 2024 invoices as 'Tax Year 2024'" | Bulk updates dozens of docs at once |
+| "Upload this PDF and file it appropriately" | Uploads, auto-tags, sets correspondent |
+| "Delete all documents tagged 'Junk'" | Removes with confirmation (dry-run by default) |
+| "Create a tag for medical records, make it red" | Creates tag with color |
+| "Who sends me the most documents?" | Lists correspondents by document count |
+| "Set up a storage path for legal documents" | Creates organized folder structure |
-The [Model Context Protocol](https://modelcontextprotocol.io/) enables AI models to securely interact with external data sources and tools. PaperlessMCP implements this protocol to give Claude direct access to your document management system.
+**43 tools** covering:
+- **Documents** — search, upload, download, update, delete, bulk operations, OCR reprocessing
+- **Tags** — full CRUD with colors and matching rules
+- **Correspondents** — track who sends you stuff
+- **Document Types** — classify invoices, receipts, contracts, whatever
+- **Storage Paths** — organize files with smart templates
+- **Custom Fields** — add your own metadata (dates, amounts, URLs, etc.)
+
+All destructive operations require explicit confirmation and default to dry-run mode. AI can't nuke your archive by accident.
---
-## ✨ Features
+## Is PaperlessMCP Right For You?
-| Category | Capabilities |
-|----------|-------------|
-| **Documents** | Search, upload, download, update, delete, bulk operations, reprocess OCR |
-| **Tags** | Create, manage, auto-tagging rules, bulk delete |
-| **Correspondents** | Track document sources with auto-assignment |
-| **Document Types** | Classify documents with custom types |
-| **Storage Paths** | Organize files with template-based paths |
-| **Custom Fields** | Define metadata fields (string, date, boolean, monetary, etc.) |
+**Yes, if:**
-**Developer Features:** Dual transport (stdio/HTTP), pagination, dry-run mode, retry logic, comprehensive tests
+- You run Paperless-ngx (self-hosted or cloud)
+- You use any AI assistant that speaks MCP (Claude, or anything else supporting the protocol)
+- You have a backlog of untagged documents and feel guilty about it
+- You'd rather say "organize this" than click 47 buttons
+- You want to query your documents in plain English
+- You think computers should work for you, not the other way around
+
+**No, if:**
+
+- You don't use Paperless-ngx (this isn't a general document tool)
+- You enjoy manually tagging documents (weirdo, but respect)
+- You don't trust AI with your files (fair, but you can dry-run everything first)
+
+**The sweet spot:** You've got Paperless running, you've got an MCP-compatible AI, and you want them to be friends.
---
-## 🚀 Installation
+## Getting Started
-### Prerequisites
+### You'll Need
-- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
-- A running [Paperless-ngx](https://github.com/paperless-ngx/paperless-ngx) instance
-- Paperless-ngx API token ([How to get one](https://docs.paperless-ngx.com/api/#authorization))
+1. **A Paperless-ngx instance** with an API token
+ *(Settings → Django Admin → Tokens → Create one for your user)*
-### Quick Start
+2. **An MCP-compatible AI** (Claude Desktop, or anything speaking the protocol)
+
+### Option 1: Docker (Recommended)
+
+The fastest path from zero to talking to your documents.
+
+[](https://github.com/barryw/PaperlessMCP/releases/latest)
```bash
-git clone https://github.com/barryw/PaperlessMCP.git
-cd PaperlessMCP
-dotnet build
+docker run -d \
+ --name paperless-mcp \
+ --restart unless-stopped \
+ -e PAPERLESS_BASE_URL=https://your-paperless.example.com \
+ -e PAPERLESS_API_TOKEN=your-token-here \
+ -p 5000:5000 \
+ ghcr.io/barryw/paperlessmcp:vX.Y.Z
```
-### Claude Desktop Integration
+> **Grab the version from the badge above.** We don't use `latest` because [you deserve reproducible deployments](https://vsupalov.com/docker-latest-tag/).
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Connect your MCP client to `http://localhost:5000/mcp` and start talking to your documents.
+
+### Option 2: Claude Desktop
+
+Add to your config file:
+
+| OS | Path |
+|----|------|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
```json
{
@@ -69,7 +114,7 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
"command": "dotnet",
"args": ["run", "--project", "/path/to/PaperlessMCP/PaperlessMCP", "--", "--stdio"],
"env": {
- "PAPERLESS_BASE_URL": "https://your-paperless-instance.com",
+ "PAPERLESS_BASE_URL": "https://your-paperless.example.com",
"PAPERLESS_API_TOKEN": "your-token-here"
}
}
@@ -77,134 +122,195 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
}
```
-### Docker
+Restart Claude Desktop. Look for the tools icon — Paperless should be there.
+
+### Option 3: Kubernetes
+
+For the homelabbers running k8s. We include ready-to-use manifests with Kustomize support.
```bash
-docker build -t paperless-mcp ./PaperlessMCP
-docker run -e PAPERLESS_BASE_URL=https://... -e PAPERLESS_API_TOKEN=... -p 5000:5000 paperless-mcp
+# Clone and customize
+git clone https://github.com/barryw/PaperlessMCP.git
+cd PaperlessMCP/k8s
+
+# Create your secrets
+kubectl create secret generic paperless-mcp \
+ --from-literal=PAPERLESS_BASE_URL=https://your-paperless.example.com
+
+kubectl create secret generic paperless-token \
+ --from-literal=token=your-api-token-here
+
+# Deploy (edit the image tag first)
+kubectl apply -k .
```
+[See the manifests](k8s/)
+
+Includes: Deployment, Service, Ingress, Kustomization. Tweak to taste.
+
+### Option 4: From Source
+
+For contributors and tinkerers:
+
+```bash
+git clone https://github.com/barryw/PaperlessMCP.git
+cd PaperlessMCP
+dotnet run --project PaperlessMCP # HTTP/SSE on :5000
+dotnet run --project PaperlessMCP -- --stdio # stdio mode
+```
+
+Requires [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0).
+
---
-## ⚙️ Configuration
+## The Full Toolbox
+
+43 tools, organized by what they touch. Every entity supports full CRUD.
+
+
+Documents — the main event
+
+| Tool | What it does |
+|------|--------------|
+| `paperless.documents.search` | Find documents with full-text search and filters |
+| `paperless.documents.get` | Get a document by ID with all metadata |
+| `paperless.documents.upload` | Upload a document (base64) |
+| `paperless.documents.upload_from_path` | Upload from a file path |
+| `paperless.documents.update` | Update title, tags, correspondent, etc. |
+| `paperless.documents.delete` | Delete a document (requires confirmation) |
+| `paperless.documents.bulk_update` | Update multiple documents at once |
+| `paperless.documents.download` | Get download URL for original file |
+| `paperless.documents.preview` | Get preview URL |
+| `paperless.documents.thumbnail` | Get thumbnail URL |
+| `paperless.documents.reprocess` | Re-run OCR on a document |
+
+
+
+
+Tags — organize everything
+
+| Tool | What it does |
+|------|--------------|
+| `paperless.tags.list` | List all tags |
+| `paperless.tags.get` | Get a tag by ID |
+| `paperless.tags.create` | Create a tag with optional color and matching rules |
+| `paperless.tags.update` | Update a tag |
+| `paperless.tags.delete` | Delete a tag |
+| `paperless.tags.bulk_delete` | Delete multiple tags |
+
+
+
+
+Correspondents — who sends you stuff
+
+| Tool | What it does |
+|------|--------------|
+| `paperless.correspondents.list` | List all correspondents |
+| `paperless.correspondents.get` | Get a correspondent by ID |
+| `paperless.correspondents.create` | Create with optional matching rules |
+| `paperless.correspondents.update` | Update a correspondent |
+| `paperless.correspondents.delete` | Delete a correspondent |
+| `paperless.correspondents.bulk_delete` | Delete multiple correspondents |
+
+
+
+
+Document Types — invoices, receipts, contracts...
+
+| Tool | What it does |
+|------|--------------|
+| `paperless.document_types.list` | List all document types |
+| `paperless.document_types.get` | Get a document type by ID |
+| `paperless.document_types.create` | Create with optional matching rules |
+| `paperless.document_types.update` | Update a document type |
+| `paperless.document_types.delete` | Delete a document type |
+| `paperless.document_types.bulk_delete` | Delete multiple document types |
+
+
+
+
+Storage Paths — where things live
+
+| Tool | What it does |
+|------|--------------|
+| `paperless.storage_paths.list` | List all storage paths |
+| `paperless.storage_paths.get` | Get a storage path by ID |
+| `paperless.storage_paths.create` | Create with path template |
+| `paperless.storage_paths.update` | Update a storage path |
+| `paperless.storage_paths.delete` | Delete a storage path |
+| `paperless.storage_paths.bulk_delete` | Delete multiple storage paths |
+
+
+
+
+Custom Fields — your own metadata
+
+| Tool | What it does |
+|------|--------------|
+| `paperless.custom_fields.list` | List all custom field definitions |
+| `paperless.custom_fields.get` | Get a custom field by ID |
+| `paperless.custom_fields.create` | Create a field (string, date, number, monetary, etc.) |
+| `paperless.custom_fields.update` | Update a field definition |
+| `paperless.custom_fields.delete` | Delete a field |
+| `paperless.custom_fields.assign` | Assign a field value to a document |
+
+
+
+
+Health — is it alive?
+
+| Tool | What it does |
+|------|--------------|
+| `paperless.ping` | Check connectivity and auth |
+| `paperless.capabilities` | List supported features |
+
+
+
+---
+
+## Configuration
+
+Environment variables. That's it. No config files to manage.
| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `PAPERLESS_BASE_URL` | Yes | - | Base URL of your Paperless-ngx instance |
-| `PAPERLESS_API_TOKEN` | Yes | - | API authentication token |
-| `MAX_PAGE_SIZE` | No | 100 | Maximum items per page |
-| `MCP_PORT` | No | 5000 | HTTP server port (HTTP mode only) |
+|----------|:--------:|---------|-------------|
+| `PAPERLESS_BASE_URL` | Yes | — | Your Paperless-ngx URL |
+| `PAPERLESS_API_TOKEN` | Yes | — | API token for authentication |
+| `MCP_PORT` | | `5000` | Port for HTTP/SSE mode |
+| `MAX_PAGE_SIZE` | | `100` | Max items per paginated request |
-**Transport Modes:**
-- `dotnet run -- --stdio` — For Claude Desktop
-- `dotnet run` — HTTP mode at `http://localhost:5000/mcp`
+Aliases supported: `PAPERLESS_URL` and `PAPERLESS_TOKEN` also work if that's your style.
---
-## 💻 Usage
+## Contributing
-Once configured, ask Claude to interact with your documents:
-
-```
-"Search for all invoices from 2024"
-"Upload this PDF and tag it as 'Receipt'"
-"Show me documents tagged 'Important' with no correspondent"
-"Create a new tag called 'Urgent' with a red color"
-```
-
----
-
-## 📖 API Reference
-
-PaperlessMCP provides **43+ MCP tools** across these categories:
-
-| Category | Tools |
-|----------|-------|
-| Health | `ping`, `capabilities` |
-| Documents | `search`, `get`, `upload`, `upload_from_path`, `update`, `delete`, `bulk_update`, `download`, `preview`, `thumbnail`, `reprocess` |
-| Tags | `list`, `get`, `create`, `update`, `delete`, `bulk_delete` |
-| Correspondents | `list`, `get`, `create`, `update`, `delete`, `bulk_delete` |
-| Document Types | `list`, `get`, `create`, `update`, `delete`, `bulk_delete` |
-| Storage Paths | `list`, `get`, `create`, `update`, `delete`, `bulk_delete` |
-| Custom Fields | `list`, `get`, `create`, `update`, `delete`, `assign` |
-
-**[📚 Full API Reference →](docs/API_REFERENCE.md)**
-
----
-
-## 🛠️ Development
+Yes please. We use trunk-based development with conventional commits.
```bash
-dotnet restore # Restore dependencies
-dotnet build # Build
-dotnet test # Run tests
+git clone https://github.com/barryw/PaperlessMCP.git
+cd PaperlessMCP
+dotnet build
+dotnet test
```
-### CI/CD
+**The rules:**
+- Conventional commits (`feat:`, `fix:`, `docs:`, etc.) — versions bump automatically
+- Tests pass or it doesn't merge
+- Destructive operations need `confirm=true` and dry-run by default
-This project uses [Woodpecker CI](https://woodpecker-ci.org/) with trunk-based development:
-
-| Event | Actions |
-|-------|---------|
-| **Pull Request** | Build → Test → Docker verify |
-| **Merge to main** | Build → Test → Version → Package → Docker → Tag → Release |
-
-**Automatic Versioning:** Version bumps are determined by [Conventional Commits](https://www.conventionalcommits.org/):
-
-| Commit Type | Version Bump | Example |
-|-------------|--------------|---------|
-| `fix:` | Patch (0.0.X) | `fix: handle null response` |
-| `feat:` | Minor (0.X.0) | `feat: add bulk export` |
-| `feat!:` | Major (X.0.0) | `feat!: change API format` |
-
-**Docker Images:**
-- `ghcr.io/barryw/paperlessmcp:latest` — Latest release
-- `ghcr.io/barryw/paperlessmcp:vX.Y.Z` — Specific version
-
-### Project Structure
-
-```
-PaperlessMCP/
-├── PaperlessMCP/ # Main application
-│ ├── Client/ # Paperless API client
-│ ├── Models/ # Data models
-│ ├── Tools/ # MCP tool implementations
-│ └── Program.cs # Entry point
-├── PaperlessMCP.Tests/ # Test project
-└── docs/ # Documentation
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full rundown.
---
-## 🤝 Contributing
+## License
-Contributions welcome! We use trunk-based development with conventional commits.
-
-See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines on:
-- Commit message format
-- Pull request process
-- Local development setup
+[MIT](LICENSE) — do whatever you want, just don't blame me.
---
-## 📄 License
+## Acknowledgments
-MIT License - see [LICENSE](LICENSE) for details.
-
----
-
-## 🙏 Acknowledgments
-
-- [Paperless-ngx](https://github.com/paperless-ngx/paperless-ngx)
-- [Model Context Protocol](https://modelcontextprotocol.io/)
-- [Anthropic](https://www.anthropic.com/)
-
----
-
-
-
-**[⬆ back to top](#-paperlessmcp)**
-
-Made with ❤️ for the Paperless-ngx community
-
-
+- [Paperless-ngx](https://github.com/paperless-ngx/paperless-ngx) — the document system that makes this worth building
+- [Model Context Protocol](https://modelcontextprotocol.io/) — the glue between AI and everything else
+- Everyone who's ever felt guilty about their untagged documents