@skyramp/mcp 0.4.3 → 0.4.4-rc.2

package/build/index.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { McpServer } from "@modelcontextprotocol/server";
 import { runnableLanguagesText } from "./types/TestTypes.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { registerStartTraceCollectionPrompt } from "./prompts/startTraceCollectionPrompts.js";
 import { registerTraceTool } from "./tools/trace/startTraceCollectionTool.js";
 import { registerTraceStopTool } from "./tools/trace/stopTraceCollectionTool.js";
 import { registerExecuteSkyrampTestTool } from "./tools/executeSkyrampTestTool.js";
+import { registerExecuteFleetTool } from "./tools/executeFleetTool.js";
 import { AUTH_PLACEHOLDER_TOKEN } from "./types/TestTypes.js";
 import { AUTH_CONFLICT_ERROR_MSG } from "./prompts/test-recommendation/recommendationSections.js";
 import { logger } from "./utils/logger.js";
 import { registerUITestTool } from "./tools/generate-tests/generateUIRestTool.js";
+import { registerUILoadTestTool } from "./tools/generate-tests/generateUILoadRestTool.js";
 import { registerSmokeTestTool } from "./tools/generate-tests/generateSmokeRestTool.js";
 import { registerFuzzTestTool } from "./tools/generate-tests/generateFuzzRestTool.js";
 import { registerContractTestTool } from "./tools/generate-tests/generateContractRestTool.js";
@@ -83,220 +85,249 @@ If the workspace root is a git repo AND \`.skyramp/workspace.yml\` does not exis
 3. Proceed with the originally requested tool, if it is not one of the two workspace-init tools above.
 Skip only if: not a git repo, \`.skyramp/workspace.yml\` already exists, or user explicitly declines.
 `;
