Merge pull request #8 from zenml-io/claude-md

Add PR test workflow for automated testing + add `CLAUDE.md` file

Author: strickvl

.github/workflows/pr-test.yml

@@ -0,0 +1,47 @@
+name: PR Tests
+
+on:
+  pull_request:
+    branches: [main]
+    paths-ignore: ["assets/**"]
+  push:
+    branches: [main]
+concurrency:
+  # New commit on branch cancels running workflows of the same branch
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    env:
+      ZENML_DISABLE_RICH_LOGGING: "1"
+      ZENML_LOGGING_COLORS_DISABLED: "true"
+      ZENML_ANALYTICS_OPT_IN: "false"
+      PYTHONIOENCODING: "UTF-8"
+      PYTHONUNBUFFERED: "1"
+      ZENML_STORE_URL: ${{ secrets.ZENML_STORE_URL }}
+      ZENML_STORE_API_KEY: ${{ secrets.ZENML_STORE_API_KEY }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Run MCP smoke test
+        run: |
+          echo "Running MCP smoke test..."
+          uv run scripts/test_mcp_server.py server/zenml_server.py

CLAUDE.md

@@ -0,0 +1,61 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+### Testing and Development
+- **Run smoke tests**: `uv run scripts/test_mcp_server.py server/zenml_server.py`
+- **Format code**: `./scripts/format.sh` (uses ruff for linting and formatting)
+- **Run MCP server locally**: `uv run server/zenml_server.py`
+
+### Code Quality
+- **Format**: `bash scripts/format.sh`
+
+## Architecture
+
+### Core Components
+
+The project is a Model Context Protocol (MCP) server that provides AI assistants with access to ZenML API functionality.
+
+**Main Server File**: `server/zenml_server.py`
+- Uses FastMCP framework for MCP protocol implementation
+- Implements lazy initialization of ZenML client to avoid startup delays
+- Provides comprehensive exception handling with the `@handle_exceptions` decorator
+- Configures minimal logging to prevent JSON protocol interference
+
+**Key Features**:
+- Reads ZenML server configuration from environment variables (`ZENML_STORE_URL`, `ZENML_STORE_API_KEY`)
+- Provides MCP tools for accessing ZenML entities (users, stacks, pipelines, runs, etc.)
+- Supports triggering new pipeline runs via run templates
+- Includes automated CI/CD testing with GitHub Actions
+
+### Environment Setup
+
+The server requires:
+- Python 3.12+
+- Dependencies managed via `uv` (preferred) or pip
+- ZenML server URL and API key configured as environment variables
+
+### Testing Infrastructure
+
+- **PR Testing**: GitHub Actions runs tests on every PR (formatting checks + smoke tests)
+- **Scheduled testing**: Comprehensive smoke tests run every 3 days with automated issue creation on failures
+- **Manual testing**: Use the test script to verify MCP protocol functionality
+- **CI/CD**: Uses UV with caching for fast dependency installation
+
+### Project Structure
+
+- `server/` - Main MCP server implementation
+- `scripts/` - Development and testing utilities
+- `assets/` - Project assets and images
+
+- Root files include configuration for Desktop Extensions (DXT) support
+
+### Important Implementation Details
+
+- **Logging**: Configured to use stderr and suppress ZenML internal logging to prevent JSON protocol conflicts
+- **Error Handling**: All tool functions wrapped with exception handling decorator
+- **Lazy Loading**: ZenML client initialized only when needed to improve startup performance
+- **Environment Variables**: Server configuration via `ZENML_STORE_URL` and
+  `ZENML_STORE_API_KEY`

README.md

@@ -61,7 +61,7 @@ This project includes automated testing to ensure the MCP server remains functio
 - **🔄 Automated Smoke Tests**: A comprehensive smoke test runs every 3 days via GitHub Actions
 - **🚨 Issue Creation**: Failed tests automatically create GitHub issues with detailed debugging information
 - **⚡ Fast CI**: Uses UV with caching for quick dependency installation and testing
-- **🧪 Manual Testing**: You can run the smoke test locally using `uv run scripts/test_mcp_server.py zenml_server.py`
+- **🧪 Manual Testing**: You can run the smoke test locally using `uv run scripts/test_mcp_server.py server/zenml_server.py`
 
 The automated tests verify:
 - MCP protocol connection and handshake