feat: deps cleanup, format→audio_format rename, argparse CLI, CI pipeline, tests

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check minimax_mcp/
+      - name: Format check
+        run: ruff format --check minimax_mcp/
+      - name: Tests
+        run: pytest tests/ -v

.gitignore

@@ -12,4 +12,9 @@
 dist/
 minimax_mcp.egg-info/
 .coverage
-coverage.xml
+coverage.xml
+
+# AI agents & copilot
+AGENTS.md
+.github/copilot-instructions.md
+.github/copilot*.md

README.md

@@ -55,7 +55,8 @@
 ### Claude Desktop
 Go to `Claude > Settings > Developer > Edit Config > claude_desktop_config.json` to include the following:
 
-```
+**Option 1: Using environment variables (traditional)**
+```json
 {
   "mcpServers": {
     "MiniMax": {
@@ -73,8 +74,34 @@ Go to `Claude > Settings > Developer > Edit Config > claude_desktop_config.json`
     }
   }
 }
+```
 
+**Option 2: Using CLI arguments (recommended for GitHub Copilot CLI)**
+```json
+{
+  "mcpServers": {
+    "MiniMax": {
+      "command": "uvx",
+      "args": [
+        "minimax-mcp",
+        "-y",
+        "--api-key=insert-your-api-key-here",
+        "--base-path=/User/xxx/Desktop",
+        "--api-host=https://api.minimax.io",
+        "--resource-mode=url"
+      ]
+    }
+  }
+}
 ```
+
+**CLI Arguments:**
+- `--api-key`: MiniMax API key (overrides MINIMAX_API_KEY)
+- `--base-path`: Local output directory path (overrides MINIMAX_MCP_BASE_PATH)
+- `--api-host`: API host URL (overrides MINIMAX_API_HOST)
+- `--resource-mode`: Resource mode [url|local] (overrides MINIMAX_API_RESOURCE_MODE)
+
+CLI arguments take precedence over environment variables.
 ⚠️ Warning: The API key needs to match the host. If an error "API Error: invalid api key" occurs, please check your api host:
 - Global Host：`https://api.minimax.io`
 - Mainland Host：`https://api.minimaxi.com`

docs/STANDARDS.md

@@ -0,0 +1,46 @@
+# Development Standards
+
+## Language and Runtime
+
+- Python >= 3.10
+- Package manager: `uv` (preferred) or `pip`
+- Dependencies declared in `pyproject.toml`
+
+## Code Quality
+
+- Linter/formatter: `ruff`
+- Run before commit: `ruff check minimax_mcp/` and `ruff format minimax_mcp/`
+- No shadowing of Python builtins (`format`, `type`, `id`, etc.)
+- All `requests.get()` / HTTP calls must include explicit `timeout`
+- File I/O must use context managers (`with open(...)`)
+
+## Testing
+
+- Framework: `pytest` with `pytest-cov`
+- Test directory: `tests/`
+- Run: `pytest tests/ -v`
+- Coverage report: `pytest --cov=minimax_mcp --cov-report=term-missing`
+
+## Git
+
+- Conventional commits: `<type>(<scope>): <subject>`
+- Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`
+- Every commit references an issue when applicable
+
+## CI/CD
+
+- GitHub Actions on push/PR to `main`
+- Pipeline: ruff check → ruff format → pytest
+- Matrix: Python 3.10, 3.12
+
+## API Client
+
+- All API requests go through `MinimaxAPIClient` (`client.py`)
+- Default timeout: `REQUEST_TIMEOUT` (30s) for API calls
+- Default timeout: `DOWNLOAD_TIMEOUT` (120s) for file downloads
+- Input parameters validated before API calls to avoid wasting credits
+
+## Constants
+
+- All defaults and valid ranges defined in `const.py`
+- No magic numbers in tool functions

minimax_mcp/__init__.py

@@ -1,3 +1,3 @@
 """Minimax MCP Server package."""
 
-__version__ = "0.0.17"
+__version__ = "0.0.18"

minimax_mcp/client.py

@@ -53,6 +53,8 @@ def _make_request(
             # requests library will set it automatically with the correct boundary
             self.session.headers.pop('Content-Type', None)
 
+        from minimax_mcp.const import REQUEST_TIMEOUT
+        kwargs.setdefault('timeout', REQUEST_TIMEOUT)
         try:
             response = self.session.request(method, url, **kwargs)
 

minimax_mcp/const.py

@@ -27,4 +27,16 @@
 RESOURCE_MODE_LOCAL = "local" # save resource to local file system
 RESOURCE_MODE_URL = "url" # provide resource url
 
-ENV_FASTMCP_LOG_LEVEL = "FASTMCP_LOG_LEVEL"
+ENV_FASTMCP_LOG_LEVEL = "FASTMCP_LOG_LEVEL"
+
+# HTTP timeout (seconds)
+REQUEST_TIMEOUT = 30
+DOWNLOAD_TIMEOUT = 120
+
+# Valid parameter ranges
+VALID_SAMPLE_RATES = {8000, 16000, 22050, 24000, 32000, 44100}
+VALID_BITRATES = {32000, 64000, 128000, 256000}
+VALID_EMOTIONS = {"happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral"}
+VALID_AUDIO_FORMATS = {"pcm", "mp3", "flac"}
+VALID_CHANNELS = {1, 2}
+VALID_ASPECT_RATIOS = {"1:1", "16:9", "4:3", "3:2", "2:3", "3:4", "9:16", "21:9"}