AUTODL-PLUGIN

<div align="center"> <img src="assets/banner.svg" alt="AutoDL Plugin" width="100%" /> </div> <div align="center"> [](CHANGELOG.md) [](#mcp-tool-list) [](skills/autodl/references/docs-index.md) [](https://github.com/wuzihuang/AUTODL-PLUGIN/actions) [](LICENSE) **Enable Codex to manage AutoDL GPU resources safely and transparently.** Typed MCP tools · Documentation-aware Skill · Confirmation gates · Credential redaction </div> --- ## What is this? The AutoDL Plugin is a community plugin for Codex that encapsulates the AutoDL official developer API and complete documentation into two layers of capabilities: 1. **AutoDL MCP Server**: 26 explicitly defined and verifiable tools for querying balance, managing container instances Pro, operating elastic deployments, querying image/GPU inventory, reading duration packages, sending WeChat notifications, and obtaining container metrics. 2. **AutoDL Skill**: Enables the Agent to understand AutoDL's billing, data retention, system disk/data disk, image, network, SSH, CUDA, training environment, and permission boundaries, and executes the correct process before high-risk operations. It's not just a simple "HTTP interface forwarder." The plugin distinguishes between read-only, state-changing, billing, and destructive operations; confirmation gates are required before actual creation, power-on, shutdown, release, scaling, deletion, or sending messages. > [!IMPORTANT] > This is a community integration, not an official AutoDL product. The actual service capabilities, prices, inventory, quotas, and rules are subject to [AutoDL Official Website](https://www.autodl.com/) and [Official Documentation](https://www.autodl.com/docs/). ## Highlights - **26 typed MCP tools**: Each interface has an independent name, parameter description, and input verification. - **Safety confirmation gate**: Change operations return a request preview with `confirm=false`, without accessing AutoDL. - **Credential protection**: Instance details default to redact `root_password` and `jupyter_token`. - **Token isolation**: Developer tokens are only read from the local environment, not entering source code, tool output, or test fixtures. - **Complete documentation awareness**: Indexes 103/103 official help pages and 463 search entries. - **Documentation drift check**: Can re-crawl official directories and generate page status and SHA-256 lists. - **Real MCP testing**: Calls all tools through stdio handshake, not just internal functions. - **Formal environment read-only verification**: Balance, Pro instance lists, and Pro image lists have been verified through real AutoDL API. ## Architecture ```mermaid flowchart LR U["User / Codex"] --> S["AutoDL Skill"] S -->|"Select tool and safety process"| M["Typed MCP Server"] M --> G{"Confirmation gate"} G -->|"Read-only"| A["AutoDL Developer API"] G -->|"Change and confirm=true"| A G -->|"confirm=false"| P["Request preview only"] A --> R["Redaction + structured result"] R --> U D["103 official docs pages"] --> S ``` ## Quick Start ### 1. Clone and Install ```bash git clone https://github.com/wuzihuang/AUTODL-PLUGIN.git cd AUTODL-PLUGIN npm install ``` Requirements: Node.js 20 or higher. ### 2. Configure AutoDL Token Obtain the developer token from the AutoDL console account settings and create a local environment file: ```bash cp .env.example .env ``` Edit `.env`: ```dotenv AUTODL_TOKEN=Your developer token ``` `.env` is ignored by Git. Do not write the real token into README, configuration examples, issues, logs, or commit records. Alternatively, you can provide it in the Codex environment: ```bash export AUTODL_TOKEN='Your developer token' ``` ### 3. Load the plugin in Codex Select this repository root directory in Codex that supports local plugins. Codex will discover the AutoDL Skill through `.codex-plugin/plugin.json` and start the local AutoDL MCP Server through `.mcp.json`. If your client does not support local plugins, configure MCP manually: ```json { "mcpServers": { "autodl": { "command": "bash", "args": ["/absolute/path/AUTODL-PLUGIN/scripts/start-mcp.sh"], "cwd": "/absolute/path/AUTODL-PLUGIN" } } } ``` The skill can also be installed separately: ```bash cp -R skills/autodl ~/.codex/skills/autodl ``` ### 4. Try asking like this - “Check my AutoDL balance, convert the amount to CNY.” - “List my Pro instances, tell me which ones are still billing.” - “Query the inventory of RTX 4090 elastic deployments in `westDC2`.” - “I want to create a single-card instance, give me the parameters and cost risk preview first, don’t create directly.” - “What other data should I backup before saving this instance’s environment?” - “Why is the CUDA version of `nvidia-smi` different from the environment’s CUDA?” ## MCP Tool List ### Account and Storage | Tool | Effect | Type | |---|---|---| | `autodl_wallet_balance` | Get balance, cumulative consumption, and voucher balance | Read-only | | `autodl_switch_exclusive_nfs` | Switch dedicated NFS / ordinary file storage | Needs confirmation | ### Container Instance Pro | Tool | Effect | Type | |---|---|---| | `autodl_pro_create_instance` | Create pay-as-you-go Pro instance | Billing, needs confirmation | | `autodl_pro_instance_snapshot` | Get instance hardware, usage, and connection information | Read-only, default redaction | | `autodl_pro_instance_status` | Get instance status | Read-only | | `autodl_pro_list_instances` | List instances by page | Read-only | | `autodl_pro_power_on` | GPU mode power-on | Billing, needs confirmation | | `autodl_pro_power_off` | Shutdown | Needs confirmation | | `autodl_pro_release_instance` | Permanent release of instance | **Destructive, needs confirmation** | | `autodl_pro_save_image` | Save system disk as private image | Needs confirmation | | `autodl_pro_list_private_images` | Query Pro private images and save status | Read-only | ### Elastic Deployment | Tool | Effect | Type | |---|---|---| | `autodl_esd_list_private_images` | Get private images available for elastic deployment | Read-only | | `autodl_esd_create_deployment` | Create ReplicaSet, Job, or Container | Billing, needs confirmation | | `autodl_esd_list_deployments` | Query deployments | Read-only | | `autodl_esd_list_container_events` | Poll container lifecycle events | Read-only | | `autodl_esd_list_containers` | Query containers, status, and connection information | Read-only | | `autodl_esd_stop_container` | Stop specified container | Needs confirmation | | `autodl_esd_set_replica_num` | Adjust ReplicaSet replica number | Billing/interruption risk, needs confirmation | | `autodl_esd_stop_deployment` | Stop entire deployment | Needs confirmation | | `autodl_esd_delete_deployment` | Stop and permanently delete deployment | **Destructive, needs confirmation** | | `autodl_esd_set_blacklist` | Add abnormal container host to scheduling blacklist | Needs confirmation | | `autodl_esd_list_blacklist` | Get effective scheduling blacklist | Read-only | | `autodl_esd_gpu_stock` | Query regional GPU total and available quantity | Read-only | | `autodl_esd_ddp_overview` | Get purchased duration package balance | Read-only | ### Notification and Monitoring | Tool | Effect | Type | |---|---|---| | `autodl_send_wechat_message` | Send notification to WeChat bound to account | External message, needs confirmation | | `autodl_local_metrics` | Get container CPU, memory, and GPU metrics | Read-only, needs to be reachable within container | See [API Reference](skills/autodl/references/api-reference.md) for complete fields, interface paths, region codes, GPU specifications, and basic image examples. ## Permission Matrix | Capability | Regular Token | Personal/Enterprise Real-name Authentication | Enterprise Authentication and Product Permissions | |---|:---:|:---:|:---:| | Account Balance | ✓ | ✓ | ✓ | | Container Instance Pro | | ✓ | ✓ | | Elastic Deployment | | | ✓ | | Elastic Deployment GPU Inventory | | | ✓ | | Container Performance Monitoring | | | ✓ | | WeChat Notification | Requires WeChat binding | Requires WeChat binding | Requires WeChat binding | If the API returns "no access permission to current resources," the plugin interprets it as an authentication or product permission issue, not an MCP fault. ## Security Model ### Confirmation Gate All tools that generate fees, change status, stop workloads, delete data, or send external messages have a `confirm` parameter: ```text confirm=false → Returns method, path, target, and parameter preview, without sending network requests confirm=true → Execute real AutoDL API requests ``` The Agent should still explain to the user before execution: - Accurate instance, deployment, or container ID; - GPU number, instance number, or replica number; - Price cap and billing impact; - Whether to interrupt training or service; - Whether system disk and data disk are backed up. ### Data and Credentials - `root_password` and `jupyter_token` are displayed as `[REDACTED]` by default. - Local metric requests do not carry AutoDL developer tokens. - Tokens do not appear in MCP structured results and error results. - Instance release and deployment deletion are marked as destructive. - Pro instance release process requires shutdown first. ### AutoDL Usage Boundary - Strictly prohibited for virtual currency mining. - Local system disk and data disk have no redundancy reliability commitment, and important data must be backed up. - Mapping service addresses should be kept private and comply with AutoDL custom service agreements. - Current prices, activities, inventory, regions, quotas, and policy dates must be verified in real-time. See [Operations Guide](skills/autodl/references/operations-guide.md) and [Security Policy](SECURITY.md) for more rules. ## Key Technical Details - API Host: `https://api.autodl.com` - Authentication: `Authorization: <raw token>`, **without `Bearer`** - Success Judgment: `code === "Success"` - Amount: Relevant integers in API divided by 1000 are in CNY - CUDA Code: e.g., `118` represents CUDA 11.8 - Pro Status/Details: Official documentation defines as `GET + JSON body` - GPU Inventory: Counted by single-card scheduling caliber, cannot prove multiple cards on the same host - Dedicated NFS: `mountable=1`; switch back to ordinary file storage: `mountable=-1` ## Configuration | Environment Variable | Default Value | Description | |---|---|---| | `AUTODL_TOKEN` | None | Required, AutoDL developer token | | `AUTODL_BASE_URL` | `https://api.autodl.com` | Developer API root address | | `AUTODL_WEB_BASE_URL` | `https://www.autodl.com` | WeChat message interface root address | | `AUTODL_METRICS_URL` | `http://127.0.0.1:2022/autopanel/v1/api/monitor/current` | Container local metric address | | `AUTODL_REQUEST_TIMEOUT_MS` | `20000` | Request timeout, milliseconds | ## Testing ### Full Automatic Testing ```bash npm test ``` Tests include: - Codex plugin manifest and MCP configuration verification; - Skill frontmatter, reference files, and 26/26 tool coverage; - 103/103 official documentation page list; - MCP stdio initialization and tool discovery; - 26/26 tool complete mock calls; - HTTP method, path, query, and GET JSON body; - Unconfirmed changes do not send network requests; - AutoDL business error mapping; - Token does not leak; - Instance credentials default redaction; - Local metric requests do not carry tokens. ### Formal Environment Read-only Testing ```bash npm run test:live ``` This command only reads balance, instances, images, deployments, and blacklists, without creating or modifying resources. Enterprise interfaces without permissions are marked as `SKIP/PERMISSION`. Current verification records: - Account balance: HTTP 200 - Pro instance list: HTTP 200 - Pro private image list: HTTP 200 - Elastic deployment: Test account has no access permission, safely skipped - Pro status/details: Test account has no existing instances, condition skipped See [Complete Test Report](docs/TEST_REPORT.md). ## Official Documentation Coverage The documentation refresh script reads AutoDL's MkDocs search index, checks the body page by page, and generates: - [Page Index](skills/autodl/references/docs-index.md) - [Documentation Audit List](skills/autodl/references/docs-manifest.json) Current snapshot: | Metric | Quantity | |---|---:| | Search index entries | 463 | | Actual pages | 103 | | Accessible pages | 103 | | Core API operations | 24 | | Help station supplementary API | 2 | Refresh: ```bash npm run docs:refresh npm test ``` The repository does not replicate AutoDL documentation wholesale, only saving routing index, summary rules, and hash metadata. Involving prices, authentication, inventory, quotas, and policies, official pages should be reviewed. ## Project Structure ```text AUTODL-PLUGIN/ ├── .codex-plugin/plugin.json # Codex plugin manifest ├── .mcp.json # MCP automatic discovery configuration ├── assets/ # Logo and README Banner ├── mcp/ │ ├── src/ # MCP Server and AutoDL HTTP Client │ └── test/ # Full tool contract testing, read-only real-time testing ├── skills/autodl/ │ ├── SKILL.md # Agent workflow and security rules │ ├── references/ # API, operation rules, documentation index │ └── scripts/ # Documentation refresh and skill verification ├── scripts/ │ ├── start-mcp.sh # Plugin MCP startup entry │ └── validate-plugin.mjs # Plugin and sensitive information verification ├── docs/TEST_REPORT.md └── .github/workflows/ci.yml ``` ## Development and Contribution Welcome to supplement new public interfaces, response samples, permission descriptions, and documentation drift fixes. Please read [CONTRIBUTING.md](CONTRIBUTING.md). Basic process: ```bash npm install npm test ``` When adding state-changing interfaces: 1. Use independent typed tool; 2. Add `confirm` preview gate; 3. Describe billing, interruption, and data impact; 4. Add mock contract testing; 5. Do not use real accounts to execute destructive CI testing. ## License [MIT](LICENSE) The AutoDL name, service, and official documentation belong to its rights holders. This project only provides community integration and does not represent AutoDL official endorsement. --- <div align="center"> Built for careful automation: inspect first, confirm changes, preserve data. </div>