KnockOutEZ/wigolo 딥다이브
— AI 코딩 에이전트에게 "열쇠도 클라우드도 없는 웹"을 통째로 쥐여 주는 로컬 MCP 서버

1프로젝트 한 줄 요약

KnockOutEZ/wigolo는 내 컴퓨터에서 도는 MCP(Model Context Protocol) 서버다. Claude Code·Cursor·Codex 같은 AI 코딩 에이전트에 붙여 두면, 에이전트가 "이거 검색해 줘 / 이 페이지 읽어 줘 / 이 사이트 크롤해 줘 / 이 표만 뽑아 줘 / 이 주제 리서치해 줘" 같은 웹 작업을 단 하나의 창구로 시킬 수 있다. package.json의 설명 그대로 "Local-first web intelligence MCP server for AI coding agents"이다.

가장 먼저 풀어야 할 오해 — 이름이 "위골로"라 낯설지만, 이건 Firecrawl·Exa·Tavily처럼 돈 받고 API를 파는 웹 서비스의 "키 없는 로컬 버전"이다. 보통 이런 도구는 회원가입 → API 키 발급 → 쿼리마다 과금이지만, wigolo는 공개 검색엔진(DuckDuckGo·Bing·Mojeek…)의 결과 HTML을 직접 긁어 오고, 그 결과의 순위 매기기·유사도 계산을 내 CPU에서 도는 작은 AI 모델(ONNX)로 처리한다. 그래서 검색 키가 필요 없고, 쿼리당 비용이 0이다.

2왜 지금 주목받는가

wigolo가 트렌딩에 오른 이유는 "또 하나의 크롤러"여서가 아니다. AI 에이전트가 폭발적으로 늘면서 "에이전트에게 웹을 어떻게 쥐여 줄 것인가"가 병목이 됐는데, 지금까지의 답은 대부분 Firecrawl·Exa·Tavily 같은 유료 API였다. wigolo는 그걸 키도 클라우드도 없이, 내 기기에서 공짜로 하겠다고 나선 정면 도전이다. README 스스로 밝히길, 공개 직후 48시간 만에 별 대부분이 몰렸다(2026년 7월 초).

주목 포인트 1 — "에이전트에게 웹을 주는 법"을 표준화하되, 값을 0으로 눌렀다

지금 AI 에이전트 생태계의 뜨거운 병목은 "모델은 똑똑한데 최신 웹을 못 본다"는 것이다. 그 틈을 Firecrawl·Exa·Tavily 같은 유료 API가 메워 왔다. wigolo는 같은 일을 MCP 도구 10개로 표준화해 어떤 에이전트에도 꽂히게 하면서, 비용은 공개 엔진 스크래핑 + 온디바이스 ML로 0에 눌렀다. "에이전트 시대의 인프라를 오픈소스로, 그것도 공짜로"라는 서사가 트렌딩의 동력이다.

주목 포인트 2 — 검색 품질을 "모델 없이" 끌어올리는 파이프라인

단순 스크래핑은 결과가 지저분하다. wigolo가 흥미로운 건 여러 엔진 결과를 합치고 순위를 매기는 과정을 전부 확정적 알고리즘 + 작은 기기 모델로 처리한다는 점이다. 여러 엔진 순위를 RRF(상호 순위 융합)로 합치고, 기기 안 크로스 인코더(ms-marco-MiniLM)로 질의–결과 적합도를 재계산해 재정렬한다. "큰 LLM 없이도 검색 품질을 어떻게 올리나"의 실전 교재다.

주목 포인트 3 — "한 서버, 다섯 얼굴"의 실전 패키징

wigolo는 사실 MCP 서버이자, CLI이자, REST API 서버이자, npm 라이브러리이자, SDK 묶음이다. 같은 구현을 stdio(MCP)·터미널 명령·127.0.0.1:3333 REST로 동시에 노출한다. "하나의 핵심 로직을 여러 진입점으로 파는" 현대적 도구 패키징을 통째로 관찰할 수 있다. 게다가 브라우저 자동화(Playwright)·SQLite 벡터검색·온디바이스 임베딩·TLS 지문 위장까지, 한 저장소 안에 요즘 인프라 기술이 밀집해 있다.

3기술 스택 전체 지도

wigolo는 TypeScript로 짠 Node ≥ 20 프로그램이다("type": "module" ESM). 코드의 압도적 다수가 .ts(1,073개)이고, .py(44개)는 별도로 버전 관리되는 파이썬 SDK·프레임워크 연동일 뿐 핵심이 아니다. 스택을 ① 프로토콜·런타임, ② 웹 수집(브라우저·HTTP), ③ 저장·검색(SQLite), ④ 지능(온디바이스 ML), ⑤ 부가(LLM·CLI UI)로 나눠 지도를 그려 보자.

① 프로토콜 · 런타임 · 빌드

