[LLM Wiki 28] Context7은 어떻게 문서를 AI 컨텍스트로 바꾸나: 공개된 동작과 직접 만드는 설계

앞 글에서는 Context7이 최신 개발 문서를 MCP로 AI Agent에 연결하는 과정을 살펴봤습니다. 이번에는 한 단계 더 안쪽으로 들어갑니다.

저장소나 문서 사이트를 Context7에 등록하면 무엇을 읽고, 어떻게 나누며, 어떤 검색 과정을 거쳐 답변용 컨텍스트가 되는지, 그리고 공개되지 않은 부분은 무엇인지 확인했습니다. 마지막에는 같은 목적의 시스템을 직접 만들 수 있도록 데이터 모델, 검색 파이프라인, 갱신 방식, 보안 경계를 하나의 설계로 연결합니다.

먼저 결론부터 말하면 이렇습니다.

Context7은 문서와 코드 예제를 미리 색인하고, 질문으로 벡터 검색한 후보를 기본적으로 LLM이 재정렬한 뒤, 출처가 붙은 snippet을 MCP 결과로 현재 대화에 전달합니다. 다만 정확한 parser, chunking, embedding model, vector database, reranker 구현은 공개하지 않았습니다.

공개 저장소가 Context7 전체는 아니다

Context7의 공식 GitHub 저장소를 보면 MCP server, CLI, TypeScript SDK, 여러 AI SDK용 도구 코드를 확인할 수 있습니다. 하지만 README는 API backend, parsing engine, crawling engine이 공개 저장소에 포함되지 않는다고 명시합니다.

따라서 공개 저장소를 실행한다고 Context7 서비스 전체가 생기지는 않습니다. 공개된 코드는 MCP 요청을 받아 비공개 REST API에 전달하는 얇은 adapter에 가깝습니다.

영역	공개 여부	확인할 수 있는 것
MCP server, CLI, SDK	공개	도구 schema, 요청 변환, REST endpoint, 결과 formatting
REST API 계약	공개	library 검색, context 검색, 응답 필드, fast 옵션
수집과 검색의 고수준 단계	일부 공개	지원 source, 문서 우선 처리, vector search, LLM reranking, 품질 관리
parser, chunker, crawler	비공개	정확한 경계, 크기, 예외 처리, source별 세부 알고리즘은 알 수 없음
embedding, vector store, reranker	SaaS 구현 비공개	모델, 저장 제품, top-k, threshold, prompt는 알 수 없음

이 구분이 중요한 이유는 단순합니다. Context7과 비슷한 제품을 만들려면 공개 MCP server만 복제하는 것이 아니라 가운데의 수집, 색인, 검색 backend를 직접 만들어야 합니다.

Agent가 보는 표면은 도구 두 개다

현재 공개 코드에서 핵심 MCP 도구는 두 개입니다. 정확한 입력은 다음과 같습니다.

resolve-library-id({
  query: string,
  libraryName: string
})

query-docs({
  libraryId: string,
  query: string
})

첫 번째 도구는 이름을 Context7 library ID 후보로 바꿉니다. 예를 들어 React만으로는 공식 문서, framework, 이름이 비슷한 package가 섞일 수 있습니다. 검색 API가 후보를 순위화하면 호출한 LLM이 이름, 설명, snippet 수, trust, benchmark, version을 읽고 최종 ID를 고릅니다. 즉 MCP handler가 첫 번째 결과를 무조건 확정하는 구조는 아닙니다.

두 번째 도구는 선택된 library 안에서 구체적인 개발 질문과 관련된 문서와 코드 예제를 가져옵니다. 공개 MCP 코드는 다음 REST endpoint를 호출합니다.

GET https://context7.com/api/v2/libs/search
    ?query=React%20useEffect%20cleanup
    &libraryName=React

GET https://context7.com/api/v2/context
    ?query=React%20useEffect%20cleanup
    &libraryId=/reactjs/react.dev

