add e2e workflow

.github/workflows/e2e-tests.yml

@@ -0,0 +1,139 @@
+name: E2E Tests with Claude
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      test_scope:
+        description: 'Scope of tests to run'
+        required: false
+        default: 'all'
+        type: choice
+        options:
+          - all
+          - projects
+          - tcases
+          - folders
+          - tags
+          - requirements
+          - custom-fields
+          - shared-steps
+          - shared-preconditions
+
+jobs:
+  e2e-test:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read
+    env:
+      TEST_SCOPE: ${{ github.event.inputs.test_scope || 'all' }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build MCP server
+        run: npm run build
+
+      - name: Create MCP Config
+        env:
+          QASPHERE_TENANT_URL: ${{ secrets.QASPHERE_TENANT_URL }}
+          QASPHERE_API_KEY: ${{ secrets.QASPHERE_API_KEY }}
+        run: |
+          cat > /tmp/mcp-config.json << EOF
+          {
+            "mcpServers": {
+              "qasphere": {
+                "command": "node",
+                "args": ["${{ github.workspace }}/dist/index.js"],
+                "env": {
+                  "QASPHERE_TENANT_URL": "${QASPHERE_TENANT_URL}",
+                  "QASPHERE_API_KEY": "${QASPHERE_API_KEY}"
+                }
+              }
+            }
+          }
+          EOF
+
+      - name: Run Claude E2E Tests
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          claude_args: --mcp-config /tmp/mcp-config.json
+          prompt: |
+            # QA Sphere MCP E2E Test Run
+
+            You are running E2E tests for the QA Sphere MCP server. The MCP server is already built and configured.
+            You have access to the `qasphere` MCP server with tools like `mcp__qasphere__list_projects`, `mcp__qasphere__get_project`, etc.
+
+            ## Test Scope: ${{ env.TEST_SCOPE }}
+
+            ## Instructions
+
+            1. Use the QA Sphere MCP tools to verify they work correctly
+            2. For each tool, make a real API call and verify the response
+            3. Report results in a structured format
+
+            ## Test Cases to Execute
+
+            ### Projects Tests
+            - [ ] `list_projects` - List all projects and verify response structure
+            - [ ] `get_project` - Get a specific project (use project code from list)
+
+            ### Test Cases Tests (if scope includes tcases or all)
+            - [ ] `list_test_cases` - List test cases from a project
+            - [ ] `get_test_case` - Get a specific test case by marker
+            - [ ] `create_test_case` - Create a new test case (use E2E folder)
+            - [ ] `update_test_case` - Update the created test case
+
+            ### Folders Tests (if scope includes folders or all)
+            - [ ] `list_folders` - List folders in a project
+            - [ ] `upsert_folders` - Create/update a test folder named "MCP-E2E-Tests"
+
+            ### Tags Tests (if scope includes tags or all)
+            - [ ] `list_test_cases_tags` - List all tags in a project
+
+            ### Requirements Tests (if scope includes requirements or all)
+            - [ ] `list_requirements` - List requirements in a project
+
+            ### Custom Fields Tests (if scope includes custom-fields or all)
+            - [ ] `list_custom_fields` - List custom fields in a project
+
+            ### Shared Steps Tests (if scope includes shared-steps or all)
+            - [ ] `list_shared_steps` - List shared steps in a project
+
+            ### Shared Preconditions Tests (if scope includes shared-preconditions or all)
+            - [ ] `list_shared_preconditions` - List shared preconditions in a project
+
+            ## Expected Output Format
+
+            For each test, report:
+            ```
+            PASS: tool_name - Brief description of what was verified
+            FAIL: tool_name - Error message or unexpected behavior
+            SKIP: tool_name - Reason for skipping
+            ```
+
+            ## Important Notes
+            - First call list_projects to discover available projects
+            - Use the first available project for testing
+            - Create test artifacts in a folder named "MCP-E2E-Tests"
+            - Clean up any test cases you create (but keep the folder for future runs)
+            - If a test fails, continue with remaining tests
+            - Provide a final summary with pass/fail counts
+
+            Please execute the tests now and provide a summary report.

.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "qasphere": {
+      "command": "node",
+      "args": ["dist/index.js"],
+      "env": {
+        "QASPHERE_TENANT_URL": "${QASPHERE_TENANT_URL}",
+        "QASPHERE_API_KEY": "${QASPHERE_API_KEY}"
+      }
+    }
+  }
+}

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -0,0 +1,123 @@
+# QA Sphere MCP Server - Development Guide
+
+## Project Overview
+
+MCP (Model Context Protocol) server enabling LLMs to interact with QA Sphere test management system. Built with TypeScript, uses stdio transport.
+
+## Architecture
+
+```
+src/
+├── index.ts              # Entry point - creates MCP server
+├── config.ts             # Environment config (QASPHERE_TENANT_URL, QASPHERE_API_KEY)
+├── types.ts              # TypeScript interfaces for API responses
+├── schemas.ts            # Zod schemas for input validation
+├── utils.ts              # JSON utilities
+├── LoggingTransport.ts   # Debug logging (MCP_LOG_TO_FILE)
+└── tools/                # MCP tool handlers (one file per domain)
+    ├── index.ts          # Registers all tools
+    ├── projects.ts       # list_projects, get_project
+    ├── tcases.ts         # list_test_cases, get_test_case, create_test_case, update_test_case
+    ├── folders.ts        # list_folders, upsert_folders
+    ├── tags.ts           # list_test_cases_tags
+    ├── requirements.ts   # list_requirements
+    ├── customFields.ts   # list_custom_fields
+    ├── shared-steps.ts   # list_shared_steps
+    └── shared-preconditions.ts  # list_shared_preconditions
+```
+
+## Commands
+
+```bash
+npm run dev              # Run with tsx (development)
+npm run build            # Compile TypeScript
+npm run typecheck        # Type check without emit
+npm run lint             # Biome lint (auto-fix)
+npm run format           # Biome format
+npm run inspector        # MCP Inspector for debugging
+npm test                 # Unit tests
+npm run test:integration # Integration tests (requires env vars)
+```
+
+## Adding a New Tool
+
+1. Create `src/tools/{domain}.ts`:
+```typescript
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp'
+import axios from 'axios'
+import { QASPHERE_API_KEY, QASPHERE_TENANT_URL } from '../config.js'
+import { projectCodeSchema } from '../schemas.js'
+
+export const registerTools = (server: McpServer) => {
+  server.tool(
+    'tool_name',                    // Tool identifier
+    'Description for the LLM',      // Description
+    { projectCode: projectCodeSchema },  // Input schema (Zod)
+    async ({ projectCode }) => {
+      const response = await axios.get(
+        `${QASPHERE_TENANT_URL}/api/public/v0/...`,
+        { headers: { Authorization: `ApiKey ${QASPHERE_API_KEY}` } }
+      )
+      return { content: [{ type: 'text', text: JSON.stringify(response.data) }] }
+    }
+  )
+}
+```
+
+2. Register in `src/tools/index.ts`:
+```typescript
+import { registerTools as registerNewTools } from './new-domain.js'
+// Add to registerTools function
+registerNewTools(server)
+```
+
+3. Add types to `src/types.ts`, schemas to `src/schemas.ts`
+
+4. Create tests in `src/tests/unit/tools/{domain}.test.ts`
+
+## Testing
+
+### Unit Tests
+- Mock axios, test tool registration and handlers
+- Location: `src/tests/unit/`
+- Fixtures: `src/tests/fixtures/`
+
+### Integration Tests
+- Real API calls against test tenant
+- Requires `.env` with `QASPHERE_TENANT_URL`, `QASPHERE_API_KEY`, `QASPHERE_AUTH_EMAIL`, `QASPHERE_AUTH_PASSWORD`
+- Location: `src/tests/integration/`
+- Uses shared session token, rate limit handling
+
+### E2E Tests
+- GitHub Action triggers Claude to exercise all MCP tools
+- Runs on PRs and main merges
+- Manual trigger via Actions tab
+
+## Code Style
+
+- Biome for linting/formatting (pre-commit hook)
+- ES modules (`.js` extension in imports)
+- Explicit error handling for axios errors
+- Return MCP content format: `{ content: [{ type: 'text', text: string }] }`
+
+## API Authentication
+
+All QA Sphere API calls use:
+```
+Authorization: ApiKey {QASPHERE_API_KEY}
+Content-Type: application/json
+```
+
+Base URL pattern: `{QASPHERE_TENANT_URL}/api/public/v0/...`
+
+## Debugging
+
+Enable MCP message logging:
+```bash
+MCP_LOG_TO_FILE=/tmp/mcp.log npm run dev
+```
+
+Use MCP Inspector:
+```bash
+npm run inspector
+```