Metadata-Version: 2.4
Name: ksyun-mcp-server
Version: 0.2.2
Summary: MCP Server for Kingsoft Cloud (Ksyun) Python SDK
License-Expression: Apache-2.0
Requires-Python: >=3.10
Requires-Dist: kingsoftcloud-sdk-python>=1.5.8
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Ksyun MCP Server

MCP Server for Kingsoft Cloud (Ksyun) Python SDK — 让 LLM 直接调用金山云 API。

## 功能

- **ksyun_api** — 调用任意金山云 API
- **ksyun_list_services** — 列出所有可用服务及版本
- **ksyun_list_actions** — 列出指定服务版本的 API Action 及参数
- **ksyun_audit_query** — 查询审计日志
- **ksyun://services** 资源 — 浏览所有服务/版本/Action 摘要
- **ksyun://audit/recent** 资源 — 最近 10 条审计记录

> **大响应自动分页**：MCP 协议的 `structuredContent` 输出有约 50KB 大小限制。当 API 返回数据超过 40KB 时，`ksyun_api` 会自动缓存完整响应并返回第一批数据，同时在 `_meta` 中附加 `next_marker`。LLM 只需再次调用同一 API 并传入 `page_marker="<next_marker>"` 即可获取下一批数据，直到所有数据返回完毕。缓存有效期为 10 分钟。

## 安装

### 从 PyPI 安装（推荐）

```bash
pip install ksyun-mcp-server
```

> SDK (`kingsoftcloud-sdk-python`) 会作为依赖自动安装。

### 从源码安装（开发用）

```bash
cd ksyun-mcp-server
pip install -e ".[dev]"
```

## 更新

已安装的 MCP Server 更新到最新版本后，**需要重启 MCP 客户端**（Claude Desktop / Cursor / VS Code 等）才能生效。

### 从压缩包安装的更新

先在项目目录下构建压缩包：

```bash
cd ksyun-mcp-server
pip install build
python -m build
```

构建产物在 `dist/` 目录下，用新版本的压缩包重新安装即可：

```bash
pip install dist/ksyun_mcp_server-0.2.2.tar.gz
```

> 也可以指定 `.whl` 文件：`pip install dist/ksyun_mcp_server-0.2.2-py3-none-any.whl`

### 从源码安装的更新

如果是可编辑安装（`pip install -e`），拉取最新代码后即自动生效：

```bash
cd ksyun-mcp-server
git pull
# 无需重新 pip install，-e 模式下代码变更即时生效
```

如果是非可编辑安装，重新执行安装命令：

```bash
cd ksyun-mcp-server
pip install ".[dev]"
```

### 重启 MCP 客户端

| 客户端 | 重启方式 |
|--------|---------|
| Claude Desktop | 完全退出应用后重新打开 |
| Cursor | 重新加载窗口（`Cmd+Shift+P` → `Reload Window`） |
| VS Code | 重新加载窗口（`Cmd+Shift+P` → `Reload Window`） |

## 配置

通过环境变量或 `.env` 文件配置（二选一）：

### 方式一：环境变量（推荐，无需 .env 文件）

在启动命令的 `env` 字段中直接传入凭证，无需创建 `.env` 文件：

```json
{
  "mcpServers": {
    "ksyun": {
      "command": "ksyun-mcp-server",
      "env": {
        "KSYUN_ACCESS_KEY_ID": "your_ak",
        "KSYUN_SECRET_ACCESS_KEY": "your_sk",
        "KSYUN_REGION": "cn-beijing-6"
      }
    }
  }
}
```

### 方式二：.env 文件

复制 `.env.example` 为 `.env` 并填入凭证：

```bash
cp .env.example .env
```

| 环境变量 | 必填 | 默认值 | 说明 |
|---------|------|--------|------|
| `KSYUN_ACCESS_KEY_ID` | ✅ | | 金山云 AccessKey ID |
| `KSYUN_SECRET_ACCESS_KEY` | ✅ | | 金山云 Secret AccessKey |
| `KSYUN_REGION` | | `cn-beijing-6` | 默认地域 |
| `KSYUN_AUDIT_BACKEND` | | `file` | 审计后端：`file` / `sqlite` |
| `KSYUN_AUDIT_DIR` | | `~/.ksyun-mcp` | 审计日志目录 |
| `KSYUN_AUDIT_REDACT_FIELDS` | | `password,secret,token,...` | 脱敏字段名 |
| `KSYUN_SDK_PATH` | | 自动检测 | SDK 路径（一般无需设置） |

## 在各工具中使用

### Claude Desktop

编辑 `claude_desktop_config.json`（路径：`%APPDATA%\Claude\claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "ksyun": {
      "command": "ksyun-mcp-server",
      "env": {
        "KSYUN_ACCESS_KEY_ID": "your_ak",
        "KSYUN_SECRET_ACCESS_KEY": "your_sk",
        "KSYUN_REGION": "cn-beijing-6"
      }
    }
  }
}
```