query-docs가 받은 text는 MCP의 tool result로 돌아가고, MCP Host가 이를 LLM의 현재 컨텍스트에 넣습니다. Context7이 모델을 다시 학습시키거나 장기 기억을 고치는 것은 아닙니다.

또 하나 눈여겨볼 점은 검색어를 만드는 위치입니다. Context7 공식 skill은 사용자의 전체 작업을 그대로 보내기보다 “문서에서 무엇을 찾아야 하는가”로 질문을 좁히도록 안내합니다.

사용자 작업
Next.js 로그인 middleware를 작성하고 테스트도 만들어줘

문서 검색 query
Next.js middleware cookie authentication and redirects

MCP adapter가 이 query를 다시 생성하는 것이 아니라, 도구를 호출하는 Agent가 먼저 검색 의도로 바꿉니다. 여러 독립 주제가 섞여 있으면 주제별로 나눠 호출하는 편이 검색 품질도 좋습니다.

무엇을 수집하나

현재 Add Library 화면에는 GitHub, GitLab, Bitbucket, Other Git, Confluence, Notion, PDF, OpenAPI, Website, LLMs.txt가 source 유형으로 노출됩니다. 다만 source마다 공개 API와 세부 처리 문서의 완성도는 다릅니다. Notion과 PDF처럼 UI에는 있지만 공개 API reference가 제한적인 유형도 있습니다.

Git repository에서는 Adding Libraries 문서에 따라 다음 문서 확장자를 우선 처리합니다.

.md, .mdx, .markdown, .rst, .txt, .ipynb

문서에서 code example과 그 주변 설명을 추출합니다. 충분한 문서가 있으면 .py, .ts, .go 같은 raw source 전체를 곧바로 문서 index에 넣지는 않습니다.

반대로 문서가 거의 없으면 source code에서 사용 예제를 만드는 fallback이 동작합니다. Public repository에서는 자동이며, private repository에서는 generateDocs: true로 켜는 방식입니다. “문서가 거의 없다”를 판정하는 수치, source symbol을 찾는 parser, 생성 prompt와 model은 공개되지 않았습니다.

이 점 때문에 “코드를 올리면 Context7이 알아서 context를 만든다”는 말은 절반만 맞습니다.

1. Git URL이나 문서 source를 등록합니다.
2. Context7 backend가 허용된 범위를 가져옵니다.
3. 문서가 있으면 문서와 code example을 우선 처리합니다.
4. 문서가 부족한 public repository는 source 기반 example 생성 경로를 사용할 수 있습니다.
5. 결과를 검색 가능한 snippet으로 색인합니다.

원본 repository의 모든 파일을 같은 방식으로 embedding하는 단순 구조라고 보기는 어렵습니다.

Library를 찾는 검색과 문서 안을 찾는 검색은 다르다

Context7에는 적어도 두 종류의 검색 문제가 있습니다.

Library catalog 검색

React, Next.js, Prisma 같은 이름을 정확한 library ID로 바꾸는 단계입니다. Upstash는 Redis Search를 이용한 catalog 검색 구조를 공개했습니다.

이 검색은 title, description 같은 자연어 필드와 exact technical field를 구분합니다. 제목에 더 높은 가중치를 주고, 기술 식별자는 stemming을 피하며, exact와 prefix match를 활용합니다. Verified 여부, trust score, stars, referring domain 같은 품질과 인기도 신호도 순위에 반영합니다.

즉 library resolution은 “이름을 embedding해서 가장 가까운 하나를 고르는 문제”가 아닙니다. 기술 이름의 정확한 일치와 신뢰 신호가 중요한 catalog search입니다.

Library 내부 문서 검색

선택된 library 안에서 질문과 관련된 snippet을 찾는 단계입니다. 공식 OpenAPI 명세는 기본 경로를 다음처럼 설명합니다.

