opencode-chromium

커뮤니티 및 로드맵

로드맵은 사용자에 의해 결정됩니다 — 제안을 열고, 반응으로 투표하고, GitHub Discussions에서 공지사항을 팔로우하세요:

• 기능 요청 — 제안을 시작하세요 (템플릿이 구조를 유지해 줍니다): 문제와 이를 해결해야 할 워크플로우를 설명하세요; 다른 사용자들이 👍/❤️ 반응으로 투표합니다. 관리자들은 투표된 제안을 예정 작업으로 분류하고 상태(planned, in progress, released)를 태그로 표시합니다. 제안 열기 →

• 공지사항 — 릴리스, 로드맵 상태 및 관리자 메모. 공지사항 팔로우 →

• 프로토콜 — 기능 요청은 이 저장소가 게시하는 내용(런타임, 확장 프로그램, 네이티브 호스트, 스킬)에 관한 것이며, 버그 리포트와 보안 발견 사항은 대신 GitHub Issues에 제출하세요.

Related MCP server: agent-browser

제공 기능

• browser_run, browser_observe, browser_session, browser_finalize의 네 가지 간결한 기본 도구.

• 명시적 호환성 및 기능 모드 뒤에 있는 완전한 다중 작업 브라우저 엔진.

• 컨텍스트 절약형 증거: 관찰 요약은 빈 필드, 중복 텍스트 및 장황한 html/styles를 생략하고 (detail: "debug"를 통해서만 사용 가능), 인라인 응답은 4,096자 예산 내에 유지되며 초과 출력은 아티팩트 리소스로 넘깁니다.

• 네이티브 호버, 승인 게이팅이 있는 JavaScript 대화 상자 처리, 품질 제어가 있는 png/jpeg/webp 스크린샷.

• 비간섭적 백그라운드 자동화: 클릭, 타이핑 및 탐색은 탭을 활성화하거나 창을 앞으로 가져오지 않으므로 도구가 백그라운드 탭을 구동하는 동안 계속 작업할 수 있습니다.

• 서버 수준 출처 정책(허용/차단 출처 글로브) 및 업로드에 대한 파일 루트 제한.

• 영구 세션 에뮬레이션(뷰포트, 네트워크, CPU, 지리적 위치, 색상 구성표, 사용자 에이전트, 헤더, 초기 스크립트) 및 finalize 시 자동 재설정.

• requestId 기반 네트워크 요청 드릴다운, 아티팩트 백업 본문 오버플로우 및 소스 매핑된 콘솔 스택 추적.

• 성능 진단: browser_observe 모드 diagnostic는 CDP 트레이스를 기록하고 네이티브 호스트에서 LCP, CLS, 긴 작업, TBT 등을 계산합니다; 원시 트레이스는 아티팩트 우선이며 CrUX/필드 데이터는 유지되지 않습니다.

• Snowflake 기본 페이지 검색, 명시적 어휘/자동 대안 및 확장 프로그램에서 모델을 로드하지 않는 Qwen 심층 검색.

• 프로필 인식 세션, 탭 소유권, 오래된 대상 복구, 제한된 읽기 재시도, 조건부 안정화, 승인 및 아티팩트 리소스.

• 프로토콜 정리 stdout이 있는 MCP stdio 및 루프백/인증 HTTP 전송.

• 네이티브 OpenCode V2 어댑터 및 공유 OpenAI, Anthropic, Gemini, MCP 스키마 어댑터.

빠른 시작 (npm)

게시된 패키지를 한 번 설치한 다음 지원되는 클라이언트에 연결하세요. 패키지에는 CLI(opencode-chromium), MCP 서버 bin(opencode-chromium-mcp), 브라우저 확장 프로그램 및 네이티브 호스트 설치 프로그램이 포함되어 있습니다:

npx -y opencode-chromium-mcp

1. 패키지 설치

npm install -g opencode-chromium

2. 브라우저 확장 프로그램 로드

Chrome 웹 스토어에서 opencode-chromium 설치. 아래의 압축 해제 흐름은 개발 및 로컬 테스트를 위해 계속 사용할 수 있습니다.

chrome://extensions을 열고 개발자 모드를 활성화한 다음 설치된 패키지에서 압축 해제된 extension/ 폴더를 로드하세요:

npm root -g
# load "<that path>\opencode-chromium\extension" as an unpacked extension

확장 프로그램 ID는 로드 경로에서 파생되므로 폴더를 현재 위치에 유지하세요. chrome://extensions에 표시된 ID를 기록해 두세요.

3. 네이티브 메시징 호스트 설치

node "$(npm root -g)/opencode-chromium/scripts/install-native-host.js" --extension-id <extension-id> --browsers chrome

4. 클라이언트 연결

