Skip to content

Commit aaa065c

Browse files
WinifyWinify
committed
docs: Simplify CLAUDE.md directory structure overview and update environment/extension points
1 parent 447e266 commit aaa065c

1 file changed

Lines changed: 30 additions & 65 deletions

File tree

‎CLAUDE.md‎

Lines changed: 30 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -15,65 +15,22 @@ npm start # Run built server from lib/server.js
1515

1616
```
1717
src/
18-
├── server.ts # MCP server entry, registers all tools + MCP resources
19-
├── session/
20-
│ ├── state.ts # Session state maps, getBrowser(), getState(), SessionMetadata
21-
│ └── lifecycle.ts # registerSession(), handleSessionTransition(), closeSession()
22-
├── providers/
23-
│ ├── types.ts # SessionProvider interface, ConnectionConfig
24-
│ ├── local-browser.provider.ts # Chrome/Firefox/Edge/Safari capability building
25-
│ └── local-appium.provider.ts # iOS/Android via appium.config.ts
26-
├── tools/
27-
│ ├── session.tool.ts # start_session (browser+mobile), close_session
28-
│ ├── tabs.tool.ts # switch_tab
29-
│ ├── launch-chrome.tool.ts # launch_chrome (remote debugging)
30-
│ ├── navigate.tool.ts # navigateAction() + navigateTool
31-
│ ├── click.tool.ts # clickAction() + clickTool
32-
│ ├── set-value.tool.ts # setValueAction() + setValueTool
33-
│ ├── scroll.tool.ts # scrollAction() + scrollTool
34-
│ ├── gestures.tool.ts # tapAction(), swipeAction(), dragAndDropAction()
35-
│ ├── context.tool.ts # switch_context (native/webview)
36-
│ ├── device.tool.ts # rotate_device, hide_keyboard
37-
│ ├── emulate-device.tool.ts # emulate_device (viewport/UA)
38-
│ ├── cookies.tool.ts # set_cookie, delete_cookies
39-
│ ├── execute-script.tool.ts # execute_script
40-
│ ├── get-elements.tool.ts # get_elements (all elements, incl. below fold)
41-
│ └── ... # Other tools follow same pattern
42-
├── resources/
43-
│ ├── index.ts # ResourceDefinition exports
44-
│ ├── sessions.resource.ts # wdio://sessions, wdio://session/*/steps, wdio://session/*/code
45-
│ ├── elements.resource.ts # wdio://session/current/elements
46-
│ ├── accessibility.resource.ts# wdio://session/current/accessibility
47-
│ ├── screenshot.resource.ts # wdio://session/current/screenshot
48-
│ ├── cookies.resource.ts # wdio://session/current/cookies
49-
│ ├── tabs.resource.ts # wdio://session/current/tabs
50-
│ ├── contexts.resource.ts # wdio://session/current/contexts
51-
│ ├── app-state.resource.ts # wdio://session/current/app-state
52-
│ └── geolocation.resource.ts # wdio://session/current/geolocation
53-
├── recording/
54-
│ ├── step-recorder.ts # withRecording HOF, appendStep, session history access
55-
│ └── code-generator.ts # SessionHistory → WebdriverIO JS code
56-
├── scripts/
57-
│ ├── get-interactable-browser-elements.ts # Browser-context element detection
58-
│ ├── get-browser-accessibility-tree.ts # Browser-context accessibility tree
59-
│ ├── get-visible-mobile-elements.ts # Mobile visible element detection
60-
│ └── get-elements.ts # Filter + paginate elements (used by tool + resource)
61-
├── locators/
62-
│ ├── element-filter.ts # Platform-specific element classification
63-
│ ├── locator-generation.ts # Multi-strategy selector generation
64-
│ ├── xml-parsing.ts # XML page source parsing for mobile
65-
│ ├── constants.ts # Shared locator constants
66-
│ ├── types.ts # Locator type definitions
67-
│ └── index.ts # Public exports
68-
├── config/
69-
│ └── appium.config.ts # iOS/Android capability builders (used by local-appium.provider)
70-
├── utils/
71-
│ ├── parse-variables.ts # URI template variable parsing (parseBool, parseNumber, etc.)
72-
│ └── zod-helpers.ts # coerceBoolean and other Zod utilities
73-
└── types/
74-
├── tool.ts # ToolDefinition interface
75-
├── resource.ts # ResourceDefinition interface
76-
└── recording.ts # RecordedStep, SessionHistory interfaces
18+
├── server.ts # MCP server entry — registers all tools + resources
19+
├── session/ # Session state (state.ts) + lifecycle (lifecycle.ts)
20+
├── providers/ # SessionProvider implementations
21+
│ ├── registry.ts # getProvider() — routes to local or cloud provider
22+
│ ├── local-browser.provider.ts # Chrome/Firefox/Edge/Safari
23+
│ ├── local-appium.provider.ts # iOS/Android via Appium
24+
│ └── cloud/
25+
│ └── browserstack.provider.ts # BrowserStack (browser + App Automate)
26+
├── tools/ # One file per MCP tool (see Tool Pattern below)
27+
├── resources/ # One file per MCP resource (see Recording below)
28+
├── recording/ # step-recorder.ts (withRecording HOF) + code-generator.ts
29+
├── scripts/ # Browser/mobile scripts executed via browser.execute() — no try/catch, raw data only
30+
├── locators/ # Element detection, selector generation, XML parsing (mobile)
31+
├── config/ # appium.config.ts — iOS/Android capability builders
32+
├── utils/ # parse-variables.ts, zod-helpers.ts (coerceBoolean)
33+
└── types/ # ToolDefinition, ResourceDefinition, RecordedStep interfaces
7734
```
7835

