dreep-mcp 0.1.0__tar.gz

dreep_mcp-0.1.0/.gitignore

@@ -0,0 +1,27 @@
+# Environments
+.venv/
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/
+
+# Node
+node_modules/
+*.tgz

dreep_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- The Dreep MCP server, built on the `dreep` Python SDK 0.1.x and the MCP Python SDK 2.x.
+- Tools: `upload_file`, `create_upload_url`, `confirm_upload`, `list_media`,
+  `remove_background`, `extract_text`, `convert_document`, `build_delivery_url`,
+  `build_signed_url`, `create_folder`, `list_folders`, `create_preset`, `list_presets`,
+  `get_usage`, and the opt-in `delete_media` and `delete_preset`.
+- stdio and streamable HTTP transports, with bearer-token protection for HTTP.
+- File-root sandboxing with `DREEP_MCP_FILE_ROOTS`.
+- The `dreep-mcp` npm package, which runs the server through `uvx` or `pipx`.

dreep_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dreep
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dreep_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,389 @@
+Metadata-Version: 2.5
+Name: dreep-mcp
+Version: 0.1.0
+Summary: The official Dreep MCP server: let any AI agent upload, transform, convert, OCR and deliver media through Dreep.
+Project-URL: Homepage, https://dreep.cloud
+Project-URL: Documentation, https://docs.dreep.cloud
+Project-URL: Repository, https://github.com/IndigoSoftwares21/dreep-mcp
+Project-URL: Issues, https://github.com/IndigoSoftwares21/dreep-mcp/issues
+Project-URL: Changelog, https://github.com/IndigoSoftwares21/dreep-mcp/blob/main/CHANGELOG.md
+Author: Dreep
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,cdn,dreep,image,mcp,media,model-context-protocol,ocr
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Multimedia
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: dreep<0.2,>=0.1.1
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<a href="https://dreep.cloud">
+  <img src="https://raw.githubusercontent.com/IndigoSoftwares21/dreep-python/main/.github/assets/dreep-logo.svg" alt="Dreep" width="96" height="107">
+</a>
+
+<h1>Dreep MCP Server</h1>
+
+<p><strong>Give any AI agent a media pipeline.</strong><br>
+The official <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server for
+<a href="https://dreep.cloud">Dreep</a>: upload, transform, convert, OCR and deliver images,
+videos and documents from Claude, Cursor, VS Code, Codex, Gemini and every other MCP client.</p>
+
+[![PyPI](https://img.shields.io/pypi/v/dreep-mcp?color=CB1C85&label=pypi&logo=pypi&logoColor=white&cacheSeconds=3600)](https://pypi.org/project/dreep-mcp/)
+[![npm](https://img.shields.io/npm/v/dreep-mcp?color=4A063A&label=npm&logo=npm&logoColor=white&cacheSeconds=3600)](https://www.npmjs.com/package/dreep-mcp)
+[![CI](https://github.com/abetoluwani/dreep-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/abetoluwani/dreep-mcp/actions/workflows/ci.yml)
+[![MCP](https://img.shields.io/badge/MCP-stdio%20%7C%20streamable%20HTTP-CB1C85)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/license-MIT-4A063A)](LICENSE)
+
+[Dreep docs](https://docs.dreep.cloud) ·
+[API reference](https://docs.dreep.cloud/api-reference/upload/upload-media) ·
+[Python SDK](https://github.com/IndigoSoftwares21/dreep-python) ·
+[Changelog](CHANGELOG.md) ·
+[Report a bug](https://github.com/abetoluwani/dreep-mcp/issues/new?template=bug_report.yml)
+
+</div>
+
+---
+
+Ask your agent things like:
+
+> *"Upload `~/Desktop/launch/hero.png` to `marketing/2026` and give me a 1200px WebP and a 400px square thumbnail."*
+>
+> *"Pull the text out of this scanned invoice."*
+>
+> *"Convert `contract.docx` to PDF and give me a link that expires in an hour."*
+>
+> *"Cut the background out of `product.jpg` and show it on white."*
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Quick start](#quick-start)
+- [Add it to your client](#add-it-to-your-client): [Claude Desktop](#claude-desktop) · [Claude Code](#claude-code) · [Cursor](#cursor) · [VS Code](#vs-code-github-copilot) · [Windsurf](#windsurf) · [Codex CLI](#openai-codex-cli) · [Gemini CLI](#gemini-cli) · [Zed](#zed) · [Cline and others](#cline-and-other-clients) · [Remote (HTTP)](#remote-clients-over-http)
+- [Tools](#tools)
+- [Configuration](#configuration)
+- [Security](#security)
+- [Development](#development)
+
+## How it works
+
+```mermaid
+flowchart LR
+    A["AI agent<br/>(Claude, Cursor, Codex...)"] -- "MCP<br/>stdio or HTTP" --> S["dreep-mcp"]
+    S -- "dreep Python SDK<br/>(your API key)" --> API["Dreep API"]
+    API --> CDN["Dreep CDN<br/>(or your custom domain)"]
+    S -. "URL building:<br/>no network" .-> CDN
+```
+
+1. Your MCP client starts `dreep-mcp` on your machine (stdio), or connects to one you host (streamable HTTP).
+2. The agent sees 14 tools (16 with deletes enabled), each with a typed JSON schema that lists every valid transform value, so it calls them correctly the first time.
+3. Each tool calls the official [`dreep` Python SDK](https://github.com/IndigoSoftwares21/dreep-python), which talks to the Dreep API with your key. Delivery and signed URLs are built locally, with no API call.
+4. Results come back as structured JSON. Every asset carries the delivery `url` exactly as Dreep returned it, custom CDN domain included.
+
+There is one implementation, in Python. The npm package `dreep-mcp` is a small launcher that runs the same PyPI package through `uvx` (or `pipx`), so `npx` users get the identical server.
+
+## Quick start
+
+1. Create an API key on the **API Keys** page of the [Dreep dashboard](https://dreep.cloud).
+2. Install [uv](https://docs.astral.sh/uv/getting-started/installation/), which runs the server with no separate install step:
+
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. Add the server to your client (below). Any of these three commands starts the same server:
+
+   | Runner | Command | Needs |
+   | :- | :- | :- |
+   | **uvx** (recommended) | `uvx dreep-mcp` | [uv](https://docs.astral.sh/uv/) |
+   | **npx** | `npx -y dreep-mcp` | Node 18+ plus uv or pipx |
+   | **pip** | `pip install dreep-mcp`, then `dreep-mcp` | Python 3.10+ |
+
+   The examples below use `uvx`. To use npx instead, swap `"command": "uvx", "args": ["dreep-mcp"]` for `"command": "npx", "args": ["-y", "dreep-mcp"]`.
+
+## Add it to your client
+
+Every client needs the same three things: a command (`uvx`), its arguments (`dreep-mcp`), and your API key in the `DREEP_API_KEY` environment variable. Replace `drp_live_your_key` with your key. Add `DREEP_SIGNING_SECRET` if you use signed folders, and `DREEP_MCP_ALLOW_DELETE` if you want the delete tools (see [Configuration](#configuration)).
+
+### Claude Desktop
+
+Open **Settings → Developer → Edit Config**, which opens `claude_desktop_config.json`:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dreep": {
+      "command": "uvx",
+      "args": ["dreep-mcp"],
+      "env": {
+        "DREEP_API_KEY": "drp_live_your_key",
+        "DREEP_SIGNING_SECRET": "your_signing_secret"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. **Dreep** appears under the tools (slider) icon in the message box.
+
+> If Claude Desktop can't find `uvx`, use its full path (run `which uvx`, for example `/Users/you/.local/bin/uvx`). GUI apps don't always inherit your shell's `PATH`.
+
+### Claude Code
+
+```bash
+claude mcp add dreep --scope user -e DREEP_API_KEY=drp_live_your_key -- uvx dreep-mcp
+```
+
+`--scope user` makes it available in every project; leave it out to add it to the current project only, or use `--scope project` to share it with your team through `.mcp.json` (keep the key out of that file, as shown below). Check it with `claude mcp list`, or `/mcp` inside a session.
+
+To share the setup in a repository without committing the key, put this in `.mcp.json` and let each person export `DREEP_API_KEY` in their own shell:
+
+```json
+{
+  "mcpServers": {
+    "dreep": {
+      "command": "uvx",
+      "args": ["dreep-mcp"],
+      "env": { "DREEP_API_KEY": "${DREEP_API_KEY}" }
+    }
+  }
+}
+```
+
+### Cursor
+
+Open **Cursor Settings → MCP → Add new MCP server**, or edit `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "dreep": {
+      "command": "uvx",
+      "args": ["dreep-mcp"],
+      "env": { "DREEP_API_KEY": "drp_live_your_key" }
+    }
+  }
+}
+```
+
+The Dreep tools are then available to the agent in chat.
+
+### VS Code (GitHub Copilot)
+
+Create `.vscode/mcp.json`. VS Code asks for the key the first time and stores it securely:
+
+```json
+{
+  "inputs": [
+    {
+      "type": "promptString",
+      "id": "dreep-api-key",
+      "description": "Dreep API key",
+      "password": true
+    }
+  ],
+  "servers": {
+    "dreep": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["dreep-mcp"],
+      "env": { "DREEP_API_KEY": "${input:dreep-api-key}" }
+    }
+  }
+}
+```
+
+Open Copilot Chat in **Agent** mode and pick the Dreep tools from the tools menu.
+
+### Windsurf
+
+Open **Windsurf Settings → Cascade → MCP Servers → View raw config**, or edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dreep": {
+      "command": "uvx",
+      "args": ["dreep-mcp"],
+      "env": { "DREEP_API_KEY": "drp_live_your_key" }
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.dreep]
+command = "uvx"
+args = ["dreep-mcp"]
+env = { DREEP_API_KEY = "drp_live_your_key" }
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json` (or `.gemini/settings.json` in a project):
+
+```json
+{
+  "mcpServers": {
+    "dreep": {
+      "command": "uvx",
+      "args": ["dreep-mcp"],
+      "env": { "DREEP_API_KEY": "drp_live_your_key" }
+    }
+  }
+}
+```
+
+### Zed
+
+Add to Zed's `settings.json` (**Zed → Settings → Open Settings**):
+
+```json
+{
+  "context_servers": {
+    "dreep": {
+      "command": "uvx",
+      "args": ["dreep-mcp"],
+      "env": { "DREEP_API_KEY": "drp_live_your_key" }
+    }
+  }
+}
+```
+
+### Cline and other clients
+
+Cline (**MCP Servers → Configure**), Roo Code, Continue, Goose, JetBrains AI Assistant, LM Studio and most other clients take the same `mcpServers` block shown for [Cursor](#cursor). Anything that can launch a stdio MCP server can run `uvx dreep-mcp` with `DREEP_API_KEY` set.
+
+### Remote clients over HTTP
+
+For web-based agents, shared team servers or containers, run the streamable HTTP transport:
+
+```bash
+export DREEP_API_KEY=drp_live_your_key
+export DREEP_MCP_HTTP_TOKEN="$(openssl rand -hex 32)"
+uvx dreep-mcp --transport http --host 0.0.0.0 --port 8000
+```
+
+The endpoint is `http://<host>:8000/mcp`, and every request must send `Authorization: Bearer <DREEP_MCP_HTTP_TOKEN>`. Put it behind HTTPS (a reverse proxy or your platform's load balancer) before exposing it. Then connect, for example from Claude Code:
+
+```bash
+claude mcp add --transport http dreep https://mcp.example.com/mcp --header "Authorization: Bearer $DREEP_MCP_HTTP_TOKEN"
+```
+
+Without `--host` it binds to `127.0.0.1`, and it refuses to bind to any other address unless `DREEP_MCP_HTTP_TOKEN` is set. Over HTTP the tools can't read files on the server unless you allow specific directories with `DREEP_MCP_FILE_ROOTS`; remote callers send files as `content_base64` instead.
+
+## Tools
+
+| Tool | What it does | Kind |
+| :- | :- | :- |
+| `upload_file` | Uploads an image, video, audio file or document from a local path or base64 content, optionally transforming it before storage. Files over 100 MB stream straight to storage. | writes |
+| `create_upload_url` | Starts a presigned upload for bytes the server can't read (PUT them, then confirm). | writes |
+| `confirm_upload` | Finalises a presigned upload and returns the asset. | writes |
+| `list_media` | Lists assets with pagination, filtered by folder. | read-only |
+| `remove_background` | Cuts the subject out of an image and stores a transparent PNG or WebP. | writes |
+| `extract_text` | OCR for images and PDFs, optionally with line blocks and bounding boxes. | writes |
+| `convert_document` | Word ↔ PDF, Excel, PowerPoint, CSV, or a PDF page to PNG/JPEG. | writes |
+| `build_delivery_url` | Resize, crop, convert, compress, blur, round or trim an asset at the CDN. | local, no network |
+| `build_signed_url` | A time-limited link for an asset in a signed folder. | local, no network |
+| `create_folder` | Creates a folder or a whole path, with access control (`public`, `private`, `signed`) on top-level folders. | writes |
+| `list_folders` | Lists folders with their paths and access control. | read-only |
+| `create_preset` | Saves a named transform for reuse. | writes |
+| `list_presets` | Lists saved presets. | read-only |
+| `get_usage` | Storage used and image, file and folder counts. | read-only |
+| `delete_media` | Permanently deletes an asset. **Only when `DREEP_MCP_ALLOW_DELETE` is set.** | destructive |
+| `delete_preset` | Deletes a preset. **Only when `DREEP_MCP_ALLOW_DELETE` is set.** | destructive |
+
+Every tool carries MCP [annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations): read-only tools are marked so clients can run them without asking, and delete tools are marked destructive so clients ask you first.
+
+A few behaviours come straight from the [API reference](https://docs.dreep.cloud), verified against the live API:
+
+- **Use URLs as returned.** Projects can serve assets from a custom CDN domain, so the tools never construct a delivery URL from scratch; they transform the one Dreep returned.
+- **Signed URLs sign the asset and expiry only** (`HMAC-SHA256` over `"{id}:{exp}"`). Transform parameters ride along unsigned.
+- **Access control is set on top-level folders**; nested folders inherit it. The API has no endpoint for deleting folders.
+- **Presets need a `format`**, and preset keys may only contain lowercase letters, digits and underscores.
+
+## Configuration
+
+| Variable | Required | Purpose |
+| :- | :- | :- |
+| `DREEP_API_KEY` | yes | Your project API key. |
+| `DREEP_SIGNING_SECRET` | for signed URLs | The URL Signing Secret from the dashboard's API Keys page. |
+| `DREEP_MCP_ALLOW_DELETE` | no | `1` registers `delete_media` and `delete_preset`. Off by default. |
+| `DREEP_MCP_FILE_ROOTS` | no | Directories the file tools may read, separated by `:` (`;` on Windows). Unset over stdio means any file you can read; unset over HTTP means none. |
+| `DREEP_MCP_HTTP_TOKEN` | for public HTTP | Bearer token every HTTP request must present. |
+
+Command-line options:
+
+```text
+dreep-mcp [--transport {stdio,http}] [--host HOST] [--port PORT] [--path PATH]
+```
+
+| Option | Default |
+| :- | :- |
+| `--transport` | `stdio` |
+| `--host` | `127.0.0.1` |
+| `--port` | `8000` |
+| `--path` | `/mcp` |
+
+## Security
+
+- **Your API key can read, upload and delete everything in the project.** It stays in the server's environment and is sent only to the Dreep API, never to the agent.
+- **Deletes are off unless you turn them on**, and are marked destructive so clients confirm them.
+- **File access is scoped.** Restrict which directories the agent can upload from with `DREEP_MCP_FILE_ROOTS`. Over HTTP, local file reads are off unless you set it.
+- **The HTTP transport binds to localhost by default** and refuses a public address without `DREEP_MCP_HTTP_TOKEN`. Tokens are compared in constant time.
+- **Signed URLs are bearer tokens.** Anyone with the link can fetch the asset until it expires.
+
+Report vulnerabilities privately; see [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+git clone https://github.com/abetoluwani/dreep-mcp.git
+cd dreep-mcp
+bash scripts/setup_hooks.sh      # venv, dev dependencies, git hooks
+bash scripts/quality_gate.sh     # lint, format, repository rules, mypy --strict, tests, npm tests
+```
+
+Try your local checkout in a client by pointing it at the venv: `"command": "/path/to/dreep-mcp/.venv/bin/dreep-mcp"`. To poke at the tools interactively, run the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+npx @modelcontextprotocol/inspector .venv/bin/dreep-mcp
+```
+
+The layout:
+
+| Path | What lives there |
+| :- | :- |
+| `src/dreep_mcp/_tools_*.py` | One module per tool group: uploads, media, processing, URLs, project |
+| `src/dreep_mcp/_server.py` | Builds the server and registers every tool group |
+| `src/dreep_mcp/_cli.py` | The `dreep-mcp` command and both transports |
+| `src/dreep_mcp/_params.py`, `_transform_input.py` | The schemas the agent reads |
+| `npm/` | The `npx` launcher |
+| `scripts/rules/` | Repository rules: file length, no magic strings, DRY, layering, security |
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request, and [AGENTS.md](AGENTS.md) if you're an AI agent working in this repository.
+
+## License
+
+[MIT](LICENSE)