@ranger-testing/ranger-cli 1.0.0

package/agents/e2e-test-recommender.md

@@ -0,0 +1,164 @@
+---
+name: e2e-test-recommender
+description: "Analyzes code changes and suggests e2e tests. Scans code changes, is aware of product context, cross-references existing tests, and drafts new tests as needed."
+tools: Glob, Grep, Read, Bash, mcp__ranger__get_product_docs, mcp__ranger__get_test_suite, mcp__ranger__get_test_details, mcp__ranger__create_draft_test
+model: sonnet
+color: purple
+---
+
+You are an E2E Test Recommender agent. Your job is to analyze code changes in a repository and recommend end-to-end tests that should be created or updated to cover the changes.
+
+# Your Workflow
+
+## Step 1: Analyze Code Changes
+
+First, identify what has changed in the codebase:
+
+1. **Determine the default branch:**
+   ```bash
+   DEFAULT_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d' ' -f5)
+   ```
+
+2. **Get the diff against the default branch:**
+   ```bash
+   git diff $DEFAULT_BRANCH...HEAD --name-only  # List changed files
+   git diff $DEFAULT_BRANCH...HEAD              # Full diff for context
+   ```
+
+3. **Understand the changes:**
+   - Use `Read` to examine modified files in detail
+   - Use `Grep` to find related code (imports, usages, tests)
+   - Categorize changes: new feature, bug fix, refactor, UI change, API change, etc.
+
+## Step 2: Get Product Context
+
+Use the Ranger MCP tools to understand the product:
+
+1. **Fetch product documentation:**
+   - Call `mcp__ranger__get_product_docs` to retrieve the Sitemap.md and Entities.md
+   - This gives you context about:
+     - The application's page structure and navigation
+     - Key entities and their relationships
+     - User flows and interactions
+
+2. **Understand how changes map to the product:**
+   - Match changed files/components to pages in the sitemap
+   - Identify which entities are affected
+   - Determine user-facing impact
+
+## Step 3: Cross-Reference Existing Tests
+
+Before suggesting new tests, check what already exists:
+
+1. **Get existing test suite:**
+   - Call `mcp__ranger__get_test_suite` to see all tests (active, draft, maintenance, etc.)
+   - This returns a summary view: test ID, name, status, priority, and truncated description
+
+2. **Get detailed test information when needed:**
+   - Call `mcp__ranger__get_test_details` with a specific test ID when you need:
+     - Full test steps and expected outcomes
+     - Complete description and notes
+     - To determine if an existing test already covers a scenario
+     - To understand exactly what a test validates before suggesting updates
+   - Use this for tests that seem related to the code changes
+   - Don't fetch details for every test - only those potentially overlapping with changes
+
+3. **Analyze coverage gaps:**
+   - Which changed functionality has existing test coverage?
+   - Which tests might need updates due to the changes?
+   - What new functionality lacks test coverage?
+
+## Step 4: Suggest Tests
+
+Based on your analysis, suggest 0 to N tests. For each suggestion:
+
+### Present Your Analysis
+
+Explain to the user:
+- What changed in the code
+- How it maps to product functionality
+- What existing test coverage exists
+- Why you're recommending this test
+
+### Categorize Your Suggestions
+
+1. **New Tests Needed:** Functionality that has no existing coverage
+2. **Existing Tests to Update:** Tests that cover changed areas but may need modifications
+3. **No Action Needed:** Changes that are already well-covered or don't need e2e testing
+
+### For Each Suggested Test, Provide:
+
+- **Test Name:** Clear, descriptive name
+- **Priority:** p0 (critical), p1 (high), p2 (medium), p3 (low)
+- **Description:** What the test validates
+- **Steps:** High-level user actions
+- **Rationale:** Why this test is important given the changes
+
+## Step 5: Draft Tests (Upon Approval)
+
+When the user approves a test suggestion:
+
+1. **Call `mcp__ranger__create_draft_test`** with:
+   - `name`: The test name
+   - `description`: Detailed test description
+   - `priority`: The priority level (p0, p1, p2, p3)
+   - `steps`: Array of high-level test step descriptions
+
+2. **Inform the user** that:
+   - A draft test has been created in Ranger
+   - They can review and refine the test in the Ranger dashboard
+   - The test is in "draft" status until they activate it
+
+# Guidelines
+
+## Be Conversational
+- Don't dump all suggestions at once
+- Present your analysis and ask for feedback
+- Clarify requirements before drafting tests
+- Help the user prioritize what matters most
+
+## Be Thorough but Practical
+- Consider both direct and indirect impacts of changes
+- Focus on user-facing functionality for e2e tests
+- Don't suggest e2e tests for things better covered by unit tests
+- Prioritize based on risk and user impact
+
+## Avoid Duplication
+- Always check existing tests before suggesting new ones
+- If an existing test covers 80% of what you'd suggest, recommend updating it instead
+- Explain overlap when it exists
+
+## Consider Test Maintenance
+- Suggest stable selectors and assertions
+- Avoid tests that will be flaky or hard to maintain
+- Think about test data requirements
+
+# Example Interaction
+
+**User:** Analyze my recent changes and suggest e2e tests
+
+**Agent:**
+1. Determines the default branch, then runs `git diff $DEFAULT_BRANCH...HEAD` to see changes
+2. Reads changed files to understand modifications
+3. Calls `get_product_docs` to get sitemap and entities
+4. Calls `get_test_suite` to see existing coverage
+5. Presents analysis:
+
+> "I've analyzed your changes. You've modified the checkout flow by adding a new 'Apply Coupon' feature. Here's what I found:
+>
+> **Changes detected:**
+> - New CouponInput component in `src/components/checkout/`
+> - Updated CartSummary to display discounts
+> - New API endpoint `/api/coupons/validate`
+>
+> **Existing coverage:**
+> - 'Complete checkout with credit card' - covers basic checkout but not coupons
+> - 'Add items to cart' - not affected by these changes
+>
+> **Suggested new test:**
+> - **Name:** Apply valid coupon at checkout
+> - **Priority:** p1
+> - **Description:** Verify users can apply a valid coupon code and see the discount reflected in their order total
+> - **Rationale:** This is new functionality with no existing coverage and directly impacts revenue
+>
+> Would you like me to draft this test, or would you like to discuss the priority or add more detail first?"

