@alternative-path/qa-path-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Alternative Path
+
+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.
+
+

package/QUICK_INSTALL.md

@@ -0,0 +1,133 @@
+# Quick Install Guide for QA-Path MCP
+
+Quick reference to install and configure the QA-Path MCP server in Cursor, VS Code, Claude, or any MCP client.
+
+## Prerequisites
+
+- **Node.js** 18.0.0 or higher
+- Access to a QA-Path instance and an API key (from your profile / API tokens)
+
+## Step 1: Install the Package
+
+Choose one method:
+
+### Method A: Using npx (Recommended — no install)
+
+Use `npx` in your MCP config; the package is downloaded and run on demand.
+
+### Method B: Global install
+
+```bash
+npm install -g @alternative-path/qa-path-mcp
+```
+
+### Method C: Local install
+
+```bash
+npm install @alternative-path/qa-path-mcp
+```
+
+## Step 2: Get Your Credentials
+
+You need:
+
+1. **API URL** — Your QA-Path API base URL (typically the auth/base API path).
+   - Example: `https://api.qa-path.com/api/auth`
+   - The client uses this as the API root (paths like `/auth/login` are appended as needed).
+
+2. **Project ID (Optional)** — UUID of your project (from project settings in the web app).
+   - Example: `977dfeb2-e572-44da-8fe6-5c88f61609e4`
+
+3. **Authentication**:
+   - **API key (required)** — `QA_PATH_API_KEY` from your QA-Path profile (API tokens). The server logs in with this on startup.
+
+## Step 3: Configure in Cursor
+
+### Where Cursor stores MCP config
+
+- **Global (all projects)**
+  - Windows: `%USERPROFILE%\.cursor\mcp.json`
+  - Mac/Linux: `~/.cursor/mcp.json`
+- **This project only**
+  - `.cursor/mcp.json` in the project root (can be committed for the team)
+
+You can also add or edit MCP servers in **Cursor Settings → MCP**.
+
+### Add the QA-Path server
+
+Open the chosen `mcp.json` and add (or merge) the `mcpServers` entry:
+
+**Required env (API key):**
+
+```json
+{
+  "mcpServers": {
+    "qa-path": {
+      "command": "npx",
+      "args": ["-y", "@alternative-path/qa-path-mcp"],
+      "env": {
+        "QA_PATH_API_URL": "https://api.qa-path.com/api/auth",
+        "QA_PATH_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+**If you installed globally (Method B), use the binary:**
+
+```json
+"qa-path": {
+  "command": "qa-path-mcp",
+  "env": { ... }
+}
+```
+
+**If you installed locally (Method C), use node and the path:**
+
+```json
+"qa-path": {
+  "command": "node",
+  "args": ["./node_modules/@alternative-path/qa-path-mcp/dist/index.js"],
+  "env": { ... }
+}
+```
+
+### Optional env vars
+
+- **`QA_PATH_PROJECT_ID`** — Default project (optional; you can set the active project at runtime via `set_active_project`).
+- WebSocket URL and origin for NLP script generation come from the organization service (`agentServiceUrl`). No separate env vars are used.
+
+## Step 4: Restart Cursor
+
+Close and reopen Cursor (or reload the window) so the new MCP server config is loaded.
+
+## Step 5: Test It
+
+In the Cursor chat, try:
+
+- *"List all projects using qa-path"*
+- *"List all modules in the current project"*
+- *"Check if I'm logged in to QA-Path"*
+
+The server logs in with your API key on startup. Use *"Check auth status"* or *"List projects"* to confirm.
+
+## Troubleshooting
+
+| Issue | What to do |
+|-------|------------|
+| **"Command not found" or "Cannot find module"** | Use the npx method (Method A); no install needed. |
+| **"Authentication failed"** | Ensure `QA_PATH_API_URL` is correct (e.g. `https://api.qa-path.com/api/auth`). Check `QA_PATH_API_KEY` is set and valid. |
+| **"Project ID is required"** | Set `QA_PATH_PROJECT_ID` in the server `env`, or pass `projectId` in the tool call when the tool supports it. |
+| **"Network error"** | Confirm `QA_PATH_API_URL` is correct and reachable; check firewall/VPN. |
+| **NLP script generation fails** | Ensure the organization service returns a valid `agentServiceUrl` for your project. |
+
+## More help
+
+- [README.md](./README.md) — full docs and auth options
+- [TOOLS_DOCUMENTATION.md](./TOOLS_DOCUMENTATION.md) — all tools and prompts
+- [SHIPPING_GUIDE.md](./SHIPPING_GUIDE.md) — for package maintainers
+
+---
+
+You're ready to use QA-Path MCP.

package/README.md