자연어 query
→ vector search
→ LLM reranking
→ 선택된 code, info snippet

REST API의 fast=true는 LLM reranking을 생략하고 vector search 상위 결과를 바로 반환합니다. 반대로 기본값인 fast=false는 LLM이 후보를 다시 평가합니다. MCP 도구 schema에는 이 옵션이 노출되지 않으므로 일반 MCP 호출은 기본 재정렬 경로를 사용합니다.

여기서 주의할 점이 있습니다. Context7이 library catalog에 Redis Search를 쓰는 것은 확인됐지만, library 내부 문서 검색에도 BM25와 RRF를 사용한다고 공개한 것은 아닙니다. 확인되는 것은 vector search와 LLM reranking입니다. 뒤에서 제안할 BM25, dense vector, RRF 조합은 재현 시스템을 위한 권장 설계이지 Context7의 공개된 내부 구현이 아닙니다.

반환되는 것은 출처가 붙은 작은 근거다

Context API의 JSON schema에는 크게 code snippet과 info snippet이 있습니다.

Code snippet에는 다음과 같은 정보가 들어갈 수 있습니다.

type CodeSnippet = {
  codeTitle: string
  codeDescription: string
  codeLanguage: string
  codeTokens: number
  codeId: string
  pageTitle: string
  codeList: Array<{
    language: string
    code: string
  }>
  isDynamic?: boolean
  sourceFile?: string
}

Info snippet은 page ID, breadcrumb, 본문, token 수를 담습니다. 중요한 것은 codeId, pageId, sourceFile, breadcrumb처럼 결과가 어디에서 왔는지 되짚을 수 있는 정보입니다.

좋은 개발 문서 검색은 “비슷한 문장”만 돌려주면 부족합니다. 어떤 library, version, page, repository path에서 가져왔는지 알아야 Agent가 잘못된 버전을 섞지 않고 사람도 결과를 검증할 수 있습니다.

품질을 지키는 네 가지 장치

공식 문서와 기술 글을 함께 보면 검색 외에도 몇 가지 품질 관리가 확인됩니다.

중복 제거

Context7은 exact match와 cosine similarity를 이용해 중복 code snippet을 줄이고, 겹치는 info content도 정리한다고 설명합니다. 다만 cosine threshold와 version을 가로질러 중복을 어떻게 처리하는지는 공개되지 않았습니다.

Version 분리

Version analyzer가 repository나 website의 다중 버전 문서를 감지하고 오래된 문서가 current index에 섞이지 않도록 처리합니다. 과거 version은 tag나 branch를 별도로 등록할 수 있고 다음처럼 version-specific ID도 지원합니다.

/owner/repository/v15.1.8
/owner/[email protected]

경로, heading, package manifest, Git tag 중 어떤 신호를 어떤 가중치로 쓰는지는 알려지지 않았습니다. 따라서 “버전을 항상 정확히 자동 판별한다”고 보장하기보다, version ID를 명시하고 결과의 source를 검증하는 것이 안전합니다.

악성 문서 검사

Context7은 prompt injection과 malware pattern을 classifier로 검사하고, 의심 content를 다시 확인하는 two-pass detection을 사용한다고 설명합니다. 이 역시 classifier model, threshold, 탐지율은 비공개입니다. Data Safety, Enterprise Quality and Safety

Benchmark와 trust

Library마다 trustScore와 benchmarkScore가 노출됩니다. Benchmark는 실제 개발자가 물을 법한 질문으로 문서 검색 품질을 확인하는 데 쓰입니다. 다만 정확한 전체 문항, feature별 가중치, score 산식은 공개되지 않았으므로 별을 몇 개 받았다는 이유만으로 산식을 역추론해서는 안 됩니다.

자주 쓰는 문서는 더 빨리 갱신한다