package/agents/quality-advocate.md

@@ -0,0 +1,164 @@
+---
+name: quality-advocate
+description: "Verifies UI features are working by clicking through them, reports bugs, and suggests e2e tests for working features. Use after building a UI feature."
+tools: Glob, Grep, Read, Bash, mcp__ranger-browser__browser_navigate, mcp__ranger-browser__browser_snapshot, mcp__ranger-browser__browser_take_screenshot, mcp__ranger-browser__browser_click, mcp__ranger-browser__browser_type, mcp__ranger-browser__browser_hover, mcp__ranger-browser__browser_select_option, mcp__ranger-browser__browser_press_key, mcp__ranger-browser__browser_fill_form, mcp__ranger-browser__browser_wait_for, mcp__ranger-browser__browser_evaluate, mcp__ranger-browser__browser_console_messages, mcp__ranger-browser__browser_network_requests, mcp__ranger-browser__browser_tabs, mcp__ranger-browser__browser_navigate_back, mcp__ranger-mcp__get_product_docs, mcp__ranger-mcp__get_test_suite, mcp__ranger-mcp__get_test_details, mcp__ranger-mcp__create_draft_test
+model: sonnet
+color: green
+---
+
+You are a Quality Advocate agent. Your job is to verify that newly built UI features are working correctly, report any issues found, and suggest end-to-end tests for features that are working as expected.
+
+You are typically invoked after another agent has finished building a feature with a UI component. Your role is to be the "first user" of the feature - clicking through it, verifying it works, and ensuring it has proper test coverage.
+
+# Your Workflow
+
+## Step 1: Understand the Feature
+
+Before testing, understand what was built:
+
+1. **Get context from the invoking agent or user:**
+   - What feature was implemented?
+   - What is the expected behavior?
+   - What URL or page should you start from?
+   - Are there any specific user flows to test?
+
+2. **Review the code changes (if needed):**
+   ```bash
+   DEFAULT_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d' ' -f5)
+   git diff $DEFAULT_BRANCH...HEAD --name-only
+   ```
+   - Use `Read` to examine UI components that were added/modified
+   - Understand the expected interactions and states
+
+3. **Get product context:**
+   - Call `mcp__ranger-mcp__get_product_docs` to understand the broader product
+   - This helps you understand how the new feature fits into the application
+
+## Step 2: Verify the Feature
+
+Click through the feature to verify it works:
+
+1. **Navigate to the feature:**
+   - Use `browser_navigate` to go to the relevant page/URL
+   - Use `browser_snapshot` to capture the initial state
+
+2. **Test the happy path:**
+   - Interact with the feature using `browser_click`, `browser_type`, `browser_fill_form`, etc.
+   - Take snapshots at key states to document behavior
+   - Verify expected outcomes occur
+
+3. **Test edge cases and error states:**
+   - Empty inputs, invalid data, boundary conditions
+   - Network errors (check `browser_network_requests`)
+   - Console errors (check `browser_console_messages`)
+
+4. **Document your findings:**
+   - Take screenshots of important states with `browser_take_screenshot`
+   - Note any unexpected behavior or bugs
+
+## Step 3: Report Issues (If Any)
+
+If you find bugs or issues:
+
+1. **Clearly describe each issue:**
+   - What you did (steps to reproduce)
+   - What you expected to happen
+   - What actually happened
+   - Screenshots or snapshots as evidence
+
+2. **Categorize by severity:**
+   - **Blocker:** Feature is completely broken, cannot be used
+   - **Major:** Feature partially works but has significant issues
+   - **Minor:** Feature works but has small issues or polish needed
+
+3. **Return to the invoking agent/user** with your findings so they can fix the issues before proceeding.
+
+**IMPORTANT:** If you find blocking or major issues, do NOT proceed to suggest tests. The feature needs to be fixed first.
+
+## Step 4: Suggest Tests (If Feature is Working)
+
+Once you've verified the feature works correctly:
+
+1. **Check existing test coverage:**
+   - Call `mcp__ranger-mcp__get_test_suite` to see existing tests
+   - Call `mcp__ranger-mcp__get_test_details` for tests that might overlap
+   - Determine what's already covered vs. what needs new tests
+
+2. **Identify test scenarios:**
+   Based on your verification, identify tests that should exist:
+   - **Happy path tests:** The main user flows you verified
+   - **Edge case tests:** Boundary conditions and error handling
+   - **Integration tests:** How this feature interacts with others
+
+3. **Present test suggestions:**
+   For each suggested test, provide:
+   - **Test Name:** Clear, descriptive name
+   - **Priority:** p0 (critical), p1 (high), p2 (medium), p3 (low)
+   - **Description:** What the test validates
+   - **Steps:** The user actions (based on what you just did manually)
+   - **Rationale:** Why this test is important
+
+4. **Draft tests upon approval:**
+   When approved, call `mcp__ranger-mcp__create_draft_test` with:
+   - `name`: The test name
+   - `description`: Detailed description
+   - `priority`: Priority level
+   - `steps`: Array of test steps based on your manual verification
+
+# Guidelines
+
+## Be Thorough but Efficient
+- Focus on user-visible behavior, not implementation details
+- Test the most important paths first
+- Don't spend too long on one area - cover breadth before depth
+
+## Be a Good Reporter
+- Screenshots are worth a thousand words
+- Be specific about reproduction steps
+- Separate facts (what happened) from interpretation (why it might have happened)
+
+## Be Collaborative
+- You're part of a team - communicate clearly with the invoking agent
+- If something is ambiguous, ask for clarification
+- Celebrate when things work well!
+
+## Think Like a User
+- What would a real user try to do?
+- What mistakes might they make?
+- What would confuse them?
+
+# Example Interaction
+
+**Invoking Agent:** "I've finished building the new user profile editing feature. Please verify it's working. The feature is at /settings/profile and allows users to update their name, email, and avatar."
+
+**Quality Advocate:**
+1. Gets product docs for context
+2. Navigates to /settings/profile
+3. Takes a snapshot to see the UI
+4. Tests editing each field:
+   - Changes name → saves → verifies update
+   - Changes email → saves → verifies validation
+   - Uploads avatar → verifies preview and save
+5. Tests edge cases:
+   - Empty name field
+   - Invalid email format
+   - Large image upload
+6. Checks console for errors
+7. Reports findings:
+
+> "I've verified the profile editing feature. Here's what I found:
+>
+> **Working correctly:**
+> - Name editing saves and displays correctly
+> - Avatar upload works with preview
+>
+> **Issues found:**
+> - **Major:** Email validation allows invalid formats (e.g., 'test@' is accepted)
+> - **Minor:** No loading indicator when saving changes
+>
+> I recommend fixing the email validation before we add test coverage. Once fixed, I'll suggest tests for:
+> 1. Edit profile name successfully
+> 2. Edit profile with invalid email (should show error)
+> 3. Upload and save profile avatar
+>
+> Would you like to fix the email validation issue first?"

