mcp-lightcast 0.1.0__tar.gz

mcp_lightcast-0.1.0/.env.example

@@ -0,0 +1,49 @@
+# ======================================
+# MCP Lightcast Server Configuration
+# ======================================
+
+# REQUIRED: Lightcast API Credentials
+# Get these from your Lightcast developer account
+# Contact https://docs.lightcast.dev/contact for API access
+LIGHTCAST_CLIENT_ID=your_client_id_here
+LIGHTCAST_CLIENT_SECRET=your_client_secret_here
+
+# OPTIONAL: Lightcast API Configuration (defaults provided)
+LIGHTCAST_BASE_URL=https://api.lightcast.io
+LIGHTCAST_OAUTH_URL=https://auth.emsicloud.com/connect/token
+LIGHTCAST_OAUTH_SCOPE=emsi_open
+LIGHTCAST_RATE_LIMIT=1000
+
+# OPTIONAL: MCP Server Configuration (defaults provided)
+MCP_SERVER_NAME=lightcast-mcp-server
+LOG_LEVEL=INFO
+MASK_ERROR_DETAILS=true
+
+# OPTIONAL: PyPI Publishing Tokens (for package maintainers)
+# Get TestPyPI token: https://test.pypi.org/manage/account/
+# Get PyPI token: https://pypi.org/manage/account/
+TEST_PYPI_TOKEN=pypi-your-testpypi-token-here
+PYPI_TOKEN=pypi-your-production-token-here
+# Alternative format (also supported):
+# TWINE_USERNAME=__token__
+# TWINE_PASSWORD=pypi-your-token-here
+
+# ======================================
+# Usage Instructions:
+# 
+# 1. Copy this file to .env:
+#    cp .env.example .env
+# 
+# 2. Edit .env with your real Lightcast API credentials
+# 
+# 3. Test your configuration:
+#    make validate-config
+# 
+# 4. Run the server:
+#    make run
+#
+# 5. For package publishing (maintainers only):
+#    Add your PyPI tokens above, then run:
+#    make publish-test  # Test PyPI first
+#    make publish-pypi  # Production PyPI
+# ======================================

mcp_lightcast-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,230 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+  release:
+    types: [ published ]
+
+env:
+  PYTHON_VERSION: '3.12'
+
+jobs:
+  test:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # For dynamic versioning
+    
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+    
+    - name: Install dependencies
+      run: |
+        uv sync --all-groups --frozen
+    
+    - name: Lint with ruff
+      run: |
+        uv run ruff check src/ tests/
+        uv run ruff format --check src/ tests/
+    
+    - name: Type check with mypy
+      run: |
+        uv run mypy src/
+    
+    - name: Test with pytest
+      run: |
+        uv run pytest --cov=src --cov-report=xml --cov-report=term
+      env:
+        # Mock environment variables for testing
+        LIGHTCAST_CLIENT_ID: "test_client_id"
+        LIGHTCAST_CLIENT_SECRET: "test_client_secret"
+    
+    - name: Upload coverage to Codecov
+      if: matrix.python-version == '3.12'
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+
+  test-basic-functionality:
+    name: Test Basic Functionality
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v3
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install dependencies
+      run: uv sync --frozen
+    
+    - name: Run basic functionality test
+      run: |
+        uv run python test_basic_functionality.py
+
+  docker-build:
+    name: Docker Build and Test
+    runs-on: ubuntu-latest
+    needs: [test]
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+    
+    - name: Build production image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        file: ./Dockerfile
+        target: production
+        tags: mcp-lightcast:test
+        load: true
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+    
+    - name: Test Docker image
+      run: |
+        # Test image can start and validate config
+        docker run --rm \
+          -e LIGHTCAST_CLIENT_ID=test_id \
+          -e LIGHTCAST_CLIENT_SECRET=test_secret \
+          mcp-lightcast:test --validate-config --quiet || echo "Expected to fail without real credentials"
+    
+    - name: Build development image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        file: ./Dockerfile.dev
+        target: development
+        tags: mcp-lightcast:dev-test
+        load: true
+
+  security-scan:
+    name: Security Scan
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v3
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Install dependencies
+      run: uv sync --frozen
+    
+    - name: Run safety check
+      run: |
+        uv add --dev safety
+        uv run safety check --json || true
+    
+    - name: Run bandit security linter
+      run: |
+        uv add --dev bandit[toml]
+        uv run bandit -r src/ -f json || true
+
+  publish-docker:
+    name: Publish Docker Images
+    runs-on: ubuntu-latest
+    needs: [test, docker-build]
+    if: github.event_name == 'release' && github.event.action == 'published'
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+    
+    - name: Login to GitHub Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    
+    - name: Extract metadata
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ghcr.io/${{ github.repository }}
+        tags: |
+          type=ref,event=branch
+          type=ref,event=pr
+          type=semver,pattern={{version}}
+          type=semver,pattern={{major}}.{{minor}}
+          type=semver,pattern={{major}}
+          type=raw,value=latest,enable={{is_default_branch}}
+    
+    - name: Build and push production image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        file: ./Dockerfile
+        target: production
+        push: true
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [test, security-scan]
+    if: github.event_name == 'release' && github.event.action == 'published'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-lightcast
+    permissions:
+      id-token: write  # For trusted publishing
+    
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0  # For dynamic versioning
+    
+    - name: Set up uv
+      uses: astral-sh/setup-uv@v3
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+    
+    - name: Build package
+      run: |
+        uv build
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        verbose: true

