chore: add release workflow and changelog management

.github/workflows/README.md

@@ -4,6 +4,41 @@ This directory contains automated CI/CD workflows for the Currents MCP Server pr
 
 ## Available Workflows
 
+### `release.yaml` - Create Release
+
+Creates a new release with changelog, git tag, and GitHub release.
+
+**Triggers:**
+
+- Manual dispatch only (workflow_dispatch)
+
+**Inputs:**
+
+- `dry_run` (boolean, default: false): Preview the release without making changes
+
+**What it does:**
+
+1. Checks out the code with full git history
+2. Sets up Node.js 24.x
+3. Installs dependencies
+4. Runs the test suite
+5. Analyzes commits since last tag to determine version bump:
+   - `feat:` commits → minor version bump (e.g., 2.1.3 → 2.2.0)
+   - `fix:` commits → patch version bump (e.g., 2.1.3 → 2.1.4)
+   - `BREAKING CHANGE:` → major version bump (e.g., 2.1.3 → 3.0.0)
+6. Updates CHANGELOG.md with new entries
+7. Creates a git commit and tag
+8. Creates a GitHub release with auto-generated notes
+
+**Usage:**
+
+1. Go to Actions → "Create Release"
+2. Click "Run workflow"
+3. Optionally enable "Dry run" to preview changes
+4. After release completes, trigger "Publish NPM Package" workflow to publish to npm
+
+---
+
 ### `test.yml` - Unit Tests
 
 Runs the unit test suite on every push and pull request.
@@ -22,12 +57,6 @@ Runs the unit test suite on every push and pull request.
 5. Generates code coverage reports
 6. Optionally uploads coverage to Codecov (requires `CODECOV_TOKEN` secret)
 
-**Matrix Strategy:**
-The workflow runs tests on multiple Node.js versions to ensure compatibility:
-
-- Node.js 20.x (LTS)
-- Node.js 22.x (Latest)
-
 **Coverage Reports:**
 Coverage reports are generated for all Node versions, but only uploaded from Node 20.x to avoid duplicate reports. Coverage files are located in `mcp-server/coverage/`.
 

.github/workflows/release.yaml

