ray-mcp-server 0.2.0__tar.gz

ray_mcp_server-0.2.0/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(export TWINE_USERNAME=__token__)",
+      "Bash(export:*)",
+      "Bash(uv tool install:*)"
+    ],
+    "deny": []
+  }
+}

ray_mcp_server-0.2.0/.github/ISSUE_TEMPLATE/release.md

@@ -0,0 +1,68 @@
+---
+name: Release Checklist
+about: Checklist for creating a new release
+title: 'Release v[VERSION]'
+labels: release
+assignees: ''
+
+---
+
+## Release Checklist for v[VERSION]
+
+### Pre-release
+- [ ] Update version in `pyproject.toml`
+- [ ] Update version references in documentation
+- [ ] Run full test suite: `uv run pytest`
+- [ ] Run linting: `make lint`
+- [ ] Test local build: `uv build`
+- [ ] Test local installation: `uvx --from ./dist/ray_mcp_server-[VERSION]-py3-none-any.whl ray-mcp-server`
+
+### Release Process
+- [ ] Commit all changes
+- [ ] Create and push tag: `git tag v[VERSION] && git push origin v[VERSION]`
+- [ ] Verify GitHub Actions workflow completes successfully
+- [ ] Verify package appears on PyPI: https://pypi.org/p/ray-mcp-server/
+- [ ] Create GitHub release with release notes
+
+### Post-release
+- [ ] Test installation from PyPI: `uvx ray-mcp-server`
+- [ ] Update Claude Desktop config example in README
+- [ ] Update `docs/config/claude_desktop_config.json` if needed
+- [ ] Announce release (if applicable)
+
+### Release Notes Template
+
+```markdown
+## What's New in v[VERSION]
+
+### ✨ Features
+- 
+
+### 🐛 Bug Fixes
+- 
+
+### 📚 Documentation
+- 
+
+### 🔧 Technical Changes
+- 
+
+## Installation
+
+```bash
+uvx ray-mcp-server
+```
+
+## Claude Desktop Configuration
+
+```json
+{
+  "mcpServers": {
+    "ray-mcp": {
+      "command": "uvx",
+      "args": ["ray-mcp-server"]
+    }
+  }
+}
+```
+```

ray_mcp_server-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,66 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+jobs:
+  test-fast:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v1
+      with:
+        version: "latest"
+    
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+    
+    - name: Run fast test suite
+      run: python -m pytest tests/ -m "fast" --tb=short -v --maxfail=3 --cov=ray_mcp --cov-report=xml --cov-report=term-missing
+    
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: false
+        verbose: true
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.12"
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v1
+      with:
+        version: "latest"
+    
+    - name: Install dependencies
+      run: uv sync --dev
+    
+    - name: Run linting
+      run: |
+        uv run black --check ray_mcp/ examples/ tests/ 
+        uv run isort --check-only ray_mcp/ examples/ tests/
+        uv run pyright ray_mcp/ examples/ tests/
+        

