Ploomber MCP

misc/ploomber-mcp/CHANGELOG.md

@@ -0,0 +1,3 @@
+# CHANGELOG
+
+## 0.1dev

misc/ploomber-mcp/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ploomber
+
+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.

misc/ploomber-mcp/README.md

@@ -0,0 +1,89 @@
+# mcp-ploomber
+
+Setup:
+
+```sh
+# requires conda
+pip install invoke
+invoke setup
+conda activate mcp-ploomber
+```
+
+If you're not using conda, create a virtual env and do:
+
+```sh
+pip install --editable .
+```
+
+## Virtual Environment Setup
+
+You'll need to set up a virtual environment to run the MCP server. We provide setup scripts to make this easy:
+
+1. Run the setup script to create and configure the virtual environment:
+
+```sh
+# Make the script executable first
+chmod +x setup_venv.sh
+./setup_venv.sh
+```
+
+This script will:
+- Create a Python virtual environment
+- Install all required dependencies
+- Set up the package in development mode
+
+## MCP Configuration
+
+To configure the MCP server, you need to create an `mcp.json` file:
+
+1. Run the generation script to create a personalized configuration:
+
+```sh
+# Make the script executable first
+chmod +x generate_mcp_json.sh
+./generate_mcp_json.sh
+```
+
+2. Edit the generated `mcp.json` file to add your Ploomber Cloud API key:
+
+```json
+{
+    "mcpServers": {
+        "ploomber-mcp": {
+            "command": "/path/to/your/venv/bin/python",
+            "args": [
+                "/path/to/your/src/mcp_ploomber/server.py"
+            ],
+            "env": {
+                "_PLOOMBER_CLOUD_ENV": "",
+                "PLOOMBER_CLOUD_KEY": "YOUR_API_KEY_HERE"
+            },
+            "setup": "/path/to/your/setup_venv.sh"
+        }
+    }
+}
+```
+
+## Running the Server
+
+Once you've completed the setup, you can start the MCP server manually using:
+
+```sh
+cd src/mcp_ploomber
+```
+
+```sh
+mcp run server.py
+```
+
+To debug, you can also run the MCP server in dev mode:
+
+```sh
+mcp dev server.py
+```
+
+To add the MCP to your LLM client, simply copy/paste your `mcp.json` where the client expects the MCP config file.
+
+
+
+

misc/ploomber-mcp/generate_mcp_json.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# generate_mcp_json.sh - Creates a personalized mcp.json file
+
+# Get the absolute path to the project directory
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Determine python executable path based on OS
+if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+    # Windows
+    PYTHON_PATH="${PROJECT_DIR}/venv/Scripts/python"
+else
+    # Unix-like (macOS, Linux)
+    PYTHON_PATH="${PROJECT_DIR}/venv/bin/python"
+fi
+
+# Path to the server script
+SERVER_SCRIPT="${PROJECT_DIR}/src/mcp_ploomber/server.py"
+
+# Create the mcp.json file
+cat > "${PROJECT_DIR}/mcp.json" << EOF
+{
+    "mcpServers": {
+        "ploomber-mcp": {
+            "command": "${PYTHON_PATH}",
+            "args": [
+                "${SERVER_SCRIPT}"
+            ],
+            "env": {
+                "_PLOOMBER_CLOUD_ENV": "",
+                "PLOOMBER_CLOUD_KEY": ""
+            },
+            "setup": "${PROJECT_DIR}/setup_venv.sh"
+        }
+    }
+}
+EOF
+
+echo "Generated mcp.json with your local paths at: ${PROJECT_DIR}/mcp.json"
+echo "Please edit the file to add your PLOOMBER_CLOUD_KEY and other environment variables as needed."

misc/ploomber-mcp/pyproject.toml