② 웹 수집 — 3단 사다리로 "막히면 세게"

수집은 가벼운 것부터 시도하고 막히면 더 강한 수단으로 올라가는 계단식이다. 이게 src/fetch/router.ts(63KB, 저장소에서 가장 큰 파일)의 SmartRouter다.

③ 저장 · 검색 — SQLite 하나에 "단어 검색 + 벡터 검색"을 얹다

④ 지능 — 임베딩·리랭킹을 전부 "기기 안에서"

⑤ 부가 — LLM(선택) · 키 보관 · 터미널 UI

LLM은 전적으로 선택이며 문장 합성(research·agent·search format=answer)에만 쓴다 — @anthropic-ai/sdk·openai·@google/genai·groq-sdk, 또는 로컬 Ollama. API 키는 선택 의존성 @napi-rs/keyring ^1.3.0으로 OS 키체인에 넣거나 AES 암호화 파일로 보관한다(config.json엔 절대 평문 저장 안 함). 터미널 UI(설정 마법사·대화형 셸)는 ink ^5.2.1 + react ^18.3.1 + @inquirer/prompts로 그린다.

4아키텍처 심화 분석

wigolo의 데이터 흐름은 "에이전트의 요청이 MCP 창구로 들어와, 도구 계층을 지나, 웹과 로컬 캐시를 오가며 답을 만들어 돌아가는" 구조다. 전체 지도를 먼저 그리고, 두 개의 핵심 엔진(수집 사다리 · 검색 파이프라인)을 확대해 보자.

핵심 설계 ① — SmartRouter: "막히면 한 단계 세게" 올라가고, 그 판단을 도메인별로 학습

웹 수집의 난제는 "어떤 페이지는 그냥 HTTP로 되고, 어떤 페이지는 봇 차단 때문에 진짜 브라우저가 필요하다"는 것이다. wigolo는 가장 싼 수단부터 시도하고, 실패 신호(403·SPA 빈 껍데기·본문 빈약·챌린지 페이지)를 보면 한 단계 올라간다. 그리고 결정적으로 — 어느 도메인이 몇 단을 요구하는지 학습해 SQLite(domain_routing)에 저장한다. 다음번 같은 도메인은 처음부터 맞는 단계로 간다.

핵심 설계 ② — 검색 파이프라인: 의도 분류 → 버티컬 엔진 → 융합 → 재정렬

wigolo의 search는 그냥 한 엔진에 던지는 게 아니다. 먼저 질의의 "의도"를 분류(intent-router.ts)해 버티컬(general·news·papers·docs·code·images)을 정하고, 그 버티컬에 맞는 엔진 묶음만 병렬로 부른다. 예컨대 논문 질의면 arXiv·Semantic Scholar가, 코드 질의면 GitHub 코드검색·StackOverflow가 붙는 식이다. 그렇게 모은 여러 순위를 RRF로 융합하고, 기기 안 크로스 인코더로 최종 재정렬한 뒤, 인용 ID가 달린 근거·하이라이트로 돌려준다.

핵심 설계 ③ — 로컬 저장소: SQLite 한 파일이 캐시·색인·학습 데이터를 겸한다

모든 로컬 상태는 ~/.wigolo/wigolo.db 하나에 모인다(src/cache/db.ts). 표 하나에 여러 검색 방식을 얹은 게 특징이다.

5디렉토리 구조 해부

저장소를 열면 압도되기 쉽다(파일 1,543개, 코드 20만 줄). 하지만 뼈대는 단순하다 — src/가 실제 두뇌이고 나머지는 테스트·배포·연동·문서다. 진입점부터 따라가 보자.

