Peekaboo/.cursor/rules/mcp-inspector.mdc

---
description: 
globs: 
alwaysApply: false
---
Rule Name: mcp-inspector
Description: Debugging and verifying the `macos-automator-mcp` server via the MCP Inspector, using Playwright for UI automation and direct terminal commands for server management. This rule prioritizes stability and detailed verification through Playwright's introspection capabilities.

**Required Tools:**
- `run_terminal_cmd`
- `mcp_playwright_browser_navigate`
- `mcp_playwright_browser_type`
- `mcp_playwright_browser_click`
- `mcp_playwright_browser_snapshot`
- `mcp_playwright_browser_console_messages`
- `mcp_playwright_browser_wait_for`

**User Workspace Path Placeholder:**
- The path to the `start.sh` script will be specified as `[WORKSPACE_PATH]/start.sh`.
- The AI assistant executing this rule **MUST** replace `[WORKSPACE_PATH]` with the absolute path to the user's current project workspace (e.g., as found in the `<user_info>` context block during rule execution).
- Example of a resolved path if the workspace is `/Users/username/Projects/my-mcp-project`: `/Users/username/Projects/my-mcp-project/start.sh`.

---
**Main Flow:**

**Phase 1: Start MCP Inspector Server**
1.  **Kill Existing Inspector Processes:**
    *   Action: Call `run_terminal_cmd`.
    *   `command`: `pkill -f 'npx @modelcontextprotocol/inspector' || true`
    *   `is_background`: `false`
    *   Expected: Cleans up any lingering Inspector processes.
2.  **Start New Inspector Process:**
    *   Action: Call `run_terminal_cmd`.
    *   `command`: `npx @modelcontextprotocol/inspector`
    *   `is_background`: `true`
    *   Expected: MCP Inspector starts in the background.
3.  **Wait for Inspector Initialization:**
    *   Action: Call `mcp_playwright_browser_wait_for`.
    *   `time`: `10` (seconds)
    *   Expected: Allows ample time for the Inspector server to be ready. This step requires an active Playwright page, so it's implicitly preceded by navigation in Phase 2 if the browser isn't already open.

**Phase 2: Connect to Server via Playwright**
1.  **Navigate to Inspector URL:**
    *   Action: Call `mcp_playwright_browser_navigate`.
    *   `url`: `http://127.0.0.1:6274`
    *   Expected: Playwright opens the MCP Inspector web UI.
    *   Snapshot: Take a snapshot (`mcp_playwright_browser_snapshot`) to confirm page load and identify initial form element references (`ref`).
2.  **Fill Form (Command & Args only):**
    *   **Set Command:**
        *   Action: Call `mcp_playwright_browser_type`.
        *   `element`: "Command textbox" (Obtain `ref` from snapshot).
        *   `text`: `macos-automator-mcp`
    *   **Set Arguments:**
        *   Action: Call `mcp_playwright_browser_type`.
        *   `element`: "Arguments textbox" (Obtain `ref` from snapshot).
        *   `text`: `[WORKSPACE_PATH]/start.sh` (This placeholder MUST be replaced by the AI executing the rule with the absolute path to the user's current workspace).
    *   *(Note: Environment Variables are skipped in this flow for simplicity and stability, as issues were previously observed when setting LOG_LEVEL=DEBUG during connection.)*
3.  **Click "Connect":**
    *   Action: Call `mcp_playwright_browser_click`.
    *   `element`: "Connect button" (Obtain `ref` from snapshot).
    *   Expected: Connection to the `macos-automator-mcp` server is established.
    *   Snapshot: Take a snapshot. Verify connection status (e.g., text changes to "Connected") and check for initial server logs in the UI.

**Phase 3: Interact with a Tool via Playwright**
1.  **List Tools:**
    *   Action: Call `mcp_playwright_browser_click`.
    *   `element`: "List Tools button" (Obtain `ref` from the latest snapshot).
    *   Expected: The list of available tools from the `macos-automator-mcp` server is displayed.
    *   Snapshot: Take a snapshot. Verify tools like `execute_script` and `get_scripting_tips` are visible.
2.  **Select 'get_scripting_tips' Tool:**
    *   Action: Call `mcp_playwright_browser_click`.
    *   `element`: "get_scripting_tips tool in list" (Obtain `ref` by identifying it in the snapshot's tool list).
    *   Expected: The parameters form for `get_scripting_tips` is displayed in the right-hand panel.
    *   Snapshot: Take a snapshot. Verify the right panel shows details for `get_scripting_tips` (e.g., its name, description, and parameter fields like 'searchTerm', 'listCategories', etc.).
3.  **Execute 'get_scripting_tips' (default parameters):**
    *   Action: Call `mcp_playwright_browser_click`.
    *   `element`: "Run Tool button" (Obtain `ref` for the 'Run Tool' button specific to the `get_scripting_tips` form in the right panel from the snapshot).
    *   Expected: The `get_scripting_tips` tool is executed with its default parameters.
    *   Snapshot: Take a snapshot.

**Phase 4: Verify Tool Execution and Logs in Playwright**
1.  **Check for Results in UI:**
    *   Action: Examine the latest snapshot.
    *   Look for: The results of the `get_scripting_tips` call (e.g., a list of script categories if `listCategories` was implicitly true by default, or an empty result if no default search term was run).
    *   The results should appear in the 'Result from tool' or a similarly named section within the right-hand panel where the tool's form was.
2.  **Check Console Logs (Optional but Recommended):**
    *   Action: Call `mcp_playwright_browser_console_messages`.
    *   Expected: Review for any errors or relevant messages from the Inspector or the tool interaction.
3.  **Check MCP Server Logs in UI:**
    *   Action: Examine the latest snapshot.
    *   Look for: Logs related to the `get_scripting_tips` tool execution in the main server log panel (usually bottom-left, titled "Error output from MCP server" or similar, but also shows general logs).

**Troubleshooting Notes:**
- If connection fails, check the `run_terminal_cmd` output for the Inspector to ensure it started correctly.
- Check Playwright console messages for clues.
- Ensure the `[WORKSPACE_PATH]` was correctly resolved and points to an existing `start.sh` script.
- Element `ref` values can change. Always use the latest snapshot to get correct `ref` values before an interaction.
- Shadow DOM: The MCP Inspector UI uses Shadow DOM extensively for the tool details and results panels. Playwright's default selectors should pierce Shadow DOM, but if issues arise with finding elements *within* the tool panel (right-hand side after selecting a tool), be mindful of this. The provided flow assumes Playwright's auto-piercing handles this sufficiently.