mcp-modal 0.2.0__tar.gz

mcp_modal-0.2.0/.gitignore

@@ -0,0 +1,174 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc

mcp_modal-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

mcp_modal-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sajid Mehmood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

mcp_modal-0.2.0/PKG-INFO

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: mcp-modal
+Version: 0.2.0
+Summary: MCP server for managing Modal (modal.com) apps, containers, volumes, and secrets.
+Project-URL: Homepage, https://github.com/george-bobby/mcp-modal
+Project-URL: Repository, https://github.com/george-bobby/mcp-modal
+Author: George Bobby
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude,mcp,modal,model-context-protocol
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.9.2
+Requires-Dist: modal>=1.0
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: uv>=0.6.9
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.george-bobby/mcp-modal -->
+
+# MCP Modal Server
+
+An MCP server for managing [Modal](https://modal.com) — apps, containers, volumes, and secrets — and for deploying & running Modal apps directly from [Claude Code](https://docs.claude.com/en/docs/claude-code) and other MCP clients.
+
+> **Heads up:** This is for [Modal](https://modal.com), the serverless cloud platform for running code on GPUs/CPUs — not any other product named "Modal".
+
+Every tool shells out to your local `modal` CLI, so it operates against whatever Modal profile and credentials are configured on your machine. There are no extra tokens to manage.
+
+## Installation
+
+1. Clone this repository:
+```bash
+git clone https://github.com/george-bobby/mcp-modal.git
+cd mcp-modal
+```
+
+2. Install dependencies using [`uv`](https://docs.astral.sh/uv/):
+```bash
+uv sync
+```
+
+## Logging in to Modal
+
+This server uses your local Modal credentials. If you haven't authenticated yet, run:
+
+```bash
+modal setup
+```
+
+This opens a browser to log in and stores a token in `~/.modal.toml`. Already logged in elsewhere? Check with `modal profile current`.
+
+## Configuration
+
+Add the server to Claude Code with the `claude mcp` CLI:
+
+```bash
+claude mcp add mcp-modal -- \
+  uv --project /path/to/mcp-modal run /path/to/mcp-modal/src/mcp_modal/server.py
+```
+
+Or add it to a `.mcp.json` file in your project root:
+
+```json
+{
+  "mcpServers": {
+    "mcp-modal": {
+      "command": "uv",
+      "args": [
+        "--project", "/path/to/mcp-modal",
+        "run", "/path/to/mcp-modal/src/mcp_modal/server.py"
+      ]
+    }
+  }
+}
+```
+
+Replace `/path/to/mcp-modal` with the absolute path to your cloned repository.
+
+## Requirements
+
+- Python 3.11 or higher
+- `uv` package manager
+- Modal CLI 1.x configured with valid credentials (`modal setup`)
+- For Modal **deploy** and **run** support:
+  - The project being deployed/run must use `uv` for dependency management
+  - `modal` must be installed in that project's virtual environment
+
+## Supported Tools
+
+26 tools, grouped by area. Account-scoped tools accept an optional `env` argument to
+target a specific [Modal environment](https://modal.com/docs/guide/environments); if
+omitted, they use the profile's default (or `MODAL_ENVIRONMENT`).
+
+### Deploy & Run
+
+1. **Deploy Modal App** (`deploy_modal_app`)
+   - Deploys a Modal app (`modal deploy`). Deployed web endpoints persist, so any links
+     in the output are live and shareable (returned in `urls`).
+   - Parameters: `absolute_path_to_app` (required), `env`, `name`, `tag`,
+     `strategy` (`rolling`/`recreate`), `stream_logs`
+   - The app's directory must use `uv` with `modal` installed in its virtualenv.
+
+2. **Run Modal App** (`run_modal_app`)
+   - Runs a function or local entrypoint once and streams its output (`modal run`).
+   - Parameters: `absolute_path_to_app` (required), `function_name`, `env`,
+     `detach`, `timeout_seconds` (default 120)
+   - Returns a snapshot with `truncated: true` if the run is still going at the timeout.
+     Pass `detach=True` to keep long jobs alive on Modal past the timeout.
+
+> **Why no `modal serve` tool?** `modal serve` only keeps its endpoints alive while the
+> blocking process runs — an MCP tool that returns would tear them down immediately,
+> handing back a dead URL. Use `deploy_modal_app` for a persistent, shareable endpoint.
+
+### Apps
+
+3. **List Modal Apps** (`list_modal_apps`)
+   - Lists apps currently deployed/running or recently stopped. Use this to find the
+     app name/ID for the other app tools.
+   - Parameters: `env`
+
+4. **Get Modal App Logs** (`get_modal_app_logs`)
+   - Fetches or streams logs for an app by name or ID (`modal app logs`).
+   - Parameters: `app_identifier` (required), `timeout_seconds` (default 30), `env`,
+     `since`, `until`, `tail`, `search`, `source` (`stdout`/`stderr`/`system`), `follow`
+   - With `follow=True`, logs stream until the app stops or `timeout_seconds` is reached,
+     returning a snapshot with `truncated: true`.
+
+5. **Stop Modal App** (`stop_modal_app`)
+   - Permanently stops an app and terminates its containers (`modal app stop`).
+   - Parameters: `app_identifier` (required), `env`
+
+6. **Roll Back Modal App** (`rollback_modal_app`)
+   - Redeploys a previous version of an app (`modal app rollback`).
+   - Parameters: `app_identifier` (required), `version` (optional — defaults to the
+     previous version), `env`
+
+7. **Get Modal App History** (`get_modal_app_history`)
+   - Returns an app's deployment history (`modal app history`). Use it to find a
+     `version` for rollback.
+   - Parameters: `app_identifier` (required), `env`
+
+### Containers
+
+8. **List Modal Containers** (`list_modal_containers`)
+   - Lists currently running containers (`modal container list`).
+   - Parameters: `app_id` (optional filter), `env`
+
+9. **Get Modal Container Logs** (`get_modal_container_logs`)
+   - Fetches or streams logs for a container ID (`modal container logs`).
+   - Parameters: `container_id` (required), `timeout_seconds` (default 30),
+     `since`, `until`, `tail`, `search`, `source`, `follow`
+
+10. **Exec in Modal Container** (`exec_modal_container`)
+    - Runs a command inside a running container (`modal container exec --no-pty`).
+    - Parameters: `container_id` (required), `command` (list of args, e.g.
+      `["python", "-c", "print('hi')"]`), `timeout_seconds` (default 60)
+
+11. **Stop Modal Container** (`stop_modal_container`)
+    - Terminates a running container (`modal container stop`).
+    - Parameters: `container_id` (required)
+
+### Log Search
+
+12. **Search Modal Logs** (`search_modal_logs`)
+    - Greps an app's or container's logs for a pattern and returns each hit **with the
+      surrounding lines** — built for "where did it go wrong?" debugging. Logs are fetched
+      once and searched locally, so (unlike the `search` argument on the log tools) you get
+      context, regex, case control, and match counts, not just the bare matching line.
+    - Parameters: `identifier` (required — app name/ID or container ID), `pattern` (required),
+      `target` (`app`/`container`, default `app`), `regex`, `case_sensitive`,
+      `context_lines` (default 3), `max_matches` (default 50), `since`, `tail`
+      (defaults to the last 1000 entries), `timeout_seconds`, `env`
+    - Returns `match_count` and `matches`: line-numbered context blocks where matched lines
+      are prefixed with `>`, e.g. `> 8: ValueError: bad input`.
+
+### Volumes — Files
+
+13. **List Modal Volumes** (`list_modal_volumes`) — lists all volumes. Parameters: none.
+14. **List Volume Contents** (`list_modal_volume_contents`) — `volume_name`, `path` (default `/`).
+15. **Copy Files** (`copy_modal_volume_files`) — `volume_name`, `paths` (last is destination).
+16. **Remove File** (`remove_modal_volume_file`) — `volume_name`, `remote_path`, `recursive`.
+17. **Upload File** (`put_modal_volume_file`) — `volume_name`, `local_path`, `remote_path`, `force`.
+18. **Download File** (`get_modal_volume_file`) — `volume_name`, `remote_path`, `local_destination`, `force`. Use `-` as the destination to stream contents to stdout.
+
+### Volumes — Lifecycle
+
+19. **Create Volume** (`create_modal_volume`) — creates a named persistent volume. Parameters: `volume_name`, `env`.
+20. **Delete Volume** (`delete_modal_volume`) — deletes a volume **and all its data** (irreversible). Parameters: `volume_name`, `env`.
+21. **Rename Volume** (`rename_modal_volume`) — Parameters: `old_name`, `new_name`, `env`.
+
+### Secrets
+
+22. **List Secrets** (`list_modal_secrets`)
+    - Lists published secrets (names and timestamps only — values are never exposed).
+    - Parameters: `env`
+
+23. **Create Secret** (`create_modal_secret`)
+    - Creates a secret from inline key/values or a local file (`modal secret create`).
+      Secret values are **redacted** from the returned `command`.
+    - Parameters: `secret_name` (required), `key_values` (dict), `from_dotenv` (path),
+      `from_json` (path), `force`, `env`. Provide at least one of `key_values`,
+      `from_dotenv`, or `from_json`.
+
+24. **Delete Secret** (`delete_modal_secret`) — Parameters: `secret_name`, `env`.
+
+### Discovery
+
+25. **Get Modal Profile** (`get_modal_profile`)
+    - Shows the active profile and all configured profiles. Use it to confirm which
+      workspace/account the server is authenticated as. Parameters: none.
+
+26. **List Modal Environments** (`list_modal_environments`)
+    - Lists the environments in the current workspace; the names are valid `env`
+      arguments for the other tools. Parameters: none.
+
+## Response Format
+
+All tools return responses in a standardized format, with slight variations depending on the operation type:
+
+```python
+# JSON / list operations (apps, containers, volumes, secrets, history, ...):
+{
+    "success": True,
+    "apps": [...]   # or "containers", "volumes", "secrets", "history", "environments"
+}
+
+# Action operations (deploy, stop, create, delete, rename, copy, put, get, rm):
+{
+    "success": True,
+    "message": "Operation successful message",
+    "command": "executed command string",
+    "stdout": "command output",  # if any
+    "stderr": "error output"     # if any
+}
+
+# Log / run / exec operations (snapshot-based):
+{
+    "success": True,
+    "logs": "...",          # or "output" for run/exec
+    "truncated": False,     # True when cut off at timeout_seconds
+    "command": "executed command string"
+}
+
+# Error case (all operations):
+{
+    "success": False,
+    "error": "Error message describing what went wrong",
+    "command": "executed command string",
+    "stdout": "command output",  # if available
+    "stderr": "error output"     # if available
+}
+```
+
+## Publishing to the MCP Registry
+
+This repo ships a [`server.json`](server.json) following the [MCP Registry](https://github.com/modelcontextprotocol/registry) spec, and the README carries the `mcp-name:` ownership marker required for PyPI verification. To publish a new version:
+
+```bash
+# 1. Build and publish the package to PyPI (the registry only hosts metadata)
+uv build
+uv publish
+
+# 2. Publish the server entry to the MCP Registry
+mcp-publisher login github      # GitHub auth for the io.github.george-bobby/* namespace
+mcp-publisher publish
+```
+
+Bump the `version` in both [`pyproject.toml`](pyproject.toml) and [`server.json`](server.json) together — they must match.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.