greenrun-cli 0.2.16 → 0.3.0

package/README.md

@@ -78,9 +78,11 @@ Detect which tests are impacted by recent git changes and offer to run them.
 | `update_test` | Update test (auto-invalidates script on content change) |
 | `prepare_test_batch` | Fetch, filter, and start runs for a batch of tests |
 | `export_test_script` | Write a test's cached Playwright script to a local file (keeps scripts out of context) |
+| `export_test_instructions` | Write a test's instructions to a local file (keeps instructions out of context) |
 | `sweep` | Find tests affected by specific pages |
 | `start_run` | Start a test run |
-| `complete_run` | Record test result |
+| `complete_run` | Record a single test result |
+| `batch_complete_runs` | Record results for multiple test runs in one call |
 | `get_run` | Get run details |
 | `list_runs` | List run history |
 

package/dist/api-client.d.ts

@@ -1,13 +1,112 @@
+/** Configuration for connecting to the Greenrun API. */
 export interface ApiConfig {
     baseUrl: string;
     token: string;
 }
+/** Credential set stored on a project. */
+export interface Credential {
+    name: string;
+    email: string;
+    password: string;
+}
+/** Project data returned by the API. */
+export interface ProjectResponse {
+    id: string;
+    name: string;
+    base_url?: string;
+    description?: string;
+    auth_mode?: string;
+    login_url?: string;
+    register_url?: string;
+    login_instructions?: string;
+    register_instructions?: string;
+    credentials?: Credential[];
+    tests_count?: number;
+    pages_count?: number;
+}
+/** Tag data as returned by the API (may be a string or object with name). */
+interface TagData {
+    name?: string;
+    [key: string]: unknown;
+}
+/** Page data as returned by the API. */
+interface PageData {
+    id: string;
+    url: string;
+    [key: string]: unknown;
+}
+/** Test data returned by the API. */
+export interface TestResponse {
+    id: string;
+    name: string;
+    instructions?: string;
+    status?: string;
+    credential_name?: string;
+    has_script?: boolean;
+    script?: string;
+    script_generated_at?: string;
+    pages?: PageData[];
+    tags?: (string | TagData)[];
+    [key: string]: unknown;
+}
+/** Run data returned by the API. */
+export interface RunResponse {
+    id: string;
+    status: string;
+    result?: string;
+    started_at?: string;
+    completed_at?: string;
+    duration_ms?: number;
+    [key: string]: unknown;
+}
+/** Summary of a test in a prepared batch. */
+export interface BatchTestSummary {
+    test_id: string;
+    test_name: string;
+    run_id: string;
+    credential_name: string | null;
+    pages: {
+        id: string;
+        url: string;
+    }[];
+    tags: string[];
+    has_script: boolean;
+}
+/** Project summary included in a batch result, with auth fields filtered by relevance. */
+export interface BatchProjectSummary {
+    id: string;
+    name: string;
+    base_url?: string;
+    auth_mode: string;
+    login_url?: string;
+    register_url?: string;
+    login_instructions?: string;
+    register_instructions?: string;
+    credentials?: Credential[];
+}
+/** Result of preparing a test batch for execution. */
+export interface BatchResult {
+    project: BatchProjectSummary;
+    tests: BatchTestSummary[];
+}
+/** A single run result for batch completion. */
+export interface RunResult {
+    run_id: string;
+    status: string;
+    result?: string;
+}
+/** HTTP client for the Greenrun API. */
 export declare class ApiClient {
     private baseUrl;
     private token;
     constructor(config: ApiConfig);
+    /** Make an authenticated request to the API. */
     private request;
-    listProjects(): Promise<unknown>;
+    /** List all projects accessible to the authenticated user. */
+    listProjects(): Promise<{
+        projects: ProjectResponse[];
+    }>;
+    /** Create a new project. */
     createProject(data: {
         name: string;
         base_url?: string;
@@ -17,13 +116,15 @@ export declare class ApiClient {
         register_url?: string;
         login_instructions?: string;
         register_instructions?: string;
-        credentials?: {
-            name: string;
-            email: string;
-            password: string;
-        }[];
-    }): Promise<unknown>;
-    getProject(id: string): Promise<unknown>;
+        credentials?: Credential[];
+    }): Promise<{
+        project: ProjectResponse;
+    }>;
+    /** Get a project by ID. */
+    getProject(id: string): Promise<{
+        project: ProjectResponse;
+    }>;
+    /** Update a project's settings. */
     updateProject(id: string, data: {
         name?: string;
         base_url?: string;
@@ -33,24 +134,41 @@ export declare class ApiClient {
         register_url?: string;
         login_instructions?: string;
         register_instructions?: string;
-        credentials?: {
-            name: string;
-            email: string;
-            password: string;
-        }[];
-    }): Promise<unknown>;
-    deleteProject(id: string): Promise<unknown>;
-    listPages(projectId: string): Promise<unknown>;
+        credentials?: Credential[];
+    }): Promise<{
+        project: ProjectResponse;
+    }>;
+    /** Delete a project by ID. */
+    deleteProject(id: string): Promise<{
+        message: string;
+    }>;
+    /** List all pages in a project. */
+    listPages(projectId: string): Promise<{
+        pages: PageData[];
+    }>;
+    /** Register a new page URL in a project. */
     createPage(projectId: string, data: {
         url: string;
         name?: string;
-    }): Promise<unknown>;
+    }): Promise<{
+        page: PageData;
+    }>;
+    /** Update a page's URL or name. */
     updatePage(id: string, data: {
         url?: string;
         name?: string;
-    }): Promise<unknown>;
-    deletePage(id: string): Promise<unknown>;
-    listTests(projectId: string, compact?: boolean): Promise<unknown>;
+    }): Promise<{
+        page: PageData;
+    }>;
+    /** Delete a page by ID. */
+    deletePage(id: string): Promise<{
+        message: string;
+    }>;
+    /** List tests in a project. Pass compact=true to omit instructions/script content. */
+    listTests(projectId: string, compact?: boolean): Promise<{
+        tests: TestResponse[];
+    }>;
+    /** Create a new test in a project. */
     createTest(projectId: string, data: {
         name: string;
         instructions: string;
@@ -58,8 +176,14 @@ export declare class ApiClient {
         status?: string;
         tags?: string[];
         credential_name?: string;
-    }): Promise<unknown>;
-    getTest(id: string): Promise<unknown>;
+    }): Promise<{
+        test: TestResponse;
+    }>;
+    /** Get full test details including instructions, pages, and recent runs. */
+    getTest(id: string): Promise<{
+        test: TestResponse;
+    }>;
+    /** Update a test's properties. */
     updateTest(id: string, data: {
         name?: string;
         instructions?: string;
@@ -69,39 +193,44 @@ export declare class ApiClient {
         credential_name?: string | null;
         script?: string | null;
         script_generated_at?: string | null;
-    }): Promise<unknown>;
-    deleteTest(id: string): Promise<unknown>;
+    }): Promise<{
+        test: TestResponse;
+    }>;
+    /** Delete a test by ID. */
+    deleteTest(id: string): Promise<{
+        message: string;
+    }>;
+    /** Find tests affected by specific pages (impact analysis). */
     sweep(projectId: string, params: {
         pages?: string[];
         url_pattern?: string;
     }): Promise<unknown>;