> 如果 `ksyun-mcp-server` 不在 PATH 中，将 `command` 改为 Python 解释器的完整路径：
> ```json
> "command": "C:\\Users\\you\\.venv\\Scripts\\ksyun-mcp-server.exe"
> ```

### Cursor

编辑 `~/.cursor/mcp.json` 或项目目录下 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "ksyun": {
      "command": "ksyun-mcp-server",
      "env": {
        "KSYUN_ACCESS_KEY_ID": "your_ak",
        "KSYUN_SECRET_ACCESS_KEY": "your_sk",
        "KSYUN_REGION": "cn-beijing-6"
      }
    }
  }
}
```

### VS Code (Copilot / Continue)

在 VS Code `settings.json` 中：

```json
{
  "mcp.servers": {
    "ksyun": {
      "command": "ksyun-mcp-server",
      "env": {
        "KSYUN_ACCESS_KEY_ID": "your_ak",
        "KSYUN_SECRET_ACCESS_KEY": "your_sk",
        "KSYUN_REGION": "cn-beijing-6"
      }
    }
  }
}
```

### 任意支持 MCP 的工具

只要工具支持 stdio 传输的 MCP Server，配置模式一致：

| 字段 | 值 |
|------|---|
| **command** | `ksyun-mcp-server` |
| **transport** | `stdio`（默认，无需指定） |
| **env** | `KSYUN_ACCESS_KEY_ID` + `KSYUN_SECRET_ACCESS_KEY`（必填），其余可选 |

## 打包与发布

### 本地构建

```bash
cd ksyun-mcp-server
pip install build
python -m build
```

构建产物在 `dist/` 目录下：`ksyun_mcp_server-0.2.2-py3-none-any.whl` 和 `ksyun_mcp_server-0.2.2.tar.gz`。

### 发布到 PyPI

```bash
pip install twine
twine upload dist/*
```

> 需要 PyPI API Token，在 `~/.pypirc` 或环境变量 `TWINE_PASSWORD` 中配置。

### 发布到 TestPyPI（测试用）

```bash
twine upload --repository testpypi dist/*
```

### 用户安装方式

发布后，用户只需一行命令即可安装使用：

```bash
pip install ksyun-mcp-server
```

然后在任意 MCP 客户端中配置 `"command": "ksyun-mcp-server"` 即可。

## 更新记录

### v0.2.2

- **修复 `_parse_client_py` 潜在 bug**：多数投票可能在比较遍历之后改变 content_type 默认值，导致 form 类型的 action 被遗漏而错误继承 JSON 默认值。重构为先收集所有 action 的 content_type，再进行多数投票，最后用最终默认值过滤 `action_content_types` 字典
- **更新文档**：README "打包与发布" 和 "更新" 部分的文件名引用从 v0.2.0 更新到 v0.2.2

### v0.2.1

- **修复参数传递问题**：LLM 经常将 API 参数扁平化到顶层（如 `{"service":"vpc", "SecurityGroupId":"xxx"}` 而非 `{"service":"vpc", "params":{"SecurityGroupId":"xxx"}}`），FastMCP 的 Pydantic 模型默认静默丢弃多余字段导致 `params={}`。通过 monkey-patch `ArgModelBase`（`extra="allow"` + 扩展 `model_dump_one_level`）自动将顶层多余字段合并到 `params` 字典中
- **增强 docstring**：在工具描述中说明参数嵌套规则，并提示扁平化参数也会被自动收集
- **参数值类型转换**：调用 SDK 前自动将所有 `params` 值转为字符串，兼容 LLM 传入的整数等非字符串类型
- **空参数警告**：当 `params` 为空但 action 要求必填参数时记录 warning 日志，便于排查

### v0.2.0

- **新增大响应自动分页**：当 API 返回数据超过 40KB 时，`ksyun_api` 会自动缓存完整响应并分批返回，通过 `_meta.next_marker` 和 `page_marker` 参数实现逐页获取，确保数据不丢失（缓存有效期 10 分钟）
- **修复**：`ksyun_api` 工具参数名从 `_marker` 改为 `page_marker`，解决 FastMCP 不允许下划线开头参数的 `InvalidSignature` 错误
- **移除**：删除无效的 `ksyun_max_response_bytes` 配置项（MCP 框架硬限制无法通过配置绕过）

### v0.1.0

- 初始版本
- 支持 `ksyun_api`、`ksyun_list_services`、`ksyun_list_actions`、`ksyun_audit_query` 工具
- 支持 `ksyun://services`、`ksyun://audit/recent` 资源
- 审计日志支持 file / sqlite 两种后端，敏感字段自动脱敏

## 审计

所有通过 MCP Server 发起的 API 调用都会自动记录审计日志，包含：

- 时间戳、服务名、版本、Action、地域
- 请求参数（敏感字段自动脱敏）
- 调用状态（success/error）、错误信息、RequestId
- 调用耗时（ms）

使用 `ksyun_audit_query` 工具或 `ksyun://audit/recent` 资源查看审计记录。

## License

Apache-2.0