@@ -0,0 +1,226 @@
+# QA-Path MCP Server
+
+QA-Path is a Model Context Protocol (MCP) server that provides comprehensive test case management capabilities for the QA-Path Test Management System. It allows you to manage test cases, modules, components, and subcomponents directly from Cursor, VS Code, Claude, or any MCP-compatible client.
+
+**Quick links:** [Install from npm](QUICK_INSTALL.md) · [All tools](TOOLS_DOCUMENTATION.md)
+
+## Features
+
+- **qa-path-test-planner agent**: Standard, repeatable test planning via an MCP prompt that uses embedded context (no manual context file required)
+- **Module Management**: Create, update, delete, and list modules, components, and subcomponents
+- **Test Case Management**: Full CRUD operations for test cases
+- **Test Case Operations**: Clone, move, and bulk create test cases
+- **Export/Import**: Export test cases to Excel and import from Excel files
+- **Permission-Aware**: Respects the same permissions as the web application
+- **API key auth**: Authenticate with your QA-Path API key
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18.0.0 or higher
+- Access to a QA-Path Test Management System instance
+- An API key from your QA-Path profile (API tokens)
+
+### Quick Install (Recommended)
+
+**Option 1: Using npx (No installation required)**
+
+Simply use `npx` in your MCP configuration - it will download and run the package automatically:
+
+```json
+{
+  "mcpServers": {
+    "qa-path": {
+      "command": "npx",
+      "args": ["-y", "@alternative-path/qa-path-mcp"],
+      "env": {
+        "QA_PATH_API_URL": "https://qa-path.com/api/auth",
+        "QA_PATH_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+**Option 2: Global Installation**
+
+```bash
+npm install -g @alternative-path/qa-path-mcp
+```
+
+Then use in your MCP configuration:
+```json
+{
+  "mcpServers": {
+    "qa-path": {
+      "command": "qa-path-mcp",
+      "env": {
+        "QA_PATH_API_URL": "https://qa-path.com/api/auth",
+        "QA_PATH_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+**Option 3: Local Installation**
+
+```bash
+npm install @alternative-path/qa-path-mcp
+```
+
+Then use the full path:
+```json
+{
+  "mcpServers": {
+    "qa-path": {
+      "command": "node",
+      "args": ["./node_modules/@alternative-path/qa-path-mcp/dist/index.js"],
+      "env": {
+        "QA_PATH_API_URL": "https://your-domain.com/api/auth",
+        "QA_PATH_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+### Install from Source (Development)
+
+```bash
+git clone <repository-url>
+cd qapath-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+QA-Path requires configuration via environment variables (e.g. in your MCP config or shell).
+
+### Required Configuration
+
+```bash
+# API base URL — use your app URL + /api/auth (e.g. http://localhost:3000/api/auth)
+QA_PATH_API_URL=http://localhost:3000/api/auth
+
+# API key (required) — from your QA-Path profile / API tokens
+QA_PATH_API_KEY=your-api-key-here
+```
+
+### Optional Configuration
+
+```bash
+# Project can be set at runtime via set_active_project; optional default:
+# QA_PATH_PROJECT_ID=your-project-id-here
+```
+
+### Example `.env` file
+
+```bash
+# API Configuration
+QA_PATH_API_URL=http://localhost:3000/api/auth
+QA_PATH_API_KEY=your-api-key-here
+```
+
+## Usage with Cursor
+
+1. Open Cursor settings
+2. Navigate to MCP settings
+3. Add the following configuration:
+
+```json
+{
+  "mcpServers": {
+    "qa-path": {
+      "command": "npx",
+      "args": ["-y", "@alternative-path/qa-path-mcp"],
+      "env": {
+        "QA_PATH_API_URL": "http://localhost:3000/api/auth",
+        "QA_PATH_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Usage with VS Code
+
+1. Install the MCP extension for VS Code
+2. Configure the MCP server in your VS Code settings:
+
+```json
+{
+  "mcp.servers": {
+    "qa-path": {
+      "command": "npx",
+      "args": ["-y", "@alternative-path/qa-path-mcp"],
+      "env": {
+        "QA_PATH_API_URL": "http://localhost:3000/api/auth",
+        "QA_PATH_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Tools and Prompts
+
+For a complete list of all MCP tools and prompts, including parameters, sample prompts, and examples, see **[TOOLS_DOCUMENTATION.md](TOOLS_DOCUMENTATION.md)**.
+
+## Permissions
+
+QA-Path respects the same permission system as the web application. Users can only perform actions they have permission for. If you receive a 403 Forbidden error, check your user permissions in the web application.
+
+## Security
+
+- **Authentication** is token-based (API key). The MCP server has the same permissions as the credentials you provide; use scoped or least-privilege tokens where your backend supports them.
+- **Authorization and multi-tenant isolation** are enforced entirely on the server. This client does not perform access control; it only forwards authenticated requests.
+- **Do not commit secrets.** Never put `QA_PATH_API_KEY` or other credentials in version control, shared configs, or screenshots. Use environment variables or a local `.env` file that is listed in `.gitignore`.
+
+## Troubleshooting
+
+### Authentication Errors
+
+- **401 Unauthorized**: Check your `QA_PATH_API_KEY`
+- **403 Forbidden**: You don't have permission for this action. Check your user role and permissions.
+
+### Connection Errors
+
+- **Network error**: Verify that `QA_PATH_API_URL` is correct and the server is accessible
+- **Timeout**: The server might be slow. Try increasing the timeout in the API client.
+
+### Project ID Errors
+
+- Set an active project via the `set_active_project` tool (after `list_projects`), or pass `projectId` to individual tool calls
+- Optionally set `QA_PATH_PROJECT_ID` in the environment as a default
+
+## Development
+
+### Building from Source
+
+```bash
+npm install
+npm run build
+```
+
+### Running in Development Mode
+
+```bash
+npm run dev
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+## License
+
+MIT — Copyright (c) 2026 Alternative Path
+
+## Support
+
+For issues and questions, please contact the Alternative Path team or open an issue in the repository.