Public library는 매번 전체 catalog를 같은 주기로 다시 만드는 방식이 아닙니다. Library Updates 문서는 요청이 들어왔을 때 stale 여부를 확인하고, 기준을 넘으면 기존 index를 즉시 제공하면서 background refresh를 시작한다고 설명합니다.

Context7 인기도 순위	오래됐다고 보는 기준
Top 100	1일
Top 1,000	15일
Top 5,000	30일
나머지	45일

이 방식은 stale-while-revalidate와 비슷합니다. 사용자는 오래 기다리지 않고 기존 결과를 받고, 다음 요청부터 갱신된 index를 사용할 수 있습니다. Private library는 기본적으로 자동 갱신하지 않고 수동 refresh를 사용하며, GitHub Actions로 default branch push 때 refresh API를 호출할 수 있습니다.

변경된 content만 다시 처리한다고 공식 문서는 설명하지만, content hash, Git diff, staging index, atomic swap 같은 정확한 incremental indexing 알고리즘은 공개하지 않았습니다.

문서에 답이 없으면 source를 다시 조사한다

2026년 6월에 공개된 Context7 Research는 정적인 문서 색인 다음 단계도 보여 줍니다.

Benchmark 점수가 낮은 질문이 들어오면 별도 sandbox에서 repository를 clone하고 Agent가 source를 조사합니다. 이 결과는 dynamic-context라는 별도 vector index에 저장되어 이후 비슷한 질문에 사용됩니다. 첫 질문에는 기존 결과를 먼저 돌려주고, 뒤의 유사 질문이 개선된 자료를 받는 비동기 학습 루프에 가깝습니다.

OpenAPI의 isDynamic과 sourceFile 필드도 primary docs index가 아니라 dynamic source-code index에서 가져온 snippet을 구분합니다. 공식 글은 2026년 6월 당시 제공된 code snippet의 약 17%가 dynamic context에서 왔다고 밝혔습니다. 이 비율은 시점에 따라 달라질 수 있습니다.

여기서 “학습”은 model weight를 fine-tuning한다는 뜻이 아닙니다. 어려웠던 질문을 계기로 검색용 자료를 추가 생성하고 index에 보관하는 retrieval 개선 루프입니다. 결과에는 TTL이 있어 시간이 지나면 현재 repository를 다시 조사합니다.

직접 만든다면 이렇게 나눈다

이제부터는 Context7 공식 구현 설명이 아니라, 공개된 계약과 일반적인 검색 시스템 원칙을 바탕으로 한 권장 재현 설계입니다.

전체 시스템을 control plane과 data plane으로 나누는 편이 좋습니다.

영역	맡는 일
Control plane	source 등록, credential, version, crawl 정책, refresh job, 권한, active generation 관리
Ingestion plane	clone, crawl, parse, chunk, safety 검사, dedup, embedding, 색인 생성
Query plane	library 식별, 권한과 version filter, 후보 검색, 융합, rerank, token packing
MCP facade	Agent가 쓸 두 개의 read-only tool과 출처가 포함된 결과 제공

첫 MVP부터 source 추가, 삭제, refresh 같은 관리 기능을 model-facing MCP tool에 넣을 필요는 없습니다. 검색 도구와 관리 기능을 분리하면 권한과 사고 범위를 크게 줄일 수 있습니다.

수집은 immutable snapshot에서 시작한다

Git의 main처럼 움직이는 branch 이름만 저장하면 같은 index를 재현하기 어렵습니다. Job이 시작할 때 commit SHA를 고정하고 그 snapshot을 기준으로 처리해야 합니다.

source_id
requested_ref: main
resolved_commit: a84f...
parser_version: markdown-v3
chunker_version: structural-v2
embedding_model: bge-m3-2026-04

이 metadata가 있어야 parser나 embedding model을 바꾼 뒤 어떤 generation을 다시 만들어야 하는지 판단할 수 있습니다. 검색 결과에도 commit SHA와 path를 붙일 수 있습니다.

