testchimp-mcp-client 0.0.3 → 0.0.4

package/README.md

@@ -18,9 +18,14 @@ MCP (Model Context Protocol) server for [TestChimp](https://testchimp.io). Expos
 - **`update_user_story`** — POST `/api/mcp/update_user_story` (full markdown `content` with `id: US-...` in frontmatter).
 - **`update_test_scenario`** — POST `/api/mcp/update_test_scenario` (full markdown `content` with `id: TS-...` and `story: US-...` in frontmatter).
 - **`get_eaas_config`** — POST `/api/mcp/get_eaas_config` (BunnyShell YAML path and project name; token excluded; `{}` when unconfigured).
-- **`provision_ephemeral_environment`** — POST `/api/mcp/provision_ephemeral_environment` (optional `branchName`).
+- **`get_branch_specific_endpoint_config`** — POST `/api/mcp/get_branch_specific_endpoint_config` (optional `branchName`). Resolves `BASE_URL` from Branch Management (template and per-branch overrides). Use when EaaS is not used and preview URLs are configured in TestChimp. Returns `baseUrl` and `resolution` (`override` \| `template` \| `none`).
+- **`provision_ephemeral_environment_and_wait`** — POST `/api/mcp/provision_ephemeral_environment` then poll `/api/mcp/get_ephemeral_environment_status` until deployed with component URLs, or return `failed` / `timeout` with `failure_phase` and `message` (optional `branchName`, `pollIntervalSeconds`, `maxWaitMinutes`). **Prefer this** for agents.
+- **`provision_ephemeral_environment`** — POST `/api/mcp/provision_ephemeral_environment` (optional `branchName`). Use when manually polling or as fallback if the wait tool is unavailable.
 - **`get_ephemeral_environment_status`** — POST `/api/mcp/get_ephemeral_environment_status` (`bnsEnvironmentId`).
 - **`destroy_ephemeral_environment`** — POST `/api/mcp/destroy_ephemeral_environment` (`bnsEnvironmentId`).
+- **`list_bunnyshell_environment_events`** — POST `/api/mcp/list_bunnyshell_environment_events` (proxies BunnyShell; response body is the API payload as returned).
+- **`list_bunnyshell_workflow_jobs`** — POST `/api/mcp/list_bunnyshell_workflow_jobs` (same: raw BunnyShell response body).
+- **`get_bunnyshell_workflow_job_logs`** — POST `/api/mcp/get_bunnyshell_workflow_job_logs` (raw logs response body from BunnyShell).
 
 ## Cursor
 

package/dist/ephemeralProvisionWait.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Poll TestChimp MCP EaaS endpoints until BunnyShell reports deployed + component URLs,
+ * or a terminal failure / timeout. See plan: provision_ephemeral_environment_and_wait.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface ProvisionWaitArgs {
+    branchName?: string;
+    pollIntervalSeconds?: number;
+    maxWaitMinutes?: number;
+}
+export declare function runProvisionEphemeralEnvironmentAndWait(postMcp: (path: string, body: unknown) => Promise<string>, server: McpServer, args: ProvisionWaitArgs): Promise<string>;

package/dist/ephemeralProvisionWait.js

@@ -0,0 +1,206 @@
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function clamp(n, min, max) {
+    return Math.min(max, Math.max(min, n));
+}
+function pickStr(obj, ...keys) {
+    for (const k of keys) {
+        const v = obj[k];
+        if (typeof v === "string" && v.trim() !== "")
+            return v;
+    }
+    return "";
+}
+function parseJsonObject(text) {
+    try {
+        const v = JSON.parse(text);
+        return v !== null && typeof v === "object" && !Array.isArray(v)
+            ? v
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function componentUrlsNonEmpty(componentUrlsJson) {
+    const t = componentUrlsJson.trim();
+    if (!t)
+        return false;
+    try {
+        const v = JSON.parse(t);
+        if (v === null || typeof v !== "object" || Array.isArray(v))
+            return false;
+        return Object.keys(v).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** True if BNS / aggregate status indicates we should stop polling with failure (deploy phase). */
+function isTerminalDeployFailure(aggregateStatus, operationStatus, clusterStatus) {
+    const ag = aggregateStatus.toLowerCase().trim();
+    if (ag === "deployed")
+        return false;
+    const op = operationStatus.toLowerCase();
+    const cl = clusterStatus.toLowerCase();
+    if (op.includes("deploying") || op.includes("in_progress") || op.includes("in progress")) {
+        return false;
+    }
+    const bad = /\b(fail|failed|failure|error|deleted)\b/;
+    if (bad.test(op) || bad.test(cl) || bad.test(ag))
+        return true;
+    return false;
+}
+function lastStatusSnapshot(obj) {
+    return {
+        status: pickStr(obj, "status", "Status"),
+        operationStatus: pickStr(obj, "operationStatus", "operation_status"),
+        clusterStatus: pickStr(obj, "clusterStatus", "cluster_status"),
+        environmentType: pickStr(obj, "environmentType", "environment_type"),
+        dashboardUrl: pickStr(obj, "dashboardUrl", "dashboard_url"),
+    };
+}
+async function logInfo(server, message) {
+    try {
+        await server.sendLoggingMessage({
+            level: "info",
+            data: message,
+        });
+    }
+    catch {
+        // Client may not support logging; ignore.
+    }
+}
+export async function runProvisionEphemeralEnvironmentAndWait(postMcp, server, args) {
+    const pollIntervalSec = clamp(Math.round(args.pollIntervalSeconds ?? 60), 30, 120);
+    const maxWaitMin = clamp(Math.round(args.maxWaitMinutes ?? 25), 5, 45);
+    const deadline = Date.now() + maxWaitMin * 60 * 1000;
+    const intervalMs = pollIntervalSec * 1000;
+    const provisionBody = {};
+    if (args.branchName != null && args.branchName.trim() !== "") {
+        provisionBody.branchName = args.branchName.trim();
+    }
+    let bnsEnvironmentId = "";
+    let branch = "";
+    let provisionRaw = "";
+    try {
+        provisionRaw = await postMcp("/api/mcp/provision_ephemeral_environment", provisionBody);
+    }
+    catch (e) {
+        const errMsg = e instanceof Error ? e.message : String(e);
+        return JSON.stringify({
+            outcome: "failed",
+            failure_phase: "provision",
+            message: `Could not start ephemeral environment (create/deploy trigger failed). ${errMsg}`,
+            bns_environment_id: "",
+            branch: "",
+            component_urls_json: "",
+            last_status: {},
+        });
+    }
+    const prov = parseJsonObject(provisionRaw);
+    bnsEnvironmentId = pickStr(prov, "bnsEnvironmentId", "bns_environment_id");
+    branch = pickStr(prov, "branch", "branch_name");
+    if (!bnsEnvironmentId) {
+        return JSON.stringify({
+            outcome: "failed",
+            failure_phase: "provision",
+            message: "Provision response did not include bns_environment_id. Check BunnyShell + GitHub integration and project EaaS settings.",
+            bns_environment_id: "",
+            branch,
+            component_urls_json: "",
+            last_status: prov,
+        });
+    }
+    await logInfo(server, `Ephemeral env provision started (bns=${bnsEnvironmentId}, branch=${branch || "?"}). Polling up to ${maxWaitMin} min, every ${pollIntervalSec}s.`);
+    let pollIndex = 0;
+    let lastSnapshot = {};
+    let lastComponentUrlsJson = "";
+    let lastDashboardUrl = "";
+    while (Date.now() < deadline) {
+        pollIndex += 1;
+        let statusRaw;
+        try {
+            statusRaw = await postMcp("/api/mcp/get_ephemeral_environment_status", {
+                bnsEnvironmentId,
+            });
+        }
+        catch (e) {
+            const errMsg = e instanceof Error ? e.message : String(e);
+            return JSON.stringify({
+                outcome: "failed",
+                failure_phase: "deploy",
+                message: `Status check failed while waiting for deployment: ${errMsg}`,
+                bns_environment_id: bnsEnvironmentId,
+                branch,
+                component_urls_json: "",
+                last_status: lastSnapshot,
+            });
+        }
+        const st = parseJsonObject(statusRaw);
+        lastSnapshot = lastStatusSnapshot(st);
+        const aggregateStatus = pickStr(st, "status", "Status");
+        const operationStatus = pickStr(st, "operationStatus", "operation_status");
+        const clusterStatus = pickStr(st, "clusterStatus", "cluster_status");
+        const componentUrlsJson = pickStr(st, "componentUrlsJson", "component_urls_json");
+        const dashboardUrl = pickStr(st, "dashboardUrl", "dashboard_url");
+        lastComponentUrlsJson = componentUrlsJson;
+        lastDashboardUrl = dashboardUrl;
+        await logInfo(server, `Ephemeral env poll ${pollIndex}: status=${aggregateStatus} op=${operationStatus} cluster=${clusterStatus} bns=${bnsEnvironmentId}`);
+        const deployed = aggregateStatus.toLowerCase() === "deployed";
+        const urlsOk = componentUrlsNonEmpty(componentUrlsJson);
+        if (deployed && urlsOk) {
+            return JSON.stringify({
+                outcome: "success",
+                message: "Ephemeral environment is deployed and component URLs are available.",
+                bns_environment_id: bnsEnvironmentId,
+                branch,
+                dashboard_url: dashboardUrl,
+                component_urls_json: componentUrlsJson,
+                ready_for_seeding: true,
+                last_status: lastSnapshot,
+            });
+        }
+        if (deployed && !urlsOk) {
+            return JSON.stringify({
+                outcome: "success",
+                message: "Environment reports deployed but component URL map is empty or missing; check BunnyShell definition or dashboard.",
+                warnings: ["component_urls_json_empty_or_unparsed"],
+                bns_environment_id: bnsEnvironmentId,
+                branch,
+                dashboard_url: dashboardUrl,
+                component_urls_json: componentUrlsJson,
+                ready_for_seeding: false,
+                last_status: lastSnapshot,
+            });
+        }
+        if (isTerminalDeployFailure(aggregateStatus, operationStatus, clusterStatus)) {
+            return JSON.stringify({
+                outcome: "failed",
+                failure_phase: "deploy",
+                message: `BunnyShell deployment did not succeed (status=${aggregateStatus}, operation=${operationStatus}, cluster=${clusterStatus}).`,
+                bns_environment_id: bnsEnvironmentId,
+                branch,
+                dashboard_url: dashboardUrl,
+                component_urls_json: componentUrlsJson,
+                last_status: lastSnapshot,
+            });
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0)
+            break;
+        const sleepMs = Math.min(intervalMs, remainingMs);
+        await sleep(sleepMs);
+    }
+    return JSON.stringify({
+        outcome: "timeout",
+        failure_phase: "wait",
+        message: `Timed out after ${maxWaitMin} minutes waiting for ephemeral environment ${bnsEnvironmentId} to become ready.`,
+        bns_environment_id: bnsEnvironmentId,
+        branch,
+        dashboard_url: lastDashboardUrl,
+        component_urls_json: lastComponentUrlsJson,
+        last_status: lastSnapshot,
+    });
+}

package/dist/index.js

@@ -2,10 +2,12 @@
 /**
  * TestChimp MCP server — calls TestChimp /api/mcp/* with TestChimp-Api-Key only.
  * Env: TESTCHIMP_BACKEND_URL (optional), TESTCHIMP_API_KEY (required).
+ * Includes SmartTests coverage, plan authoring, EaaS, and TrueCoverage analytics endpoints.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { runProvisionEphemeralEnvironmentAndWait } from "./ephemeralProvisionWait.js";
 const DEFAULT_BACKEND = "https://featureservice.testchimp.io";
 function getBackendUrl() {
     const raw = process.env.TESTCHIMP_BACKEND_URL?.trim();
@@ -75,6 +77,15 @@ const updatePlanMarkdownInput = z.object({
     content: z.string().min(1),
 });
 const emptyInput = z.object({});
+const getBranchSpecificEndpointConfigInput = z.object({
+    /** Git branch name (e.g. PR head). Required to resolve template or per-branch override. */
+    branchName: z.string().optional(),
+});
+/** Proto-shaped JSON for TrueCoverage (e.g. list_events: baseExecutionScope, comparisonExecutionScope). */
+const truecoverageJsonInput = z.record(z.string(), z.unknown());
+const eventMetadataKeysInput = z.object({
+    eventTitle: z.string().min(1),
+});
 const provisionEphemeralInput = z.object({
     /** Git branch to deploy; omit to use the repo default branch. */
     branchName: z.string().optional(),
@@ -83,6 +94,30 @@ const bnsEnvironmentIdInput = z.object({
     /** BunnyShell environment id returned from provision_ephemeral_environment. */
     bnsEnvironmentId: z.string().min(1),
 });
+const provisionEphemeralWaitInput = z.object({
+    /** Git branch to deploy; omit to use the repo default branch. */
+    branchName: z.string().optional(),
+    /** Seconds between status polls (clamped 30–120). Default 60. */
+    pollIntervalSeconds: z.number().optional(),
+    /** Max minutes to wait for deployed + URLs (clamped 5–45). Default 25. */
+    maxWaitMinutes: z.number().optional(),
+});
+const listBunnyshellEnvironmentEventsInput = z.object({
+    bnsEnvironmentId: z.string().min(1),
+    /** BunnyShell event type filter (e.g. env_deploy). */
+    eventType: z.string().optional(),
+    /** BunnyShell event status: new | in_progress | success | fail */
+    eventStatus: z.string().optional(),
+    page: z.number().int().positive().optional(),
+});
+const listBunnyshellWorkflowJobsInput = z.object({
+    bnsEnvironmentId: z.string().min(1),
+    page: z.number().int().positive().optional(),
+});
+const getBunnyshellWorkflowJobLogsInput = z.object({
+    bnsEnvironmentId: z.string().min(1),
+    workflowJobId: z.string().min(1),
+});
 function textResult(json) {
     return {
         content: [{ type: "text", text: json }],
@@ -107,7 +142,7 @@ function normalizeScope(scope) {
     return out;
 }
 async function main() {
-    const server = new McpServer({ name: "testchimp-mcp", version: "0.1.0" }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: "testchimp-mcp", version: "0.0.8" }, { capabilities: { tools: {}, logging: {} } });
     server.registerTool("get_requirement_coverage", {
         description: "Fetch requirement (scenario) coverage under an optional platform-rooted folder scope (tests/... or plans/...). " +
             "Use branchName (Git branch) and scope.filePaths (paths under platform tests root) rather than internal ids. " +
@@ -200,9 +235,35 @@ async function main() {
         const json = await postMcp("/api/mcp/get_eaas_config", {});
         return textResult(json);
     });
+    server.registerTool("get_branch_specific_endpoint_config", {
+        description: "Resolve BASE_URL for a Git branch from TestChimp Branch Management (URL template and per-branch overrides). " +
+            "Prefer this when BunnyShell EaaS is not configured and the project uses bespoke PR preview URLs. " +
+            "Pass branchName (e.g. the PR branch). Response includes baseUrl and resolution: override | template | none.",
+        inputSchema: getBranchSpecificEndpointConfigInput,
+    }, async (args) => {
+        const body = {};
+        if (args.branchName != null && args.branchName.trim() !== "") {
+            body.branchName = args.branchName.trim();
+        }
+        const json = await postMcp("/api/mcp/get_branch_specific_endpoint_config", body);
+        return textResult(json);
+    });
+    server.registerTool("provision_ephemeral_environment_and_wait", {
+        description: "Preferred: provision a BunnyShell ephemeral environment for the current Git branch, then poll until the stack is deployed and component URLs are available (typically ~5–10 minutes). " +
+            "Returns one JSON with outcome success|failed|timeout, failure_phase (provision|deploy|wait), user-facing message, and component_urls_json on success. " +
+            "Requires BunnyShell + GitHub integration. If this tool is unavailable or the host aborts long calls, fall back to provision_ephemeral_environment + polling get_ephemeral_environment_status (~1/min, max ~25m).",
+        inputSchema: provisionEphemeralWaitInput,
+    }, async (args) => {
+        const json = await runProvisionEphemeralEnvironmentAndWait(postMcp, server, {
+            branchName: args.branchName,
+            pollIntervalSeconds: args.pollIntervalSeconds,
+            maxWaitMinutes: args.maxWaitMinutes,
+        });
+        return textResult(json);
+    });
     server.registerTool("provision_ephemeral_environment", {
-        description: "Create a BunnyShell ephemeral environment for the TestChimp project from the configured Git repo + YAML path. " +
-            "Requires BunnyShell + GitHub integration in project settings. Poll with get_ephemeral_environment_status using bnsEnvironmentId.",
+        description: "Create a BunnyShell ephemeral environment (create + deploy trigger only). Prefer provision_ephemeral_environment_and_wait unless you must poll manually. " +
+            "Requires BunnyShell + GitHub integration. Use get_ephemeral_environment_status with bnsEnvironmentId to poll until deployed.",
         inputSchema: provisionEphemeralInput,
     }, async (args) => {
         const body = {};
@@ -213,7 +274,7 @@ async function main() {
         return textResult(json);
     });
     server.registerTool("get_ephemeral_environment_status", {
-        description: "Poll BunnyShell for environment status and definition. When deployed, environmentSpec may contain URLs/components JSON.",
+        description: "Poll BunnyShell for environment status and component_urls_json. Used for manual fallback when provision_ephemeral_environment_and_wait is not available; prefer the wait tool for normal flows.",
         inputSchema: bnsEnvironmentIdInput,
     }, async (args) => {
         const json = await postMcp("/api/mcp/get_ephemeral_environment_status", {
@@ -230,6 +291,108 @@ async function main() {
         });
         return textResult(json);
     });
+    server.registerTool("list_bunnyshell_environment_events", {
+        description: "Troubleshooting: list BunnyShell platform events for an environment (GET /v1/events). " +
+            "Use after a failed or stuck ephemeral deploy. The HTTP response body is the BunnyShell payload as returned by the API (no extra wrapping). " +
+            "Optional filters: eventType, eventStatus (new|in_progress|success|fail), page.",
+        inputSchema: listBunnyshellEnvironmentEventsInput,
+    }, async (args) => {
+        const body = { bnsEnvironmentId: args.bnsEnvironmentId };
+        if (args.eventType != null && args.eventType.trim() !== "")
+            body.eventType = args.eventType.trim();
+        if (args.eventStatus != null && args.eventStatus.trim() !== "")
+            body.eventStatus = args.eventStatus.trim();
+        if (args.page != null)
+            body.page = args.page;
+        const json = await postMcp("/api/mcp/list_bunnyshell_environment_events", body);
+        return textResult(json);
+    });
+    server.registerTool("list_bunnyshell_workflow_jobs", {
+        description: "Troubleshooting: list BunnyShell workflow jobs for an environment. Response body is the BunnyShell API payload as returned (no extra wrapping). " +
+            "Use to find workflowJobId for get_bunnyshell_workflow_job_logs.",
+        inputSchema: listBunnyshellWorkflowJobsInput,
+    }, async (args) => {
+        const body = { bnsEnvironmentId: args.bnsEnvironmentId };
+        if (args.page != null)
+            body.page = args.page;
+        const json = await postMcp("/api/mcp/list_bunnyshell_workflow_jobs", body);
+        return textResult(json);
+    });
+    server.registerTool("get_bunnyshell_workflow_job_logs", {
+        description: "Troubleshooting: fetch logs for a BunnyShell workflow job (deploy/build pipeline). " +
+            "Response body is the BunnyShell /v1/workflow_jobs/{id}/logs payload as returned (no truncation or wrapping).",
+        inputSchema: getBunnyshellWorkflowJobLogsInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/get_bunnyshell_workflow_job_logs", {
+            bnsEnvironmentId: args.bnsEnvironmentId,
+            workflowJobId: args.workflowJobId,
+        });
+        return textResult(json);
+    });
+    server.registerTool("list_rum_environments", {
+        description: "List distinct RUM environment tags seen for this project (for TrueCoverage scoping). " +
+            "Maps to POST /api/mcp/list_rum_environments.",
+        inputSchema: emptyInput,
+    }, async () => {
+        const json = await postMcp("/api/mcp/list_rum_environments", {});
+        return textResult(json);
+    });
+    server.registerTool("get_truecoverage_events", {
+        description: "TrueCoverage event funnel summaries for the given execution scopes (same JSON body as platform list_events). " +
+            "Maps to POST /api/mcp/truecoverage_list_events.",
+        inputSchema: truecoverageJsonInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/truecoverage_list_events", args ?? {});
+        return textResult(json);
+    });
+    server.registerTool("get_truecoverage_event_details", {
+        description: "TrueCoverage drill-down for one event title (GetEventDetailsRequest JSON). " +
+            "Maps to POST /api/mcp/truecoverage_event_details.",
+        inputSchema: truecoverageJsonInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/truecoverage_event_details", args ?? {});
+        return textResult(json);
+    });
+    server.registerTool("get_truecoverage_child_event_tree", {
+        description: "TrueCoverage next-event tree for an event (ListChildEventTreeRequest JSON). " +
+            "Maps to POST /api/mcp/truecoverage_list_child_event_tree.",
+        inputSchema: truecoverageJsonInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/truecoverage_list_child_event_tree", args ?? {});
+        return textResult(json);
+    });
+    server.registerTool("get_truecoverage_event_transition", {
+        description: "TrueCoverage detailed transition summary between events (GetDetailedEventTransitionSummaryRequest JSON). " +
+            "Maps to POST /api/mcp/truecoverage_detailed_event_transition.",
+        inputSchema: truecoverageJsonInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/truecoverage_detailed_event_transition", args ?? {});
+        return textResult(json);
+    });
+    server.registerTool("get_truecoverage_event_time_series", {
+        description: "TrueCoverage time series for sessions or metrics (EventTimeSeriesRequest JSON). " +
+            "Maps to POST /api/mcp/truecoverage_event_time_series.",
+        inputSchema: truecoverageJsonInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/truecoverage_event_time_series", args ?? {});
+        return textResult(json);
+    });
+    server.registerTool("get_truecoverage_session_metadata_keys", {
+        description: "List session-level metadata keys observed for TrueCoverage. Maps to POST /api/mcp/truecoverage_session_metadata_keys.",
+        inputSchema: emptyInput,
+    }, async () => {
+        const json = await postMcp("/api/mcp/truecoverage_session_metadata_keys", {});
+        return textResult(json);
+    });
+    server.registerTool("get_truecoverage_event_metadata_keys", {
+        description: "List metadata keys for a given event title. Maps to POST /api/mcp/truecoverage_event_metadata_keys.",
+        inputSchema: eventMetadataKeysInput,
+    }, async (args) => {
+        const json = await postMcp("/api/mcp/truecoverage_event_metadata_keys", {
+            eventTitle: args.eventTitle,
+        });
+        return textResult(json);
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testchimp-mcp-client",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "MCP server for TestChimp — coverage, execution history, and plan authoring",
   "type": "module",
   "main": "dist/index.js",
@@ -22,11 +22,11 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "zod": "^3.23.8"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^20.10.0",
-    "typescript": "^5.3.0"
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.2"
   },
   "keywords": [
     "testchimp",