Claude Code로 Context7 로컬-퍼스트 대안을 구축했습니다

Source: Dev.to

Source: …

Context — AI 에이전트를 위한 로컬‑퍼스트 문서 도구

Context7이 무료 티어를 축소하고 속도 제한을 추가한 뒤에 만들었습니다. 결과물은 팀 전체와 공유할 수 있는 휴대용, 오프라인‑퍼스트 문서 데이터베이스입니다.

“아하” 순간: 왜 문서를 그냥 로컬에 저장하지 않을까?

클라우드 문서 서비스(Context7, Deepcon 등)는 보통 세 가지 일을 합니다:

1. Clone 라이브러리의 문서 저장소를 복제한다.
2. Index 마크다운을 검색 가능한 청크로 인덱싱한다.
3. Serve API를 통해 결과를 제공한다.

1·2 단계는 라이브러리 버전당 한 번만 수행하면 되지만, 서비스는 이를 서버에서 실행하고 3단계에 대해 쿼리당 요금을 부과합니다—매번요.

해결책: 1·2 단계를 로컬에서 수행하고 결과를 파일로 저장한 뒤, 네트워크를 완전히 생략한다.

context add https://github.com/vercel/next.js

• context add는 레포를 복제하고, 문서를 파싱하고, 모든 내용을 SQLite 데이터베이스에 인덱싱한 뒤 ~/.context/packages/nextjs@16.0.db에 저장합니다.
• 생성된 .db 파일에는 Next.js 16 문서 전체가 사전 인덱싱되어 즉시 쿼리할 수 있는 상태로 들어 있습니다.
• 인터넷도 없고, 속도 제한도 없으며, 월 요금도 없습니다.

Claude Code 로 구축하기

전체 작업을 Claude Code와 함께 만들었습니다. 단순히 “보일러플레이트를 생성‑수정”하는 도우미가 아니라, 아키텍처, 구현, 디버깅까지 협업해 주는 진정한 파트너였습니다.

스택

빌드 파이프라인 동작 방식

context add <source>를 실행하면 다음 단계가 수행됩니다:

1. 소스 감지 – 인수가 git URL, 로컬 디렉터리, 혹은 미리 만든 .db 파일인지 판단합니다. GitHub, GitLab, Bitbucket, Codeberg, SSH 단축형(git@host:user/repo), 그리고 모노레포 URL 패턴을 지원합니다.
2. 얕은 복제 – git clone --depth 1을 실행해(전체 히스토리가 아닌 문서만) 복제합니다. CLI는 태그를 가져와 인터랙티브하게 버전을 선택하게 하거나, 자동화를 위해 --tag v16.0.0을 전달할 수 있습니다.
3. 문서 폴더 감지 – docs/, documentation/, doc/ 디렉터리를 자동 스캔하고, .gitignore를 존중하며, 언어별 필터링을 수행합니다(기본: 영어; --lang all이면 다국어 레포도 포함).
4. 마크다운 파싱 및 청크화 –
   • YAML 프론트‑머터에서 제목과 설명을 추출합니다.
   • H2 헤딩을 기준으로 청크를 나눕니다(문서의 자연 단위).
   • 청크당 약 800 토큰을 목표로 하며, 최대 1 200 토큰을 초과하지 않게 합니다.
   • 크기가 큰 섹션은 먼저 코드 블록 경계에서, 그 다음 문단 경계에서 나눕니다.
   • 링크 비율이 50 %를 초과하는 목차 섹션은 필터링합니다.
   • MDX 전용 React 태그(````와 ``` 등)를 제거합니다.
   • 내용 해시를 이용해 동일한 섹션을 중복 제거합니다.
5. SQLite 패키징 – 모든 것이 하나의 .db 파일에 저장됩니다:

CREATE TABLE chunks (
  id            INTEGER PRIMARY KEY,
  doc_path      TEXT NOT NULL,
  doc_title     TEXT NOT NULL,
  section_title TEXT NOT NULL,
  content       TEXT NOT NULL,
  tokens        INTEGER NOT NULL,
  has_code      INTEGER DEFAULT 0
);

CREATE VIRTUAL TABLE chunks_fts USING fts5(
  doc_title, section_title, content,
  content='chunks', content_rowid='id',
  tokenize='porter unicode61'
);

Porter 형태소 분석을 적용한 FTS5 가상 테이블 덕분에 “authentication middleware”와 같은 쿼리가 “authenticating in middleware”와도 매칭됩니다. BM25 랭킹은 섹션 제목에 ×10, 문서 제목에 ×5 가중치를 부여해 임베딩 없이도 관련성을 확보합니다.

검색 파이프라인: 단순함을 유지하기

사용자가 context query "<질문>"을 입력하면… (이하 내용은 다음 파트에 이어집니다)

MCP 클라이언트(예: Claude)가 호출합니다:

get_docs({ library: "nextjs@16.0", topic: "middleware" })

인‑프로세스 파이프라인은 다음과 같이 실행됩니다:

FTS5 query → BM25 ranking → Relevance filter → Token budget → Merge adjacent → Format

• Relevance filter – 최상위 히트 점수의 50 % 이하인 결과를 제외합니다.
• Token budget – 출력 토큰을 2 000 토큰으로 제한합니다(컨텍스트 창을 넘치게 하지 않으면서도 충분히 유용).
• Merge adjacent – 같은 문서의 인접한 청크를 합쳐 LLM이 단편이 아닌 일관된 섹션을 받도록 합니다.

총 지연 시간: 10 ms 미만, 클라우드 왕복 100–500 ms와 AI 대기 시간을 합친 것보다 훨씬 빠릅니다. 코딩 세션 중에 어시스턴트가 즉시 반응해야 할 때 이 속도가 중요합니다.

TL;DR

• Local‑first 문서 → 속도 제한 없음, 월 비용 없음.
• SQLite + FTS5 → 빠르고 설정이 필요 없는 저장 및 검색.
• Claude Code → 페어 프로그래밍 한 주 만에 전체를 구현했습니다.

한 번 사용해 보세요: Context on GitHub.

AI 코딩 에이전트와 로컬‑퍼스트 문서화

AI 코딩 에이전트는 세션당 수십 번의 도구 호출을 수행합니다. 각 문서 조회마다 약 300 ms의 네트워크 지연이 추가된다면, 상호작용당 몇 초의 대기 시간이 발생합니다. 로컬에서는 사실상 비용이 없습니다.

진정한 승리: 한 번 빌드하고 어디서든 공유

문서 패키지를 빌드하면 결과는 단일 .db 파일이 됩니다. 이 파일은 메타데이터, 콘텐츠, 검색 인덱스 등 모든 것이 완전히 자체 포함되어 있습니다. 다음과 같이 사용할 수 있습니다:

# Build and export
context add https://github.com/your-org/design-system \
  --name design-system --pkg-version 3.1 --save ./packages/

# The result: a portable file
ls -la packages/design-system@3.1.db
# 2.4 MB – your entire design‑system docs, indexed and ready

이제 원하는 방식으로 파일을 공유하세요: S3 버킷에 업로드하거나, 리포지토리에 커밋하거나, 공유 드라이브에 놓을 수 있습니다. 팀원들은 다음과 같이 설치합니다:

context add https://your-cdn.com/design-system@3.1.db

그들의 쪽에서는 빌드 단계가 없습니다. 리포지토리를 클론하지 않습니다. 인덱싱을 기다릴 필요도 없습니다. 사전 빌드된 패키지는 이미 인덱싱되어 있기 때문에 즉시 설치됩니다.

로컬‑퍼스트의 핵심 아키텍처적 장점: 클라우드 서비스에서는 각 사용자가 쿼리 비용을 지불하지만, 로컬 패키지는 빌드 비용을 한 번만 지불하고 결과를 배포합니다. 이는 컴파일된 바이너리와 인터프리터 스크립트의 차이와 동일한 원리로, 비용이 많이 드는 작업을 미리 수행합니다.

내부 라이브러리의 경우 이는 매우 큰 이점입니다. 내부 API를 문서화하고 CI에서 패키지를 빌드한 뒤 npm 패키지와 함께 배포하면, 팀의 모든 개발자는 최신 문서에 즉시, 사적으로, 오프라인으로 접근할 수 있습니다. 클라우드 서비스는 여러분의 독점 API 쿼리를 볼 수 없습니다.

Claude Code로 개발하면서 배운 점

Claude Code를 주요 개발 도구로 사용하면서 얻은 솔직한 관찰 몇 가지:

• 코드 배치를 정말 잘한다. Git URL 파싱, CLI 인수 처리, SQLite 스키마 설계—지루하지만 정확해야 하는 종류의 코드. Claude Code는 이를 빠르고 정확하게 처리했다. git 모듈은 내가 생각하지 못한 엣지 케이스도 다룬다: @ai-sdk/gateway@1.2.3 같은 모노레포 태그 형식, SSH 단축 URL, 레포 이름에서 -docs 접미사 제거 등.
• “맛”에 관한 결정은 어려워한다. 청크 크기, 낮은 관련성 결과를 얼마나 적극적으로 필터링할지, 혹은 BM25 가중치가 어느 정도가 적당한지는 인간의 판단과 반복이 필요하다. 나는 값을 시도하고 실제 문서와 비교 테스트를 거쳐 조정하고 다시 반복했다. Claude Code는 각 변형을 빠르게 구현하는 데 도움을 줬지만, 어느 것이 옳은지는 내 선택이었다.
• 반복 속도가 진정한 초능력이다. 전체 프로젝트—CLI, 빌드 파이프라인, 검색 엔진, MCP 서버, 테스트—가 약 일주일 만에 완성되었다. 코드가 사소해서가 아니라(마크다운 파서는 이미 수십 개의 엣지 케이스를 처리한다) 피드백 루프가 촘촘했기 때문이다. 원하는 것을 설명하고, 결과를 검토하고, 조정하고, 다시 진행한다.
• 테스트 기반 프롬프트가 잘 작동한다. 원하는 동작을 테스트 케이스 형태로 설명한다: “이 마크다운 입력은 이 청크들을 생성해야 한다.” Claude Code는 구현 코드와 테스트 코드를 모두 작성했다. 일치하지 않을 때는 함께 원인을 찾아냈다.

숫자

설정하기

# Install
npm install -g @neuledge/context

# Add some docs
context add https://github.com/vercel/next.js
context add https://github.com/vercel/ai

# Connect to your AI agent (Claude Code example)
claude mcp add context -- context serve

Claude Desktop, Cursor, VS Code Copilot, Windsurf, Zed, Goose 및 MCP와 호환되는 모든 에이전트에서 작동합니다. MCP 서버는 설치된 라이브러리의 동적 열거형을 제공하는 단일 get_docs 도구를 노출합니다—AI는 사용 가능한 항목을 정확히 확인하고 필요할 때 이를 쿼리합니다.

다음 단계

검색은 현재 키워드 기반(FTS5 + BM25)입니다. “middleware authentication”이나 “ai sdk agent loop”와 같은 직접적인 쿼리에는 잘 작동하지만 의미적 유사성은 이해하지 못합니다. “How do I protect routes?”와 같은 질문은 단어가 겹치지 않는 한 “Authentication Guards”라는 섹션과 매치되지 않습니다.

예정된 개선 사항:

1. 의미 검색을 위한 로컬 임베딩 – 여전히 완전 오프라인이며, 아마도 작은 모델을 사용한 ONNX Runtime을 활용합니다. SQLite 구조 덕분에 간단히 구현할 수 있습니다: embeddings 테이블을 추가하고, 빌드 시 벡터를 계산한 뒤, 검색 시 코사인 유사도로 쿼리합니다.
2. GraphRAG‑스타일 관계 테이블 – 연결된 문서를 탐색합니다. 미들웨어에 대해 질문하면 인증, 라우팅, 오류 처리도 함께 보고 싶을 가능성이 높습니다. 관계 그래프를 통해 이러한 항목들을 자동으로 표시할 수 있습니다.
3. 패키지 레지스트리 – 커뮤니티가 사전 구축된 문서 패키지를 발견하고 공유할 수 있는 GitHub 기반 인덱스입니다. 모두가 개별적으로 같은 Next.js 문서를 빌드하는 대신, 한 번 빌드하고 공개하면 됩니다.

핵심 요약

프로젝트에서 얻은 핵심 교훈: 모든 것이 클라우드 서비스일 필요는 없습니다.

AI 에이전트용 문서는 로컬‑우선 접근에 완벽히 맞습니다. 데이터는 라이브러리 버전마다 드물게 변경되고, 쿼리는 빠르게 처리되어야 합니다(에이전트가 많이 호출함), 프라이버시가 중요합니다(코드베이스에 대한 질문이므로), 그리고 “한 번 빌드하고 영원히 사용” 모델이 자연스럽게 맞습니다.

속도 제한, 지연 시간, 혹은 정적 파일이어야 할 것을 매월 비용을 내며 이용하는 것이 답답하다면—한 번 시도해 보세요.

Context MCP는 github.com/neuledge/context 에서 오픈 소스로 제공됩니다. npm에 @neuledge/context 로 공개되었습니다.