@@ -0,0 +1,41 @@
+name: Create Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Dry run (no actual release)"
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./mcp-server
+
+    permissions:
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24.x"
+          registry-url: "https://registry.npmjs.org"
+
+      - run: npm ci
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Release
+        run: npx release-it --ci ${{ inputs.dry_run && '--dry-run' || '' }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mcp-server/.release-it.json

@@ -0,0 +1,26 @@
+{
+  "git": {
+    "commitMessage": "chore: release v${version}",
+    "tagName": "v${version}",
+    "requireCleanWorkingDir": true,
+    "requireBranch": "main"
+  },
+  "github": {
+    "release": true,
+    "releaseName": "v${version}",
+    "autoGenerate": true
+  },
+  "npm": {
+    "publish": false
+  },
+  "plugins": {
+    "@release-it/conventional-changelog": {
+      "preset": "angular",
+      "infile": "CHANGELOG.md",
+      "header": "# Changelog"
+    }
+  },
+  "hooks": {
+    "before:init": ["npm run test:run"]
+  }
+}

mcp-server/CHANGELOG.md

@@ -0,0 +1,6 @@
+# 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).

mcp-server/README.md

@@ -0,0 +1,186 @@
+# Currents MCP Server
+
+![Unit Tests](https://github.com/currents-dev/currents-mcp/actions/workflows/test.yml/badge.svg)
+
+This is a MCP server that allows you to provide test results context to your AI agents by connecting them to Currents. Useful for asking AI to fix or optimize tests failing in CI.
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=currents&config=eyJjb21tYW5kIjoibnB4IC15IEBjdXJyZW50cy9tY3AiLCJlbnYiOnsiQ1VSUkVOVFNfQVBJX0tFWSI6InlvdXItYXBpLWtleSJ9fQ%3D%3D)
+
+## Tools
+
+| Tool                                  | Description                                                                |
+| ------------------------------------- | -------------------------------------------------------------------------- |
+| `currents-get-projects`               | Retrieves a list of all projects available.                                |
+| `currents-get-runs`                   | Retrieves a list the latest runs for a specific project.                   |
+| `currents-get-run-details`            | Retrieves details of a specific test run.                                  |
+| `currents-get-spec-instances`         | Retrieves debugging data a specific execution of a test spec file.         |
+| `currents-get-spec-files-performance` | Retrieves spec file historical performance metrics for a specific project. |
+| `currents-get-tests-performance`      | Retrieves test historical performance metrics for a specific project.      |
+| `currents-get-tests-signatures`       | Retrieves a test signature by its spec file name and test name.            |
+| `currents-get-test-results`           | Retrieves debugging data from test results of a test by its signature.     |
+| `currents-list-webhooks`              | List all webhooks configured for a project.                                |
+| `currents-create-webhook`             | Create a new webhook to receive notifications on run events.               |
+| `currents-get-webhook`                | Get details of a specific webhook by ID.                                   |
+| `currents-update-webhook`             | Update an existing webhook's URL, headers, events, or label.               |
+| `currents-delete-webhook`             | Delete a webhook.                                                          |
+
+## Setup
+
+### API Key
+
+Get a Currents API key by following the [instructions here](https://docs.currents.dev/resources/api/api-keys).
+
+### Usage with Cursor Editor
+
+1. Go to Cursor Settings > MCP > Enable
+2. Add the following to your `mcp.json`.
+
+### NPX
+
+```
+{
+  "mcpServers": {
+    "currents": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@currents/mcp"
+      ],
+      "env": {
+        "CURRENTS_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Usage with Claude Desktop
+
+Add the following to your `claude_desktop_config.json`:
+
+#### NPX
+
+```
+{
+  "mcpServers": {
+    "currents": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@currents/mcp"
+      ],
+      "env": {
+        "CURRENTS_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### ⚠️ Notice
+
+By connecting AI tools (e.g., via MCP) to Currents, you are granting them access to your API key, test results and CI metadata. It is your responsibility to vet any AI agents or services you use, and to ensure they handle your data securely.
+
+## How to Contribute
+
+We welcome contributions of all kinds—bug fixes, features, and documentation updates!
+
+### Quick Start
+
+1. Fork this repository and clone your fork:
+   ```bash
+   git clone https://github.com/<your-username>/currents-mcp.git
+   cd currents-mcp
+   ```
+2. Install dependencies:
+   ```bash
+   cd mcp-server
+   npm install
+   ```
+3. Build the project:
+   ```bash
+   npm run build
+   ```
+4. Run tests:
+   ```bash
+   npm test
+   ```
+   See [TESTING.md](./mcp-server/TESTING.md) for more details on testing.
+5. Run locally (stdio):
+   ```bash
+   npm start
+   ```
+   You should see: `Currents MCP Server running on stdio`.
+
+### Local Development with a Client (optional)
+
+To test with a local MCP client (e.g., Cursor or Claude Desktop), point the client to your built server:
+
+- Command: `node`
+- Args: `./mcp-server/build/index.js`
+- Env: set `CURRENTS_API_KEY` to a valid key
+
+Example snippet for a client config:
+
+```json
+{
+  "mcpServers": {
+    "currents": {
+      "command": "node",
+      "args": ["./mcp-server/build/index.js"],
+      "env": {
+        "CURRENTS_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Test tools locally
+
+To test the tools locally without any LLM, you can use the following command:
+
+```bash
+ npm run build
+```
+
+then run the tools script:
+
+```bash
+ node scripts/call-tools.js
+```
+
+### Making Changes
+
+- Create a feature branch:
+  ```bash
+  git checkout -b feat/short-description
+  ```
+- Make changes under `mcp-server/src/`, then rebuild and re-run:
+  ```bash
+  npm run build && npm start
+  ```
+- Write tests for your changes in `*.test.ts` files alongside your code
+- Run tests to ensure everything works:
+  ```bash
+  npm test
+  ```
+- Keep changes focused and documented (add comments/types where helpful).
+
+### Commit and PR Guidelines
+
+- Write clear commit messages (e.g., “fix: handle missing env vars” or “feat: add get-run tool filters”).
+- Push your branch and open a Pull Request:
+  ```bash
+  git push origin feat/short-description
+  ```
+- In your PR, describe the motivation, approach, and any trade-offs. Link related issues if applicable.
+
+### Reporting Issues
+
+- Before creating a new issue, please search existing issues to avoid duplicates.
+- When filing a bug report, include steps to reproduce, expected vs. actual behavior, and environment details (OS, Node.js version).
+
+### License
+
+By contributing, you agree that your contributions will be licensed under the ISC license (as specified in the package metadata).