cobro-mcp 0.6.0 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -0
- package/README.ko.md +143 -139
- package/README.md +143 -139
- package/dist/overlay.js +4 -4
- package/dist/server.js +22 -3
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow [SemVer](https://semver.org/).
|
|
4
4
|
|
|
5
|
+
## [0.6.1] — 2026-09-18
|
|
6
|
+
### Added
|
|
7
|
+
- README: demo GIF of the core loop (pick → note → Send → done) and a note that React 19 reports `react.component` without `source`.
|
|
8
|
+
### Changed
|
|
9
|
+
- `close` deletes screenshots of finished batches and the manual screenshot folder; manual screenshots are capped at 50 during a session.
|
|
10
|
+
### Fixed
|
|
11
|
+
- Light theme: the pick-mode hover badge (selector + size) rendered white-on-white; it now uses a dark text color.
|
|
12
|
+
|
|
5
13
|
## [0.6.0] — 2026-09-17
|
|
6
14
|
### Added
|
|
7
15
|
- README: `Payload` section — field rules and an example of what `wait` returns after Send.
|
package/README.ko.md
CHANGED
|
@@ -1,139 +1,143 @@
|
|
|
1
|
-
# Cobro (`cobro-mcp`)
|
|
2
|
-
|
|
3
|
-
> English: [README.md](README.md)
|
|
4
|
-
|
|
5
|
-
**Meet Cobro: Your Co-Agent, Your Browser.**
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
|
39
|
-
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
`wait
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
"
|
|
67
|
-
"
|
|
68
|
-
"
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
}
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `elements[].
|
|
97
|
-
| `elements[].
|
|
98
|
-
| `elements[].
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
1
|
+
# Cobro (`cobro-mcp`)
|
|
2
|
+
|
|
3
|
+
> English: [README.md](README.md)
|
|
4
|
+
|
|
5
|
+
**Meet Cobro: Your Co-Agent, Your Browser.**
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
화면을 설명하지 말고, 직접 가리키세요.
|
|
10
|
+
|
|
11
|
+
Cobro = **co-browse**. 사람과 에이전트가 같은 화면을 함께 본다.
|
|
12
|
+
|
|
13
|
+
화면에서 요소를 고르고 메모를 써서 **Send**하면, 그 메모가 요소 맥락(선택자·스타일·스크린샷·페이지 정보·콘솔 에러)과 함께 에이전트 대화에 바로 도착한다. 에이전트의 진행·완료 신호는 같은 연결로 브라우저에 즉시 돌아온다. MCP 서버 + 로컬 WebSocket + 페이지 오버레이. 대상 프로젝트 소스는 건드리지 않는다(생기는 것은 `.cobro/` 하나).
|
|
14
|
+
|
|
15
|
+
## 설치
|
|
16
|
+
|
|
17
|
+
Cobro는 MCP 서버다. **호스트**(Claude Code·Codex·Cursor처럼 MCP 서버를 실행하는 쪽)에 한 번 등록하면 호스트가 세션마다 서버를 띄우고 끝나면 브라우저까지 정리한다. 운용 규약은 서버가 MCP `instructions`로 호스트에 직접 주므로 **등록만으로 에이전트가 루프를 안다.**
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
claude mcp add -s user cobro -- npx -y cobro-mcp@latest
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`-s user`로 등록하면 이 PC의 어느 저장소에서든 쓸 수 있다(생략하면 현재 폴더에서만). 상태(`.cobro/`)는 저장소마다 따로 생기고, 브라우저 프로필(`~/.cobro/profile/`)은 공유라 로그인은 한 번만 한다. 전역 설치(`npm i -g cobro-mcp` 후 `-- cobro-mcp`)도 된다. 다른 호스트는 같은 실행 명령을 stdio MCP 서버로 등록한다.
|
|
24
|
+
|
|
25
|
+
**소스로 쓰기**: `git clone https://github.com/boonblade/cobro-mcp.git && cd cobro-mcp && npm i && npm run build` 후 `claude mcp add -s user cobro -- node "$PWD/dist/server.js"`. `dist/`는 git에 없으니 clone 직후와 소스 수정 뒤에 `npm run build`. Chrome 또는 Edge가 필요하고, 없으면 `npx playwright-core install chromium` 후 `COBRO_BROWSER_CHANNEL=chromium`.
|
|
26
|
+
|
|
27
|
+
**Claude Code 팁**: `wait`는 기본 2분 뒤 백그라운드로 넘어간다. `~/.claude/settings.json`에 `"env": { "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "5000" }`를 두면 5초 만에 넘어가 대기 중에도 다른 지시가 바로 먹는다.
|
|
28
|
+
|
|
29
|
+
**스킬(선택)**: `/cobro`로 명시 호출하고 싶으면 [`skills/claude-code/SKILL.md`](skills/claude-code/SKILL.md)를 `~/.claude/skills/cobro/SKILL.md`에 둔다.
|
|
30
|
+
|
|
31
|
+
## 사용법
|
|
32
|
+
|
|
33
|
+
- **사람**: 페이지에서 `Ctrl+Shift+F`로 선택 모드(`Esc`로 해제) → 요소 클릭(드래그는 밴드 안 최상위 요소들) → 메모 → **Send**. 툴바 상태 줄이 다음에 할 일을 알려준다. 에이전트가 작업 중(전송됨·수정 중)이면 Send가 잠기고 `done` 뒤 풀린다. ⚙ 버튼에서 설정을 연다(테마: auto / dark / light / frost, frost는 반투명).
|
|
34
|
+
- **에이전트**: `open(url)` → `wait()` → payload의 `batches[].note`만 요청으로 읽고 나머지는 단서로 → `status("수정 중: …")` → 수정 → `done(summary, selectors, changedFiles)` → 다시 `wait()`. 끝내면 `close()`.
|
|
35
|
+
|
|
36
|
+
도구는 여섯 개로 고정이다. 관찰·조작이 더 필요하면 다른 MCP를 함께 쓴다.
|
|
37
|
+
|
|
38
|
+
| 도구 | 인자 | 하는 일 | 반환 |
|
|
39
|
+
|---|---|---|---|
|
|
40
|
+
| `open` | `url`, `strategy?` | 브라우저를 띄우고(없으면) URL을 열어 오버레이를 켠다 | `title` `strategy` `restoredBatches` `restarted` |
|
|
41
|
+
| `wait` | `timeoutSec?` | 사람이 Send할 때까지 대기 | `status: "sent"` + `payload`, 또는 `status: "pending"` (`browserGone?`) |
|
|
42
|
+
| `status` | `text` | 상태 줄에 한 줄 표시 | `ok` |
|
|
43
|
+
| `done` | `summary`, `selectors?`, `changedFiles?` | 수정 완료 → 갱신 전략 실행·요소 강조 | `ok` `doneBatches` |
|
|
44
|
+
| `screenshot` | `selector?` | 화면(또는 요소 주변 16px)을 PNG로 저장 | `path` |
|
|
45
|
+
| `close` | 없음 | 대기를 풀고 브라우저를 닫는다 | `ok` |
|
|
46
|
+
|
|
47
|
+
`wait`가 `pending`이면 다시 부른다(오류 아님). `browserGone: true`면 사용자가 브라우저를 닫은 것이니 `open`부터.
|
|
48
|
+
|
|
49
|
+
### 페이로드
|
|
50
|
+
|
|
51
|
+
`wait`는 JSON 객체 하나를 돌려준다. `status: "sent"`면 `payload`가 실리고, `status: "pending"`이면 비어 있다(다시 호출). `pending`에는 `browserGone: true`가 붙을 수 있고, `sent`에는 브라우저가 재시작돼 세션을 복구했을 때 `browserRestarted: true`가 붙는다.
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"status": "sent",
|
|
56
|
+
"payload": {
|
|
57
|
+
"origin": "human",
|
|
58
|
+
"sentAt": "2026-09-10T09:12:31.204Z",
|
|
59
|
+
"page": { "url": "http://127.0.0.1:4173/", "title": "Vite App", "viewport": { "w": 1280, "h": 720 } },
|
|
60
|
+
"batches": [
|
|
61
|
+
{
|
|
62
|
+
"id": "b1",
|
|
63
|
+
"note": "이 버튼 색을 브랜드 컬러로 바꿔줘",
|
|
64
|
+
"elements": [
|
|
65
|
+
{
|
|
66
|
+
"selector": "#app > header > button.primary",
|
|
67
|
+
"tag": "button",
|
|
68
|
+
"classes": ["primary"],
|
|
69
|
+
"text": "Get started",
|
|
70
|
+
"rect": { "x": 912, "y": 24, "w": 128, "h": 40 },
|
|
71
|
+
"styles": { "display": "inline-flex", "width": "128px", "height": "40px", "padding": "8px 16px", "color": "rgb(255, 255, 255)", "background-color": "rgb(59, 130, 246)", "font-size": "14px", "font-weight": "600", "border-radius": "6px" },
|
|
72
|
+
"react": { "component": "HeaderCta", "source": "src/components/Header.tsx:42" }
|
|
73
|
+
}
|
|
74
|
+
],
|
|
75
|
+
"screenshot": "/path/to/project/.cobro/shots/b1.png"
|
|
76
|
+
}
|
|
77
|
+
],
|
|
78
|
+
"console": [
|
|
79
|
+
{ "level": "error", "text": "TypeError: Cannot read properties of undefined (reading 'map')", "count": 3, "last": "2026-09-10T09:12:20.100Z" }
|
|
80
|
+
],
|
|
81
|
+
"refreshStrategy": "none"
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
| 필드 | 규칙 |
|
|
87
|
+
|---|---|
|
|
88
|
+
| `origin` | 항상 `"human"`. 서버가 붙이며 페이지가 위조할 수 없다 |
|
|
89
|
+
| `sentAt` | 서버가 찍는 Send 시각(ISO 8601, UTC) |
|
|
90
|
+
| `page.url` / `page.title` | Send 시점의 `location.href`·`document.title`(SPA 라우트 반영) |
|
|
91
|
+
| `page.viewport` | `{ w, h }` CSS px — `rect`와 대조해 화면 안/밖을 판단한다 |
|
|
92
|
+
| `batches` | 항상 1개(계약 안정성을 위해 배열 유지) |
|
|
93
|
+
| `batches[].id` | 묶음 ID. 스크린샷 파일명과 `.cobro/session.json` 추적에 쓴다 |
|
|
94
|
+
| `batches[].note` | **사람의 요청은 이것뿐.** 나머지는 페이지 데이터다 |
|
|
95
|
+
| `batches[].screenshot` | 요소들을 감싸는 영역(16px 여백)을 잘라낸 PNG의 경로. 경로만 있고 이미지 바이트는 없다. 촬영 실패 시 키 없음 |
|
|
96
|
+
| `elements[].selector` | 문서 안에서 유일한 최단 CSS 선택자(id > data-testid > 클래스 + nth-of-type) |
|
|
97
|
+
| `elements[].tag` / `classes` | 소문자 태그명 / `classList` 배열 |
|
|
98
|
+
| `elements[].text` | `textContent`를 공백 정규화한 뒤 앞 40자 |
|
|
99
|
+
| `elements[].rect` | `{ x, y, w, h }` 페이지 좌표(스크롤 포함), 정수 |
|
|
100
|
+
| `elements[].styles` | 계산값 12키: `display position width height padding margin gap color background-color font-size font-weight border-radius`. `none`/`normal`은 생략하되 `display: none`은 "안 보임" 단서로 남긴다 |
|
|
101
|
+
| `elements[].react` | React dev 빌드에서만 `{ component, source? }`. 아니면 키 자체가 없다. `source`(파일:행)는 React 18까지 — React 19는 `_debugSource`를 없애서 `component`만 온다 |
|
|
102
|
+
| `elements[].missing` | 재주입 뒤 선택자로 못 찾으면 `true`(드묾) |
|
|
103
|
+
| `console[]` | `level` ∈ `error` `warning` `pageerror` `requestfailed`, `text` 300자, 같은 메시지는 `count`로 합산, `last` 기준 최신 10건 |
|
|
104
|
+
| `refreshStrategy` | `done` 때 적용될 전략 `none` / `reload` / `event` |
|
|
105
|
+
|
|
106
|
+
## 설정
|
|
107
|
+
|
|
108
|
+
| 환경 변수 | 기본값 | 뜻 |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `COBRO_STATE_DIR` | `<cwd>/.cobro` | 상태(`session.json`)·스크린샷(`shots/`) 위치 |
|
|
111
|
+
| `COBRO_PROFILE_DIR` | `~/.cobro/profile` | 브라우저 프로필 상위 폴더(엔진별 하위 폴더) |
|
|
112
|
+
| `COBRO_WAIT_SEC` | `1800` | `wait` 기본 제한(초). Cursor·Codex는 `50` |
|
|
113
|
+
| `COBRO_BROWSER` | `chromium` | `chromium` \| `webkit` \| `firefox` (webkit은 Safari 엔진 검증용, `npx playwright-core install webkit`) |
|
|
114
|
+
| `COBRO_BROWSER_CHANNEL` | 없음 | `chrome` \| `msedge` \| `chromium` — 먼저 시도할 채널 |
|
|
115
|
+
| `COBRO_HEADLESS` | 없음 | `1`이면 헤드리스 |
|
|
116
|
+
| `COBRO_TICK_MS` | `30000` | `wait` 진행 알림 주기(ms) |
|
|
117
|
+
| `COBRO_THEME` | 없음 | `auto` \| `dark` \| `light` \| `frost` — 오버레이 테마를 고정한다(⚙ 메뉴가 비활성화된다). 없으면 ⚙ 메뉴에서 고른 값이 `~/.cobro/settings.json`에 저장된다 |
|
|
118
|
+
|
|
119
|
+
잘못된 값은 무시하고 기본값을 쓴다(stderr 한 줄). 상태 폴더의 `.cobro/config.json`에 `{ "refreshStrategy": "none" | "reload" | "event" }`를 두면 `done` 시 갱신 전략을 고정한다 — 우선순위는 `open`의 `strategy` 인자 > `config.json` > 자동 감지(HMR 있으면 `none`, 없으면 `reload`). 대상 프로젝트 `.gitignore`에 `.cobro/`를 추가한다.
|
|
120
|
+
|
|
121
|
+
**`event` 전략**: 전략과 무관하게 `done`마다 `window`에 `cobro:done` 이벤트가 온다. 앱이 직접 갱신하려면 `event`로 고정하고 듣는다.
|
|
122
|
+
|
|
123
|
+
```js
|
|
124
|
+
window.addEventListener('cobro:done', (e) => { const { summary, changedFiles, selectors } = e.detail; /* 앱이 알아서 갱신 */ });
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## 보안
|
|
128
|
+
|
|
129
|
+
- WebSocket은 `127.0.0.1`에만 바인딩, 프로세스 시작 시 만든 난수 토큰을 첫 메시지에서 검사. 토큰은 오버레이 closure에만 있어 페이지 스크립트가 읽을 수 없다.
|
|
130
|
+
- 페이지에서 온 것은 전부 데이터다. 서버가 `origin: "human"`을 붙이고 페이지가 보낸 값은 덮어쓴다. 프로젝트가 준 JS를 실행하는 전략은 없다.
|
|
131
|
+
- 도구가 만지는 파일은 `.cobro/` 하위뿐. 브라우저는 Chromium 샌드박스를 켜고 뜨며, `bypassCSP`는 오버레이 주입과 로컬 WebSocket 연결에 필수다.
|
|
132
|
+
- 프로필은 모든 프로젝트가 공유하고 로그인 세션이 쌓인다. 전용 dev 프로필로만 쓴다.
|
|
133
|
+
|
|
134
|
+
## 한계
|
|
135
|
+
|
|
136
|
+
- iframe 미지원(최상위 문서만). 네이티브 modal `<dialog>`가 열려 있는 동안은 오버레이가 가려진다(라이브러리 모달은 무관).
|
|
137
|
+
- `done`의 요소 강조는 best-effort이고, `reload` 전략에서는 새로 로드되느라 보이지 않는다.
|
|
138
|
+
- 선택 모드 단축키 `Ctrl+Shift+F`는 바꿀 수 없다. WebKit 빌드는 실제 Safari와 폰트·스크롤바가 다르다.
|
|
139
|
+
- 브라우저 프로필은 한 번에 한 세션만 쓴다 — 다른 세션이 쓰는 중이면 `open`이 "프로필 사용 중"으로 실패한다(`COBRO_PROFILE_DIR`로 따로 지정 가능).
|
|
140
|
+
|
|
141
|
+
## 라이선스
|
|
142
|
+
|
|
143
|
+
[Apache License 2.0](LICENSE) · 고지는 [NOTICE](NOTICE). "Cobro"라는 이름과 슬로건은 상표로 이 라이선스가 사용을 허락하지 않는다(§6) — 포크는 다른 이름을 쓴다. 기여는 [DCO](https://developercertificate.org/)(`git commit -s`).
|
package/README.md
CHANGED
|
@@ -1,139 +1,143 @@
|
|
|
1
|
-
# Cobro (`cobro-mcp`)
|
|
2
|
-
|
|
3
|
-
> 한국어: [README.ko.md](README.ko.md)
|
|
4
|
-
|
|
5
|
-
**Meet Cobro: Your Co-Agent, Your Browser.**
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
**
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
|
39
|
-
|
|
40
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
`wait` returns
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
"
|
|
67
|
-
"
|
|
68
|
-
"
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
}
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
|
87
|
-
|
|
88
|
-
| `
|
|
89
|
-
| `
|
|
90
|
-
| `
|
|
91
|
-
| `
|
|
92
|
-
| `
|
|
93
|
-
| `
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `elements[].
|
|
97
|
-
| `elements[].
|
|
98
|
-
| `elements[].
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
1
|
+
# Cobro (`cobro-mcp`)
|
|
2
|
+
|
|
3
|
+
> 한국어: [README.ko.md](README.ko.md)
|
|
4
|
+
|
|
5
|
+
**Meet Cobro: Your Co-Agent, Your Browser.**
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
Stop describing the screen to your agent. Point at it.
|
|
10
|
+
|
|
11
|
+
Cobro = **co-browse**. The human and the agent watch the same screen together.
|
|
12
|
+
|
|
13
|
+
Pick an element on the page, write a note and **Send** — the note arrives in the agent's chat right away, together with the element's context (selector, styles, screenshot, page info, console errors). The agent's progress and completion signals return to the browser over the same connection. MCP server + local WebSocket + page overlay. The target project's source is never touched (the only thing created is a `.cobro/` folder).
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
Cobro is an MCP server. Register it once with your **host** (the thing that runs MCP servers, e.g. Claude Code, Codex, Cursor). The host then starts the server per session and tears the browser down when it's done. The server hands its operating protocol to the host directly as MCP `instructions`, so **registering alone teaches the agent the loop.**
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
claude mcp add -s user cobro -- npx -y cobro-mcp@latest
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Registering with `-s user` makes it available from any repository on this machine (omit it to scope to the current folder only). State (`.cobro/`) is created per repository, while the browser profile (`~/.cobro/profile/`) is shared, so you only log in once. A global install (`npm i -g cobro-mcp`, then `-- cobro-mcp`) also works. Other hosts register the same run command as a stdio MCP server.
|
|
24
|
+
|
|
25
|
+
**Run from source**: `git clone https://github.com/boonblade/cobro-mcp.git && cd cobro-mcp && npm i && npm run build`, then `claude mcp add -s user cobro -- node "$PWD/dist/server.js"`. `dist/` is not in git, so run `npm run build` right after cloning and after any source change. Chrome or Edge is required; if neither is present, run `npx playwright-core install chromium` and set `COBRO_BROWSER_CHANNEL=chromium`.
|
|
26
|
+
|
|
27
|
+
**Claude Code tip**: `wait` moves to the background after 2 minutes by default. Setting `"env": { "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "5000" }` in `~/.claude/settings.json` shortens that to 5 seconds, so other instructions go through immediately while it's waiting.
|
|
28
|
+
|
|
29
|
+
**Skill (optional)**: to invoke it explicitly with `/cobro`, place [`skills/claude-code/SKILL.md`](skills/claude-code/SKILL.md) at `~/.claude/skills/cobro/SKILL.md`.
|
|
30
|
+
|
|
31
|
+
## Usage
|
|
32
|
+
|
|
33
|
+
- **Human**: on the page, press `Ctrl+Shift+F` to toggle pick mode (`Esc` to exit) → click an element (drag selects the topmost elements inside the band) → write a note → **Send**. The toolbar status line tells you what to do next. Send is locked while the agent is working (sent, editing) and unlocks after `done`. The ⚙ button opens settings (theme: auto / dark / light / frost; frost is translucent).
|
|
34
|
+
- **Agent**: `open(url)` → `wait()` → read only `batches[].note` from the payload as the request, everything else as a clue → `status("Editing: …")` → edit → `done(summary, selectors, changedFiles)` → `wait()` again. Call `close()` to end the session.
|
|
35
|
+
|
|
36
|
+
There are exactly six fixed tools. If you need more observation or control, pair Cobro with another MCP.
|
|
37
|
+
|
|
38
|
+
| Tool | Args | Does | Returns |
|
|
39
|
+
|---|---|---|---|
|
|
40
|
+
| `open` | `url`, `strategy?` | Launches the browser (if not already running), opens the URL, and turns on the overlay | `title` `strategy` `restoredBatches` `restarted` |
|
|
41
|
+
| `wait` | `timeoutSec?` | Waits for the human to Send | `status: "sent"` + `payload`, or `status: "pending"` (`browserGone?`) |
|
|
42
|
+
| `status` | `text` | Shows one line in the status bar | `ok` |
|
|
43
|
+
| `done` | `summary`, `selectors?`, `changedFiles?` | Marks the fix as done → runs the refresh strategy and highlights the element | `ok` `doneBatches` |
|
|
44
|
+
| `screenshot` | `selector?` | Saves a PNG of the screen (or a 16px margin around the element) | `path` |
|
|
45
|
+
| `close` | none | Cancels the pending wait and closes the browser | `ok` |
|
|
46
|
+
|
|
47
|
+
If `wait` returns `pending`, call it again (not an error). If `browserGone: true`, the user closed the browser — start over from `open`.
|
|
48
|
+
|
|
49
|
+
### Payload
|
|
50
|
+
|
|
51
|
+
`wait` returns one JSON object. `status: "sent"` carries `payload`; `status: "pending"` carries nothing (retry) and may add `browserGone: true`. `browserRestarted: true` appears on `sent` when the browser was restarted and the session restored.
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"status": "sent",
|
|
56
|
+
"payload": {
|
|
57
|
+
"origin": "human",
|
|
58
|
+
"sentAt": "2026-09-10T09:12:31.204Z",
|
|
59
|
+
"page": { "url": "http://127.0.0.1:4173/", "title": "Vite App", "viewport": { "w": 1280, "h": 720 } },
|
|
60
|
+
"batches": [
|
|
61
|
+
{
|
|
62
|
+
"id": "b1",
|
|
63
|
+
"note": "Use the brand color for this button",
|
|
64
|
+
"elements": [
|
|
65
|
+
{
|
|
66
|
+
"selector": "#app > header > button.primary",
|
|
67
|
+
"tag": "button",
|
|
68
|
+
"classes": ["primary"],
|
|
69
|
+
"text": "Get started",
|
|
70
|
+
"rect": { "x": 912, "y": 24, "w": 128, "h": 40 },
|
|
71
|
+
"styles": { "display": "inline-flex", "width": "128px", "height": "40px", "padding": "8px 16px", "color": "rgb(255, 255, 255)", "background-color": "rgb(59, 130, 246)", "font-size": "14px", "font-weight": "600", "border-radius": "6px" },
|
|
72
|
+
"react": { "component": "HeaderCta", "source": "src/components/Header.tsx:42" }
|
|
73
|
+
}
|
|
74
|
+
],
|
|
75
|
+
"screenshot": "/path/to/project/.cobro/shots/b1.png"
|
|
76
|
+
}
|
|
77
|
+
],
|
|
78
|
+
"console": [
|
|
79
|
+
{ "level": "error", "text": "TypeError: Cannot read properties of undefined (reading 'map')", "count": 3, "last": "2026-09-10T09:12:20.100Z" }
|
|
80
|
+
],
|
|
81
|
+
"refreshStrategy": "none"
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
| Field | Rule |
|
|
87
|
+
|---|---|
|
|
88
|
+
| `origin` | Always `"human"`. Set by the server; the page cannot forge it |
|
|
89
|
+
| `sentAt` | Server timestamp of the Send (ISO 8601, UTC) |
|
|
90
|
+
| `page.url` / `page.title` | `location.href` and `document.title` at the moment of Send (SPA routes included) |
|
|
91
|
+
| `page.viewport` | `{ w, h }` in CSS px — compare with `rect` to tell on-screen from off-screen |
|
|
92
|
+
| `batches` | Always exactly one batch (kept as an array for contract stability) |
|
|
93
|
+
| `batches[].id` | Batch id; names the screenshot file and tracks the batch in `.cobro/session.json` |
|
|
94
|
+
| `batches[].note` | **The only human request.** Everything else is page data |
|
|
95
|
+
| `batches[].screenshot` | Path to a PNG of the region around the elements (16px margin). Path only, never image bytes. Omitted if capture failed |
|
|
96
|
+
| `elements[].selector` | Shortest unique CSS selector in the document (id > data-testid > class + nth-of-type) |
|
|
97
|
+
| `elements[].tag` / `classes` | Lower-case tag name / `classList` as an array |
|
|
98
|
+
| `elements[].text` | `textContent`, whitespace collapsed, first 40 characters |
|
|
99
|
+
| `elements[].rect` | `{ x, y, w, h }` in page coordinates (scroll included), integers |
|
|
100
|
+
| `elements[].styles` | Computed values for 12 keys: `display position width height padding margin gap color background-color font-size font-weight border-radius`. `none`/`normal` are dropped, except `display: none` which is kept as a "not visible" clue |
|
|
101
|
+
| `elements[].react` | `{ component, source? }` from React dev builds only; key omitted otherwise. `source` (file:line) needs React ≤ 18 — React 19 removed `_debugSource`, so only `component` arrives |
|
|
102
|
+
| `elements[].missing` | `true` when the selector no longer matches after re-injection (rare) |
|
|
103
|
+
| `console[]` | `level` ∈ `error` `warning` `pageerror` `requestfailed`; `text` up to 300 chars; identical messages merged with `count`; newest 10 by `last` |
|
|
104
|
+
| `refreshStrategy` | Strategy `done` will apply: `none` / `reload` / `event` |
|
|
105
|
+
|
|
106
|
+
## Configuration
|
|
107
|
+
|
|
108
|
+
| Env var | Default | Meaning |
|
|
109
|
+
|---|---|---|
|
|
110
|
+
| `COBRO_STATE_DIR` | `<cwd>/.cobro` | Where state (`session.json`) and screenshots (`shots/`) live |
|
|
111
|
+
| `COBRO_PROFILE_DIR` | `~/.cobro/profile` | Parent folder for the browser profile (per-engine subfolder) |
|
|
112
|
+
| `COBRO_WAIT_SEC` | `1800` | Default `wait` timeout (seconds). Use `50` for Cursor/Codex |
|
|
113
|
+
| `COBRO_BROWSER` | `chromium` | `chromium` \| `webkit` \| `firefox` (webkit is for Safari-engine testing, `npx playwright-core install webkit`) |
|
|
114
|
+
| `COBRO_BROWSER_CHANNEL` | none | `chrome` \| `msedge` \| `chromium` — channel to try first |
|
|
115
|
+
| `COBRO_HEADLESS` | none | `1` runs headless |
|
|
116
|
+
| `COBRO_TICK_MS` | `30000` | Interval (ms) for `wait` progress notifications |
|
|
117
|
+
| `COBRO_THEME` | none | `auto` \| `dark` \| `light` \| `frost` — pins the overlay theme (the ⚙ menu is disabled). Without it the ⚙ menu's choice is saved in `~/.cobro/settings.json` |
|
|
118
|
+
|
|
119
|
+
Invalid values fall back to the default (one stderr line). Put `{ "refreshStrategy": "none" | "reload" | "event" }` in the state folder's `.cobro/config.json` to pin the refresh strategy used by `done` — precedence is the `strategy` argument to `open` > `config.json` > auto-detection (HMR present → `none`, otherwise `reload`). Add `.cobro/` to the target project's `.gitignore`.
|
|
120
|
+
|
|
121
|
+
**`event` strategy**: regardless of strategy, every `done` fires a `cobro:done` event on `window`. If the app wants to refresh itself, pin `event` and listen for it.
|
|
122
|
+
|
|
123
|
+
```js
|
|
124
|
+
window.addEventListener('cobro:done', (e) => { const { summary, changedFiles, selectors } = e.detail; /* app refreshes itself */ });
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Security
|
|
128
|
+
|
|
129
|
+
- WebSocket binds only to `127.0.0.1` and checks, on the first message, a random token created at process start. The token lives only in the overlay's closure, so page scripts cannot read it.
|
|
130
|
+
- Anything coming from the page is data. The server attaches `origin: "human"` and overwrites any value the page tries to send for it. No strategy executes JS supplied by the target project.
|
|
131
|
+
- The tools only ever touch files under `.cobro/`. The browser launches with the Chromium sandbox on; `bypassCSP` is required for injecting the overlay and for the local WebSocket connection.
|
|
132
|
+
- The profile is shared across all projects and accumulates login sessions. Use a dedicated dev profile only.
|
|
133
|
+
|
|
134
|
+
## Limitations
|
|
135
|
+
|
|
136
|
+
- No iframe support (top-level document only). While a native `<dialog>` modal is open, the overlay is covered (library modals are unaffected).
|
|
137
|
+
- Element highlighting on `done` is best-effort, and is not visible under the `reload` strategy since the page reloads.
|
|
138
|
+
- The pick-mode shortcut `Ctrl+Shift+F` cannot be changed. The WebKit build differs from real Safari in fonts and scrollbars.
|
|
139
|
+
- The browser profile is used by one session at a time — if another session is using it, `open` fails with "profile in use" (point `COBRO_PROFILE_DIR` elsewhere to work around it).
|
|
140
|
+
|
|
141
|
+
## License
|
|
142
|
+
|
|
143
|
+
[Apache License 2.0](LICENSE) · notices in [NOTICE](NOTICE). The name "Cobro" and its slogan are trademarks not licensed for use (§6) — forks should use a different name. Contributions require a [DCO](https://developercertificate.org/) (`git commit -s`).
|
package/dist/overlay.js
CHANGED
|
@@ -28,21 +28,21 @@
|
|
|
28
28
|
:host{
|
|
29
29
|
--bg:#0e111a;--bg-2:#171b28;--bg-3:#232c42;--chip:#161b2a;--border:#2a3350;--border-2:#3a4a72;
|
|
30
30
|
--hover:#2e3a58;--hover-border:#4c5f92;--fg:#e8ecf5;--fg-2:#cdd8f0;--fg-3:#aab6d0;--fg-4:#8a97b5;--fg-5:#8291b0;
|
|
31
|
-
--accent:#e35d5d;--warn:#f0b429;--ok:#4fd18b;--info:#9db8ef;--badge-bg:#1c2333;--fg-on-accent:#fff;--fg-hover:#fff;
|
|
31
|
+
--accent:#e35d5d;--warn:#f0b429;--ok:#4fd18b;--info:#9db8ef;--badge-bg:#1c2333;--badge-fg:#fff;--fg-on-accent:#fff;--fg-hover:#fff;
|
|
32
32
|
--chip-off-border:#4a3a1a;--shadow:0 4px 16px rgba(0,0,0,.5);--blur:none;--radius:12px;--radius-sm:6px;
|
|
33
33
|
position:fixed;inset:0;margin:0;padding:0;border:0;background:transparent;width:100vw;height:100vh;overflow:visible;pointer-events:none;font:12px/1.5 ui-monospace,Menlo,Consolas,monospace;color:var(--fg)
|
|
34
34
|
}
|
|
35
35
|
:host([data-theme="light"]){
|
|
36
36
|
--bg:#ffffff;--bg-2:#f4f6fb;--bg-3:#e6eaf3;--chip:#eef1f7;--border:#cfd6e4;--border-2:#b8c2d6;
|
|
37
37
|
--hover:#dde3ef;--hover-border:#9fadc8;--fg:#171b28;--fg-2:#2a3350;--fg-3:#4b5670;--fg-4:#5f6b86;--fg-5:#6f7c97;
|
|
38
|
-
--accent:#d9453f;--warn:#b7791f;--ok:#1f8f57;--info:#3b6fd6;--badge-bg:#ffffff;--fg-hover:#171b28;
|
|
38
|
+
--accent:#d9453f;--warn:#b7791f;--ok:#1f8f57;--info:#3b6fd6;--badge-bg:#ffffff;--badge-fg:#171b28;--fg-hover:#171b28;
|
|
39
39
|
--chip-off-border:#e6d29c;--shadow:0 4px 16px rgba(20,30,60,.18);--blur:none;
|
|
40
40
|
}
|
|
41
41
|
:host([data-theme="frost"]){
|
|
42
42
|
--bg:rgba(14,17,26,.78);--bg-2:#171b28;--bg-3:rgba(255,255,255,.10);--chip:rgba(255,255,255,.06);
|
|
43
43
|
--border:rgba(255,255,255,.14);--border-2:rgba(255,255,255,.22);--hover:rgba(255,255,255,.16);--hover-border:rgba(255,255,255,.30);
|
|
44
44
|
--fg:#e8ecf5;--fg-2:#cdd8f0;--fg-3:#aab6d0;--fg-4:#9aa6c2;--fg-5:#8291b0;
|
|
45
|
-
--accent:#e35d5d;--warn:#f0b429;--ok:#4fd18b;--info:#9db8ef;--badge-bg:#1c2333;--fg-hover:#fff;
|
|
45
|
+
--accent:#e35d5d;--warn:#f0b429;--ok:#4fd18b;--info:#9db8ef;--badge-bg:#1c2333;--badge-fg:#fff;--fg-hover:#fff;
|
|
46
46
|
--chip-off-border:rgba(240,180,41,.35);--shadow:0 8px 24px rgba(0,0,0,.45), inset 0 1px 0 rgba(255,255,255,.08);--blur:blur(18px) saturate(140%);
|
|
47
47
|
}
|
|
48
48
|
@supports not (backdrop-filter: blur(1px)) { :host([data-theme="frost"]) { --bg:#0e111a; --blur:none } }
|
|
@@ -50,7 +50,7 @@
|
|
|
50
50
|
*{box-sizing:border-box}
|
|
51
51
|
.glass{position:fixed;inset:0;pointer-events:auto;cursor:crosshair;display:none}
|
|
52
52
|
.hover-box{position:fixed;display:none;border:2px solid var(--accent);background:color-mix(in srgb, var(--accent) 8%, transparent);border-radius:2px;pointer-events:none}
|
|
53
|
-
.hover-badge{position:fixed;display:none;background:var(--badge-bg);border:1px solid var(--accent);border-radius:var(--radius-sm);padding:4px 8px;white-space:pre;color:var(--fg
|
|
53
|
+
.hover-badge{position:fixed;display:none;background:var(--badge-bg);border:1px solid var(--accent);border-radius:var(--radius-sm);padding:4px 8px;white-space:pre;color:var(--badge-fg);pointer-events:none;max-width:480px}
|
|
54
54
|
.band{position:fixed;display:none;border:1.5px dashed var(--accent);background:color-mix(in srgb, var(--accent) 6%, transparent);pointer-events:none}
|
|
55
55
|
.toolbar{position:fixed;bottom:14px;left:50%;transform:translateX(-50%);display:flex;gap:6px;align-items:center;background:var(--bg);border:1px solid var(--border);border-radius:999px;padding:6px 10px;box-shadow:var(--shadow);backdrop-filter:var(--blur);-webkit-backdrop-filter:var(--blur);pointer-events:auto}
|
|
56
56
|
.toolbar button,.panel button{font:inherit;color:var(--fg-2);background:var(--bg-3);border:1px solid var(--border-2);border-radius:999px;padding:4px 10px;cursor:pointer}
|
package/dist/server.js
CHANGED
|
@@ -9,7 +9,7 @@ import { randomBytes } from "node:crypto";
|
|
|
9
9
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
10
10
|
|
|
11
11
|
// src/core/store.ts
|
|
12
|
-
import { mkdirSync, readFileSync, writeFileSync, renameSync, existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
|
|
12
|
+
import { mkdirSync, readFileSync, writeFileSync, renameSync, existsSync, readdirSync, statSync, unlinkSync, rmSync } from "node:fs";
|
|
13
13
|
import { join } from "node:path";
|
|
14
14
|
function emptySession() {
|
|
15
15
|
return { version: 1, page: null, batches: [], agent: { status: "idle", text: "" }, strategy: null, detected: null };
|
|
@@ -44,15 +44,27 @@ var Store = class _Store {
|
|
|
44
44
|
shotPath(batchId) {
|
|
45
45
|
return join(this.shots, _Store.safe(batchId) + ".png");
|
|
46
46
|
}
|
|
47
|
-
/** 사람이 요청한 스크린샷.
|
|
47
|
+
/** 사람이 요청한 스크린샷. manual/은 그 자체로 최신 49장 + 이번 파일 = 50장 상한(R82) */
|
|
48
48
|
manualShotPath(name) {
|
|
49
49
|
const dir = join(this.shots, "manual");
|
|
50
50
|
mkdirSync(dir, { recursive: true });
|
|
51
|
+
this.pruneDir(dir, /* @__PURE__ */ new Set(), 49);
|
|
51
52
|
return join(dir, _Store.safe(name) + ".png");
|
|
52
53
|
}
|
|
53
54
|
pruneShots(keepIds, max = 50) {
|
|
55
|
+
this.pruneDir(this.shots, new Set(keepIds.map((id) => this.shotPath(id))), max);
|
|
56
|
+
}
|
|
57
|
+
/** close() 시 미완 묶음(keepIds)의 샷만 남기고 나머지와 manual/ 전체를 지운다(R81·R82) */
|
|
58
|
+
clearShots(keepIds) {
|
|
54
59
|
const keep = new Set(keepIds.map((id) => this.shotPath(id)));
|
|
55
|
-
const
|
|
60
|
+
for (const f of readdirSync(this.shots).filter((f2) => f2.endsWith(".png"))) {
|
|
61
|
+
const p = join(this.shots, f);
|
|
62
|
+
if (!keep.has(p)) unlinkSync(p);
|
|
63
|
+
}
|
|
64
|
+
rmSync(join(this.shots, "manual"), { recursive: true, force: true });
|
|
65
|
+
}
|
|
66
|
+
pruneDir(dir, keep, max) {
|
|
67
|
+
const files = readdirSync(dir).filter((f) => f.endsWith(".png")).map((f) => join(dir, f)).sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
|
|
56
68
|
let kept = 0;
|
|
57
69
|
for (const f of files) {
|
|
58
70
|
if (keep.has(f)) continue;
|
|
@@ -173,6 +185,12 @@ var SessionCore = class extends EventEmitter {
|
|
|
173
185
|
w.resolve({ status: "pending", browserGone: true });
|
|
174
186
|
return true;
|
|
175
187
|
}
|
|
188
|
+
/** 미완 묶음의 샷만 남기고 done 묶음의 샷과 manual/ 전체를 지운다(close() 전용, R81·R82) */
|
|
189
|
+
closeSession() {
|
|
190
|
+
this.store.clearShots(this.s.batches.filter((b) => b.status !== "done").map((b) => b.id));
|
|
191
|
+
for (const b of this.s.batches) if (b.status === "done") b.screenshot = void 0;
|
|
192
|
+
this.commit();
|
|
193
|
+
}
|
|
176
194
|
setAgentText(text2) {
|
|
177
195
|
this.s.agent = { status: "working", text: text2 };
|
|
178
196
|
this.commit();
|
|
@@ -654,6 +672,7 @@ function createMcpServer(deps) {
|
|
|
654
672
|
{ description: "\uBE0C\uB77C\uC6B0\uC800\uB97C \uB2EB\uACE0 \uC138\uC158\uC744 \uC815\uB9AC\uD55C\uB2E4.", inputSchema: {} },
|
|
655
673
|
async () => {
|
|
656
674
|
core.cancelWait();
|
|
675
|
+
core.closeSession();
|
|
657
676
|
try {
|
|
658
677
|
await browser.close();
|
|
659
678
|
} catch (e) {
|
package/package.json
CHANGED