OpenCode V2 — 전역 ~/.config/opencode/opencode.json에 패키지 이름을 추가하세요:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chromium"]
}

Codex — 필수 MCP 서버를 등록하세요:

codex mcp add opencode-browser-plugin -- npx -y opencode-chromium-mcp

모든 MCP 클라이언트 — stdio 서버를 추가하세요:

{
  "mcpServers": {
    "opencode-browser-plugin": {
      "command": "npx",
      "args": ["-y", "opencode-chromium-mcp"]
    }
  }
}

직접 JavaScript — SDK 런타임 또는 MCP 서버를 프로그래밍 방식으로 가져오세요 (docs/direct-sdk.md 참조).

5. 확인

opencode-chromium doctor --json
opencode-chromium verify

네 가지 도구(browser_run, browser_observe, browser_session, browser_finalize)는 연결된 모든 클라이언트에서 사용할 수 있습니다. 중복 도구가 의도적이지 않은 한 하나의 클라이언트 세션에서 네이티브 OpenCode 어댑터와 MCP 서버를 모두 활성화하지 마세요.

요구 사항

• npm 패키지 및 SDK용 Node.js 20 이상.

• 소스에서 빌드하거나 저장소 스크립트를 실행할 때 Bun 1.1 이상.

• 압축 해제된 extension/이 로드된 Chromium 계열 브라우저.

• 확장 프로그램 ID에 대한 네이티브 메시징 호스트 설치.

설치 및 빌드

bun install --frozen-lockfile
bun run build
bun test
bun run check

패키지는 npm 이름 opencode-chromium으로 1.6.1로 릴리스됩니다. 안정적인 런타임 및 MCP 서버 ID는 클라이언트 호환성을 위해 opencode-browser-plugin으로 유지됩니다.

MCP

stdio를 통해 네 가지 도구 서버를 실행하세요:

bun run mcp

또는 패키징된 바이너리를 사용하세요:

opencode-chromium-mcp

루프백 Streamable HTTP는 다음으로 사용할 수 있습니다:

bun run mcp:http

비루프백 HTTP는 AGENT_BROWSER_AUTH_TOKEN에 베어러 토큰이 필요합니다(또는 --auth-token-env로 선택된 변수). 기본 서버 이름은 opencode-browser-plugin입니다. 출처 및 파일 루트 안전 구성은 서버 수준입니다: --allowed-origin / --blocked-origin 글로브를 전달하거나 AGENT_BROWSER_ALLOWED_ORIGINS, AGENT_BROWSER_BLOCKED_ORIGINS, AGENT_BROWSER_ALLOWED_FILE_ROOTS를 설정하세요 (docs/mcp.md 참조).

OpenCode V2

패키지 루트는 OpenCode 1.18.x의 공식 { id, server() } 경로 플러그인 모듈 형태를 사용하는 네이티브 어댑터를 V2 설정 계약과 함께 내보냅니다:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-chromium"]
}

로컬 빌드의 경우 클라이언트를 dist/adapters/opencode/index.js로 지정하거나 opencode-chromium install --client opencode 명령을 사용하세요. 어댑터는 정확히 네 가지 도구를 등록하고, codemode: false를 설정하며, 리로드를 위한 정리 함수를 반환합니다.

동일한 브라우저 런타임은 MCP 호환성 모드를 통해 사용할 수 있습니다. 중복 도구가 의도적이지 않은 한 하나의 클라이언트 세션에서 두 표면을 모두 활성화하지 마세요.

Codex

npm 패키지에서 MCP 서버를 등록하세요:

codex mcp add opencode-browser-plugin -- npx -y opencode-chromium-mcp
codex mcp list

로컬 체크아웃에서 Bun으로 dist/adapters/mcp/server.js를 등록하세요:

codex mcp add opencode-browser-plugin -- bun C:\absolute\path\to\dist\adapters\mcp\server.js

번들된 스킬은 skills/opencode-browser-plugin/SKILL.md입니다. 공개 Agent Skills 표준을 따르며 커넥터 우선 라우팅, 프로필 선택, 작업 일괄 처리, Snowflake 기본 검색, 승인 토큰, 아티팩트 및 finalization을 다룹니다. ChatGPT/Codex 데스크톱 Skills 선택기 및 MCP 종속성 메타데이터를 위한 agents/openai.yaml이 포함되어 있습니다.

스킬 호환 클라이언트 모두에 한 번에 설치하세요:

opencode-chromium install --client skills
opencode-chromium install --client skills --dry-run
opencode-chromium uninstall --client skills

이렇게 하면 스킬이 ~/.codex/skills/, ~/.claude/skills/, ~/.agents/skills/에 (opencode-browser-plugin/ 아래) 복사되고, ~/.codex/config.toml에 활성화된 [[skills.config]] 항목을 등록하면서 오래된 opencode-browser-adapter 항목을 제거합니다.