-    startRun(testId: string): Promise<unknown>;
+    /** Start a new test run (sets status to running). */
+    startRun(testId: string): Promise<{
+        run: RunResponse;
+    }>;
+    /** Record the result of a single test run. */
     completeRun(runId: string, data: {
         status: string;
         result?: string;
-    }): Promise<unknown>;
-    getRun(runId: string): Promise<unknown>;
-    listRuns(testId: string): Promise<unknown>;
-    prepareTestBatch(projectId: string, filter?: string, testIds?: string[]): Promise<{
-        project: {
-            id: any;
-            name: any;
-            base_url: any;
-            auth_mode: any;
-            login_url: any;
-            register_url: any;
-            login_instructions: any;
-            register_instructions: any;
-            credentials: any;
-        };
-        tests: {
-            test_id: any;
-            test_name: any;
-            run_id: any;
-            credential_name: any;
-            pages: any;
-            tags: any;
-            has_script: any;
-        }[];
+    }): Promise<{
+        run: RunResponse;
+    }>;
+    /** Complete multiple test runs in a single batch call. */
+    batchCompleteRuns(runs: RunResult[]): Promise<{
+        completed: number;
     }>;
+    /** Get details of a specific test run. */
+    getRun(runId: string): Promise<{
+        run: RunResponse;
+    }>;
+    /** List run history for a test (newest first). */
+    listRuns(testId: string): Promise<unknown>;
+    /**
+     * Prepare a batch of tests for execution. Lists tests, applies filters,
+     * fetches project details, and starts runs — all in one call.
+     * Only includes credentials referenced by the batch's tests.
+     */
+    prepareTestBatch(projectId: string, filter?: string, testIds?: string[]): Promise<BatchResult>;
 }
+export {};

package/dist/api-client.js