mcp_lightcast-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,182 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g., v0.1.0)'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v5
+      with:
+        fetch-depth: 0
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        enable-cache: true
+        cache-dependency-glob: "uv.lock"
+    
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+    
+    - name: Run tests
+      run: uv run pytest tests/ -v
+    
+    - name: Run linting
+      run: |
+        uv run ruff check .
+        uv run ruff format --check .
+    
+    - name: Run type checking
+      run: uv run mypy src/
+    
+    - name: Build package
+      run: uv build
+    
+    - name: Check distribution
+      run: |
+        uv run twine check dist/*
+    
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/mcp-lightcast
+    
+    steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        attestations: true
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch'
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/mcp-lightcast
+    
+    steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+    
+    - name: Publish to TestPyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        attestations: true
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    
+    steps:
+    - uses: actions/checkout@v5
+    
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+    
+    - name: Extract version from tag
+      id: version
+      run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+    
+    - name: Generate release notes
+      id: release_notes
+      run: |
+        cat > release_notes.md << 'EOF'
+        ## MCP Lightcast v${{ steps.version.outputs.version }}
+        
+        ### 🚀 Features
+        - Complete Skills API integration with 6/10 endpoints working
+        - Complete Titles API integration with 5/8 endpoints working  
+        - Skills extraction from text with high accuracy
+        - Bulk operations for efficient data retrieval
+        - Modern OAuth2 authentication with Lightcast APIs
+        - FastMCP-based server with streamable-HTTP transport
+        - uv package management with lock files
+        - Docker deployment support
+        - Comprehensive CLI interface
+        
+        ### 📊 API Coverage
+        - **Skills API**: search, individual retrieval, bulk operations, text extraction, metadata
+        - **Titles API**: search, individual retrieval, bulk operations, metadata
+        - **Version Support**: Uses "latest" keyword with backward compatibility
+        - **Authentication**: OAuth2 with emsi_open scope
+        
+        ### 🛠️ Installation
+        ```bash
+        # Using uv (recommended)
+        uvx --from mcp-lightcast mcp-lightcast
+        
+        # Using pip
+        pip install mcp-lightcast
+        
+        # Using Docker
+        docker run -e LIGHTCAST_CLIENT_ID=your_id -e LIGHTCAST_CLIENT_SECRET=your_secret ghcr.io/your-username/mcp-lightcast
+        ```
+        
+        ### 📚 Documentation
+        See the [README](https://github.com/${{ github.repository }}/blob/main/README.md) for complete setup and usage instructions.
+        
+        ### 🔗 Links
+        - [PyPI Package](https://pypi.org/project/mcp-lightcast/)
+        - [Docker Image](https://github.com/${{ github.repository }}/pkgs/container/mcp-lightcast)
+        - [Testing Summary](https://github.com/${{ github.repository }}/blob/main/TESTING_SUMMARY.md)
+        EOF
+    
+    - name: Create Release
+      uses: softprops/action-gh-release@v2
+      with:
+        name: "MCP Lightcast v${{ steps.version.outputs.version }}"
+        body_path: release_notes.md
+        files: |
+          dist/*.tar.gz
+          dist/*.whl
+        draft: false
+        prerelease: false
+        generate_release_notes: true