7936
### Session State
@@ -157,12 +114,12 @@ MCP resources expose live session data — all at fixed URIs discoverable via Li
157114
| `src/server.ts` | MCP server init, tool + resource registration |
158115
| `src/session/state.ts` | Session state maps, `getBrowser()`, `getState()` |
159116
| `src/session/lifecycle.ts` | `registerSession()`, `closeSession()`, session transitions |
117+
| `src/providers/registry.ts` | `getProvider()` — routes to local or cloud provider |
118+
| `src/providers/cloud/browserstack.provider.ts` | BrowserStack session provider |
160119
| `src/tools/session.tool.ts` | `start_session` (browser + mobile), `close_session` |
161-
| `src/tools/tabs.tool.ts` | `switch_tab` |
162120
| `src/tools/get-elements.tool.ts` | `get_elements` — all elements with filtering + pagination |
163-
| `src/resources/` | All MCP resource definitions (10 files) |
164-
| `src/providers/local-browser.provider.ts` | Chrome/Firefox/Edge/Safari capability building |
165-
| `src/providers/local-appium.provider.ts` | iOS/Android capabilities via appium.config.ts |
121+
| `src/tools/browserstack.tool.ts` | `list_apps`, `upload_app` — BrowserStack App Automate |
122+
| `src/resources/` | All MCP resource definitions (12 files) |
166123
| `src/scripts/get-interactable-browser-elements.ts` | Browser-context element detection |
167124
| `src/locators/` | Mobile element detection + locator generation |
168125
| `src/recording/step-recorder.ts` | `withRecording(toolName, cb)` HOF — wraps tools for step logging |
@@ -234,9 +191,17 @@ catch (e) {
234191
- iOS Predicate: `-ios predicate string:label == "Login"`
235192
- XPath: `//XCUIElementTypeButton[@label="Login"]`
236193

194+
## Environment
195+
196+
| Variable | Required for |
197+
|----------|-------------|
198+
| `BROWSERSTACK_USERNAME` | BrowserStack sessions + tools |
199+
| `BROWSERSTACK_ACCESS_KEY` | BrowserStack sessions + tools |
200+
237201
## Planned Improvements
238202

239203
See `docs/architecture/` for proposals:
240204

241-
- `session-configuration-proposal.md` — Cloud provider pattern (BrowserStack, SauceLabs) — providers/types.ts is the extension point
242-
- `multi-session-proposal.md` — Parallel sessions for sub-agent coordination
205+
- `session-configuration-proposal.md` — Cloud provider pattern (SauceLabs etc.) — BrowserStack already implemented; `providers/registry.ts` + `providers/cloud/` is the extension point
206+
- `multi-session-proposal.md` — Parallel sessions for sub-agent coordination
207+
- `interaction-sequencing-proposal.md` — Sequencing model for tool interactions

0 commit comments

Comments
 (0)