# couchdrop-mcp

Local stdio MCP server for Couchdrop. It lets MCP clients list Couchdrop files,
inspect file metadata, download and upload files, list users and groups, and
read folder permissions.

## Requirements

- Node.js 22 or newer
- A Couchdrop API token

## Couchdrop Token

Create or retrieve an API token from your Couchdrop account, then provide it to
the server as `COUCHDROP_API_TOKEN`. Keep the token in your local MCP client
configuration or shell environment. Do not commit it to source control.

Use a token with the narrowest access that fits your workflow.

## Install And Configure

You can run the package with `npx`; no global install is required.

### Claude Desktop

Add the server to your Claude Desktop MCP configuration, then restart Claude
Desktop.

```json
{
  "mcpServers": {
    "couchdrop": {
      "command": "npx",
      "args": ["-y", "couchdrop-mcp"],
      "env": {
        "COUCHDROP_API_TOKEN": "your-couchdrop-api-token"
      }
    }
  }
}
```

### Codex

Codex reads MCP servers from `~/.codex/config.toml` or a trusted project
`.codex/config.toml`.

```toml
[mcp_servers.couchdrop]
command = "npx"
args = ["-y", "couchdrop-mcp"]

[mcp_servers.couchdrop.env]
COUCHDROP_API_TOKEN = "your-couchdrop-api-token"
```

### Generic MCP Client

Configure the client to start a stdio server with this command:

```json
{
  "command": "npx",
  "args": ["-y", "couchdrop-mcp"],
  "env": {
    "COUCHDROP_API_TOKEN": "your-couchdrop-api-token"
  }
}
```

If your client prefers an installed binary, install the package and run
`couchdrop-mcp` as the stdio command.

## Environment Variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `COUCHDROP_API_TOKEN` | Yes | None | Couchdrop API token sent to Couchdrop API and FileIO requests. |
| `COUCHDROP_API_BASE` | No | `https://api.couchdrop.io` | Base URL for Couchdrop management API requests. |
| `COUCHDROP_FILEIO_BASE` | No | `https://fileio.couchdrop.io` | Base URL for Couchdrop FileIO requests. |
| `COUCHDROP_MAX_INLINE_BYTES` | No | `65536` | Maximum bytes returned inline for downloads without `outputPath`. |

## Tools

All Couchdrop paths must start with `/`. Path segments must not contain `..`.

| Tool | Arguments | Description |
| --- | --- | --- |
| `couchdrop_list_files` | `path` optional, default `/` | Lists files and folders at a Couchdrop path. |
| `couchdrop_get_file_info` | `path` required | Gets metadata for a Couchdrop file or folder. |
| `couchdrop_download_file` | `path` required, `outputPath` optional | Downloads a file. Without `outputPath`, returns small UTF-8 text inline. With `outputPath`, saves the file locally. |
| `couchdrop_upload_file` | `localPath` required, `destinationPath` required | Uploads a local file to a Couchdrop path. |
| `couchdrop_list_users` | None | Lists Couchdrop users visible to the token. |
| `couchdrop_list_groups` | None | Lists Couchdrop groups visible to the token. |
| `couchdrop_get_folder_permissions` | `path` required | Gets permissions for a Couchdrop folder path. |

## Safety Notes

- Tokens stay local to your MCP client configuration or environment. This server
  does not persist tokens.
- v0.1 exposes no delete, move, chmod, user mutation, or group mutation tools.
- `couchdrop_upload_file` writes to the requested `destinationPath`; check the
  path before calling it.
- Use `outputPath` for large or binary downloads. Inline downloads are intended
  for small UTF-8 text files.
- In v0.1, uploads and downloads saved with `outputPath` are buffered in memory
  before being sent or written.

## Local Development

```sh
npm install
npm run typecheck
npm test
npm run build
npm run dev
```

To inspect the package contents before publishing:

```sh
npm run build
npm pack --dry-run
```

## Contributing

Contributions are welcome. Keep changes small, add or update tests for behavior
changes, and run the local verification commands before opening a pull request.

Do not commit real Couchdrop tokens, generated secrets, or private customer
paths in tests or documentation.

## License

MIT