Metadata-Version: 2.5
Name: mcp-aliyun-oss
Version: 0.1.0
Summary: MCP server: upload files to Aliyun OSS with MD5 object names
Project-URL: Homepage, https://github.com/kinginsun/mcp-aliyun-oss
Project-URL: Repository, https://github.com/kinginsun/mcp-aliyun-oss
Project-URL: Issues, https://github.com/kinginsun/mcp-aliyun-oss/issues
Author: kinginsun
License: MIT
License-File: LICENSE
Keywords: aliyun,mcp,model-context-protocol,oss
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: mcp>=2.0.0
Requires-Dist: oss2>=2.18.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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