진입점 읽는 순서는 이렇다. ① src/index.ts(CLI 라우팅 — 무슨 명령이 뭘 하는지) → ② src/server.ts(MCP 서버가 어떻게 뜨고 도구를 등록하는지) → ③ src/server/tool-schemas.ts(각 도구가 받는 입력 스키마) → ④ 관심 도구의 src/tools/*.ts → ⑤ 그 도구가 부르는 서브시스템(search/ 또는 fetch/). 가장 큰 파일 src/fetch/router.ts(63KB)와 src/types.ts(71KB)가 각각 "수집 두뇌"와 "타입 지도"라, 이 둘을 훑으면 전체 그림이 빠르게 잡힌다.

6학습 포인트

wigolo가 학습 표본으로 훌륭한 이유는 MCP 서버 설계, 웹 스크래핑, 브라우저 자동화, SQLite 벡터 검색, 온디바이스 ML, TLS 위장, 다중 진입점 패키징이 한 저장소에 모여 있기 때문이다. 관심사별로 배울 것을 짚어 보자.

① MCP 서버를 "제대로" 짜는 법

src/server.ts + src/server/tool-schemas.ts는 MCP 서버의 실전 레퍼런스다. 도구를 어떻게 등록하고(ListToolsRequestSchema/CallToolRequestSchema), 입력 스키마를 어떻게 선언하며, 사용 안내를 MCP Resource로 어떻게 노출하는지 볼 수 있다. 특히 도구 10개가 하나의 stdio 서버에 깔끔히 얹힌 구조는, 직접 MCP 서버를 만들 때 그대로 베낄 만한 골격이다.

② "봇 차단을 어떻게 우회하나"의 실전 계단

src/fetch/는 웹 스크래핑의 현실을 담은 교재다. 순수 HTTP → TLS 지문 위장 → 헤드리스 브라우저로 올라가는 escalation 전략, 실패 신호(403·SPA 껍데기·챌린지)를 읽는 법, 그리고 도메인별로 필요한 강도를 학습·저장해 다음번을 빠르게 하는 최적화까지. "왜 어떤 페이지는 requests로 안 되는가"를 코드로 이해하게 된다.

③ "큰 LLM 없이 검색 품질 올리기"

src/search/는 정보 검색(IR)의 압축 강의다. 여러 엔진 순위를 RRF로 융합하고, 크로스 인코더로 재정렬하고, 중복을 지우고, 근거·하이라이트를 뽑는 전 과정이 확정적 코드 + 작은 온디바이스 모델로 짜여 있다. "검색은 무조건 큰 LLM"이라는 통념 대신, 값싼 부품으로 품질을 조립하는 법을 배운다.

④ SQLite 하나로 "단어 + 의미" 하이브리드 검색

src/cache/db.ts + src/embedding/는 SQLite에 FTS5(단어)와 sqlite-vec(벡터)를 함께 얹어 하이브리드 검색을 만드는 법을 보여 준다. 임베딩을 기기 안 fastembed(ONNX)로 뽑아 url_cache 테이블에 벡터째 저장하는 구조는, RAG를 "서버 없이 로컬로" 만들고 싶은 사람에게 최고의 참고 예시다.

⑤ "하나의 코어, 여러 얼굴"의 패키징

같은 로직을 MCP(stdio)·CLI·REST(127.0.0.1:3333)·npm 라이브러리로 동시에 파는 구조(src/index.ts·src/daemon/)는 현대적 도구 배포의 정석이다. tsup로 빌드하고 @yao-pkg/pkg로 단일 실행파일을 만들고 Docker 이미지를 굽는 packaging/까지, "라이브러리를 여러 채널로 배포"하는 전 과정을 통독할 수 있다.

7시스템 · 실행 요구사항

wigolo는 클라우드 인프라가 필요 없다. 대신 첫 실행 때 브라우저 엔진 바이너리와 온디바이스 ONNX 모델을 ~/.wigolo/로 한 번 내려받는다(수백 MB). 이후 유휴 메모리는 ~47MB로 가볍다(v0.2.0 기준).

설치 · 실행 명령

# 가장 쉬운 길: 에이전트에 자동 연결 (MCP 설정 + 스킬 + 모델 다운로드 + 헬스체크)
npx wigolo init --agents=claude-code
#   지원: claude-code · cursor · codex · gemini-cli · vscode · windsurf · zed · antigravity

# 또는 MCP 클라이언트 설정에 직접 등록
#   mcpServers: { "wigolo": { "command": "npx", "args": ["-y", "wigolo"] } }

# CLI 한 방 (MCP 없이 바로 도구 실행)
npx wigolo search "rust async runtime comparison"
npx wigolo fetch  "https://example.com/article"

# 관리 명령
npx wigolo doctor      # 환경 점검
npx wigolo tune        # 도메인별 학습된 수집 단계 확인
npx wigolo serve       # REST API 모드 (127.0.0.1:3333, OpenAPI 3.1)

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

저장소 · 제품
· GitHub: github.com/KnockOutEZ/wigolo (AGPL-3.0-only © 2026 Towhid Khan · v0.2.0)
· 최신 커밋: c0afc83 (2026-07-17, PR #184 "fix/vercel-ai-sdk-ignore-scripts" 병합)
· 겨냥한 유료 대체 대상: Firecrawl · Exa · Tavily

핵심 파일(클론 후)
· src/server.ts — MCP 서버 코어(도구 10개 등록)
· src/index.ts — CLI 진입점(명령 라우팅)
· src/fetch/router.ts — SmartRouter 3단 수집 사다리(63KB, 최대 파일)
· src/search/core/ + verticals/ — 의도 분류 → 버티컬 엔진 → RRF → 재정렬
· src/cache/db.ts — SQLite(FTS5 + vec0) 로컬 저장
· src/embedding/fastembed-provider.ts — 온디바이스 임베딩

배경 지식
· Model Context Protocol — MCP 규격의 원전
· Playwright · sqlite-vec · fastembed
· Reciprocal Rank Fusion(RRF) — 순위 융합의 개념
· SQLite FTS5 — 내장 전문 검색