Website, OpenAPI, PDF도 같은 원칙을 적용할 수 있습니다. fetch 시각, canonical URL, ETag, checksum을 snapshot manifest에 남깁니다.

Chunk는 길이보다 구조를 먼저 본다

고정된 1,000 token마다 자르는 방식은 간단하지만 개발 문서에서는 code fence, heading, symbol 설명을 끊기 쉽습니다.

Markdown과 MDX는 heading tree를 유지하면서 section 단위로 자릅니다. 너무 큰 section만 문단과 code fence 경계에서 다시 나누고, 작은 section은 같은 부모 아래의 이웃과 합칩니다. 시작점으로 600~900 token을 시험할 수 있지만 정답값은 평가 데이터로 조정해야 합니다.

각 chunk에는 원문만 넣지 말고 다음 metadata를 함께 저장합니다.

type ChunkOccurrence = {
  tenantId: string
  libraryId: string
  versionId: string
  generationId: string
  commitSha: string
  path: string
  headingPath: string[]
  symbol?: string
  language?: string
  startLine?: number
  endLine?: number
  sourceUrl: string
  prevChunkId?: string
  nextChunkId?: string
}

Source code fallback은 Tree-sitter 같은 parser로 class, function, method 등 named node를 기준으로 자르는 편이 낫습니다. 큰 node는 재귀적으로 분할하고, 지나치게 작은 sibling은 합칩니다. cAST 연구는 이런 구조 보존 chunking이 code retrieval에 유리할 수 있음을 보여 줍니다. 논문의 유리한 길이를 그대로 복사하기보다 자신의 언어 구성과 질문으로 다시 측정해야 합니다.

검색용 text와 사용자에게 보여 줄 text를 분리하는 것도 유용합니다.

displayText
원래 문서와 코드, 사람이 읽고 인용할 내용

retrievalText
library, version, path, heading, symbol, 짧은 문맥 설명을 덧붙인 검색용 표현

Contextual Retrieval처럼 chunk가 전체 문서에서 어떤 위치인지 짧은 context를 붙이면 작은 조각의 의미가 살아납니다. 다만 반환할 때는 생성된 설명이 아니라 원문과 정확한 출처를 중심으로 제공해야 합니다.

Content와 위치를 분리해 저장한다

Version이 다른 문서에는 거의 같은 code example이 반복됩니다. 중복을 줄이겠다고 하나만 남기면 어느 version에서 나온 코드인지 잃게 됩니다.

그래서 실제 내용과, 그 내용이 특정 version에 등장한 위치를 분리합니다.

Entity	핵심 필드	목적
libraries	tenant, slug, title, policy	검색 대상과 권한의 기준
versions	library, ref, commit, status	current와 과거 version 분리
sources	type, URL, credential reference	Git, Website, OpenAPI 등 원본 연결
contents	content hash, raw text, retrieval text, embedding	같은 내용을 재사용
occurrences	content, version, path, line, source URL	version별 출처와 위치 보존
generations	version, build metadata, active flag	완성된 index 세대를 원자적으로 교체
jobs	requested commit, stage, retry, error	수집과 갱신 운영
eval_queries	query, relevant occurrence, version	검색 품질 회귀 검사

완전 동일한 byte hash는 content를 재사용할 수 있지만 occurrence는 지우지 않습니다. Near duplicate는 검색 결과에서 접는 용도로 먼저 쓰는 것이 안전합니다. 작은 API 차이가 중요한 code를 version 사이에서 잘못 합치면 저장 공간은 줄어도 정답성이 깨집니다.

검색은 hard filter 뒤에 hybrid retrieval을 둔다

권장 query 순서는 다음과 같습니다.