@@ -0,0 +1,71 @@
+[tool.pytest.ini_options]
+addopts = "--pdbcls=IPython.terminal.debugger:Pdb"
+
+[tool.nbqa.addopts]
+flake8 = [
+    # notebooks allow non-top imports
+    "--extend-ignore=E402",
+    # jupysql notebooks might have "undefined name" errors
+    # due to the << operator
+    # W503, W504 ignore line break after/before
+    # binary operator since they are conflicting
+    "--ignore=F821, W503, W504",
+]
+
+[tool.pkgmt]
+# used to add links to issue numbers in CHANGELOG.md
+github = "ploomber/mcp-ploomber"
+# used to check that the package is importable when running pkgmt setup
+package_name = "mcp_ploomber"
+# defines the conda environment name when using pkgmt setup, if missing,
+# package_name is used
+env_name = "mcp-ploomber"
+
+[tool.pkgmt.check_links]
+extensions = ["md", "rst", "py", "ipynb"]
+
+
+# build settings
+# https://github.com/pypa/sampleproject/blob/main/pyproject.toml
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-ploomber"
+version = "0.1dev"
+description = "A sample Python project"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE.txt" }
+keywords = ["sample", "setuptools", "development"]
+authors = [{ name = "A. Random Developer", email = "author@example.com" }]
+maintainers = [
+    { name = "A. Great Maintainer", email = "maintainer@example.com" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = []
+[project.optional-dependencies]
+dev = ["pytest", "flake8", "invoke", "twine"]
+
+[project.urls]
+"Homepage" = "https://github.com/pypa/sampleproject"
+"Bug Reports" = "https://github.com/pypa/sampleproject/issues"
+"Funding" = "https://donate.pypi.org"
+"Say Thanks!" = "http://saythanks.io/to/example"
+"Source" = "https://github.com/pypa/sampleproject/"
+
+[project.scripts]
+mcp-ploomber = "mcp_ploomber.cli:cli"
+
+[tool.setuptools]
+package-data = { "mcp_ploomber" = ["assets/*", "templates/*", "*.md"] }

misc/ploomber-mcp/requirements.txt

@@ -0,0 +1,2 @@
+ploomber_cloud
+mcp[cli]

misc/ploomber-mcp/settings.py

@@ -0,0 +1,13 @@
+# import os
+from pathlib import Path
+
+# from dotenv import load_dotenv
+
+# load_dotenv()
+
+
+PATH_TO_PROJECT_ROOT = Path(__file__).parent
+
+# PATH_TO_DB = PATH_TO_PROJECT_ROOT / "data" / "db.sqlite"
+# LOCAL_DB_URI = f"sqlite:///{PATH_TO_DB}"
+# OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")

misc/ploomber-mcp/setup.cfg

@@ -0,0 +1,7 @@
+[metadata]
+description-file = README.md
+
+[flake8]
+max-line-length = 88
+extend-ignore = E203
+extend-exclude = build,node_modules

misc/ploomber-mcp/setup_venv.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+# setup_venv.sh - Script to set up virtual environment for Ploomber MCP
+
+# Exit on error
+set -e
+
+echo "Setting up virtual environment for Ploomber MCP..."
+
+# Create virtual environment
+python -m venv venv
+echo "Virtual environment created."
+
+# Determine the correct activation script based on OS
+if [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+    # Windows
+    ACTIVATE="venv/Scripts/activate"
+    PIP="venv/Scripts/pip"
+    PYTHON="venv/Scripts/python"
+else
+    # Unix-like (macOS, Linux)
+    ACTIVATE="venv/bin/activate"
+    PIP="venv/bin/pip"
+    PYTHON="venv/bin/python"
+fi
+
+# Upgrade pip
+echo "Upgrading pip..."
+$PIP install --upgrade pip
+
+# Install dependencies
+echo "Installing dependencies..."
+if [ -f "requirements.txt" ]; then
+    $PIP install -r requirements.txt
+else
+    echo "Warning: requirements.txt not found. Creating minimal requirements..."
+    echo "mcp" > requirements.txt
+    echo "ploomber_cloud" >> requirements.txt
+    $PIP install -r requirements.txt
+fi
+
+# Install package in development mode
+echo "Installing package in development mode..."
+$PIP install -e .
+
+# Verify installation
+echo "Verifying installation..."
+$PYTHON -c "import sys; print(f'Setup complete! Python version: {sys.version}')"
+
+echo ""
+echo "Setup complete! To activate the virtual environment, run:"
+echo "source $ACTIVATE  # On Unix-like systems (Linux, macOS)"
+echo "or"
+echo "$ACTIVATE  # On Windows"
+echo ""

misc/ploomber-mcp/src/mcp_ploomber/__init__.py

@@ -0,0 +1,3 @@
+from mcp_ploomber._settings import Settings
+
+SETTINGS = Settings()