ray_mcp_server-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,141 @@
+name: Build and Publish
+
+on:
+  # Manual trigger
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 'Target repository'
+        required: true
+        default: 'testpypi'
+        type: choice
+        options:
+          - testpypi
+          - pypi
+      
+  # Automatic trigger on GitHub releases
+  release:
+    types: [published]
+
+  # Trigger on tags for releases
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.12"
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v1
+      with:
+        version: "latest"
+    
+    - name: Install dependencies
+      run: uv sync --dev
+    
+    - name: Build package
+      run: uv build
+    
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'pypi')
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ray-mcp-server
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://upload.pypi.org/legacy/
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'testpypi'
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/ray-mcp-server
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+    
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        password: ${{ secrets.TEST_PYPI_API_TOKEN }}
+
+  github-release:
+    name: Create GitHub Release
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+    - publish-to-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v3
+      with:
+        name: python-package-distributions
+        path: dist/
+    
+    - name: Sign the dists with Sigstore
+      uses: sigstore/gh-action-sigstore-python@v2.1.1
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        '${{ github.ref_name }}'
+        --repo '${{ github.repository }}'
+        --notes ""
+    
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release upload
+        '${{ github.ref_name }}' dist/**
+        --repo '${{ github.repository }}'

ray_mcp_server-0.2.0/.gitignore

@@ -0,0 +1,206 @@
+# 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/
+.coverage_data/
+.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
+
+# 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/#use-with-ide
+.pdm.toml
+
+# uv
+#   uv.lock should be committed to version control for reproducible builds
+.uv/
+
+# 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
+
+# Virtual 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/
+
+# IDEs and editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+*.sublime-project
+*.sublime-workspace
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+*.code-workspace
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+Desktop.ini
+
+# Ray specific
+ray_logs/
+ray_mcp_logs/
+/tmp/ray/
+
+# Project specific
+cleanup_repo.sh
+.env.local
+.env.development
+.env.test
+.env.production
+
+# Temporary files
+*.tmp
+*.temp
+.tmp/
+temp/
+
+# Backup files
+*.bak
+*.backup
+*~

ray_mcp_server-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

ray_mcp_server-0.2.0/CLAUDE.md

@@ -0,0 +1,138 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Ray MCP (Model Context Protocol) server that provides comprehensive Ray cluster management, job execution, and distributed computing capabilities. The server acts as an MCP bridge to Ray, enabling LLMs to manage Ray clusters and jobs through structured tool calls.
+
+## Architecture
+
+- **`ray_mcp/main.py`**: Main MCP server entry point with tool definitions and request handlers
+- **`ray_mcp/ray_manager.py`**: Core Ray cluster management (RayManager class)
+- **`ray_mcp/worker_manager.py`**: Multi-node worker management and orchestration
+- **`ray_mcp/tools.py`**: MCP tool implementations and validation
+- **`ray_mcp/types.py`**: Type definitions and Pydantic models for all data structures
+- **`examples/`**: Working examples demonstrating Ray usage patterns
+- **`tests/`**: Comprehensive test suite with multiple test categories
+
+## Key Development Commands
+
+### Testing
+```bash
+# Fast development tests (excludes e2e)
+make test
+
+# Full test suite including e2e tests
+make test-full  
+
+# Smart test runner (detects changes)
+make test-smart
+
+# Specific test categories
+make test-smoke    # Basic functionality verification
+make test-e2e      # End-to-end integration tests
+```
+
+### Code Quality
+```bash
+# Run all linting checks
+make lint
+
+# Auto-format code
+make format
+
+# Individual checks
+uv run pyright ray_mcp/    # Type checking
+uv run black ray_mcp/      # Code formatting
+uv run isort ray_mcp/      # Import sorting
+```
+
+### Development Setup
+```bash
+# Full development setup
+make dev-install
+
+# Install dependencies only
+uv sync
+
+# Run the MCP server
+uv run ray-mcp
+```
+
+### Testing Infrastructure
+
+The project uses pytest with custom markers:
+- `fast`: Quick unit/integration tests for development
+- `e2e`: End-to-end tests requiring full Ray cluster setup
+- `smoke`: Minimal verification tests
+- `slow`: Performance-intensive tests
+
+Test files follow patterns: `test_*.py` in the `tests/` directory.
+
+## Multi-Node Architecture
+
+The server supports both single-node and multi-node Ray clusters:
+- **Default**: Creates head node + 2 worker nodes automatically
+- **Custom**: Supports configurable worker node specifications
+- **WorkerManager**: Handles worker lifecycle and resource management
+
+## Key Implementation Details
+
+- All Ray operations are wrapped with proper error handling for Ray availability
+- The server uses async/await patterns for MCP protocol compliance
+- Type safety is enforced with Pydantic models and pyright type checking
+- Multi-node clusters use localhost networking with configurable ports
+- Job submission supports both simple scripts and complex workflow orchestration
+
+## Claude Desktop Setup
+
+### Local Development
+```json
+{
+  "mcpServers": {
+    "ray-mcp": {
+      "command": "/opt/homebrew/bin/uv",
+      "args": ["run", "--directory", "/path/to/ray-mcp", "ray-mcp"]
+    }
+  }
+}
+```
+
+### Connecting to Remote Ray Cluster
+```json
+{
+  "mcpServers": {
+    "ray-mcp": {
+      "command": "/opt/homebrew/bin/uv", 
+      "args": ["run", "--directory", "/path/to/ray-mcp", "ray-mcp"],
+      "env": {
+        "RAY_ADDRESS": "ray://127.0.0.1:10001"
+      }
+    }
+  }
+}
+```
+
+### Kubernetes Ray Cluster
+For Kubernetes-deployed Ray clusters, port-forward the Ray client port:
+```bash
+kubectl port-forward -n ray-cluster ray-cluster-kuberay-head-<pod-id> 10001:10001
+```
+
+Then use `RAY_ADDRESS=ray://127.0.0.1:10001` in Claude Desktop config.
+
+### Version Compatibility
+Ensure local Ray/Python versions match your cluster:
+- Check cluster versions: `kubectl logs -n ray-cluster ray-cluster-kuberay-head-<pod-id>`
+- Update `pyproject.toml` to match cluster Ray version
+- Use `uv python pin <version>` to match Python version
+- Run `uv sync` to update dependencies
+
+## Development Notes
+
+- This project uses `uv` exclusively (not pip or python directly)
+- All commands should use `uv run` prefix
+- The codebase follows black formatting and isort import organization
+- Coverage threshold is set to 80% minimum
+- Test execution time is optimized with parallel test runners and smart test selection