1. 인증 정보에서 tenant와 허용 source를 결정합니다.
2. library와 version, active generation을 hard filter로 고정합니다.
3. BM25와 dense vector search를 병렬로 실행합니다.
4. 두 순위를 RRF로 합칩니다.
5. 상위 후보를 cross-encoder나 LLM으로 rerank합니다.
6. 같은 section과 중복 code를 정리합니다.
7. 필요한 parent, prev, next chunk를 제한적으로 확장합니다.
8. token budget 안에서 원문과 citation을 묶습니다.

BM25는 useQuery, ERR_MODULE_NOT_FOUND, v15.1.8처럼 정확한 symbol, error, version 문자열에 강합니다. Dense retrieval은 “요청이 취소될 때 resource를 정리하는 법”처럼 표현이 달라도 의미가 비슷한 문서를 찾는 데 유리합니다.

점수 범위가 다른 두 검색 결과를 억지로 정규화하기보다 RRF로 각 결과의 순위를 합치면 구현이 단순하고 안정적입니다. 시작값으로 lexical 50~75개, dense 50~75개, rerank 30~50개, 최종 8~20개를 시험할 수 있습니다. 이 숫자는 제품 기본값이 아니라 평가를 시작하기 위한 범위입니다.

Version과 tenant filter는 rerank 뒤가 아니라 후보 검색 전에 적용해야 합니다. “관련도는 높지만 다른 고객의 private 문서”나 “동일 API의 구버전 설명”이 후보에 들어오는 것 자체를 막아야 합니다.

변경된 파일만 새 generation에 반영한다

직접 구현할 때의 incremental indexing은 다음처럼 구성할 수 있습니다.

1. Webhook signature와 delivery ID를 검증한 뒤 queue에 넣습니다.
2. 마지막 성공 commit과 새 commit의 diff를 구합니다.
3. 추가, 변경, 삭제, rename된 파일을 찾습니다.
4. 정규화한 content hash가 같으면 parse와 embedding을 재사용합니다.
5. 변경된 파일만 새 staging generation에 반영합니다.
6. document 수, chunk 수, quarantine 수, source coverage를 검사합니다.
7. 검증을 통과하면 active generation pointer를 원자적으로 바꿉니다.
8. 실패하면 기존 generation을 계속 제공합니다.

Embedding cache key에는 최소한 content hash와 embedding model version이 함께 들어가야 합니다. Parser, chunker, safety classifier, policy version이 바뀌면 원문이 같아도 필요한 단계를 다시 실행해야 합니다.

GitHub Compare API의 changed file 목록에는 제한이 있으므로 큰 변경과 force push는 local git diff나 전체 tree reconciliation으로 보완합니다. Permission이 회수되거나 repository가 삭제되면 다음 refresh까지 기다리지 말고 serving ACL부터 즉시 막아야 합니다.

MCP 계약은 작게 유지한다

초기 제품은 Context7과 비슷하게 두 개의 read-only tool이면 충분합니다.

resolve_library({
  name: string,
  query: string,
  version?: string
})

query_docs({
  libraryId: string,
  query: string,
  version?: string,
  maxTokens?: number
})

응답에는 snippet text만 넣지 말고 구조화된 provenance를 함께 제공합니다.

type SearchResult = {
  text: string
  score?: number
  libraryId: string
  versionId: string
  title: string
  path: string
  headingPath: string[]
  sourceUrl: string
  commitSha?: string
  startLine?: number
  endLine?: number
  trust: "official" | "community" | "generated"
}

새 구현은 현재 MCP Streamable HTTP와 Authorization 명세를 기준으로 잡는 편이 좋습니다. Remote server라면 OAuth resource와 audience를 검증하고, Origin을 확인하며, 다른 service용 token을 Git provider에 그대로 전달하지 않아야 합니다.

Context7 공개 master와 실제 배포 release의 transport 구현 시점이 다를 수 있으므로, 공개 저장소의 session 처리 코드를 그대로 복사하기보다 자신이 지원할 MCP protocol version을 먼저 고정해야 합니다.

보안은 parser 앞과 검색 뒤에 모두 둔다

