@webapper/cloudsee-drive-mcp 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented here. This file is managed by
+[semantic-release](https://semantic-release.gitbook.io/) from
+[Conventional Commits](https://www.conventionalcommits.org/) once releasing begins.
+
+## [Unreleased]
+
+### Added
+
+- Initial CloudSee Drive MCP server (CSD-586, Phase 2).
+- Stdio MCP server exposing **16 tools** across read / download / write:
+  `list_buckets`, `browse_folder`, `search_files`, `recent_files`, `get_file_metadata`,
+  `get_file_tags`, `download_file`, `share_link`, `upload_file`, `create_folder`,
+  `rename_file`, `move_file`, `duplicate_file`, `delete_files`, `update_metadata`,
+  `restore_archived_file`.
+- Typed `CloudSeeClient` over the `drive-bridge` `/v1/*` data plane: `X-Api-Key-Id` /
+  `X-Api-Key-Secret` auth, envelope unwrapping, retry with backoff + `Retry-After`, and
+  secret-safe error handling.
+- Opaque, dialect-tagged pagination cursors normalizing the API's `nextPage` / `marker` /
+  `lastEvaluatedKey` / `pageToken` / `nextToken` families.
+- Two-step confirmation guardrail (`confirm: true`) on destructive tools, with
+  `destructiveHint` annotations.
+- Tool↔contract drift test gating the build against a committed snapshot of the API surface.
+- OSS scaffolding: MIT license, README quickstart, contributing/security docs, GitHub Actions
+  CI (lint/typecheck/test/build/smoke on macOS/Linux/Windows × Node 18/20), and a
+  semantic-release publish workflow.
+
+### Notes
+
+- Write/delete/share tools are present but their end-to-end authorization is **sequenced
+  behind the gateway's RBAC wiring (CSD-572)**.
+- `upload_file` supports single-file uploads up to 8 MiB (multipart planned);
+  `search_files` is single-folder (non-recursive).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Webapper
+
+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.

package/README.md

@@ -0,0 +1,146 @@
+# CloudSee Drive MCP server
+
+[![CI](https://github.com/webapper/cloudsee-drive-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/webapper/cloudsee-drive-mcp/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@webapper/cloudsee-drive-mcp.svg)](https://www.npmjs.com/package/@webapper/cloudsee-drive-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+An open-source [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
+**[CloudSee Drive](https://www.cloudsee.cloud)** — connect your CloudSee account (a browser
+interface for Amazon S3) to Claude Desktop and any MCP-compatible client, and manage your
+files in natural language.
+
+> Browse, search, download, share, upload, organize, and tag your CloudSee Drive files from
+> your AI assistant — with explicit confirmation before anything destructive happens.
+
+📘 **New here?** The [Installation, Commands & Testing Guide](docs/GUIDE.md) walks through
+install, configuration, every tool with examples, and how to test against a live API.
+
+---
+
+## Quickstart (≈5 minutes)
+
+### 1. Get an API key
+
+In the CloudSee Drive dashboard, create a public-API key. You'll receive a **key id**
+(looks like `AKIA…`) and a **secret**. Copy both — the secret is shown only once.
+
+### 2. Add the server to Claude Desktop
+
+Open Claude Desktop → **Settings → Developer → Edit Config**, and add a `cloudsee-drive`
+entry under `mcpServers` (no install needed — `npx` fetches it on demand):
+
+```json
+{
+  "mcpServers": {
+    "cloudsee-drive": {
+      "command": "npx",
+      "args": ["-y", "@webapper/cloudsee-drive-mcp"],
+      "env": {
+        "CLOUDSEE_API_KEY_ID": "<your key id>",
+        "CLOUDSEE_API_KEY_SECRET": "<your secret>",
+        "CLOUDSEE_API_BASE_URL": "https://drive-api.cloudsee.cloud"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Desktop and try it
+
+> "List my CloudSee buckets, then show the most recent files."
+
+That's it. The server runs locally on your machine; your API key never leaves it.
+
+---
+
+## Installation
+
+`npx` (above) always runs the latest version. To install the `cloudsee-drive-mcp` binary
+globally instead:
+
+```bash
+npm install -g @webapper/cloudsee-drive-mcp
+```
+
+Requires **Node.js ≥ 18**. No native dependencies — works on macOS, Linux, and Windows.
+
+## Configuration
+
+All configuration is via environment variables (set them in the Claude Desktop `env` block,
+or a local `.env` for development — see [`.env.example`](.env.example)).
+
+| Variable | Required | Default | Description |
+| --- | --- | --- | --- |
+| `CLOUDSEE_API_KEY_ID` | ✅ | — | Your CloudSee Drive API key id. |
+| `CLOUDSEE_API_KEY_SECRET` | ✅ | — | The matching API key secret. **Never commit this.** |
+| `CLOUDSEE_API_BASE_URL` | — | `https://drive-api.cloudsee.cloud` | API base URL. UAT: `https://drive-api-uat.cloudsee.cloud`. |
+| `CLOUDSEE_LOG_LEVEL` | — | `info` | `error` \| `warn` \| `info` \| `debug` (logs go to stderr only). |
+| `CLOUDSEE_TIMEOUT_MS` | — | `30000` | Per-request timeout in milliseconds. |
+
+## Tools
+
+| Tool | Description | Access |
+| --- | --- | --- |
+| `list_buckets` | List accessible buckets | read |
+| `browse_folder` | List a folder's contents (one level) | read |
+| `search_files` | Find files/folders by name keyword | read |
+| `recent_files` | List recently used files | read |
+| `get_file_metadata` | Get a file's metadata | read |
+| `get_file_tags` | Get a file's S3 tags | read |
+| `download_file` | Get a temporary pre-signed download URL | download |
+| `share_link` | Create a shareable, time-limited link | download |
+| `upload_file` | Upload a local file (≤ 8 MiB) | write |
+| `create_folder` | Create a folder | write |
+| `rename_file` | Rename a file/folder | write · **confirm** |
+| `move_file` | Move (or copy) a file/folder | write · **confirm** (move) |
+| `duplicate_file` | Duplicate a file | write |
+| `delete_files` | Permanently delete objects | delete · **confirm** |
+| `update_metadata` | Update a file's metadata | write · **confirm** |
+| `restore_archived_file` | Un-archive a Glacier object | write · **confirm** |
+
+### Destructive operations require confirmation
+
+Tools marked **confirm** (delete, rename, move, update-metadata, restore) use **two-step
+confirmation**: the first call returns a preview and makes **no changes**; you must call again
+with `confirm: true` to proceed. This is a client-side safety prompt — the CloudSee API
+authorizes every operation server-side; confirmation is not the security boundary.
+
+## Security
+
+- Your API key id + secret are read from the environment and **held only in this local
+  process**. The server **never logs the secret**, never returns it in tool output, and
+  never writes it to a file. All diagnostics go to **stderr** (stdout is the MCP transport).
+- File downloads/shares return **short-lived pre-signed URLs**, never AWS credentials.
+- Report vulnerabilities per [`SECURITY.md`](SECURITY.md). Never paste a real key/secret into
+  an issue.
+
+## Status & known limitations
+
+This wraps CloudSee Drive's public API (the `drive-bridge` `/v1/*` gateway).
+
+- **Read & download tools are fully functional today.**
+- **Write/delete/share tools are present but their end-to-end authorization is sequenced
+  behind the gateway's RBAC/scope wiring (CSD-572).** Until that lands, the gateway may deny
+  these operations — the tools surface that cleanly; it is expected, not a bug here.
+- `upload_file` supports single-file uploads up to 8 MiB; multipart (larger files) is planned.
+- `search_files` matches a single folder level (not a whole-tree recursive search).
+
+## Development
+
+```bash
+npm install
+npm test            # vitest: unit + tool↔contract drift tests
+npm run typecheck   # tsc --noEmit
+npm run lint        # eslint
+npm run build       # tsup → dist/ (ESM, with bin shebang)
+npm run sync:contract  # regenerate contract/registry.snapshot.json from the API seed
+node scripts/smoke.mjs # build first; spawns the server and lists tools over MCP
+```
+
+The **contract-drift test** (`test/contract/drift.test.ts`) fails the build if any tool drifts
+from the committed API contract snapshot — so tool schemas can't silently diverge from the
+real `/v1/*` surface.
+
+## License
+
+[MIT](LICENSE) © Webapper