네이티브 호스트 및 확장 프로그램

extension/을 압축 해제된 확장 프로그램으로 로드한 다음 호스트를 설치하세요:

bun run install:native-host -- --extension-id <extension-id> --browsers chrome
bun run check:native-host -- --json

새 구성에는 AGENT_BROWSER_* 환경 변수를 사용하세요. 이전 OPENCODE_BROWSER_* 이름은 1.x 호환성 기간 동안 낮은 우선순위 별칭으로 유지됩니다.

CLI

opencode-chromium doctor --json
opencode-chromium verify
opencode-chromium install --client opencode --dry-run
opencode-chromium install --client opencode-mcp --dry-run
opencode-chromium install --client codex --dry-run
opencode-chromium install --client skills --dry-run
opencode-chromium uninstall --client codex --dry-run
opencode-chromium uninstall --client skills --dry-run

설치 및 제거는 변경 전에 명명된 구성을 백업하고, 표준 항목만 건드리며, 드라이 런을 지원하고, 변경된 파일을 보고합니다.

컨텍스트 및 기능

기본 도구 스키마는 작게 유지됩니다. 고급 설명은 다음을 통해 요청하세요:

{"mode":"capabilities","pack":"downloads"}

최상위 도구를 추가하지 않고 browser_run을 통해 고급 작업을 실행하세요:

{
  "steps": [{
    "action": "capability",
    "capability": "downloads.events",
    "input": {}
  }]
}

심층 요청/응답 디버깅을 위해 필요할 때만 지연 네트워크 팩을 요청하세요:

{"mode":"capabilities","pack":"network"}

그런 다음 browser_run에서 대상 tabId로 network.inspect를 실행하세요. 탭의 CDP 요청/응답 수명 주기를 따르고, URL/메서드/유형/상태/requestId 필터를 지원하며, includeHeaders가 요청된 경우에만 수정된 헤더를 반환합니다. 본문은 명시적으로 요청되고 승인되지 않는 한 비활성화된 상태로 유지됩니다. bodyDelivery: "artifact"는 옵트인된 본문을 인라인 미리보기 대신 아티팩트 저장소로 넘깁니다. target.requestId가 있는 browser_observe 모드 inspect는 단일 요청의 수명 주기 세부 정보를 반환합니다.

큰 결과와 스크린샷은 아티팩트 우선입니다. MCP 클라이언트는 browser://sessions/<session-id>/artifacts/<artifact-id>를 통해 검색합니다; OpenCode는 browser_observe 모드 artifact로 동일한 URI를 요청할 수 있습니다.

저장소 구조

src/core/                 shared runtime, schemas, safety, artifacts, versions
src/browser/              profile-aware IPC client, policies, and operation engine
src/adapters/mcp/         universal MCP server and transports
src/adapters/opencode/    native OpenCode V2 adapter
src/adapters/sdk/         provider schema adapters and direct agent API
src/cli/                  install, configure, uninstall, doctor, verify
extension/                Manifest V3 browser integration
native-host/              native messaging host and semantic workers
skills/                   provider-neutral browser skill
tests/                    unit, contract, browser, and adapter regression tests
docs/                     architecture, compatibility, security, and migration guides

검증 및 릴리스

bun run build
bun run check:schemas
bun run check:package
bun run check:mcp
bun run test:contracts
bun run test:opencode
bun run pack
bun run test:tarball
bun run check:release

릴리스 검사는 오래된 V1 경로, 개인 상태, 중복 레거시 패키지 표면, 예산을 초과하는 스키마 증가 및 내장 어댑터가 누락된 tarball을 거부합니다.

GitHub Actions는 풀 리퀘스트 및 master 푸시에서 동일한 검증을 실행합니다. 릴리스는 보호된 npm-production 환경을 통해 npm Trusted Publishing을 사용하여 일치하는 v* 태그에서만 게시됩니다. 저장소 또는 워크플로우에 npm 토큰이 저장되지 않습니다.

보안

브라우저 콘텐츠는 신뢰할 수 없습니다. 중요한 작업에는 수명이 짧은 불변 승인 토큰이 필요합니다. 쓰기는 불확실한 실행 후 자동으로 반복되지 않습니다. 아티팩트는 세션 범위로 제한되고, 만료되며, 트래버설을 거부하고, 로그에 기록되지 않습니다. MCP 프로토콜 데이터는 stdout에 유지되고 진단은 stderr에 유지됩니다.

docs/architecture.md, docs/security.md, docs/compatibility.md 및 docs/migration-1.0.md를 참조하세요.

라이선스

MIT