@@ -1,3 +1,4 @@
+/** HTTP client for the Greenrun API. */
 export class ApiClient {
     baseUrl;
     token;
@@ -5,6 +6,7 @@ export class ApiClient {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.token = config.token;
     }
+    /** Make an authenticated request to the API. */
     async request(method, path, body) {
         const url = `${this.baseUrl}/api/v1${path}`;
         const headers = {
@@ -31,53 +33,68 @@ export class ApiClient {
         }
         return response.json();
     }
-    // Projects
+    // --- Projects ---
+    /** List all projects accessible to the authenticated user. */
     async listProjects() {
         return this.request('GET', '/projects');
     }
+    /** Create a new project. */
     async createProject(data) {
         return this.request('POST', '/projects', data);
     }
+    /** Get a project by ID. */
     async getProject(id) {
         return this.request('GET', `/projects/${id}`);
     }
+    /** Update a project's settings. */
     async updateProject(id, data) {
         return this.request('PUT', `/projects/${id}`, data);
     }
+    /** Delete a project by ID. */
     async deleteProject(id) {
         return this.request('DELETE', `/projects/${id}`);
     }
-    // Pages
+    // --- Pages ---
+    /** List all pages in a project. */
     async listPages(projectId) {
         return this.request('GET', `/projects/${projectId}/pages`);
     }
+    /** Register a new page URL in a project. */
     async createPage(projectId, data) {
         return this.request('POST', `/projects/${projectId}/pages`, data);
     }
+    /** Update a page's URL or name. */
     async updatePage(id, data) {
         return this.request('PUT', `/pages/${id}`, data);
     }
+    /** Delete a page by ID. */
     async deletePage(id) {
         return this.request('DELETE', `/pages/${id}`);
     }
-    // Tests
+    // --- Tests ---
+    /** List tests in a project. Pass compact=true to omit instructions/script content. */
     async listTests(projectId, compact) {
         const query = compact ? '?compact=1' : '';
         return this.request('GET', `/projects/${projectId}/tests${query}`);
     }
+    /** Create a new test in a project. */
     async createTest(projectId, data) {
         return this.request('POST', `/projects/${projectId}/tests`, data);
     }
+    /** Get full test details including instructions, pages, and recent runs. */
     async getTest(id) {
         return this.request('GET', `/tests/${id}`);
     }
+    /** Update a test's properties. */
     async updateTest(id, data) {
         return this.request('PUT', `/tests/${id}`, data);
     }
+    /** Delete a test by ID. */
     async deleteTest(id) {
         return this.request('DELETE', `/tests/${id}`);
     }
-    // Sweep
+    // --- Sweep ---
+    /** Find tests affected by specific pages (impact analysis). */
     async sweep(projectId, params) {
         const searchParams = new URLSearchParams();
         if (params.pages) {
@@ -90,69 +107,112 @@ export class ApiClient {
         }
         return this.request('GET', `/projects/${projectId}/sweep?${searchParams.toString()}`);
     }
-    // Test Runs
+    // --- Test Runs ---
+    /** Start a new test run (sets status to running). */
     async startRun(testId) {
         return this.request('POST', `/tests/${testId}/runs`);
     }
+    /** Record the result of a single test run. */
     async completeRun(runId, data) {
         return this.request('PUT', `/runs/${runId}`, data);
     }
+    /** Complete multiple test runs in a single batch call. */
+    async batchCompleteRuns(runs) {
+        return this.request('PUT', '/runs/batch', { runs });
+    }
+    /** Get details of a specific test run. */
     async getRun(runId) {
         return this.request('GET', `/runs/${runId}`);
     }
+    /** List run history for a test (newest first). */
     async listRuns(testId) {
         return this.request('GET', `/tests/${testId}/runs`);
     }
-    // Batch operations
+    // --- Batch Operations ---
+    /**
+     * Prepare a batch of tests for execution. Lists tests, applies filters,
+     * fetches project details, and starts runs — all in one call.
+     * Only includes credentials referenced by the batch's tests.
+     */
     async prepareTestBatch(projectId, filter, testIds) {
         const [projectResult, testsResult] = await Promise.all([
             this.getProject(projectId),
             this.listTests(projectId, true),
         ]);
         const project = projectResult.project;
-        let tests = (testsResult.tests || []).filter((t) => t.status === 'active');
-        if (testIds && testIds.length > 0) {
-            const idSet = new Set(testIds);
-            tests = tests.filter((t) => idSet.has(t.id));
-        }
-        else if (filter) {
-            if (filter.startsWith('tag:')) {
-                const tag = filter.slice(4).toLowerCase();
-                tests = tests.filter((t) => (t.tags || []).some((tg) => (tg.name || tg).toLowerCase() === tag));
-            }
-            else if (filter.startsWith('/')) {
-                tests = tests.filter((t) => (t.pages || []).some((p) => (p.url || '').includes(filter)));
-            }
-            else {
-                const term = filter.toLowerCase();
-                tests = tests.filter((t) => (t.name || '').toLowerCase().includes(term));
-            }
-        }
-        const projectSummary = {
-            id: project.id, name: project.name, base_url: project.base_url,
-            auth_mode: project.auth_mode ?? 'none',
-            login_url: project.login_url ?? null,
-            register_url: project.register_url ?? null,
-            login_instructions: project.login_instructions ?? null,
-            register_instructions: project.register_instructions ?? null,
-            credentials: project.credentials ?? null,
-        };
-        if (tests.length === 0) {
+        const activeTests = filterTests(testsResult.tests || [], filter, testIds);
+        const projectSummary = buildProjectSummary(project, activeTests);
+        if (activeTests.length === 0) {
             return { project: projectSummary, tests: [] };
         }
-        // Start runs in parallel (listTests already has full details, no need for getTest)
-        const runs = await Promise.all(tests.map((t) => this.startRun(t.id)));
+        const runs = await startBatchRuns(activeTests, (testId) => this.startRun(testId));
         return {
             project: projectSummary,
-            tests: tests.map((t, i) => ({
-                test_id: t.id,
-                test_name: t.name,
-                run_id: runs[i].run.id,
-                credential_name: t.credential_name ?? null,
-                pages: (t.pages || []).map((p) => ({ id: p.id, url: p.url })),
-                tags: (t.tags || []).map((tg) => tg.name || tg),
-                has_script: t.has_script ?? !!t.script,
+            tests: activeTests.map((test, index) => ({
+                test_id: test.id,
+                test_name: test.name,
+                run_id: runs[index].run.id,
+                credential_name: test.credential_name ?? null,
+                pages: (test.pages || []).map((page) => ({ id: page.id, url: page.url })),
+                tags: (test.tags || []).map((tag) => typeof tag === 'string' ? tag : tag.name || ''),
+                has_script: test.has_script ?? !!test.script,
             })),
         };
     }
 }
+/** Filter tests by test IDs, tag, page URL, or name substring. */
+function filterTests(tests, filter, testIds) {
+    let activeTests = tests.filter((test) => test.status === 'active');
+    if (testIds && testIds.length > 0) {
+        const idSet = new Set(testIds);
+        activeTests = activeTests.filter((test) => idSet.has(test.id));
+    }
+    else if (filter) {
+        if (filter.startsWith('tag:')) {
+            const tagName = filter.slice(4).toLowerCase();
+            activeTests = activeTests.filter((test) => (test.tags || []).some((tag) => {
+                const name = typeof tag === 'string' ? tag : tag.name || '';
+                return name.toLowerCase() === tagName;
+            }));
+        }
+        else if (filter.startsWith('/')) {
+            activeTests = activeTests.filter((test) => (test.pages || []).some((page) => (page.url || '').includes(filter)));
+        }
+        else {
+            const term = filter.toLowerCase();
+            activeTests = activeTests.filter((test) => (test.name || '').toLowerCase().includes(term));
+        }
+    }
+    return activeTests;
+}
+/**
+ * Build a project summary for the batch response.
+ * Omits auth fields when auth_mode is 'none'.
+ * Only includes credentials referenced by the batch's tests.
+ */
+function buildProjectSummary(project, tests) {
+    const authMode = project.auth_mode ?? 'none';
+    if (authMode === 'none') {
+        return { id: project.id, name: project.name, base_url: project.base_url, auth_mode: 'none' };
+    }
+    const referencedNames = new Set(tests.map((test) => test.credential_name).filter((name) => !!name));
+    const allCredentials = project.credentials ?? [];
+    const filteredCredentials = referencedNames.size > 0
+        ? allCredentials.filter((cred) => referencedNames.has(cred.name))
+        : allCredentials;
+    return {
+        id: project.id,
+        name: project.name,
+        base_url: project.base_url,
+        auth_mode: authMode,
+        login_url: project.login_url,
+        register_url: project.register_url,
+        login_instructions: project.login_instructions,
+        register_instructions: project.register_instructions,
+        credentials: filteredCredentials.length > 0 ? filteredCredentials : undefined,
+    };
+}
+/** Start runs for all tests in parallel. */
+async function startBatchRuns(tests, startRun) {
+    return Promise.all(tests.map((test) => startRun(test.id)));
+}

package/dist/commands/init.js

@@ -100,12 +100,14 @@ async function validateToken(token) {
         return { valid: true, projectCount: projects.length };
     }
     catch (err) {
-        return { valid: false, error: err?.message || String(err) };
+        const message = err instanceof Error ? err.message : String(err);
+        return { valid: false, error: message };
     }
 }
 function getClaudeConfigPath() {
     return join(homedir(), '.claude.json');
 }
+/** Read the Claude Code config from ~/.claude.json. */
 function readClaudeConfig() {
     const configPath = getClaudeConfigPath();
     if (!existsSync(configPath))
@@ -117,6 +119,7 @@ function readClaudeConfig() {
         return {};
     }
 }
+/** Write the Claude Code config to ~/.claude.json. */
 function writeClaudeConfig(config) {
     writeFileSync(getClaudeConfigPath(), JSON.stringify(config, null, 2) + '\n');
 }
@@ -233,19 +236,8 @@ function installClaudeMd() {
         console.log('  Created CLAUDE.md with Greenrun instructions');
     }
 }
-function installSettings() {
-    const settingsDir = join(process.cwd(), '.claude');
-    mkdirSync(settingsDir, { recursive: true });
-    const settingsPath = join(settingsDir, 'settings.local.json');
-    let existing = {};
-    if (existsSync(settingsPath)) {
-        try {
-            existing = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-        }
-        catch {
-            // overwrite invalid JSON
-        }
-    }
+/** Build the list of MCP tool permissions needed for Greenrun and Playwright. */
+function buildPermissionsList() {
     const greenrunTools = [
         'mcp__greenrun__list_projects',
         'mcp__greenrun__get_project',
@@ -259,10 +251,13 @@ function installSettings() {
         'mcp__greenrun__update_test',
         'mcp__greenrun__start_run',
         'mcp__greenrun__complete_run',
+        'mcp__greenrun__batch_complete_runs',
         'mcp__greenrun__get_run',
         'mcp__greenrun__list_runs',
         'mcp__greenrun__sweep',
         'mcp__greenrun__prepare_test_batch',
+        'mcp__greenrun__export_test_script',
+        'mcp__greenrun__export_test_instructions',
     ];
     const browserTools = [
         'mcp__playwright__browser_navigate',
@@ -270,10 +265,6 @@ function installSettings() {
         'mcp__playwright__browser_click',
         'mcp__playwright__browser_type',
         'mcp__playwright__browser_handle_dialog',
-        'mcp__playwright__browser_tab_list',
-        'mcp__playwright__browser_tab_new',
-        'mcp__playwright__browser_tab_select',
-        'mcp__playwright__browser_tab_close',
         'mcp__playwright__browser_select_option',
         'mcp__playwright__browser_hover',
         'mcp__playwright__browser_drag',
@@ -291,11 +282,27 @@ function installSettings() {
         'mcp__playwright__browser_tabs',
         'mcp__playwright__browser_network_requests',
     ];
-    const requiredTools = [...greenrunTools, ...browserTools];
-    existing.permissions = existing.permissions || {};
-    const currentAllow = existing.permissions.allow || [];
+    return [...greenrunTools, ...browserTools];
+}
+function installSettings() {
+    const settingsDir = join(process.cwd(), '.claude');
+    mkdirSync(settingsDir, { recursive: true });
+    const settingsPath = join(settingsDir, 'settings.local.json');
+    let existing = {};
+    if (existsSync(settingsPath)) {
+        try {
+            existing = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+        }
+        catch {
+            // overwrite invalid JSON
+        }
+    }
+    const requiredTools = buildPermissionsList();
+    const permissions = (existing.permissions ?? {});
+    const currentAllow = (permissions.allow ?? []);
     const merged = [...new Set([...currentAllow, ...requiredTools])];
-    existing.permissions.allow = merged;
+    permissions.allow = merged;
+    existing.permissions = permissions;
     writeFileSync(settingsPath, JSON.stringify(existing, null, 2) + '\n');
     console.log('  Updated .claude/settings.local.json with tool permissions');
 }

package/dist/server.js

@@ -1,9 +1,46 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { writeFileSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { ApiClient } from './api-client.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** Remove keys with null or undefined values from an object (shallow). */
+function stripNulls(obj) {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (value != null) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/** Build a compact MCP text response from data, stripping nulls and using minimal JSON. */
+function jsonResponse(data) {
+    const cleaned = data && typeof data === 'object' && !Array.isArray(data)
+        ? stripNulls(data)
+        : data;
+    return { content: [{ type: 'text', text: JSON.stringify(cleaned) }] };
+}
+/** Read the package version from package.json. */
+function readPackageVersion() {
+    try {
+        const pkgPath = join(__dirname, '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return pkg.version || '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+/** Shared zod schema for credential sets, used by create_project and update_project. */
+const credentialSchema = z.object({
+    name: z.string().describe('Credential set name (e.g. "admin", "viewer")'),
+    email: z.string().describe('Login email'),
+    password: z.string().describe('Login password'),
+});
 export async function startServer() {
     const GREENRUN_API_URL = process.env.GREENRUN_API_URL || 'https://app.greenrun.dev';
     const GREENRUN_API_TOKEN = process.env.GREENRUN_API_TOKEN;
@@ -17,12 +54,12 @@ export async function startServer() {
     });
     const server = new McpServer({
         name: 'greenrun',
-        version: '0.1.0',
+        version: readPackageVersion(),
     });
     // --- Projects ---
     server.tool('list_projects', 'List all projects', {}, async () => {
         const result = await api.listProjects();
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     server.tool('create_project', 'Create a new project', {
         name: z.string().describe('Project name'),
@@ -33,18 +70,14 @@ export async function startServer() {
         register_url: z.string().optional().describe('URL of registration page (for new_user auth mode)'),
         login_instructions: z.string().optional().describe('Steps to log in with existing credentials'),
         register_instructions: z.string().optional().describe('Steps to register a new user'),
-        credentials: z.array(z.object({
-            name: z.string().describe('Credential set name (e.g. "admin", "viewer")'),
-            email: z.string().describe('Login email'),
-            password: z.string().describe('Login password'),
-        })).optional().describe('Named credential sets for test authentication (max 20)'),
+        credentials: z.array(credentialSchema).optional().describe('Named credential sets for test authentication (max 20)'),
     }, async (args) => {
         const result = await api.createProject(args);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     server.tool('get_project', 'Get project details', { project_id: z.string().describe('Project UUID') }, async (args) => {
         const result = await api.getProject(args.project_id);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     server.tool('update_project', 'Update project settings', {
         project_id: z.string().describe('Project UUID'),
@@ -56,20 +89,16 @@ export async function startServer() {
         register_url: z.string().optional().describe('URL of registration page (for new_user auth mode)'),
         login_instructions: z.string().optional().describe('Steps to log in with existing credentials'),
         register_instructions: z.string().optional().describe('Steps to register a new user'),
-        credentials: z.array(z.object({
-            name: z.string().describe('Credential set name (e.g. "admin", "viewer")'),
-            email: z.string().describe('Login email'),
-            password: z.string().describe('Login password'),
-        })).optional().describe('Named credential sets for test authentication (max 20)'),
+        credentials: z.array(credentialSchema).optional().describe('Named credential sets for test authentication (max 20)'),
     }, async (args) => {
         const { project_id, ...data } = args;
         const result = await api.updateProject(project_id, data);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     // --- Pages ---
     server.tool('list_pages', 'List pages in a project', { project_id: z.string().describe('Project UUID') }, async (args) => {
         const result = await api.listPages(args.project_id);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     server.tool('create_page', 'Register a page URL in a project', {
         project_id: z.string().describe('Project UUID'),
@@ -77,16 +106,16 @@ export async function startServer() {
         name: z.string().optional().describe('Human-friendly page name'),
     }, async (args) => {
         const result = await api.createPage(args.project_id, { url: args.url, name: args.name });
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     // --- Tests ---
     server.tool('list_tests', 'List tests in a project (includes latest run status)', { project_id: z.string().describe('Project UUID') }, async (args) => {
         const result = await api.listTests(args.project_id);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     server.tool('get_test', 'Get test details including instructions, pages, and recent runs', { test_id: z.string().describe('Test UUID') }, async (args) => {
         const result = await api.getTest(args.test_id);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     server.tool('create_test', 'Store a new test case in a project', {
         project_id: z.string().describe('Project UUID'),
@@ -105,7 +134,7 @@ export async function startServer() {
             tags: args.tags,
             credential_name: args.credential_name,
         });
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     server.tool('update_test', 'Update test instructions, name, status, or page associations', {
         test_id: z.string().describe('Test UUID'),
@@ -119,8 +148,8 @@ export async function startServer() {
         script_generated_at: z.string().optional().nullable().describe('ISO timestamp when the script was generated'),
     }, async (args) => {
         const { test_id, ...data } = args;
-        const result = await api.updateTest(test_id, data);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        await api.updateTest(test_id, data);
+        return jsonResponse({ success: true });
     });
     server.tool('export_test_script', 'Fetch a test\'s cached Playwright script and write it directly to a file. The script content is never returned — only a confirmation. Use this to export scripts without consuming context.', {
         test_id: z.string().describe('Test UUID'),
@@ -135,6 +164,20 @@ export async function startServer() {
         writeFileSync(args.file_path, script, 'utf-8');
         return { content: [{ type: 'text', text: `Script written to ${args.file_path} (${script.length} chars)` }] };
     });
+    server.tool('export_test_instructions', 'Fetch a test\'s instructions and write them to a local file. The instructions are never returned — only a confirmation. Use this so agents can read instructions from disk instead of receiving them through MCP context.', {
+        test_id: z.string().describe('Test UUID'),
+        file_path: z.string().describe('Absolute file path to write the instructions to (e.g. /tmp/greenrun-tests/{test_id}.instructions.md)'),
+    }, async (args) => {
+        const result = await api.getTest(args.test_id);
+        const instructions = result.test?.instructions;
+        if (!instructions) {
+            return { content: [{ type: 'text', text: `No instructions found for test ${args.test_id}` }] };
+        }
+        mkdirSync(dirname(args.file_path), { recursive: true });
+        const header = result.test.name ? `# ${result.test.name}\n\n` : '';
+        writeFileSync(args.file_path, header + instructions, 'utf-8');
+        return { content: [{ type: 'text', text: `Instructions written to ${args.file_path} (${instructions.length} chars)` }] };
+    });
     // --- Sweep ---
     server.tool('sweep', 'Find tests affected by specific pages (impact analysis). Use after making changes to determine which tests to re-run.', {
         project_id: z.string().describe('Project UUID'),
@@ -145,7 +188,7 @@ export async function startServer() {
             pages: args.pages,
             url_pattern: args.url_pattern,
         });
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     // --- Batch ---
     server.tool('prepare_test_batch', 'Prepare a batch of tests for execution: lists tests, filters, fetches full details, and starts runs — all in one call. Returns everything needed to execute tests.', {
@@ -155,35 +198,46 @@ export async function startServer() {
     }, async (args) => {
         try {
             const result = await api.prepareTestBatch(args.project_id, args.filter, args.test_ids);
-            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            return jsonResponse(result);
         }
         catch (error) {
-            return { content: [{ type: 'text', text: `Error: ${error.message}` }], isError: true };
+            const message = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
         }
     });
     // --- Test Runs ---
     server.tool('start_run', 'Start a test run (sets status to running)', { test_id: z.string().describe('Test UUID') }, async (args) => {
         const result = await api.startRun(args.test_id);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse({ run_id: result.run.id });
     });
     server.tool('complete_run', 'Record the result of a test run', {
         run_id: z.string().describe('Run UUID'),
         status: z.enum(['passed', 'failed', 'error']).describe('Run result status'),
         result: z.string().optional().describe('Summary of what happened during the run'),
     }, async (args) => {
-        const result = await api.completeRun(args.run_id, {
+        await api.completeRun(args.run_id, {
             status: args.status,
             result: args.result,
         });
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse({ success: true });
+    });
+    server.tool('batch_complete_runs', 'Record results for multiple test runs in a single call. More efficient than calling complete_run individually.', {
+        runs: z.array(z.object({
+            run_id: z.string().describe('Run UUID'),
+            status: z.enum(['passed', 'failed', 'error']).describe('Run result status'),
+            result: z.string().optional().describe('Summary of what happened'),
+        })).describe('Array of run results to complete'),
+    }, async (args) => {
+        const result = await api.batchCompleteRuns(args.runs);
+        return jsonResponse(result);
     });
     server.tool('get_run', 'Get details of a specific test run', { run_id: z.string().describe('Run UUID') }, async (args) => {
         const result = await api.getRun(args.run_id);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     server.tool('list_runs', 'List run history for a test (newest first)', { test_id: z.string().describe('Test UUID') }, async (args) => {
         const result = await api.listRuns(args.test_id);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return jsonResponse(result);
     });
     // Start server
     const transport = new StdioServerTransport();

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "greenrun-cli",
-  "version": "0.2.16",
+  "version": "0.3.0",
   "description": "CLI and MCP server for Greenrun - browser test management for Claude Code",
   "type": "module",
   "main": "dist/server.js",
   "bin": {
-    "greenrun": "dist/cli.js"
+    "greenrun": "dist/cli.js",
+    "greenrun-cli": "dist/cli.js"
   },
   "files": [
     "dist",

package/templates/claude-md.md

@@ -12,9 +12,11 @@ The Greenrun MCP server provides these tools:
 - **list_projects** / **get_project** / **create_project** - Manage projects (includes auth configuration)
 - **list_pages** / **create_page** - Manage page URLs within a project
 - **list_tests** / **get_test** / **create_test** / **update_test** - Manage test cases
-- **start_run** / **complete_run** / **get_run** / **list_runs** - Execute and track test runs
+- **start_run** / **complete_run** / **batch_complete_runs** / **get_run** / **list_runs** - Execute and track test runs
 - **sweep** - Impact analysis: find tests affected by changed pages
 - **prepare_test_batch** - Batch prepare tests for execution (lists, filters, fetches details, starts runs in one call)
+- **export_test_script** - Write a test's cached Playwright script to a local file (keeps scripts out of context)
+- **export_test_instructions** - Write a test's instructions to a local file (keeps instructions out of context)
 
 ### Running Tests
 

package/templates/commands/procedures.md

@@ -25,7 +25,7 @@ If auth fails (login form still visible after following instructions), report al
 
 You have a batch result from `prepare_test_batch` containing `project` (with `credentials` array) and `tests[]` (each with `test_id`, `test_name`, `run_id`, `credential_name`, `pages`, `tags`, `has_script`).
 
-Note: The batch does not include `instructions` or `script` content. Use `get_test(test_id)` to fetch these when needed.
+Note: The batch does not include `instructions` or `script` content. Use `export_test_instructions(test_id, file_path)` to write instructions to disk — agents read from the file instead of receiving them through MCP context.
 
 If `tests` is empty, tell the user no matching active tests were found and stop.
 
@@ -44,7 +44,10 @@ If all tests are scripted, skip to Step 4.
 
 ### Step 3: Generate scripts for unscripted tests
 
-For each **unscripted** test, launch a Task agent sequentially (one at a time, wait for each to complete before starting the next). This keeps browser snapshot data out of the parent context.
+For each **unscripted** test:
+
+1. Call `export_test_instructions(test_id, "/tmp/greenrun-tests/{test_id}.instructions.md")` to write instructions to disk
+2. Launch a Task agent sequentially (one at a time, wait for each to complete before starting the next). This keeps browser snapshot data out of the parent context.
 
 ```
 Task tool with:
@@ -68,7 +71,7 @@ Credentials: {credential_name} — email: {email}, password: {password}
 
 ## Task
 
-1. Call `get_test("{test_id}")` to fetch the full test instructions
+1. Read the test instructions from `/tmp/greenrun-tests/{test_id}.instructions.md` (exported before agent launch)
 2. Authenticate: navigate to {login_url} and log in with the credential above using `browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`
 3. Do a scouting pass — follow the test instructions step by step in the browser:
    - Navigate to the test's starting page via `browser_navigate`
@@ -153,7 +156,7 @@ npx playwright test --config /tmp/greenrun-tests/playwright.config.ts
 
 **3. Parse results**: Read `/tmp/greenrun-tests/results.json`. Map each result back to a run ID via the filename: `{test_id}.spec.ts` → test_id → find the matching run_id from the batch.
 
-**4. Report results**: Call `complete_run(run_id, status, result_summary)` for each test. Map Playwright statuses: `passed` → `passed`, `failed`/`timedOut` → `failed`, other → `error`.
+**4. Report results**: Call `batch_complete_runs` with all results at once. Map Playwright statuses: `passed` → `passed`, `failed`/`timedOut` → `failed`, other → `error`. Example: `batch_complete_runs({ runs: [{ run_id, status, result }] })`.
 
 **5. Clean up**: Call `browser_close` to reset the MCP browser context.
 
@@ -170,7 +173,10 @@ After parsing all native results, walk through them in completion order. Track c
 
 For tests that **failed** in native execution (and circuit breaker has not tripped), execute them one at a time via Task agents. This keeps snapshot data out of the parent context.
 
-For each failed test, launch a Task agent sequentially (wait for each to complete before the next):
+For each failed test:
+
+1. Call `export_test_instructions(test_id, "/tmp/greenrun-tests/{test_id}.instructions.md")` to write instructions to disk
+2. Launch a Task agent sequentially (wait for each to complete before the next):
 
 ```
 Task tool with:
@@ -193,7 +199,7 @@ Native execution failed with: {failure_message}
 
 ## Task
 
-1. Call `get_test("{test_id}")` to fetch the full test instructions
+1. Read the test instructions from `/tmp/greenrun-tests/{test_id}.instructions.md` (exported before agent launch)
 2. Start a new run: `start_run("{test_id}")` — note the run_id
 3. Authenticate: navigate to {login_url} and log in with the credential above
 4. Follow the test instructions step by step using Playwright MCP tools (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`)