-const server = new McpServer({
-    name: "Skyramp MCP Server",
-    version: "1.0.0",
-}, {
-    capabilities: {
-        tools: {
-            listChanged: true,
+/**
+ * Builds one fully-registered server. `serveStdio` calls this per connection,
+ * so every registration must happen here rather than at module load.
+ */
+async function createServer({ era }) {
+    const server = new McpServer({
+        name: "Skyramp MCP Server",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: {
+                listChanged: true,
+            },
+            prompts: {
+                listChanged: true,
+            },
+            resources: {
+                listChanged: true,
+            },
         },
-        prompts: {
-            listChanged: true,
-        },
-        resources: {
-            listChanged: true,
-        },
-    },
-    instructions: `Skyramp MCP Server — generates and executes API tests (fuzz, contract, integration, E2E, UI).
-${workspaceInitInstructions}
-## Rules
-- NEVER show CLI commands. NEVER attempt to install or configure the Skyramp CLI. ALWAYS use the MCP tools provided.
-- For UI and E2E tests, there are TWO recording modes:
-  1. **AI-driven recording** (default): Use the browser_* tools (browser_navigate, browser_click, etc.) to record interactions, then call skyramp_export_zip to export the trace, then call skyramp_ui_test_generation with the zip path.
-  2. **Manual recording**: ONLY when the user explicitly says "manual recording", "record myself", "I will interact", or "Docker trace" — use skyramp_start_trace_collection / skyramp_stop_trace_collection to let the user interact with the browser themselves.
-- To capture an authentication session for re-use (e.g. "save session", "store login", "record auth state"): call \`skyramp_start_trace_collection\` (\`playwrightSaveStoragePath\` defaults to saving the session in \`outputDir\` — no need to set it). Tell the user to log in once and then call \`skyramp_stop_trace_collection\` IMMEDIATELY after login completes. The saved file can be passed back as \`playwrightStoragePath\` on later trace runs, or referenced as \`storageState\` in generated tests.${oneClickInstructions}
+        instructions: `Skyramp MCP Server — generates and executes API tests (fuzz, contract, integration, E2E, UI).
+  ${workspaceInitInstructions}
+  ## Rules
+  - NEVER show CLI commands. NEVER attempt to install or configure the Skyramp CLI. ALWAYS use the MCP tools provided.
+  - For UI and E2E tests, there are TWO recording modes:
+    1. **AI-driven recording** (default): Use the browser_* tools (browser_navigate, browser_click, etc.) to record interactions, then call skyramp_export_zip to export the trace, then call skyramp_ui_test_generation with the zip path.
+    2. **Manual recording**: ONLY when the user explicitly says "manual recording", "record myself", "I will interact", or "Docker trace" — use skyramp_start_trace_collection / skyramp_stop_trace_collection to let the user interact with the browser themselves.
+  - To capture an authentication session for re-use (e.g. "save session", "store login", "record auth state"): call \`skyramp_start_trace_collection\` (\`playwrightSaveStoragePath\` defaults to saving the session in \`outputDir\` — no need to set it). Tell the user to log in once and then call \`skyramp_stop_trace_collection\` IMMEDIATELY after login completes. The saved file can be passed back as \`playwrightStoragePath\` on later trace runs, or referenced as \`storageState\` in generated tests.${oneClickInstructions}
 
-## Test Management Flow
-Use \`skyramp_analyze_changes\` as the single entry point for both test recommendations and test health analysis.
+  ## Test Management Flow
+  Use \`skyramp_analyze_changes\` as the single entry point for both test recommendations and test health analysis.
 
-### Recommendations (2-step)
-1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → scans endpoints, computes branch diff, discovers existing tests → returns a \`stateFile\` **and** inline ranked test recommendations.
-2. (Optional) Use the \`skyramp_recommend_tests\` prompt with \`stateFile\` in Cursor/IDE chat for a focused recommendation view.
+  ### Recommendations (2-step)
+  1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → scans endpoints, computes branch diff, discovers existing tests → returns a \`stateFile\` **and** inline ranked test recommendations.
+  2. (Optional) Use the \`skyramp_recommend_tests\` prompt with \`stateFile\` in Cursor/IDE chat for a focused recommendation view.
 
-### Health Analysis (5-step)
-1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → returns a \`stateFile\`.
-2. Run each external test in ${runnableLanguagesText()} with \`skyramp_execute_test\`, \`phase: "before"\`, and \`stateFile\` → the server runs your command and writes the verdict back to stateFile. The tool takes no other language, and the gate in step 3 does not ask for those.
-3. Call \`skyramp_analyze_test_health\` with \`stateFile\` → runs drift analysis + health scoring + LLM semantic assessment. It refuses until step 2 has run.
-4. (Optional) Run Skyramp-generated tests with \`skyramp_execute_test\` and \`stateFile\` → writes each verdict back for health scoring.
-5. Call \`skyramp_actions\` with \`stateFile\` → executes UPDATE/REGENERATE/ADD recommendations (with execution-aware prioritization if step 4 ran).
+  ### Health Analysis (5-step)
+  1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → returns a \`stateFile\`.
+  2. Run each external test in ${runnableLanguagesText()} with \`skyramp_execute_test\`, \`phase: "before"\`, and \`stateFile\` → the server runs your command and writes the verdict back to stateFile. The tool takes no other language, and the gate in step 3 does not ask for those.
+  3. Call \`skyramp_analyze_test_health\` with \`stateFile\` → runs drift analysis + health scoring + LLM semantic assessment. It refuses until step 2 has run.
+  4. (Optional) Run Skyramp-generated tests with \`skyramp_execute_test\` and \`stateFile\` → writes each verdict back for health scoring.
+  5. Call \`skyramp_actions\` with \`stateFile\` → executes UPDATE/REGENERATE/ADD recommendations (with execution-aware prioritization if step 4 ran).
 
-After \`skyramp_analyze_changes\`, inspect enriched data via MCP Resources (use the \`sessionId\` returned in the output):
-- \`skyramp://analysis/{sessionId}/summary\` — high-level overview
-- \`skyramp://analysis/{sessionId}/endpoints\` — compact endpoint listing
-- \`skyramp://analysis/{sessionId}/endpoints/{path}\` — full path detail
-- \`skyramp://analysis/{sessionId}/endpoints/{path}/{method}\` — single method detail
-- \`skyramp://analysis/{sessionId}/scenarios\` — drafted scenarios
-- \`skyramp://analysis/{sessionId}/diff\` — branch diff context
+  After \`skyramp_analyze_changes\`, inspect enriched data via MCP Resources (use the \`sessionId\` returned in the output):
+  - \`skyramp://analysis/{sessionId}/summary\` — high-level overview
+  - \`skyramp://analysis/{sessionId}/endpoints\` — compact endpoint listing
+  - \`skyramp://analysis/{sessionId}/endpoints/{path}\` — full path detail
+  - \`skyramp://analysis/{sessionId}/endpoints/{path}/{method}\` — single method detail
+  - \`skyramp://analysis/{sessionId}/scenarios\` — drafted scenarios
+  - \`skyramp://analysis/{sessionId}/diff\` — branch diff context
 
-## Workspace Defaults for Test Generation (MANDATORY)
-Before calling ANY test generation tool, you MUST follow this flow:
+  ## Workspace Defaults for Test Generation (MANDATORY)
+  Before calling ANY test generation tool, you MUST follow this flow:
 
-1. **Read** the .skyramp/workspace.yml file to get the configured defaults.
-2. **Extract** the \`language\`, \`framework\`, \`testDirectory\`, \`api.baseUrl\`, \`api.authHeader\`, and \`api.authType\` from the matching service in the services section.
-3. **Use those values** as defaults for the test generation tool call. Pass the service \`testDirectory\` as the generation tool \`outputDir\`. Do NOT ask the user for these values if they are already configured in the workspace file.
-4. **CRITICAL — endpointURL**: The \`endpointURL\` parameter MUST be the full URL to the specific endpoint being tested, NOT just the base URL. Construct it by combining \`api.baseUrl\` with the endpoint path. Example: if \`api.baseUrl\` is \`http://localhost:8000\` and the endpoint is \`/api/v1/products\`, pass \`endpointURL: "http://localhost:8000/api/v1/products"\`. NEVER pass just the base URL (e.g. \`http://localhost:8000\`) as \`endpointURL\`.
-5. **CRITICAL — scenario generation**: When calling \`skyramp_batch_scenario_test_generation\`, ALWAYS pass:
-   - \`baseURL\`: The full base URL from \`api.baseUrl\` (e.g., \`http://localhost:3000\`). This determines the scheme, host, and port in the generated trace. Without it, the trace defaults to https:443 which is almost always wrong for local development.
-   - \`authHeader\`: Which HTTP header carries the auth credential. Get it from \`api.authHeader\` in workspace config. Examples: \`Authorization\` (Bearer/Token auth), \`X-Api-Key\` (API key auth), \`Cookie\` (session/cookie auth like NextAuth). Pass \`""\` to document the endpoint as unauthenticated in the generated test's assertions (unauthenticated endpoints or \`api.authType: "none"\`).
-   - \`authScheme\`: Only when \`authHeader\` is \`Authorization\`. The prefix before the token (e.g., \`"Bearer"\` → \`Authorization: Bearer <token>\`). **Derive from**: (1) OpenAPI spec \`securitySchemes\`/\`securityDefinitions\`, (2) source code auth middleware, (3) workspace \`api.authType\`. **Do NOT guess.**
-   - \`authToken\`: The full header value, used verbatim. When omitted, \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-generated. Only provide when the header needs a specific format (e.g., \`"session=${AUTH_PLACEHOLDER_TOKEN}"\` for Cookie). **Do NOT fabricate token values.**
-   - \`apiSchema\` is OPTIONAL — omit it for code-first apps without OpenAPI specs.
-6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`:
-   - If workspace has \`api.authType\` set: omit auth params entirely — passing auth here alongside workspace \`authType\` causes "${AUTH_CONFLICT_ERROR_MSG}".
-   - If workspace has no \`api.authType\`: pass \`authHeader\` only (no \`authScheme\`).
-7. **If the workspace file does not exist**, or the needed values (language, framework, testDirectory) are missing from the workspace config, ASK the user which language, framework, and outputDir they want before calling the tool.
-8. The user can always override workspace defaults by explicitly specifying values in their request.
-`,
-});
-// Register prompts
-logger.info("Starting prompt registration process");
-const prompts = [
-    registerStartTraceCollectionPrompt,
-    registerRecommendTestsPrompt,
-    registerTraceRecordingPrompt,
-];
-if (isTestbotEnabled()) {
-    prompts.push(registerTestbotPrompt);
-    registerTestbotResource(server);
-    logger.info("Testbot prompt enabled via SKYRAMP_FEATURE_TESTBOT");
-    registerSutSetupResource(server);
-    logger.info("Testbot SUT setup resource enabled via SKYRAMP_FEATURE_TESTBOT");
-}
-if (isLocalDevEnabled()) {
-    prompts.push(registerLocalDevPrompt);
-    logger.info("Local-dev prompt enabled via SKYRAMP_FEATURE_LOCAL_DEV");
-}
-prompts.forEach((registerPrompt) => registerPrompt(server));
-logger.info("All prompts registered successfully");
-// Register test generation tools
-const testGenerationTools = [
-    registerSmokeTestTool,
-    registerFuzzTestTool,
-    registerContractTestTool,
-    registerLoadTestTool,
-    registerIntegrationTestTool,
-    registerE2ETestTool,
-    registerUITestTool,
-    registerBatchScenarioTestTool,
-    registerMockTool,
-    registerBatchMockTool,
-];
-testGenerationTools.forEach((registerTool) => registerTool(server));
-// Register modularization and code quality tools
-const codeQualityTools = [
-    registerModularizationTool,
-    registerCodeReuseTool,
-    registerEnhanceAssertionsTool,
-    registerAssertionVerifyTool,
-    registerVerifyTestDependenciesTool,
-];
-// With the Skyramp plugin loaded the agent already has the
-// fix-test-import-errors skill; the tool would be a second copy of
-// the same text (SKYR-4296).
-if (!isSkillsLoaded()) {
-    // Same reasoning as fix-test-import-errors: with the plugin loaded the agent
-    // has the validate-assertion-alignment-post-execution skill directly; this
-    // tool exists so an agent without skill support still gets the same
-    // procedure, rendered from the same markdown with real arguments filled in.
-    codeQualityTools.push(registerFixErrorTool, registerAlignAssertionsTool);
-}
-else {
-    // The enhance-assertions skill drives its own snapshot step itself (SKYR-4310).
-    codeQualityTools.push(registerAssertionSnapshotTool);
-}
-codeQualityTools.forEach((registerTool) => registerTool(server));
-// Register analysis resources (MCP Resources for enriched data access)
-registerAnalysisResources(server);
-registerProgressResource(server);
-// Register unified test-management tools (replaces separate test-maintenance tools)
-registerAnalyzeChangesTool(server);
-registerAnalyzeTestHealthTool(server);
-registerActionsTool(server);
-registerRegisterTestPlanTool(server);
-registerResolveScreenTool(server);
-// Register workspace management tools
-registerInitScanWorkspaceTool(server);
-registerInitializeWorkspaceTool(server);
-// Register one-click orchestrated workflows
-if (oneClickEnabled || localDevEnabled) {
-    registerOneClickTool(server);
-    logger.info("One-click tools enabled", {
-        enabledBy: {
-            SKYRAMP_FEATURE_ONE_CLICK: oneClickEnabled,
-            SKYRAMP_FEATURE_LOCAL_DEV: localDevEnabled,
-        },
+  1. **Read** the .skyramp/workspace.yml file to get the configured defaults.
+  2. **Extract** the \`language\`, \`framework\`, \`testDirectory\`, \`api.baseUrl\`, \`api.authHeader\`, and \`api.authType\` from the matching service in the services section.
+  3. **Use those values** as defaults for the test generation tool call. Pass the service \`testDirectory\` as the generation tool \`outputDir\`. Do NOT ask the user for these values if they are already configured in the workspace file.
+  4. **CRITICAL — endpointURL**: The \`endpointURL\` parameter MUST be the full URL to the specific endpoint being tested, NOT just the base URL. Construct it by combining \`api.baseUrl\` with the endpoint path. Example: if \`api.baseUrl\` is \`http://localhost:8000\` and the endpoint is \`/api/v1/products\`, pass \`endpointURL: "http://localhost:8000/api/v1/products"\`. NEVER pass just the base URL (e.g. \`http://localhost:8000\`) as \`endpointURL\`.
+  5. **CRITICAL — scenario generation**: When calling \`skyramp_batch_scenario_test_generation\`, ALWAYS pass:
+     - \`baseURL\`: The full base URL from \`api.baseUrl\` (e.g., \`http://localhost:3000\`). This determines the scheme, host, and port in the generated trace. Without it, the trace defaults to https:443 which is almost always wrong for local development.
+     - \`authHeader\`: Which HTTP header carries the auth credential. Get it from \`api.authHeader\` in workspace config. Examples: \`Authorization\` (Bearer/Token auth), \`X-Api-Key\` (API key auth), \`Cookie\` (session/cookie auth like NextAuth). Pass \`""\` to document the endpoint as unauthenticated in the generated test's assertions (unauthenticated endpoints or \`api.authType: "none"\`).
+     - \`authScheme\`: Only when \`authHeader\` is \`Authorization\`. The prefix before the token (e.g., \`"Bearer"\` → \`Authorization: Bearer <token>\`). **Derive from**: (1) OpenAPI spec \`securitySchemes\`/\`securityDefinitions\`, (2) source code auth middleware, (3) workspace \`api.authType\`. **Do NOT guess.**
+     - \`authToken\`: The full header value, used verbatim. When omitted, \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-generated. Only provide when the header needs a specific format (e.g., \`"session=${AUTH_PLACEHOLDER_TOKEN}"\` for Cookie). **Do NOT fabricate token values.**
+     - \`apiSchema\` is OPTIONAL — omit it for code-first apps without OpenAPI specs.
+  6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`:
+     - If workspace has \`api.authType\` set: omit auth params entirely — passing auth here alongside workspace \`authType\` causes "${AUTH_CONFLICT_ERROR_MSG}".
+     - If workspace has no \`api.authType\`: pass \`authHeader\` only (no \`authScheme\`).
+  7. **If the workspace file does not exist**, or the needed values (language, framework, testDirectory) are missing from the workspace config, ASK the user which language, framework, and outputDir they want before calling the tool.
+  8. The user can always override workspace defaults by explicitly specifying values in their request.
+  `,
     });
-}
-// Register other Skyramp tools
-const infrastructureTools = [
-    registerLoginTool,
-    registerLogoutTool,
-    registerExecuteSkyrampTestTool,
-    registerTraceTool,
-    registerTraceStopTool,
-];
-if (isLocalDevEnabled()) {
-    infrastructureTools.push(registerEnrichTestWithMocksTool, registerPreflightMockCheckTool, registerGenerateEnrichedIntegrationTestTool, registerLocalDevWorkerComposeTool, registerQueryProxyMocksTool);
-    logger.info("Local-dev tools enabled via SKYRAMP_FEATURE_LOCAL_DEV");
-}
-if (isTestbotEnabled()) {
-    infrastructureTools.push(registerSubmitReportTool);
-    logger.info("Testbot tools enabled via SKYRAMP_FEATURE_TESTBOT");
-}
-infrastructureTools.forEach((registerTool) => registerTool(server));
-// Register Playwright browser tools (trace recording via browser automation).
-//
-// Tell the capture which attribute this repository uses for test ids. Without
-// it the capture assumes Playwright's `data-testid`, and a repo using anything
-// else gets no test-id anchor and a positional xpath for every element — which
-// resolves at capture time and breaks later, so the miss never announces itself
-// (SKYR-4136). This server is the only component that knows which repository it
-// is running against.
-//
-// A declared `use.testIdAttribute` is authoritative. Failing that, the
-// repository's own tests name the attribute whenever they select on it, so read
-// it out of their selectors rather than guessing from a list of popular names.
-// Never fatal: no answer leaves the capture on Playwright's default.
-(async () => {
-    let testIdAttribute;
-    try {
-        const root = await findRoot(process.cwd());
-        testIdAttribute = await readTestIdAttribute(root);
-        if (testIdAttribute) {
-            logger.info(`testIdAttribute declared by the Playwright config: ${testIdAttribute}`);
-        }
-        else {
-            const discovered = await discoverTestIdAttribute(root);
-            testIdAttribute = discovered.attribute;
+    // Register prompts
+    logger.info("Starting prompt registration process");
+    const prompts = [
+        registerStartTraceCollectionPrompt,
+        registerRecommendTestsPrompt,
+        registerTraceRecordingPrompt,
+    ];
+    if (isTestbotEnabled()) {
+        prompts.push(registerTestbotPrompt);
+        registerTestbotResource(server);
+        logger.info("Testbot prompt enabled via SKYRAMP_FEATURE_TESTBOT");
+        registerSutSetupResource(server);
+        logger.info("Testbot SUT setup resource enabled via SKYRAMP_FEATURE_TESTBOT");
+    }
+    if (isLocalDevEnabled()) {
+        prompts.push(registerLocalDevPrompt);
+        logger.info("Local-dev prompt enabled via SKYRAMP_FEATURE_LOCAL_DEV");
+    }
+    prompts.forEach((registerPrompt) => registerPrompt(server));
+    logger.info("All prompts registered successfully");
+    // Register test generation tools
+    const testGenerationTools = [
+        registerSmokeTestTool,
+        registerFuzzTestTool,
+        registerContractTestTool,
+        registerLoadTestTool,
+        registerIntegrationTestTool,
+        registerE2ETestTool,
+        registerUITestTool,
+        registerUILoadTestTool,
+        registerBatchScenarioTestTool,
+        registerMockTool,
+        registerBatchMockTool,
+    ];
+    testGenerationTools.forEach((registerTool) => registerTool(server));
+    // Register modularization and code quality tools
+    const codeQualityTools = [
+        registerModularizationTool,
+        registerCodeReuseTool,
+        registerEnhanceAssertionsTool,
+        registerAssertionVerifyTool,
+        registerVerifyTestDependenciesTool,
+    ];
+    // With the Skyramp plugin loaded the agent already has the
+    // fix-test-import-errors skill; the tool would be a second copy of
+    // the same text (SKYR-4296).
+    if (!isSkillsLoaded()) {
+        // Same reasoning as fix-test-import-errors: with the plugin loaded the agent
+        // has the validate-assertion-alignment-post-execution skill directly; this
+        // tool exists so an agent without skill support still gets the same
+        // procedure, rendered from the same markdown with real arguments filled in.
+        codeQualityTools.push(registerFixErrorTool, registerAlignAssertionsTool);
+    }
+    else {
+        // The enhance-assertions skill drives its own snapshot step itself (SKYR-4310).
+        codeQualityTools.push(registerAssertionSnapshotTool);
+    }
+    codeQualityTools.forEach((registerTool) => registerTool(server));
+    // Register analysis resources (MCP Resources for enriched data access)
+    registerAnalysisResources(server);
+    registerProgressResource(server);
+    // Register unified test-management tools (replaces separate test-maintenance tools)
+    registerAnalyzeChangesTool(server);
+    registerAnalyzeTestHealthTool(server);
+    registerActionsTool(server);
+    registerRegisterTestPlanTool(server);
+    registerResolveScreenTool(server);
+    // Register workspace management tools
+    registerInitScanWorkspaceTool(server);
+    registerInitializeWorkspaceTool(server);
+    // Register one-click orchestrated workflows
+    if (oneClickEnabled || localDevEnabled) {
+        registerOneClickTool(server);
+        logger.info("One-click tools enabled", {
+            enabledBy: {
+                SKYRAMP_FEATURE_ONE_CLICK: oneClickEnabled,
+                SKYRAMP_FEATURE_LOCAL_DEV: localDevEnabled,
+            },
+        });
+    }
+    // Register other Skyramp tools
+    const infrastructureTools = [
+        registerLoginTool,
+        registerLogoutTool,
+        registerExecuteSkyrampTestTool,
+        registerExecuteFleetTool,
+        registerTraceTool,
+        registerTraceStopTool,
+    ];
+    if (isLocalDevEnabled()) {
+        infrastructureTools.push(registerEnrichTestWithMocksTool, registerPreflightMockCheckTool, registerGenerateEnrichedIntegrationTestTool, registerLocalDevWorkerComposeTool, registerQueryProxyMocksTool);
+        logger.info("Local-dev tools enabled via SKYRAMP_FEATURE_LOCAL_DEV");
+    }
+    if (isTestbotEnabled()) {
+        infrastructureTools.push(registerSubmitReportTool);
+        logger.info("Testbot tools enabled via SKYRAMP_FEATURE_TESTBOT");
+    }
+    infrastructureTools.forEach((registerTool) => registerTool(server));
+    // Register Playwright browser tools (trace recording via browser automation).
+    //
+    // Tell the capture which attribute this repository uses for test ids. Without
+    // it the capture assumes Playwright's `data-testid`, and a repo using anything
+    // else gets no test-id anchor and a positional xpath for every element — which
+    // resolves at capture time and breaks later, so the miss never announces itself
+    // (SKYR-4136). This server is the only component that knows which repository it
+    // is running against.
+    //
+    // A declared `use.testIdAttribute` is authoritative. Failing that, the
+    // repository's own tests name the attribute whenever they select on it, so read
+    // it out of their selectors rather than guessing from a list of popular names.
+    // Never fatal: no answer leaves the capture on Playwright's default.
+    //
+    // Awaited, and worth the wait: `PlaywrightTraceService.initialize()` is 206ms
+    // of it and the browser tools come out of that service, so nothing can
+    // register them earlier. Running it in the background instead delays every
+    // connection's first response by nothing but leaves the client holding 27
+    // tools of 52 — Claude Code does not re-list on `tools/list_changed`, so all
+    // 23 `browser_*` tools stay invisible for the whole run.
+    await (async () => {
+        let testIdAttribute;
+        try {
+            const root = await findRoot(process.cwd());
+            testIdAttribute = await readTestIdAttribute(root);
             if (testIdAttribute) {
-                // Log the runner-up counts: on a part-migrated repo the most-used
-                // attribute wins, and a wrong pick should be visible here rather than
-                // showing up later as brittle selectors.
-                logger.info(`testIdAttribute discovered from test selectors: ${testIdAttribute}`, { counts: discovered.counts, filesScanned: discovered.filesScanned });
+                logger.info(`testIdAttribute declared by the Playwright config: ${testIdAttribute}`);
             }
             else {
-                // No name rule can reach an arbitrary convention like `xyz-id`, so name
-                // what the selectors did contain and the variable that overrides it.
-                // Editing the repo's own Playwright config is the wrong instruction: a
-                // suite may have several, and none of them at the root.
-                logger.info("No testIdAttribute declared or discovered — capture stays on Playwright's data-testid. " +
-                    "Set PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE to override.", {
-                    attributesSeenInSelectors: discovered.observed,
-                    filesScanned: discovered.filesScanned,
-                });
+                const discovered = await discoverTestIdAttribute(root);
+                testIdAttribute = discovered.attribute;
+                if (testIdAttribute) {
+                    // Log the runner-up counts: on a part-migrated repo the most-used
+                    // attribute wins, and a wrong pick should be visible here rather than
+                    // showing up later as brittle selectors.
+                    logger.info(`testIdAttribute discovered from test selectors: ${testIdAttribute}`, {
+                        counts: discovered.counts,
+                        filesScanned: discovered.filesScanned,
+                    });
+                }
+                else {
+                    // No name rule can reach an arbitrary convention like `xyz-id`, so name
+                    // what the selectors did contain and the variable that overrides it.
+                    // Editing the repo's own Playwright config is the wrong instruction: a
+                    // suite may have several, and none of them at the root.
+                    logger.info("No testIdAttribute declared or discovered — capture stays on Playwright's data-testid. " +
+                        "Set PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE to override.", {
+                        attributesSeenInSelectors: discovered.observed,
+                        filesScanned: discovered.filesScanned,
+                    });
+                }
             }
         }
-    }
-    catch (err) {
-        logger.warning("Could not determine this repository's testIdAttribute", {
-            error: err,
+        catch (err) {
+            logger.warning("Could not determine this repository's testIdAttribute", {
+                error: err,
+            });
+        }
+        await registerPlaywrightTools(server, { testIdAttribute });
+    })().catch((err) => {
+        logger.error("Failed to register Playwright tools", { error: err });
+    });
+    const runInitTrigger = () => {
+        registerInitTriggerOnMCPInitialized().catch((err) => {
+            logger.error("Failed to run MCP initialized trigger", { error: err });
         });
-    }
-    await registerPlaywrightTools(server, { testIdAttribute });
-})().catch((err) => {
-    logger.error("Failed to register Playwright tools", { error: err });
-});
+    };
+    server.server.oninitialized = runInitTrigger;
+    // A 2026-07-28 connection has no `initialize` exchange, so `oninitialized`
+    // never fires on it.
+    if (era === "modern")
+        runInitTrigger();
+    return server;
+}
 // Global error handlers for crash telemetry
 process.on("uncaughtException", async (error) => {
     // Don't send analytics for EPIPE errors
@@ -350,13 +381,11 @@ process.on("unhandledRejection", async (reason) => {
 });
 // Start MCP server
 async function main() {
-    const transport = new StdioServerTransport();
-    server.server.oninitialized = () => {
-        registerInitTriggerOnMCPInitialized().catch((err) => {
-            logger.error("Failed to run MCP initialized trigger", { error: err });
-        });
-    };
-    await server.connect(transport);
+    // `serveStdio` owns the era decision: it reads the opening exchange and pins
+    // one instance from the factory for the connection. `StdioServerTransport`
+    // serves the 2025 handshake only, so the 2026-07-28 revision is unreachable
+    // through it however the client asks.
+    const handle = serveStdio(createServer);
     logger.info("MCP Server started successfully");
     // Listen for stdin closure (parent process disconnected)
     // Using multiple events for robustness across different disconnection scenarios
@@ -372,7 +401,7 @@ async function main() {
             ? playwrightService.shutdown().catch(() => { })
             : Promise.resolve();
         cleanupPlaywright.finally(() => {
-            server.close().finally(() => {
+            handle.close().finally(() => {
                 process.exit(0);
             });
         });

package/build/playwright/PlaywrightTraceService.d.ts

@@ -5,7 +5,7 @@
  * The Playwright fork is CJS; this project is ESM. We use createRequire
  * to bridge the module systems.
  */
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult } from "@modelcontextprotocol/server";
 interface McpTool {
     name: string;
     description?: string;

package/build/playwright/blueprintDigestStore.d.ts

@@ -1,4 +1,4 @@
-import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult } from "@modelcontextprotocol/server";
 import type { BlueprintCaptureDigest } from "../types/BlueprintDigest.js";
 /** A run that takes more captures than this has a browsing problem of its own;
  *  the cap is here so a runaway loop cannot grow the process without bound. */

package/build/playwright/registerPlaywrightTools.d.ts

@@ -3,6 +3,6 @@
  * tools in the Skyramp MCP server, delegating calls to PlaywrightTraceService.
  */
 import { PlaywrightTraceService, type PlaywrightTraceOptions } from "./PlaywrightTraceService.js";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 export declare function getPlaywrightTraceService(): PlaywrightTraceService | null;
 export declare function registerPlaywrightTools(server: McpServer, options?: PlaywrightTraceOptions): Promise<void>;

package/build/playwright/traceRecordingPrompt.d.ts

@@ -2,7 +2,7 @@
  * MCP prompt that guides the LLM through the Playwright-based trace recording
  * and Skyramp test generation flow.
  */
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 export interface TraceRecordingPromptOpts {
     /** Directory where zip files should be written. Defaults to same dir as test file. */
     outputDir?: string;

package/build/playwright/traceRecordingPrompt.js

@@ -5,6 +5,7 @@
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { getPersonaPrefix } from "../prompts/personas.js";
+import { ORDER_ASSERTION_RULE } from "../prompts/orderAssertionRule.js";
 export function getTraceRecordingPromptText(opts) {
     const outputDir = opts?.outputDir;
     const modularize = opts?.modularize ?? true;
@@ -65,7 +66,7 @@ Call \`browser_assert\` when assertions are needed. Provide \`expected\` for eve
 
 **Visual / screenshot assertions.** When the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (as opposed to its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline image on every run.
 
-**When the change under test is how something looks** — a colour, class or attribute the diff changes — assert it directly with \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children); if it has no stable ref, note a recording gap rather than assert the wrong element. Order has no kind: \`flex-direction\` when the diff flipped it, else a \`boundingBox()\` comparison at enhance. \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
+**When the change under test is how something looks** — a colour, class or attribute the diff changes — assert it directly with \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children); if it has no stable ref, note a recording gap rather than assert the wrong element. ${ORDER_ASSERTION_RULE} \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
 
 Do NOT use \`browser_take_screenshot\` to record a visual check: it only captures a throwaway image, is dropped at export (it produces no assertion), and will NOT appear in the generated test. Use it only to view the page yourself while recording. \`filename\` is optional on \`browser_visual_snapshot\`: if the instruction names a baseline file (e.g. \`page-001.png\`) pass it as \`filename\`, otherwise omit it and one is auto-generated per \`snapshotType\` (\`page-NNN.png\` for a page, \`el-NNN.png\` for an element, \`region-NNN.png\` for a region).
 
@@ -81,7 +82,7 @@ export function registerTraceRecordingPrompt(server) {
     logger.info("Registering trace recording prompt");
     server.registerPrompt("skyramp_trace_recording_prompt", {
         description: "Guide for recording browser interactions as a Skyramp trace and generating UI tests",
-        argsSchema: {
+        argsSchema: z.object({
             outputDir: z
                 .string()
                 .optional()
@@ -91,7 +92,7 @@ export function registerTraceRecordingPrompt(server) {
                 .default(true)
                 .optional()
                 .describe("Whether to run skyramp_modularization after generation. Default: true. Set to false in CI."),
-        },
+        }),
     }, (args) => ({
         messages: [
             {

package/build/prompts/local-dev/local-dev-prompts.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer } from "@modelcontextprotocol/server";
 import { type Service } from "../../workspace/workspace.js";
 export declare function getLocalDevPrompt(baseCommit: string, repositoryPath: string, repository: string, sandboxWorkerUrl?: string, maxRecommendations?: number, maxGenerate?: number, services?: Service[], stateOutputFile?: string, servicesToMock?: string[], realServices?: string[], mockProtocols?: string[], proxyKubeconfig?: string, proxyNamespace?: string): string;
 export declare function registerLocalDevPrompt(server: McpServer): void;

package/build/prompts/local-dev/local-dev-prompts.js

@@ -121,7 +121,7 @@ export function registerLocalDevPrompt(server) {
     logger.info("Registering local-dev prompt");
     server.registerPrompt("skyramp_local_dev", {
         description: "Run Skyramp local-dev workflow: diff from a base commit, discover downstream dependencies, document mock requirements, generate mocks and backend tests, execute them against a local environment, and report results.",
-        argsSchema: {
+        argsSchema: z.object({
             baseCommit: z
                 .string()
                 .describe("Base commit reference to diff against — accepts a branch name (e.g. 'main'), a commit SHA (e.g. 'abc123f'), or a tag (e.g. 'v1.2.0'). The diff is computed between this ref and the current working tree (committed plus uncommitted changes)."),
@@ -167,7 +167,7 @@ export function registerLocalDevPrompt(server) {
                 .string()
                 .optional()
                 .describe("Comma-separated list of downstream service names that are already running locally and should receive real traffic (e.g. 'postgres,redis,envoy'). These will NOT be mocked."),
-        },
+        }),
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
         // skyramp_analyze_changes and skyramp_execute_test both name their repository

package/build/prompts/orderAssertionRule.d.ts

@@ -0,0 +1,9 @@
+/**
+ * When to record a swap, move or reorder as an order assertion. It lives in the
+ * trace-recording prompt, which the testbot flow includes; the top-level testbot
+ * prompt does not repeat test-type details. The type's parameters are
+ * documented by browser_assert's own description, and the pairing rule (two
+ * sibling blocks, not a block and something inside it) is enforced and
+ * explained by the tool, so neither is repeated here.
+ */
+export declare const ORDER_ASSERTION_RULE = "**A swap, move or reorder** (left/right columns swapped, a sidebar moved, blocks reordered) is recorded with `browser_assert` `type: \"order\"` on two blocks (`ref` and `otherRef`), so the test fails if the swap is undone; `flex-direction` alone is not enough when the diff reorders markup.";

package/build/prompts/orderAssertionRule.js

@@ -0,0 +1,9 @@
+/**
+ * When to record a swap, move or reorder as an order assertion. It lives in the
+ * trace-recording prompt, which the testbot flow includes; the top-level testbot
+ * prompt does not repeat test-type details. The type's parameters are
+ * documented by browser_assert's own description, and the pairing rule (two
+ * sibling blocks, not a block and something inside it) is enforced and
+ * explained by the tool, so neither is repeated here.
+ */
+export const ORDER_ASSERTION_RULE = '**A swap, move or reorder** (left/right columns swapped, a sidebar moved, blocks reordered) is recorded with `browser_assert` `type: "order"` on two blocks (`ref` and `otherRef`), so the test fails if the swap is undone; `flex-direction` alone is not enough when the diff reorders markup.';