feat: Add CHANGELOG, LICENSE and improve release workflow

shtse8 · shtse8 · commit 3412a07ea0b4 · 2025-04-05T20:07:57.000+01:00
Added standard CHANGELOG.md and MIT LICENSE files. Updated GitHub Actions workflow to trigger on main/tags, conditionally publish artifacts and jobs, and create GitHub releases using the changelog.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -1,15 +1,19 @@
-name: Build and Publish
+name: CI, Publish & Release
 
 on:
   push:
+    branches:
+      - main # Trigger on push to main branch
     tags:
-      - 'v*.*.*' # Trigger on version tags like v0.1.0, v1.2.3
+      - 'v*.*.*' # Trigger on push of version tags (e.g., v0.5.5)
 
 jobs:
   build:
     runs-on: ubuntu-latest
     outputs:
-      package_version: ${{ steps.get_version.outputs.version }} # Output version for other jobs
+      version: ${{ steps.get_version.outputs.version }}
+      artifact_name: build-artifacts-archive # Consistent name for upload/download
+      archive_filename: ${{ steps.archive_build.outputs.archive_name }} # Actual .tar.gz filename
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
@@ -27,58 +31,70 @@ jobs:
 
       - name: Get package version
         id: get_version
-        run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
-
-      - name: Upload build artifacts
+        # Use tag name if available, otherwise use package.json version
+        run: |
+          VERSION=""
+          if [[ "${{ github.ref_type }}" == "tag" && "${{ github.ref }}" == refs/tags/v* ]]; then
+            VERSION=$(echo "${{ github.ref }}" | sed 's#refs/tags/##')
+          else
+            # Fallback for main branch pushes or if tag logic fails
+            VERSION=$(node -p "require('./package.json').version")-SNAPSHOT
+          fi
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      # --- Conditional Artifact Archiving and Upload ---
+      - name: Archive build artifacts (only on tag push)
+        if: startsWith(github.ref, 'refs/tags/v') # Condition: Only run for tags
+        id: archive_build
+        run: |
+          tar -czf build-artifacts.tar.gz build package.json package-lock.json README.md CHANGELOG.md LICENSE Dockerfile .dockerignore
+          echo "archive_name=build-artifacts.tar.gz" >> $GITHUB_OUTPUT
+
+      - name: Upload build artifacts (only on tag push)
+        if: startsWith(github.ref, 'refs/tags/v') # Condition: Only run for tags
         uses: actions/upload-artifact@v4
         with:
-          name: build-artifacts
-          path: |
-            build/
-            package.json
-            package-lock.json
-            README.md
-            Dockerfile # Include Dockerfile if needed for docker build context
-            # Add any other files needed by publish jobs
+          name: ${{ job.outputs.artifact_name }} # Use consistent name from job outputs
+          path: ${{ steps.archive_build.outputs.archive_name }}
 
   publish-npm:
-    needs: build # Depends on the build job
+    needs: build
     runs-on: ubuntu-latest
-    # Removed if condition, now triggered by tag push
+    if: startsWith(github.ref, 'refs/tags/v') # Condition: Only run for tags
     steps:
-      - name: Set up Node.js
+      - name: Download build artifacts archive
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ needs.build.outputs.artifact_name }} # Use consistent artifact name
+          path: .
+
+      - name: Extract build artifacts
+        run: tar -xzf ${{ needs.build.outputs.archive_filename }} # Use the correct archive filename from build job
+
+      - name: Set up Node.js for npm publish
         uses: actions/setup-node@v4
         with:
           node-version: '20'
           registry-url: 'https://registry.npmjs.org/'
 
-      - name: Download build artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: build-artifacts
-          path: . # Download to current directory
-
-      # Optional: Verify downloaded files if needed
-      # - run: ls -la
-
       - name: Publish to npm
         run: npm publish --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
   publish-docker:
-    needs: build # Depends on the build job
+    needs: build
     runs-on: ubuntu-latest
-    # Removed if condition, now triggered by tag push
+    if: startsWith(github.ref, 'refs/tags/v') # Condition: Only run for tags
     steps:
-      - name: Checkout repository (needed for git sha tag)
-        uses: actions/checkout@v4
-
-      - name: Download build artifacts
+      - name: Download build artifacts archive
         uses: actions/download-artifact@v4
         with:
-          name: build-artifacts
-          path: . # Download to current directory, overwriting local files if necessary
+          name: ${{ needs.build.outputs.artifact_name }} # Use consistent artifact name
+          path: .
+
+      - name: Extract build artifacts
+        run: tar -xzf ${{ needs.build.outputs.archive_filename }} # Use the correct archive filename from build job
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@v3
@@ -96,21 +112,46 @@ jobs:
         id: meta
         uses: docker/metadata-action@v5
         with:
-          images: shtse8/pdf-reader-mcp # *** UPDATED IMAGE NAME ***
+          images: shtse8/pdf-reader-mcp # Ensure this is the correct image name
+          # Use version from the build job output (which is derived from the tag)
           tags: |
-            type=schedule
-            type=ref,event=branch
-            type=ref,event=pr
-            type=semver,pattern={{version}},value=${{ needs.build.outputs.package_version }} # Use version from build job
-            type=semver,pattern={{major}}.{{minor}},value=${{ needs.build.outputs.package_version }}
-            type=sha # Add git sha tag
+            type=semver,pattern={{version}},value=${{ needs.build.outputs.version }}
+            type=semver,pattern={{major}}.{{minor}},value=${{ needs.build.outputs.version }}
+            type=sha,prefix=,suffix=,event=tag
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v') }} # Add latest tag for main and version tags
 
       - name: Build and push Docker image
         uses: docker/build-push-action@v6
         with:
-          context: . # Context now includes downloaded artifacts + checked out repo files
-          push: true # Already checked condition in 'if'
+          context: . # Context is the directory with extracted artifacts
+          push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
-          cache-to: type=gha,mode=max
+          cache-to: type=gha,mode=max
+
+  create-release:
+    needs: [build, publish-npm, publish-docker] # Depend on build and both publish jobs
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v') # Condition: Only run for tags
+    permissions:
+      contents: write # Need permission to create releases
+    steps:
+      - name: Download build artifacts archive
+        uses: actions/download-artifact@v4
+        with:
+          name: ${{ needs.build.outputs.artifact_name }} # Use consistent artifact name
+          path: .
+
+      - name: Extract build artifacts
+        run: tar -xzf ${{ needs.build.outputs.archive_filename }} # Use the correct archive filename from build job
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Release ${{ github.ref_name }}
+          body_path: CHANGELOG.md # Assumes CHANGELOG.md is in the artifact root
+          # files: ${{ needs.build.outputs.archive_filename }} # Optional: Attach the full archive to the release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project setup based on filesystem-mcp.
+- Core `read_pdf` tool using `pdfjs-dist` library.
+- Support for reading text, metadata, and page count.
+- Support for local file paths and URLs.
+- Support for processing multiple sources in one call with per-source page selection.
+- Basic README and Memory Bank documentation.
+- Dockerfile and .dockerignore.
+- GitHub Actions workflow for publishing (initial version).
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [Your Name or Organization]
+
+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.
diff --git a/memory-bank/activeContext.md b/memory-bank/activeContext.md
@@ -1,3 +1,5 @@
+<!-- Version: 1.0 | Last Updated: 2025-04-05 | Updated By: Cline -->
+
 # Active Context: PDF Reader MCP Server (Initial Setup)
 
 ## 1. Current Focus
@@ -23,15 +25,18 @@ implementing the core PDF reading tools based on the `filesystem-mcp` template.
   parameter into each source object, allowing different page selections for
   different files in the same request. Updated `README.md` and Memory Bank files
   again.
+- Created `CHANGELOG.md` with initial structure.
+- Created `LICENSE` file (MIT License).
+- Updated `.github/workflows/publish.yml` to include main branch trigger, conditional artifact creation/upload, conditional job execution based on tags, and a `create-release` job using `CHANGELOG.md`.
 
 ## 3. Next Steps
 
-- Update `memory-bank/progress.md` to reflect tool consolidation.
-- Build the project (`npm run build`) again after adding multi-source support.
+- Update `memory-bank/progress.md` to reflect recent changes (Changelog, License, Workflow).
+- Build the project (`npm run build`).
+- Test the updated GitHub Actions workflow by pushing a tag (e.g., `v0.3.0`).
 - Consider adding basic tests for the PDF handlers.
-- Commit the initial implementation to the Git repository.
-- Potentially test the server using `@modelcontextprotocol/inspector` or by
-  integrating with Cline.
+- Commit changes to the Git repository.
+- Potentially test the server using `@modelcontextprotocol/inspector` or by integrating with Cline.
 
 ## 4. Active Decisions & Considerations
 
diff --git a/memory-bank/progress.md b/memory-bank/progress.md
@@ -1,3 +1,5 @@
+<!-- Version: 1.0 | Last Updated: 2025-04-05 | Updated By: Cline -->
+
 # Progress: PDF Reader MCP Server (Initial Implementation)
 
 ## 1. What Works
@@ -14,32 +16,24 @@
 - **Documentation:**
   - `README.md`: Updated with PDF tool descriptions.
   - Memory Bank: Core files created/updated with initial context.
+- **Changelog:** `CHANGELOG.md` created with initial structure.
+- **License:** `LICENSE` file created (MIT).
+- **GitHub Actions:** `.github/workflows/publish.yml` updated to trigger on main/tags, conditionally publish, and create releases using `CHANGELOG.md`.
 
 ## 2. What's Left to Build/Verify
 
-- **Compilation:** Need to run `npm run build` again after moving `pages`
-  parameter.
+- **Compilation:** Need to run `npm run build`.
 - **Runtime Testing:**
   - Verify the server starts correctly.
-  - Test the consolidated `read_pdf` tool with various parameter combinations,
-    multiple sources, and per-source `pages` specifications via
-    `@modelcontextprotocol/inspector` or a live agent. Verify the `results`
-    array structure and error handling per source.
-  - Specifically test `read_pdf` with the `pages` parameter for different page
-    ranges and edge cases across multiple sources.
-  - Verify error handling (e.g., file not found, URL fetch errors, corrupted
-    PDF).
-- **Testing Framework:** Consider adding automated tests (e.g., using Jest or
-  Vitest) for handlers.
+  - Test the consolidated `read_pdf` tool via `@modelcontextprotocol/inspector` or a live agent.
+  - Verify error handling (e.g., file not found, URL fetch errors, corrupted PDF).
+- **Testing Framework:** Consider adding automated tests (e.g., using Jest or Vitest) for handlers.
 - **Refinement:** Review code for potential improvements or edge cases missed.
-- **Publishing Setup:** Ensure GitHub Actions workflow in
-  `.github/workflows/publish.yml` is correctly configured for the new package
-  name and Docker image name (if not already done).
+- **Publishing Workflow Test:** Test the updated GitHub Actions workflow by pushing a version tag (e.g., `v0.3.0`) and verifying npm/Docker publish and GitHub Release creation.
 
 ## 3. Current Status
 
-Moved `pages` parameter to be per-source in `read_pdf` handler. Documentation
-updated. Ready for final build and testing.
+Added `CHANGELOG.md`, `LICENSE`. Updated GitHub Actions workflow for improved release process. Ready for build and testing, including workflow verification.
 
 ## 4. Known Issues/Risks
 