Repository와 website는 신뢰할 수 없는 입력입니다. README, hidden HTML, SVG metadata, notebook cell에 “앞의 지시를 무시하고 secret을 전송하라”는 문장이 들어갈 수 있습니다.

권장 방어는 한 번의 classifier로 끝나지 않습니다.

원본 정규화
→ active content, secret, PII 검사
→ 빠른 규칙과 classifier
→ 의심 content 2차 검사
→ allow, quarantine, reject
→ chunk별 검사
→ retrieval 결과 묶음 재검사
→ 신뢰하지 않은 근거로 표시해 반환

최소한 다음 경계가 필요합니다.

• Repository의 build script, notebook cell, MDX code를 실행하지 않습니다.
• Website crawler는 private IP, cloud metadata endpoint, redirect 목적지를 차단해 SSRF를 막습니다.
• GitHub App은 selected repository와 read-only 최소 권한을 사용하고 짧은 installation token만 job 동안 보관합니다.
• Tenant는 tool argument가 아니라 검증된 access token이나 API key mapping에서 결정합니다.
• PostgreSQL RLS와 vector search filter를 함께 적용하고 결과 반환 직전에도 ACL을 확인합니다.
• Private query와 result cache는 public cache와 분리합니다.
• Retrieved text 안의 URL, shell command, tool instruction을 자동 실행하지 않습니다.
• Source 추가, 삭제, refresh는 검색 MCP와 분리된 control plane에서 처리합니다.

Prompt-injection 탐지는 방어선 중 하나일 뿐입니다. 악성 문서가 검사를 통과하더라도 다른 tenant의 data나 credential에 접근하고 tool을 실행할 수 없도록 capability와 ACL을 따로 막아야 합니다. OWASP Prompt Injection

검색 품질은 실제 질문으로 측정한다

Chunk 크기나 embedding model을 감으로 고르면 개선 여부를 알 수 없습니다. 먼저 100~300개의 작은 gold set을 만듭니다.

질문에는 다음 유형을 섞습니다.

• 정확한 API와 symbol 이름
• 자연어로 묻는 사용법
• error message와 해결 방법
• migration과 deprecated API
• 같은 symbol의 구버전과 신버전
• 한국어 질문과 영어 문서
• 이름이 비슷한 다른 library
• 두 개 이상의 chunk가 필요한 질문

평가도 단계별로 나눕니다.

단계	볼 지표
Parser	처리 성공률, 원문 coverage, code fence와 AST 보존률
Candidate retrieval	Recall@50, Recall@100, exact search 대비 ANN recall
Final ranking	MRR@10, nDCG@10, Recall@5와 Recall@10
Version	wrong-version retrieval rate
Context packing	relevant-token ratio, 중복 token 비율
End-to-end	citation 정확성, 답변 근거 충실성, example 실행 성공
운영	p50과 p95 latency, freshness lag, ingest와 query 비용

BEIR는 검색 평가 구조를 잡는 데 좋은 출발점입니다. 다만 개발 문서의 version-sensitive 정확성은 일반 benchmark만으로 부족합니다. 실제로 지원할 library와 version에서 사람이 relevant occurrence를 확인하고, 실행 가능한 code example은 test까지 연결하는 편이 좋습니다.

처음부터 다 만들 필요는 없다

Context7에 가장 가까운 출발점은 Grounded Docs입니다. MIT license이며 crawler, parser, version, job, SQLite 기반 hybrid search, MCP 연결을 한 repository에서 볼 수 있습니다. 먼저 Architecture 문서를 읽으면 backend를 어떤 service로 나누는지 빠르게 파악할 수 있습니다.

용도에 따라 다음 프로젝트도 참고할 만합니다.

