MCP와 CLI를 통해 AI 코딩 에이전트가 저장소 구조를 조사하고, 코드를 검색하며, 프로젝트 컨벤션을 기억할 수 있도록 지원합니다.
다른 이름 PatrickSys/codebase-context
- 스타
- 68
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 7일
- 라이선스
- —
Codebase Context MCP란?
Codebase Context은(는) MCP server입니다. MCP와 CLI를 통해 AI 코딩 에이전트가 저장소 구조를 조사하고, 코드를 검색하며, 프로젝트 컨벤션을 기억할 수 있도록 지원합니다.
프로젝트 README에서 생성된 요약
Codebase Context MCP server 정보
codebase-context는 특화된 인덱싱 및 검색 도구를 통해 AI 코딩 에이전트가 복잡한 저장소를 이해할 수 있도록 돕습니다. 개발자는 이 도구를 사용하여 에이전트에 상위 수준의 저장소 맵, 심볼 참조 및 파일 관계를 제공함으로써, AI가 수정을 시도하기 전에 프로젝트 구조를 먼저 조사할 수 있게 합니다. 이 도구는 stdio를 통한 로컬 방식 또는 고급 HTTP 설정을 통해 작동하며, Claude Code, Cursor, Codex, OpenCode와 같은 특정 클라이언트에 맞춰 초기화할 수 있습니다.
사용자는 API key나 GPU가 필요 없는 기본 키워드 기반 인덱스와 임베딩 프로바이더를 사용하는 선택적 시맨틱 인덱싱 모드 중 하나를 선택할 수 있습니다. 시스템에는 컨벤션을 저장하는 프로젝트 메모리와 Git diff에서 제한된 패킷을 생성하는 리뷰 컨텍스트 도구와 같은 고유한 기능이 포함되어 있습니다. 키워드 인덱스는 기본적으로 검색 가능한 청크가 5,000개로 제한되지만, 사용자는 설정을 통해 이 제한을 조정할 수 있습니다. 또한 React, Next.js, Angular, NestJS와 같은 프레임워크를 위한 전용 분석기를 제공하여 에이전트의 코드베이스 탐색 성능을 향상시킵니다.
활용 사례
- 1저장소 구조 맵핑작업을 시작하기 전에 AI 에이전트에게 프로젝트 구성 및 패턴에 대한 상위 수준의 개요를 생성하도록 요청합니다.
- 2특정 코드 검색순위가 지정된 검색 결과 기능을 사용하여 AI가 코드베이스 내의 특정 심볼이나 기능을 찾도록 지시합니다.
- 3프로젝트 컨벤션 회상메모리 도구를 사용하여 에이전트가 이전에 저장된 결정 사항이나 아키텍처 규칙을 불러오도록 지시합니다.
- 4최근 변경 사항 분석AI에게 최근 커밋으로부터 필요한 컨텍스트를 제공하여 집중적인 코드 리뷰를 수행하게 합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
Codebase Context MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 Codebase Context MCP 설치
$ claude mcp add codebase-context -- npx -y codebase-contextCursor에 Codebase Context MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"codebase-context": {
"command": "npx",
"args": [
"-y",
"codebase-context"
]
}
}
}VS Code에 Codebase Context MCP 설치
.vscode/mcp.json
{
"servers": {
"codebase-context": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"codebase-context"
]
}
}
}VS Code CLI에 Codebase Context MCP 설치
$ code --add-mcp '{"name":"codebase-context","type":"stdio","command":"npx","args":["-y","codebase-context"]}'Claude Desktop에 Codebase Context MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"codebase-context": {
"command": "npx",
"args": [
"-y",
"codebase-context"
]
}
}
}Codex에 Codebase Context MCP 설치
$ codex mcp add codebase-context -- npx -y codebase-contextCodex config.toml에 Codebase Context MCP 설치
~/.codex/config.toml
[mcp_servers.codebase-context] command = "npx" args = ["-y", "codebase-context"]
Gemini CLI에 Codebase Context MCP 설치
$ gemini mcp add -s user codebase-context npx -- -y codebase-contextGemini settings.json에 Codebase Context MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"codebase-context": {
"command": "npx",
"args": [
"-y",
"codebase-context"
]
}
}
}자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능patricksys/codebase-context is public and reachablegithub.com/patricksys/codebase-context ↗통과
- 패키지가 이 저장소를 소스로 명시codebase-context names patricksys/codebase-context as sourcenpmjs.com/package/codebase-context ↗통과
- 빌드 출처(Sigstore 증명)Sigstore attestation for codebase-contextnpmjs.com/package/codebase-context/v/2.2.0#provenance ↗통과
- 오픈 소스 라이선스 (OSI)No license결함 발견
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-07github.com/patricksys/codebase-context ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음No popular package one edit away from codebase-context통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기Codebase Context
Local repository maps, code search and symbol references for coding agents. Codebase Context exposes these through MCP and a CLI so an agent can inspect the repository before editing it.
Published beta: 2.3.1-beta.0 (stable: 2.2.0)
As checked on 4 November 2026, npm beta points to 2.3.1-beta.0, while npm latest remains 2.2.0. The beta requires Node.js 22 or newer. An unpinned npx -y codebase-context may use an already installed local version; without one, it resolves npm latest (currently the stable 2.2.0). To select the published beta explicitly, use npx -y codebase-context@2.3.1-beta.0 --version. A source checkout or a local tarball is separate from a verified registry release.
Fresh beta indexes use keyword search without downloading an embedding or reranker model. Existing indexes keep their recorded mode. Semantic indexing is an explicit option; its optional runtimes and model downloads are separate from the default path.
Try the beta or a local build from the terminal
Use an explicitly installed 2.3.1-beta.0, a built checkout (pnpm install, then pnpm build in the CBC checkout) or an installed local tarball. From the repository you want to inspect, point Node at that installation's actual entrypoint:
node /path/to/codebase-context/dist/index.js --version
node /path/to/codebase-context/dist/index.js map
node /path/to/codebase-context/dist/index.js search --query "a symbol or feature in this repository" --limit 5
node /path/to/codebase-context/dist/index.js status
Replace the paths and query with your own. For a tarball installed under /path/to/cbc-local, the entrypoint is /path/to/cbc-local/node_modules/codebase-context/dist/index.js. Quote paths containing spaces.
map builds an index when the folder has no previous index. It then returns a bounded repository map. Search returns ranked source locations; open the returned code before relying on it. Low confidence means weak matching evidence, not that an implementation is absent.
To refresh the index, use reindex. Omitting mode flags preserves the recorded mode; reindex --no-embeddings explicitly selects keyword-only indexing. reindex --embeddings selects the configured embedding provider and requires optional LanceDB storage. The default local provider also requires Transformers and may download models; an explicitly configured remote provider has its own connection requirements. Changing modes requires a full rebuild, including when --incremental is supplied.
Set up your AI client
From the target repository, the installed beta or built source can write project registrations for selected detected clients:
node /path/to/codebase-context/dist/index.js init
# Or select one client explicitly:
node /path/to/codebase-context/dist/index.js init --client codex --root /path/to/project --yes
The wizard recognizes Claude Code, Codex, Cursor and OpenCode. It saves the Node binary and package entrypoint that ran setup. If that installation or its npx cache is moved or removed, rerun setup. Writing a config does not prove that a native client connected or completed a coding task.
After registration, restart the client and ask:
Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project, wait for indexing if needed, and open the relevant source files.
The client setup guide contains beta setup instructions and dated checks for the older stable package. Historical manual recipes, including Windsurf, retain their dated verification limits. For example, the following manual registration leaves the package version unpinned; it may use an already installed local version or fall back to npm latest, so it does not reliably select the beta:
claude mcp add --scope user --transport stdio codebase-context -- npx -y codebase-context
The default transport is stdio: the client starts the server. HTTP is an advanced option with client-specific setup. Explicit project selection is the portable default. A successful selection becomes active for later calls in that server process; select again after restarting or changing repositories.
What your agent can inspect
- Repository map: structure, detected patterns and example files before narrowing to a task.
- Code search: bounded, ranked results with source locations and search-quality information. The default compact response contains at most six results.
- Symbol references: static identifier occurrences. They are not a runtime call graph.
- File relationships: TypeScript/JavaScript imports and re-exports, with unresolved or stale edges reported. Python and Go import navigation are not supported.
- Team patterns: file-level frequencies and example files. These are observations about the repository, not prescriptions about code quality.
- Project memory:
rememberandget_memorystore and retrieve project conventions, decisions, gotchas and failures. - Review context:
codebase-context-reviewbuilds a bounded packet from a committed Git diff. It does not review code or establish reviewer quality. The review-context guide retains a separate historical version preview; it is not evidence of this candidate's publication.
Dedicated analyzers in the source cover Angular, React, Next.js and NestJS. Other files use the generic analyzer and available parsers. See the capabilities reference for scope and limitations.
Privacy and storage
The default keyword index is built locally. Docker, a GPU and an API key are not required. Optional local embeddings also run on the machine. If you explicitly configure a remote embedding provider, code chunks are sent to that provider.
Your AI client may send returned code to its own model provider; CBC does not control that connection. Project memory also travels with the repository if you commit and push it.
Generated index data should stay out of version control. To share project memory while ignoring the generated index:
.codebase-context/*
!.codebase-context/memory.json
Evidence and limits
The benchmark report and prior report archive describe separate historical experiments. These are retrieval observations, not a winner or a coding-quality claim. This historical evidence does not establish patch correctness or end-to-end coding quality. Versions, fixtures and failure records matter; these reports do not certify this candidate. This draft makes no claim that CBC beats text search, improves coding outcomes, or reduces time or tokens.
The default keyword path can miss natural-language questions when their vocabulary differs from the code. A returned file and a high score are not proof that an answer is correct. Inspect the cited implementation. Optional semantic search has not established a retrieval-quality advantage for this candidate.
Other practical limits:
- The default keyword index holds at most 5,000 searchable chunks per project.
projects[].parsing.maxChunkscan raise that limit. - Search has bounded candidate inspection. Narrow a query when the candidate budget is exhausted; refresh when source files changed or became unavailable.
- Existing formats or incomplete generations can require an explicit rebuild or recovery choice. A failed operation is not a successful recovery.
- Setup evidence differs by client. Config writing, protocol connectivity and native-client task completion are separate checks.
- Stdio routing checks do not establish concurrent HTTP client isolation.
Reference
- Client setup — candidate registration, dated checks and limits
- Capabilities — tools, routing, configuration and optional modes
- CLI — local-candidate commands and historical illustrations
- Benchmark — historical methods, observations and failures
- Contributing — local development and evaluation commands
- Changelog — candidate changes and historical entries
Elastic-2.0. See LICENSE.
Codebase Context MCP 질문
Codebase Context MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add codebase-context -- npx -y codebase-context를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
Codebase Context MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
Codebase Context로 AI 에이전트가 무엇을 조사할 수 있나요?
에이전트는 저장소 맵을 확인하고, 순위가 지정된 코드 검색을 실행하며, 심볼 참조 및 파일 관계를 조회하고, 팀의 패턴을 관찰하며, 프로젝트 메모리를 저장하거나 불러올 수 있습니다.
Codebase Context를 사용하려면 Docker, GPU 또는 API key가 필요한가요?
아니요. 기본 키워드 인덱스는 Docker, GPU 또는 API key 없이 로컬에서 구축됩니다. 선택 사항인 임베딩 또한 원격 프로바이더를 명시적으로 설정하지 않는 한 로컬에서 실행됩니다.
Codebase Context가 자동으로 설정할 수 있는 AI 클라이언트는 무엇인가요?
init 위저드가 Claude Code, Codex, Cursor 및 OpenCode를 인식하여 해당 클라이언트를 위한 프로젝트 등록 정보를 작성합니다.
기본 코드 검색은 몇 개의 결과를 반환하나요?
기본 compact 검색 응답에는 최대 6개의 순위 지정된 결과가 포함됩니다.
생성된 인덱스 데이터를 버전 관리 시스템에 커밋해야 하나요?
아니요. 생성된 인덱스 데이터는 버전 관리에서 제외해야 하며, 선택적으로 프로젝트 메모리 파일만 커밋할 수 있습니다.