# mcp-aliyun-oss

<!-- mcp-name: io.github.kinginsun/mcp-aliyun-oss -->

Standalone MCP server (Python SDK 2.x `MCPServer`) with one tool, `oss-upload`: put an object on Aliyun OSS named `{prefix}/{md5}{ext}`.

Repository: [github.com/kinginsun/mcp-aliyun-oss](https://github.com/kinginsun/mcp-aliyun-oss)

Credentials are read from the environment only. Never put AccessKeys in this repo or in chat.

## Tool: `oss-upload`

Provide **exactly one** source:

| Argument | Use when | Bytes | Extension |
|---|---|---|---|
| `local_file_path` | File already on disk | Read the **absolute** path | Path suffix; optional `filename` overrides |
| `content` | Generated text (HTML / Markdown / JSON) | UTF-8 | **Required** `filename` (e.g. `report.html`) |
| `content_base64` | Binary | `base64` decode; strips a `data:*;base64,` prefix | Same as `content` |

Other arguments:

- `oss_path_prefix` — default `agents/docs`. Must start with `agents/`. No `..`.
- Return value: `{ status, file_size, key, url }` (`file_size` is decoded bytes).

Decoded size cap is **100MB**. Large files: pass `local_file_path`. Do not send huge base64 over stdio.

## Environment

Required (or the `OSS_TEST_*` aliases):

| Variable | Meaning |
|---|---|
| `OSS_ACCESS_KEY_ID` | AccessKey ID |
| `OSS_ACCESS_KEY_SECRET` | AccessKey Secret |
| `OSS_BUCKET` | Bucket name |
| `OSS_ENDPOINT` | Regional endpoint **without** `https://`, e.g. `oss-cn-shenzhen.aliyuncs.com` |

Optional: `OSS_PUBLIC_URL_BASE` (CDN / custom domain), `OSS_CONNECT_TIMEOUT` (seconds, default `120`).

If `OSS_PUBLIC_URL_BASE` is set, `url` is `{base}/{key}`; otherwise `https://{bucket}.{endpoint}/{key}`.

Copy `.env.example` to a local `.env` for development; do not commit `.env`.

## Install

**From PyPI** (after release):

```bash
uv tool install mcp-aliyun-oss
# or: pip install mcp-aliyun-oss
```

**From source**:

```bash
git clone https://github.com/kinginsun/mcp-aliyun-oss.git
cd mcp-aliyun-oss
uv sync --extra dev
```

## Cursor (`~/.cursor/mcp.json`)

**PyPI / uvx** (recommended for end users):

```json
{
  "mcpServers": {
    "aliyun-oss": {
      "command": "uvx",
      "args": ["mcp-aliyun-oss"],
      "env": {
        "OSS_ACCESS_KEY_ID": "your-id",
        "OSS_ACCESS_KEY_SECRET": "your-secret",
        "OSS_BUCKET": "your-bucket",
        "OSS_ENDPOINT": "oss-cn-hangzhou.aliyuncs.com"
      }
    }
  }
}
```

**Local checkout** (development):

```json
{
  "mcpServers": {
    "aliyun-oss": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-aliyun-oss", "mcp-aliyun-oss"],
      "env": {
        "OSS_ACCESS_KEY_ID": "your-id",
        "OSS_ACCESS_KEY_SECRET": "your-secret",
        "OSS_BUCKET": "your-bucket",
        "OSS_ENDPOINT": "oss-cn-hangzhou.aliyuncs.com"
      }
    }
  }
}
```

## Tests

```bash
uv run pytest
```

OSS `put_object` is mocked; no live bucket is required.

## Publish (maintainers)

1. **GitHub** — push to `https://github.com/kinginsun/mcp-aliyun-oss` (public).
2. **PyPI** — bump `version` in `pyproject.toml` and `server.json`, then either:
   - GitHub **Release** with tag `v0.1.0` (workflow `.github/workflows/publish-pypi.yml` uses secret `PYPI_API_TOKEN`), or
   - Local: `uv build && uv publish` with a [PyPI API token](https://pypi.org/manage/account/token/).
3. **MCP Registry** — after the same version is on PyPI, install [mcp-publisher](https://github.com/modelcontextprotocol/registry), log in with GitHub, and from this repo run `mcp-publisher publish` (uses root `server.json`).

Registry server name: `io.github.kinginsun/mcp-aliyun-oss`.

## License

MIT