프로젝트	살펴볼 부분
ContextMCP	개발 문서를 수집해 MCP로 제공하는 비교적 작은 Apache-2.0 구현
Probe docs-mcp	code와 documentation 검색을 MCP tool로 노출하는 구조
Claude Context	codebase indexing과 semantic search 흐름
GitMCP	GitHub repository를 빠르게 MCP documentation source로 연결하는 접근
pgvector	PostgreSQL metadata filter와 vector search를 함께 운영하는 방법

가장 현실적인 구현 순서는 다음과 같습니다.

1. Public Git의 Markdown과 MDX만 지원합니다.
2. Commit SHA, version hard filter, path와 line provenance를 완성합니다.
3. Heading 기반 문서 chunk와 Tree-sitter 기반 code chunk를 만듭니다.
4. BM25 baseline과 gold set 평가부터 연결합니다.
5. Dense retrieval과 RRF를 추가합니다.
6. Reranker와 token packing을 붙입니다.
7. resolve_library, query_docs 두 MCP tool을 노출합니다.
8. Webhook, content hash, staging generation, atomic publish를 추가합니다.
9. Private source, ACL, OAuth, deletion lifecycle을 구현합니다.
10. Website, OpenAPI, PDF, notebook과 source research fallback을 차례로 확장합니다.

복잡한 LLM enrichment보다 먼저 version, provenance, evaluation을 완성하는 편이 좋습니다. 검색이 틀렸을 때 어느 단계가 문제인지 측정할 수 있어야 이후 개선도 의미가 있습니다.

공개 정보만으로는 알 수 없는 것

Context7과 매우 비슷한 결과를 만들 수는 있어도 다음 항목을 같은 방식으로 복제했다고 말할 수는 없습니다.

• 문서 chunk의 정확한 크기와 overlap
• Markdown, MDX, RST, notebook parser의 세부 구현
• 문서가 부족하다고 판단하는 threshold
• Source code에서 example을 만드는 prompt와 model
• SaaS에서 사용하는 embedding model과 vector database
• Vector 검색의 top-k와 LLM rerank prompt, score
• Cosine duplicate threshold와 version analyzer heuristic
• Incremental refresh의 hash, locking, atomic swap 방식
• Safety classifier의 model과 threshold

이 영역은 “Context7이 이렇게 한다”가 아니라 “같은 목적을 위해 이렇게 설계할 수 있다”고 표현해야 정확합니다.

핵심만 다시 연결하면

Context7의 공개된 동작은 비교적 선명합니다.

문서와 code example 수집
→ 검색 가능한 snippet과 metadata 생성
→ library catalog에서 정확한 대상 식별
→ library와 version 안에서 vector search
→ 기본적으로 LLM reranking
→ source가 붙은 작은 근거를 MCP result로 반환
→ Agent가 현재 작업의 context로 사용

직접 만들 때의 승부처는 MCP server 자체보다 그 뒤에 있습니다. 문서 구조를 보존하는 chunking, version과 tenant hard filter, lexical과 dense 검색의 결합, provenance, 안전한 incremental indexing, 실제 질문을 이용한 평가가 품질을 결정합니다.

Context7의 공개 repository는 좋은 API와 MCP facade 참고서입니다. 전체 제품을 재현하려면 Grounded Docs 같은 오픈소스를 출발점으로 삼고, 공개되지 않은 ingestion과 retrieval backend는 자신의 데이터와 평가 기준에 맞춰 설계해야 합니다.

참고 자료

Context7 공식 자료

• Context7 GitHub repository와 비공개 backend 고지
• Adding Libraries
• Context REST API
• Library Updates
• Data Privacy
• Data Safety
• Redis Search로 library catalog를 찾는 방법
• Context7 Research와 dynamic context
• Context7 초기 Parse, Enrich, Vectorize, Rerank, Cache 구조

구현과 평가 자료

• MCP Streamable HTTP 2026-07-28
• MCP Authorization 2026-07-28
• cAST: 구조를 보존하는 code chunking
• Contextual Retrieval
• Reciprocal Rank Fusion
• BEIR benchmark
• OWASP Prompt Injection