Metadata-Version: 2.4
Name: alibabacloud-sls-mcp-proxy
Version: 0.1.0a1
Summary: Local MCP proxy for Alibaba Cloud Simple Log Service
Keywords: alibabacloud,mcp,model-context-protocol,sls
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: Proxy Servers
Requires-Python: >=3.10
Requires-Dist: aiohttp<4,>=3.9
Description-Content-Type: text/markdown

# Alibaba Cloud SLS MCP Proxy

[简体中文](README.zh-CN.md) | English

`alibabacloud-sls-mcp-proxy` connects local Model Context Protocol (MCP)
clients to Alibaba Cloud Simple Log Service (SLS). It signs each upstream
request with your Alibaba Cloud credentials while keeping the MCP connection
on your machine.

The proxy supports:

- stdio transport for desktop MCP clients and IDEs;
- a loopback-only Streamable HTTP transport;
- static AccessKey credentials with an optional STS token;
- credentials from an Alibaba Cloud CLI profile, including refresh of
  temporary credentials close to expiration.

## Requirements

- Python 3.10 or later;
- Alibaba Cloud credentials that are authorized to use the SLS MCP service;
- [Alibaba Cloud CLI](https://www.alibabacloud.com/help/en/cli/) when using
  `--profile`.

[`uv`](https://docs.astral.sh/uv/) is recommended for running the proxy
without a permanent installation.

## Installation

Run the latest release directly with `uvx`:

```sh
uvx alibabacloud-sls-mcp-proxy@latest --profile default
```

Alternatively, install the command in an isolated environment:

```sh
uv tool install alibabacloud-sls-mcp-proxy
alibabacloud-sls-mcp-proxy --help
```

The package can also be installed with `pipx` or `pip`:

```sh
pipx install alibabacloud-sls-mcp-proxy
```

Or install it in the current Python environment:

```sh
python -m pip install alibabacloud-sls-mcp-proxy
```

## Quick start

### Use an Alibaba Cloud CLI profile

Configure a profile with Alibaba Cloud CLI, then start the proxy with its
name:

```sh
uvx alibabacloud-sls-mcp-proxy@latest --profile default
```

stdio is the default transport. The proxy reads MCP JSON-RPC messages from
stdin, writes responses to stdout, and sends logs to stderr.

The following MCP client configuration starts the proxy on demand:

```json
{
  "mcpServers": {
    "alibabacloud-sls": {
      "command": "uvx",
      "args": [
        "alibabacloud-sls-mcp-proxy@latest",
        "--profile",
        "default"
      ]
    }
  }
}
```

If a desktop application cannot find `uvx`, replace `uvx` with its absolute
path.

### Use credentials from environment variables

Without `--profile`, provide both of these environment variables in the
process that starts the proxy:

- `ALIBABA_CLOUD_ACCESS_KEY_ID`
- `ALIBABA_CLOUD_ACCESS_KEY_SECRET`

For temporary credentials, also provide
`ALIBABA_CLOUD_SECURITY_TOKEN`. Then run:

```sh
uvx alibabacloud-sls-mcp-proxy@latest
```

Prefer a secret manager or the MCP client's environment configuration over
putting credentials directly on a command line.

### Use the local HTTP transport

To expose an MCP endpoint to another local process:

```sh
alibabacloud-sls-mcp-proxy \
  --profile default \
  --transport http \
  --port 8080 \
  --endpoint sls.aliyuncs.com
```

Connect the MCP client to `http://127.0.0.1:8080/mcp`. The listener always
binds to the loopback interface and is not exposed to the network.

## Credential selection

The proxy selects exactly one credential provider:

1. A non-empty `--profile` or `ALIBABA_CLOUD_PROFILE` selects an Alibaba
   Cloud CLI profile.
2. In profile mode, `--sts-token` or `ALIBABA_CLOUD_SECURITY_TOKEN` overrides
   the STS token read from the profile.
3. Without a profile, the proxy requires both the AccessKey ID and AccessKey
   secret from command-line options or environment variables.
4. The proxy does not silently fall back between profile and static
   credential modes.

When a profile contains an expiration time, the proxy asks Alibaba Cloud CLI
to refresh temporary credentials shortly before they expire.

## Command-line options

| Option | Environment variable | Default | Description |
| --- | --- | --- | --- |
| `--access-key-id` | `ALIBABA_CLOUD_ACCESS_KEY_ID` | none | AccessKey ID used without a profile. |
| `--access-key-secret` | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | none | AccessKey secret used without a profile. |
| `--profile` | `ALIBABA_CLOUD_PROFILE` | none | Alibaba Cloud CLI profile. Takes precedence over static credentials. |
| `--sts-token` | `ALIBABA_CLOUD_SECURITY_TOKEN` | none | Optional STS token. Overrides the token from a profile. |
| `--endpoint` | `MCP_UPSTREAM_ENDPOINT` | `sls.aliyuncs.com` | SLS MCP endpoint. A host without a scheme uses HTTPS. |
| `--transport` | none | `stdio` | Local transport: `stdio` or `http`. |
| `--port` | `MCP_PROXY_PORT` | `8080` | Listen port for HTTP transport. |
| `--headers KEY=VALUE` | none | none | Extra upstream header; repeat the option to add more than one. Do not use it for credentials. |
| `--timeout` | none | `120` | Total request timeout in seconds. |
| `--connect-timeout` | none | `10` | Connection timeout in seconds. |
| `--read-timeout` | none | same as `--timeout` | Socket read timeout in seconds. |
| `--retries` | none | `0` | Number of retries after an upstream connection failure. |
| `--log-level` | none | `info` | `debug`, `info`, `warning`, or `error`. |
| `--log-file` | none | none | Also write logs to this local file. |
| `--version` | none | — | Print the installed version and exit. |

Run `alibabacloud-sls-mcp-proxy --help` to see the options supported by the
installed version.

## Security notes

- Prefer an Alibaba Cloud CLI profile or environment variables over
  command-line credential options, which may be visible in shell history or
  the local process list.
- Remote endpoints must use HTTPS. Plain HTTP is accepted only for loopback
  addresses used in local testing.
- Redirects are not followed.
- Credentials and signed authorization values are not written to logs.
- The stdio transport reserves stdout for MCP protocol messages; logs are
  written to stderr.

## Troubleshooting

`--profile requires the aliyun CLI`

: Install Alibaba Cloud CLI and make sure the `aliyun` executable is in the
  starting process's `PATH`.

`aliyun configure get failed`

: Check that the selected profile exists and contains usable credentials.

`--access-key-id and --access-key-secret are required`

: Supply both static credential environment variables, or select a configured
  profile with `--profile`.

Authentication errors from the endpoint

: Check that the credentials are active, an STS token has not expired, and the
  identity has permission to use the SLS MCP service.

## Development

From the package directory:

```sh
uv sync
uv run python -m unittest -v
uv run python -m compileall -q src tests
./scripts/build.sh
```

To exercise the installed console entry point from the development
environment:

```sh
uv run alibabacloud-sls-mcp-proxy --version
```

## Publishing

The publish script rebuilds both distributions before upload. It publishes to
TestPyPI by default:

```sh
./scripts/publish.sh
```

Set `UV_PUBLISH_TOKEN` to the API token for the target package index. TestPyPI
and PyPI use separate tokens. The script requires this environment variable
and never accepts or prints a token on the command line.

Pass `pypi` explicitly to publish to the production index:

```sh
./scripts/publish.sh pypi
```
