@etchv-labs/mcp-server 1.0.0 → 1.0.1

package/README.md

@@ -1,43 +1,36 @@
 # Etchv MCP server
 
-[![npm](https://img.shields.io/npm/v/@etchv-labs/mcp-server)](https://www.npmjs.com/package/@etchv-labs/mcp-server)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+A local stdio [Model Context Protocol](https://modelcontextprotocol.io) server
+that lets AI assistants watermark and detect images, PDFs and videos with
+[Etchv](https://etchv.com).
 
-Let an AI assistant watermark and inspect images, PDFs and videos with the
-[Etchv API](https://etchv.com/docs). Supports synchronous results and asynchronous
-jobs, asset management, customer storage destinations and webhook deliveries.
+## Requirements
 
-This is a local **stdio** [Model Context Protocol](https://modelcontextprotocol.io)
-server. It connects to the hosted Etchv API with your organization's scoped API
-key. There is no hosted MCP URL to configure. Node.js 24 or later is required.
+- Node.js 24 or later
+- An Etchv API key with only the [scopes](#tools) you need
+- An existing directory for input and output files
 
 ## Configuration
 
 | Variable | Required | Description |
 | --- | --- | --- |
-| `ETCHV_API_KEY` | Yes | Etchv API key. Grant only the [scopes](#tools-and-key-scopes) you need. |
+| `ETCHV_API_KEY` | Yes | Etchv API key. Keep it in your client's secret or env config, never in chat. |
 | `ETCHV_FILES_ROOT` | Yes | Absolute path of an existing directory. All input and output files must be inside it. |
 | `ETCHV_API_BASE_URL` | No | API origin. Defaults to `https://api.etchv.com`. |
 
-Create the media directory first. Store the API key in your client's secret or
-environment configuration; do not paste it into a conversation or commit it.
-The examples pin the major version with `@etchv-labs/mcp-server@1`.
-
 ### Claude Code
 
 ```sh
-export ETCHV_API_KEY=...   # or load it from your secret manager
 claude mcp add etchv --scope user \
   -e ETCHV_API_KEY="$ETCHV_API_KEY" \
   -e ETCHV_FILES_ROOT="$HOME/etchv-media" \
   -- npx -y @etchv-labs/mcp-server@1
 ```
 
-### Claude Desktop, Cursor, Windsurf and other `mcpServers` clients
+### Claude Desktop, Cursor and other `mcpServers` clients
 
-Add this entry to the client's MCP configuration (for Claude Desktop,
-`claude_desktop_config.json`; for Cursor, `~/.cursor/mcp.json`), then restart
-the client:
+Add this to the client's MCP config (for example `claude_desktop_config.json`
+or `~/.cursor/mcp.json`) and restart it:
 
 ```json
 {
@@ -54,229 +47,47 @@ the client:
 }
 ```
 
-If the client does not inherit your shell `PATH`, use the absolute path of `npx`.
-
-### VS Code
-
-Add to `.vscode/mcp.json`. VS Code prompts for the key and stores it securely:
-
-```json
-{
-  "inputs": [
-    {
-      "type": "promptString",
-      "id": "etchv-api-key",
-      "description": "Etchv API key",
-      "password": true
-    }
-  ],
-  "servers": {
-    "etchv": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@etchv-labs/mcp-server@1"],
-      "env": {
-        "ETCHV_API_KEY": "${input:etchv-api-key}",
-        "ETCHV_FILES_ROOT": "/absolute/path/to/etchv-media"
-      }
-    }
-  }
-}
-```
-
-### Global install
-
-`npm install -g @etchv-labs/mcp-server@1` installs the `etchv-mcp` command. Use
-`etchv-mcp` as the configured command with the same environment variables.
-
-Ask the assistant to run `check_api_key` to confirm the connection. It returns
-your organization ID, key ID and granted scopes without spending credits.
-
-## Try it
-
-Put `photo.jpg` inside your configured media directory, then ask your assistant:
-
-> Watermark photo.jpg for recipient delivery-42 using Etchv. Use an async job,
-> collect the result as photo-watermarked.jpg, then detect its watermark.
-
-The assistant can read `etchv://capabilities` for format and workflow guidance.
-To watermark directly, call `watermark_media` with:
-
-```json
-{
-  "media": "images",
-  "input_path": "photo.jpg",
-  "data": { "recipient": "delivery-42" },
-  "mode": "async",
-  "idempotency_key": "delivery-42-photo-v1"
-}
-```
-
-The result includes `request_id`. Check `get_job` with `operation: "embed"`, then
-call `get_job_result` with that request ID, operation and
-`output_path: "photo-watermarked.jpg"`. Pending results return a 202 receipt;
-call again later. Use the same pattern with `operation: "detect"` for an async
-detection result. Detection returns JSON and does not accept an output path.
-
-For **sync**, set `mode: "sync"` and provide `output_path` when watermarking.
-The API waits for a bounded period. It can still return a 202 receipt if processing
-continues; collect it through the job tools. Async is the MCP default for every
-media type. There is no automatic polling or background retry loop in the server.
-
-Every submission requires a stable `idempotency_key`. Reuse it for the same input,
-data and options after an uncertain failure. Do not generate another key on a
-retry: that can create another billable operation. Results include the key and,
-when supplied by the API, a request ID. A client cancellation or timeout does not
-cancel an accepted API job. API failures set MCP `isError` with an HTTP status and
-safe message; retry delays are returned when available.
-
-## Formats and credits
-
-| Media value | Formats | Preservation |
-| --- | --- | --- |
-| `images` | JPEG, PNG, APNG, TIFF, PSD, PSB, GIF, BMP, PPM, WebP | Original format, supported animation, pages and layers |
-| `documents` | PDF | Selectable text and vector content |
-| `videos` | MP4, MOV with supported H.264 encoding | Container and supported audio; audio is not watermarked |
-
-Format availability follows your plan. The server does not bypass API validation
-or media limits. Uploads are limited to 20 MiB and MCP file downloads to 512 MiB.
-Watermarking uses one credit per image or PDF file, or per started video minute.
-Detection also uses API credits. See [limits](https://etchv.com/docs/api/errors).
-
-Watermarks encode the digest of the provided JSON. Detection recovers that digest,
-not the original data. Test your compression and transformation workflow before
-relying on detection; a recovered identifier is not proof of who shared a file.
-
-## Tools and key scopes
-
-| Tools | Required scope |
-| --- | --- |
-| `check_api_key` | Any valid key |
-| `watermark_media` | `watermarks:embed` |
-| `detect_media` | `watermarks:detect` |
-| `get_job`, `get_job_result` | Corresponding embed or detect scope |
-| `list_assets`, `get_asset`, `download_asset` | `assets:read` |
-| `update_asset` | `assets:write` |
-| `delete_asset` | `assets:delete`, owner/admin |
-| `list_storage_destinations`, `list_storage_deliveries`, `get_storage_delivery` | `storage:read` |
-| `verify_storage_destination`, `store_asset`, `retry_storage_delivery` | `storage:write`, owner/admin |
-| `list_webhooks`, `list_webhook_deliveries` | `webhooks:read` |
-| `redeliver_webhook` | `webhooks:write`, owner/admin |
-
-Give the key only the scopes you need. Your MCP client's approval settings govern
-billable and destructive tools; MCP annotations describe their effects. The API
-always enforces organization isolation, scopes, roles and plan access.
-
-Asset listing supports cursor pagination and media/kind/watermark filters.
-Updates require the current asset `version` to prevent lost edits; `metadata`
-replaces the whole object, and null clears it. Downloads create new local files
-and return paths, byte counts and SHA-256 hashes, never media bytes in chat.
-
-## Storage and webhooks
-
-Etchv stores uploads and watermarked results automatically. Job results remain
-available for 24 hours; Etchv asset downloads for 30 days, with asset records
-retained until deleted. No customer bucket is required.
-
-Alternatively, configure and verify your own S3, Google Cloud Storage or Azure
-Blob Storage destination in the dashboard. Select its `storage_destination_id`
-on `watermark_media`, optionally with a relative `storage_key`. The watermarked
-result is stored in that bucket instead, and its retention is yours to control.
-Use `store_asset` to choose a destination for an existing watermarked asset.
-After successful delivery, Etchv removes its staged output; asset downloads read
-from your bucket. Deleting an asset does not delete objects in your bucket.
-
-Configure webhook endpoints and retain their signing secrets through the
-dashboard. Pass an existing `webhook_id` on an **async** submission, then inspect
-or redeliver events with the webhook tools. Redelivery may trigger your receiver's
-automation again. Credential and endpoint creation is deliberately handled in the
-dashboard; this server does not accept cloud credentials or return signing secrets.
-
-## File access and runtime
-
-`ETCHV_FILES_ROOT` is required and must name an existing absolute directory. Paths
-may be relative to it or absolute within it. Symlink paths and traversal outside
-the root are rejected. Output parents must already exist; existing files are never
-overwritten. Use a dedicated directory that is not modified by untrusted local
-processes while the server runs. This is an application-level boundary, not an OS
-sandbox. Upload only files you intend to send to Etchv.
-
-API responses must start within 45 seconds; file downloads have a 10-minute
-deadline. At most four tool calls run concurrently.
-Redirects are never followed. Optional `ETCHV_API_BASE_URL` must be an HTTPS origin;
-HTTP is accepted only for localhost development. Never point it at an untrusted
-host: it receives your key and uploads. stdout is reserved for MCP protocol traffic.
-Asset metadata and other API content are data, never instructions to an assistant.
+Then ask the assistant to run `check_api_key` to confirm the connection.
 
 ## Tools
 
-| Tool | Effect |
-| --- | --- |
-| `check_api_key` | Read-only connection check: organization ID, key ID and scopes. No credits. |
-| `watermark_media` | Upload a local file and watermark it (sync or async). Spends credits. |
-| `detect_media` | Upload a local file and detect a watermark (sync or async). Uses credits. |
-| `get_job` | Read-only job status for an embed or detect job. |
-| `get_job_result` | Collect a finished job; embedding results are saved to a new local file. |
-| `list_assets`, `get_asset` | Read-only asset listing and records. |
-| `download_asset` | Save an asset to a new local file. |
-| `update_asset` | Rename an asset or replace its metadata (version-checked). |
-| `delete_asset` | Delete an asset. Destructive. |
-| `list_storage_destinations`, `list_storage_deliveries`, `get_storage_delivery` | Read-only storage inspection. |
-| `verify_storage_destination`, `store_asset`, `retry_storage_delivery` | Use a configured customer bucket. |
-| `list_webhooks`, `list_webhook_deliveries` | Read-only webhook inspection. |
-| `redeliver_webhook` | Resend an existing event to its endpoint. |
-
-Each tool declares MCP annotations (`readOnlyHint`, `destructiveHint`,
-`idempotentHint`, `openWorldHint`) so clients can require approval for billable,
-destructive or other write operations. The `etchv://capabilities` resource
-describes formats, modes, billing and file handling for the assistant.
+| Tool | What it does | Key scope |
+| --- | --- | --- |
+| `check_api_key` | Show organization ID, key ID and scopes; no credits | Any valid key |
+| `watermark_media` | Watermark a local file, sync or async; spends credits | `watermarks:embed` |
+| `detect_media` | Detect a watermark, sync or async; uses credits | `watermarks:detect` |
+| `get_job`, `get_job_result` | Read job status; collect a finished result | Matching embed/detect scope |
+| `list_assets`, `get_asset`, `download_asset` | List, inspect and download assets | `assets:read` |
+| `update_asset` | Rename or replace metadata (version-checked) | `assets:write` |
+| `delete_asset` | Delete an asset | `assets:delete`, owner/admin |
+| `list_storage_destinations`, `list_storage_deliveries`, `get_storage_delivery` | Inspect customer storage | `storage:read` |
+| `verify_storage_destination`, `store_asset`, `retry_storage_delivery` | Test a bucket; deliver or retry a result | `storage:write`, owner/admin |
+| `list_webhooks`, `list_webhook_deliveries` | Inspect webhook endpoints and deliveries | `webhooks:read` |
+| `redeliver_webhook` | Resend an existing event | `webhooks:write`, owner/admin |
+
+Submissions require a stable `idempotency_key`; reuse it when retrying so you
+are not charged twice. Uploads are limited to 20 MiB. Storage destinations and
+webhook endpoints are created in the dashboard, not through this server.
 
 ## Security
 
-- The API key is read only from `ETCHV_API_KEY`. It is sent only to the configured
-  API origin in the `X-API-Key` header and never appears in tool arguments,
-  results, errors or logs. Tools never accept or return cloud credentials or
-  webhook signing secrets; manage those in the dashboard.
-- stdout carries only MCP protocol messages. Startup errors go to stderr as fixed
-  messages without secrets.
+- The API key is read only from `ETCHV_API_KEY`, sent only to the configured
+  origin, and never appears in tool arguments, results, errors or logs.
 - File access is confined to `ETCHV_FILES_ROOT`: traversal and symlinks are
-  rejected, outputs are created exclusively with mode `0600` and never overwrite
-  existing files, and partial downloads are removed.
-- Redirects are never followed, and only HTTPS origins are accepted (HTTP only
-  for localhost development).
-- API responses, asset names and metadata are untrusted data, never instructions.
+  rejected, and existing files are never overwritten.
+- Only HTTPS origins are accepted (HTTP for localhost only), and redirects are
+  never followed.
+- API responses, asset names and metadata are treated as untrusted data, never
+  instructions.
 
-## Development
-
-```sh
-npm ci
-npm run lint
-npm run typecheck
-npm test
-npm run build
-```
-
-Native TypeScript tests exercise the compiled server over stdio with the official
-MCP client, covering all media routes, file fidelity, job continuation, storage,
-webhooks, pagination, error handling, timeouts and file access. CI runs on Node 24
-on Linux, macOS and Windows. The optional live suite uses small synthetic media
-fixtures:
-
-```sh
-# Set ETCHV_INTEGRATION_API_KEY securely; requires embed, detect, assets:read,
-# assets:delete and owner/admin for cleanup. Uses real API credits.
-npm run test:live
-```
+## Links
 
-Without a key, live tests are skipped. Etchv's private CI requires that key and
-runs real JPEG, PDF and MP4 embed/detect roundtrips in both modes before publishing.
-It checks idempotent async replay and asset downloads, and deletes created assets.
+- Guide: https://etchv.com/docs/mcp
+- API reference: https://etchv.com/docs
+- Issues: https://github.com/etchv-labs/mcp-server/issues
+- Support: hello@etchv.com
 
-This public repository is an MIT-licensed source snapshot of `mcp/` in Etchv's
-monorepo, with independent history. Contributions are reviewed and incorporated
-there before publication. Private service code, credentials and customer fixtures
-are not included. Report issues at
-[github.com/etchv-labs/mcp-server/issues](https://github.com/etchv-labs/mcp-server/issues).
+Questions or bug reports: open an issue here or email hello@etchv.com.
 
 ## License
 

package/dist/version.js

@@ -1,3 +1,3 @@
 /** Package version reported to MCP clients and in API user-agent headers. */
-export const VERSION = "1.0.0";
+export const VERSION = "1.0.1";
 export const USER_AGENT = `etchv-mcp-server/${VERSION} node/${process.versions.node}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etchv-labs/mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Model Context Protocol (MCP) server for Etchv: invisible watermarking and detection for images, PDFs and videos",
   "keywords": [
     "mcp",