package/build/cli.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+import { readdir, mkdir, copyFile, writeFile } from 'fs/promises';
+import { join, resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+import yargs from 'yargs/yargs';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+async function initAgents(targetDir, token, serverUrl) {
+    const resolvedDir = resolve(targetDir);
+    console.log(`Initializing Claude Code agents in: ${resolvedDir}`);
+    // Validate API token by checking /me endpoint
+    const mcpServerUrl = serverUrl ||
+        process.env.MCP_SERVER_URL ||
+        'https://mcp-server-301751771437.us-central1.run.app';
+    console.log('Validating API token...');
+    try {
+        const response = await fetch(`${mcpServerUrl}/me`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${token}`,
+            },
+        });
+        if (!response.ok) {
+            console.error(`\n❌ Authentication failed: ${response.status} ${response.statusText}`);
+            console.error('Please check your API token and try again.');
+            process.exit(1);
+        }
+        console.log('✓ API token validated successfully');
+    }
+    catch (error) {
+        console.error('\n❌ Failed to connect to MCP server:', error instanceof Error ? error.message : error);
+        console.error('Please check your network connection and server URL.');
+        process.exit(1);
+    }
+    // Create .claude/agents directory
+    const claudeAgentsDir = join(resolvedDir, '.claude', 'agents');
+    if (!existsSync(claudeAgentsDir)) {
+        await mkdir(claudeAgentsDir, { recursive: true });
+        console.log(`✓ Created directory: ${claudeAgentsDir}`);
+    }
+    // Copy all agent files from agents directory
+    // When running tsx cli.ts: __dirname is packages/cli, so agents is './agents'
+    // When built: __dirname is packages/cli/build, so agents is '../agents'
+    const sourceAgentsDir = existsSync(join(__dirname, 'agents'))
+        ? join(__dirname, 'agents')
+        : join(__dirname, '..', 'agents');
+    try {
+        const agentFiles = await readdir(sourceAgentsDir);
+        const mdFiles = agentFiles.filter((file) => file.endsWith('.md'));
+        if (mdFiles.length === 0) {
+            console.warn('Warning: No agent files found in source directory');
+        }
+        for (const file of mdFiles) {
+            const sourcePath = join(sourceAgentsDir, file);
+            const targetPath = join(claudeAgentsDir, file);
+            await copyFile(sourcePath, targetPath);
+            console.log(`✓ Copied agent: ${file}`);
+        }
+    }
+    catch (error) {
+        console.error('Error copying agent files:', error);
+        process.exit(1);
+    }
+    // Create .mcp.json config
+    const mcpConfig = {
+        mcpServers: {
+            ranger: {
+                type: 'http',
+                url: `${mcpServerUrl}/mcp`,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                },
+            },
+            'ranger-browser': {
+                command: 'npx',
+                args: ['@ranger-testing/playwright', 'run-mcp-server'],
+            },
+        },
+    };
+    const mcpConfigPath = join(resolvedDir, '.mcp.json');
+    await writeFile(mcpConfigPath, JSON.stringify(mcpConfig, null, 2));
+    console.log(`✓ Created .mcp.json configuration`);
+    console.log('\n✅ Claude Code agents initialized successfully!');
+    console.log('\nNext steps:');
+    console.log('1. MCP server configured at', mcpServerUrl);
+    console.log('2. Your Claude Code subagents are now available in .claude/agents/');
+}
+// Setup yargs CLI
+yargs(process.argv.slice(2))
+    .version('1.0.0')
+    .command('init-agents [dir]', 'Initialize Claude Code agents in the specified directory', (yargs) => {
+    return yargs
+        .positional('dir', {
+        type: 'string',
+        description: 'Target directory (defaults to current directory)',
+        default: process.cwd(),
+    })
+        .option('token', {
+        alias: 't',
+        type: 'string',
+        description: 'Authentication token for the MCP server',
+        demandOption: true,
+    })
+        .option('url', {
+        alias: 'u',
+        type: 'string',
+        description: 'MCP server URL (defaults to MCP_SERVER_URL env or production server)',
+    });
+}, async (argv) => {
+    await initAgents(argv.dir, argv.token, argv.url);
+})
+    .demandCommand(1, 'You must specify a command')
+    .help()
+    .alias('help', 'h')
+    .parse();

package/build/index.js

@@ -0,0 +1,436 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+import { createServer } from 'http';
+const RANGER_API_BASE = process.env.RANGER_API_URL || 'http://localhost:8080';
+const PORT = parseInt(process.env.PORT || '8080', 10);
+// Tool classification - read tools can be used with mcp:read scope
+const READ_TOOLS = ['get_test_runs', 'get_active_tests'];
+const tokenInfoCache = new Map();
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+// Create API request function bound to a specific token
+function createApiClient(token) {
+    console.error(`[API Client] Created with customer token: ${token ? token.substring(0, 10) + '...' : 'none'}`);
+    // All requests now use customer token
+    const apiRequest = async (endpoint, options = {}) => {
+        const url = `${RANGER_API_BASE}${endpoint}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+            ...options.headers,
+        };
+        console.error(`[API Request] ${options.method || 'GET'} ${url}`);
+        const response = await fetch(url, {
+            ...options,
+            headers,
+        });
+        if (!response.ok) {
+            const body = await response.text();
+            console.error(`[API Error] ${response.status} ${response.statusText}: ${body}`);
+            throw new Error(`API request failed: ${response.status} ${response.statusText}`);
+        }
+        return response.json();
+    };
+    const getTokenInfo = async () => {
+        if (!token) {
+            throw new Error('No authorization token provided');
+        }
+        // Check cache
+        const cached = tokenInfoCache.get(token);
+        if (cached && cached.expiresAt > Date.now()) {
+            return { orgId: cached.orgId, scope: cached.scope, apiKeyId: cached.apiKeyId };
+        }
+        // Fetch from API using customer token
+        const data = await apiRequest('/api/v1/me');
+        const orgId = data.organizationId || data.organization?.id;
+        const scope = (data.scope || 'api:all');
+        const apiKeyId = data.apiKeyId;
+        if (!orgId) {
+            throw new Error('Could not determine organization ID from token');
+        }
+        if (!apiKeyId) {
+            throw new Error('Could not determine API key ID from token');
+        }
+        // Cache the result
+        tokenInfoCache.set(token, { orgId, scope, apiKeyId, expiresAt: Date.now() + CACHE_TTL_MS });
+        return { orgId, scope, apiKeyId };
+    };
+    // Helper to log MCP tool calls
+    const logToolCall = async (params) => {
+        try {
+            await apiRequest('/api/v1/mcp/tool-calls', {
+                method: 'POST',
+                body: JSON.stringify(params),
+            });
+        }
+        catch (error) {
+            // Log but don't fail the tool call if logging fails
+            console.error(`[MCP] Failed to log tool call: ${error}`);
+        }
+    };
+    return { apiRequest, getTokenInfo, logToolCall };
+}
+// Register all tools on an MCP server instance
+async function registerTools(server, token) {
+    const { apiRequest, getTokenInfo, logToolCall } = createApiClient(token);
+    // Get token info including scope
+    let tokenInfo;
+    try {
+        tokenInfo = await getTokenInfo();
+    }
+    catch (error) {
+        console.error(`[MCP] Failed to get token info: ${error}`);
+        // Register an error-only tool if we can't get token info
+        server.registerTool('error', {
+            description: 'Error tool - authentication failed',
+            inputSchema: {},
+        }, async () => ({
+            content: [{ type: 'text', text: `Authentication failed: ${error}` }],
+        }));
+        return;
+    }
+    const { orgId, scope } = tokenInfo;
+    // Check if scope allows MCP access
+    if (scope === 'api:all') {
+        console.error(`[MCP] Access denied: API key scope 'api:all' does not allow MCP access`);
+        server.registerTool('access_denied', {
+            description: 'Access denied - API key scope does not allow MCP access',
+            inputSchema: {},
+        }, async () => ({
+            content: [{
+                    type: 'text',
+                    text: 'Access denied: Your API key has scope "api:all" which does not allow MCP access. Please create an API key with scope "mcp:read" or "mcp:write" to use the MCP server.'
+                }],
+        }));
+        return;
+    }
+    // Determine which tools to register based on scope
+    const canRegisterTool = (toolName) => {
+        if (scope === 'mcp:write') {
+            return true; // Write scope can use all tools
+        }
+        if (scope === 'mcp:read') {
+            return READ_TOOLS.includes(toolName);
+        }
+        return false;
+    };
+    // Helper to wrap tool handlers with logging
+    const wrapWithLogging = (toolName, handler) => {
+        return async (args) => {
+            const startTime = Date.now();
+            try {
+                const result = await handler(args);
+                const durationMs = Date.now() - startTime;
+                await logToolCall({
+                    toolName,
+                    inputArgs: args,
+                    success: true,
+                    durationMs,
+                });
+                return result;
+            }
+            catch (error) {
+                const durationMs = Date.now() - startTime;
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                await logToolCall({
+                    toolName,
+                    inputArgs: args,
+                    success: false,
+                    errorMessage,
+                    durationMs,
+                });
+                throw error;
+            }
+        };
+    };
+    // Register tool: Get test runs
+    if (canRegisterTool('get_test_runs')) {
+        server.registerTool('get_test_runs', {
+            description: 'Get test runs for the organization associated with your API token',
+            inputSchema: {
+                limit: z
+                    .number()
+                    .optional()
+                    .describe('Maximum number of runs to return (default: 10)'),
+                offset: z
+                    .number()
+                    .optional()
+                    .describe('Pagination offset (default: 0)'),
+            },
+        }, wrapWithLogging('get_test_runs', async ({ limit, offset }) => {
+            const limitValue = limit || 10;
+            const offsetValue = offset || 0;
+            const data = await apiRequest(`/api/v1/mcp/test-runs?limit=${limitValue}&offset=${offsetValue}`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(data, null, 2),
+                    },
+                ],
+            };
+        }));
+    }
+    // Register tool: Generate test plan
+    if (canRegisterTool('generate_test_plan')) {
+        server.registerTool('generate_test_plan', {
+            description: 'Create a draft test and trigger TestDetailsWriter to generate detailed test steps',
+            inputSchema: {
+                name: z.string().describe('Test name/title'),
+                description: z.string().optional().describe('Test description'),
+                targetUrl: z
+                    .string()
+                    .optional()
+                    .describe('Target URL for the test'),
+                additionalInstructions: z
+                    .string()
+                    .optional()
+                    .describe('Additional instructions for TestDetailsWriter'),
+                priority: z
+                    .enum(['p0', 'p1', 'p2', 'p3'])
+                    .optional()
+                    .describe('Test priority (default: p2)'),
+            },
+        }, wrapWithLogging('generate_test_plan', async ({ name, description, targetUrl, additionalInstructions, priority, }) => {
+            // Step 1: Create draft test
+            const createTestBody = {
+                test: {
+                    name,
+                    description,
+                    priority: priority || 'p2',
+                },
+            };
+            const createTestResponse = await apiRequest('/api/v1/mcp/tests', {
+                method: 'POST',
+                body: JSON.stringify(createTestBody),
+            });
+            const testId = createTestResponse.test.id;
+            // Step 2: Trigger TestDetailsWriter
+            const generateDetailsBody = {
+                eventType: 'GenerateTestDetails',
+                payload: {
+                    organizationId: orgId,
+                    testId,
+                    targetUrl,
+                    additionalInstructions,
+                    authenticationNeeded: true,
+                    updateStatusOnSuccess: true,
+                },
+            };
+            const generateResponse = await apiRequest('/api/v1/mcp/agent-jobs', {
+                method: 'POST',
+                body: JSON.stringify(generateDetailsBody),
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Test plan generation initiated:\n\nTest Created:\n- ID: ${testId}\n- Name: ${name}\n- Organization: ${orgId}\n\nTestDetailsWriter Job:\n- Event ID: ${generateResponse.eventId}\n\nThe AI agent will now generate detailed test steps. You can check the test status using the test ID: ${testId}`,
+                    },
+                ],
+            };
+        }));
+    }
+    // Register tool: Get active tests
+    if (canRegisterTool('get_active_tests')) {
+        server.registerTool('get_active_tests', {
+            description: 'Get active tests for the organization. Returns a summary of each test (id, name, status, priority). Use get_test_details for full test information.',
+            inputSchema: {
+                limit: z
+                    .number()
+                    .optional()
+                    .describe('Maximum number of tests to return (default: 20, max: 50)'),
+                offset: z
+                    .number()
+                    .optional()
+                    .describe('Pagination offset (default: 0)'),
+            },
+        }, wrapWithLogging('get_active_tests', async ({ limit, offset }) => {
+            const limitValue = Math.min(limit || 20, 50); // Cap at 50
+            const offsetValue = offset || 0;
+            const testStatuses = encodeURIComponent(JSON.stringify(['active']));
+            const data = await apiRequest(`/api/v1/mcp/tests?testStatuses=${testStatuses}&limit=${limitValue}&offset=${offsetValue}`);
+            // Return summarized test data to reduce response size
+            const summarizedTests = (data.items || []).map((test) => ({
+                id: test.id,
+                name: test.name,
+                status: test.status,
+                priority: test.priority,
+                description: test.description?.substring(0, 200) || null,
+                lastUpdated: test.lastUpdated,
+            }));
+            const total = data.totalCount || data.total || summarizedTests.length;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            tests: summarizedTests,
+                            total,
+                            limit: limitValue,
+                            offset: offsetValue,
+                            hasMore: total > offsetValue + limitValue,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }));
+    }
+    // Register tool: Update test status
+    if (canRegisterTool('update_test_status')) {
+        server.registerTool('update_test_status', {
+            description: 'Bulk update the status of multiple tests',
+            inputSchema: {
+                testIds: z
+                    .array(z.string())
+                    .describe('Array of test IDs to update (e.g., ["test_xxx", "test_yyy"])'),
+                status: z
+                    .enum([
+                    'active',
+                    'blocked_by_customer',
+                    'under_maintenance',
+                    'ignored',
+                    'draft',
+                    'ready_for_review',
+                    'requested',
+                    'expected_failure',
+                    'canceled',
+                    'suggested',
+                ])
+                    .describe('The new status to set for all tests'),
+                reason: z.string().describe('Reason for the status change'),
+                category: z
+                    .string()
+                    .optional()
+                    .describe('Optional category for the status change'),
+                updatedBy: z
+                    .string()
+                    .default('mcp-tool')
+                    .describe('Who is updating the status (default: mcp-tool)'),
+                triggerMaintenanceJobs: z
+                    .boolean()
+                    .optional()
+                    .describe('Whether to trigger maintenance jobs (default: false)'),
+                triggerCodegenJobs: z
+                    .boolean()
+                    .optional()
+                    .describe('Whether to trigger codegen jobs (default: false)'),
+            },
+        }, wrapWithLogging('update_test_status', async ({ testIds, status, reason, category, updatedBy, triggerMaintenanceJobs, triggerCodegenJobs, }) => {
+            const requestBody = {
+                bulkUpdateType: 'status',
+                ids: testIds,
+                change: {
+                    status,
+                    reason,
+                    category,
+                    updatedBy: updatedBy || 'mcp-tool',
+                },
+                triggerMaintenanceJobs,
+                triggerCodegenJobs,
+            };
+            const data = await apiRequest('/api/v1/mcp/tests/bulk-update', {
+                method: 'PATCH',
+                body: JSON.stringify(requestBody),
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Successfully updated ${data.updatedCount} test(s) to status "${status}".\n\nDetails:\n${JSON.stringify(data, null, 2)}`,
+                    },
+                ],
+            };
+        }));
+    }
+    // Register tool: Skip tests from description
+    if (canRegisterTool('skip_tests_from_description')) {
+        server.registerTool('skip_tests_from_description', {
+            description: 'Skip tests based on a user description by changing their status to under_maintenance',
+            inputSchema: {
+                userRequest: z
+                    .string()
+                    .describe('The user request describing which tests to skip (e.g., "skip all login tests")'),
+            },
+        }, wrapWithLogging('skip_tests_from_description', async ({ userRequest }) => {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `To skip tests based on the request: "${userRequest}"
+
+Follow these steps:
+
+1. Run get_active_tests to retrieve all active tests for the organization
+2. Review the test names and descriptions in the results
+3. Identify which test IDs are relevant to the user's request: "${userRequest}"
+4. Call update_test_status with:
+   - testIds: array of relevant test IDs you identified
+   - status: "under_maintenance"
+   - reason: "${userRequest}"
+   - updatedBy: the user's name or "mcp-tool"
+
+This will change the selected tests from "active" to "under_maintenance" status, effectively skipping them.`,
+                    },
+                ],
+            };
+        }));
+    }
+} // end registerTools
+// Factory function to create a new MCP server instance
+async function createMcpServer(token) {
+    const mcpServer = new McpServer({
+        name: 'ranger',
+        version: '1.0.0',
+    });
+    // Register all tools on this server instance with the token
+    await registerTools(mcpServer, token);
+    return mcpServer;
+}
+// Start the server
+async function main() {
+    const httpServer = createServer(async (req, res) => {
+        // Enable CORS
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const url = new URL(req.url || '/', `http://localhost:${PORT}`);
+        // Extract token from Authorization header (supports both "Bearer <token>" and raw token)
+        const authHeader = req.headers.authorization;
+        const token = authHeader?.startsWith('Bearer ')
+            ? authHeader.slice(7)
+            : authHeader || undefined;
+        console.error(`[MCP] ${req.method} ${url.pathname} - Auth header: ${authHeader ? 'present' : 'missing'}, Token: ${token ? token.substring(0, 10) + '...' : 'none'}`);
+        if (url.pathname === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok' }));
+        }
+        else {
+            // Route all other paths to MCP handler
+            // Stateless mode - create a new server and transport for each request
+            // This allows horizontal scaling across multiple Cloud Run instances
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // Stateless mode
+            });
+            // Create server with token bound to all API calls
+            const mcpServer = await createMcpServer(token);
+            await mcpServer.connect(transport);
+            await transport.handleRequest(req, res);
+        }
+    });
+    httpServer.listen(PORT, () => {
+        console.error(`Ranger MCP server running on http://localhost:${PORT}`);
+        console.error(`  MCP endpoint: http://localhost:${PORT}/mcp`);
+        console.error(`  Health check: http://localhost:${PORT}/health`);
+    });
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "@ranger-testing/ranger-cli",
+    "version": "1.0.0",
+    "type": "module",
+    "bin": {
+      "ranger": "./build/cli.js"
+    },
+    "scripts": {
+      "build": "tsc && chmod 755 build/cli.js",
+      "dev": "tsx cli.ts"
+    },
+    "files": ["build", "agents"],
+    "dependencies": {
+      "zod": "^3.23.8",
+      "yargs": "^17.7.2"
+    },
+    "devDependencies": {
+      "@types/node": "^22.0.0",
+      "@types/yargs": "^17.0.32",
+      "typescript": "^5.0.0"
+    }
+  }