CodeGraph MCP server
2026년 11월 13일 커밋tree-sitter 파싱과 벡터 검색을 사용하여 소스 코드와 프로젝트 지식을 AI agent를 위한 검색 가능한 그래프로 변환합니다.
다른 이름 Phoenixrr2113/codebase-graph
- 스타
- 7
- Tools
- 5
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 13일
- 라이선스
- MIT
CodeGraph MCP란?
CodeGraph은(는) MCP server입니다. tree-sitter 파싱과 벡터 검색을 사용하여 소스 코드와 프로젝트 지식을 AI agent를 위한 검색 가능한 그래프로 변환합니다. 5개 도구를 제공합니다. 예: analyze, search, knowledge.
프로젝트 README에서 생성된 요약
CodeGraph MCP server 정보
CodeGraph는 소스 코드와 프로젝트 문서를 AI agent 및 개발자를 위해 설계된 검색 가능한 그래프 구조로 변환합니다. tree-sitter 파싱을 사용하여 함수, 클래스, 인터페이스, import와 같은 복잡한 관계를 추출합니다. 이 시스템은 이러한 구조적 및 시간적 사실을 FalkorDB에 저장하여 코드 계층 구조 및 프로젝트 지식에 대한 정밀한 쿼리를 가능하게 합니다.
사용자는 analyze, codebase, knowledge, query, search 등 5가지 특화된 MCP 도구를 통해 서버와 상호작용할 수 있습니다. TypeScript, JavaScript, Python, Go, Rust를 포함한 다양한 프로그래밍 언어를 지원합니다. 서버는 Linux x64 또는 Apple silicon macOS에서 내장된 FalkorDBLite를 사용하여 로컬에서 실행하거나, 그 외 다른 플랫폼에서는 외부 FalkorDB 서비스에 연결할 수 있습니다.
시맨틱 검색 기능을 위해 서버는 여러 embedding provider를 지원합니다. nomic-embed-text-v1.5를 사용하여 완전히 로컬에서 실행하거나, API key를 통해 Voyage 또는 OpenRouter와 같은 원격 서비스에 연결할 수 있습니다. 또한 웹 기반 대시보드를 통해 브라우저 인터페이스에서 그래프를 시각화하고 인덱싱 프로세스를 관리할 수 있습니다.
활용 사례
- 1코드 영향도 및 계층 구조 분석AI agent가 호출 계층 구조를 조사하거나, 데드 코드를 탐지하고, 저장소 내의 변경 결합(change coupling)을 식별할 수 있습니다.
- 2시맨틱 코드 검색 수행개발자는 단순한 텍스트 일치가 아닌 의미 기반 검색을 통해 특정 코드 스니펫이나 프로젝트 로직을 찾을 수 있습니다.
- 3프로젝트 지식 사실 관리시스템을 통해 agent가 코드베이스와 관련된 특정 엔티티, 관계 및 문서를 저장하고 불러올 수 있습니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
CodeGraph MCP 도구 5
README에서 감지됨analyzesearchknowledgecodebasequery
| analyze | — | |
| search | — | |
| knowledge | — | |
| codebase | — | |
| query | — |
구성
CODEGRAPH_DRIVERFALKORDB_HOSTFALKORDB_PORTFALKORDB_URL
| 이름 | 설명 | 유형 |
|---|---|---|
| CODEGRAPH_DRIVER | — | |
| FALKORDB_HOST | — | |
| FALKORDB_PORT | — | |
| FALKORDB_URL | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능phoenixrr2113/codebase-graph is public and reachablegithub.com/phoenixrr2113/codebase-graph ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-13github.com/phoenixrr2113/codebase-graph ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음5 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기CodeGraph
CodeGraph turns source code and project knowledge into a searchable graph for AI agents and developers. It parses code with tree-sitter, stores structural and temporal relationships in FalkorDB, and exposes five focused tools through the Model Context Protocol (MCP).
Access the project
- Landing page
- npm package
- Source code
- Issues
- Discussions
- Contribution guide
- Security policy
- MIT license
The public npm package is @agntk/codegraph-mcp. Version 0.1.0 provides the codegraph-mcp and codegraph-dashboard bins.
What it does
- Searches code by symbol, structure, and meaning.
- Extracts functions, classes, interfaces, variables, types, imports, calls, and other relationships.
- Stores project facts with
valid_atandinvalid_attimestamps for point-in-time queries. - Supports first-class TypeScript, JavaScript, Python, Go, Rust, and Markdown parsing, with generic tree-sitter support for additional languages.
- Runs with embedded FalkorDBLite on Linux x64 and Apple silicon macOS, or an external FalkorDB service on any supported Node.js platform. Apple silicon requires Homebrew
libompandopenssl@3runtime libraries. - Explores exact graph totals in Files or Symbols view with most-connected-first windows, Previous/Next paging, append-style loading, in-place neighbor expansion, and a Files-view toggle for unresolved external modules.
- Exposes
analyze,codebase,knowledge,query, andsearchMCP tools.
Choose how to start
CodeGraph requires Node.js 20 or newer. The npm commands below install the public @agntk/codegraph-mcp package from the registry.
Agent-first with MCP
Add this server configuration to an MCP client:
{
"mcpServers": {
"codegraph": {
"command": "npx",
"args": ["-y", "@agntk/codegraph-mcp"]
}
}
}
In the first conversation, ask the agent to check CodeGraph status:
{"method":"tools/call","params":{"name":"codebase","arguments":{"action":"status"}}}
On a fresh install, codebase status returns configured: false and setupRequired: true. An empty database is a valid first run. Configure one absolute project path, then start a full index:
{"method":"tools/call","params":{"name":"codebase","arguments":{"action":"configure","projectAction":"set","projects":["/absolute/path/to/project"]}}}
{"method":"tools/call","params":{"name":"codebase","arguments":{"action":"reindex","mode":"full","scope":"/absolute/path/to/project"}}}
Configuration saves the project but does not index it. The full reindex parses structure first and then finishes embeddings. With the local provider, codebase status includes model load and indexing state while work is running.
Dashboard-first in a browser
Start the dashboard directly from the package:
npx -y -p @agntk/codegraph-mcp codegraph-dashboard
Open the URL printed by the process. A fresh database opens on the setup flow. Confirm storage and embeddings, choose Browse to select a folder, then select Index project. The page shows model download and indexing progress, finishes remaining embeddings automatically, and reports file, symbol, edge, and embedding counts before opening the graph explorer.
The dashboard and MCP server are separate entry points. They can run at the same time against the same data path.
Platform and storage
| Platform | Default driver | Prerequisites | Configuration |
|---|---|---|---|
| Linux x64 | Embedded FalkorDBLite | Node.js 20 or newer | No database configuration when the embedded package is available |
| macOS Apple silicon | Embedded FalkorDBLite | Node.js 20 or newer, brew install libomp openssl@3 |
No database configuration when the libraries and embedded package are available |
| macOS Intel | External FalkorDB | Node.js 20 or newer | Set the external variables below |
| Windows x64 | External FalkorDB | Node.js 20 or newer | Set the external variables below |
| Linux arm64 and other platforms | External FalkorDB | Node.js 20 or newer | Set the external variables below |
An explicit CODEGRAPH_DRIVER always wins. Without it, a configured FALKORDB_URL or FALKORDB_HOST selects external FalkorDB. Otherwise CodeGraph selects embedded FalkorDBLite on Linux x64, or on Apple silicon macOS when its native libraries are present, and falls back to external FalkorDB if the embedded package cannot load. All other platforms default to external FalkorDB.
CODEGRAPH_DATA_DIR defaults to ~/.codegraph; the MCP project configuration is stored at ~/.codegraph/mcp-context.json. Embedded database storage separately defaults to <current working directory>/.codegraph/falkordb. If that database path is too long for a Unix socket, CodeGraph relocates it to ~/.codegraph/graphs/<12-hex-digest>. Set CODEGRAPH_DATA_DIR to a writable directory for MCP configuration, and set CODEGRAPH_DB_PATH to a writable directory for embedded database files.
For external FalkorDB, set either a URL:
CODEGRAPH_DRIVER=falkordb
FALKORDB_URL=host:6379
Or set a host and port:
CODEGRAPH_DRIVER=falkordb
FALKORDB_HOST=host
FALKORDB_PORT=6379
One database server runs per data directory; a second CodeGraph process attaches to it.
Embeddings and privacy
| Provider | Model and dimensions | Configuration | First run |
|---|---|---|---|
| Local | nomic-ai/nomic-embed-text-v1.5, 768 |
No key and no provider override | Default no-key path. Downloads approximately 132 MiB, measured as 138,011,417 bytes (131.6 MiB), shows progress, then caches the model locally. |
| Voyage | voyage-code-3, 1024 |
CODEGRAPH_EMBEDDING_PROVIDER=voyage and VOYAGE_API_KEY |
Sends embedding inputs to Voyage. |
| OpenRouter | openai/text-embedding-3-small, 1536 |
CODEGRAPH_EMBEDDING_PROVIDER=openrouter and OPENROUTER_API_KEY |
Sends embedding inputs to OpenRouter. |
| None | No model, 0 | CODEGRAPH_EMBEDDING_PROVIDER=none |
Explicit structural-only mode. Semantic similarity search is unavailable. |
If no provider is set, a configured Voyage key selects Voyage, a configured OpenRouter key selects OpenRouter, and no key selects local. Set CODEGRAPH_EMBEDDING_PROVIDER explicitly when you need to pin the choice.
Provider, model, and dimension are stored with the graph. If any of them changes, CodeGraph blocks graph mutation with this remedy: Run an explicit re-embed migration or a full reindex before using the requested embedding profile.
MCP tools
| Tool | Purpose |
|---|---|
analyze |
Inspect impact, call hierarchy, cycles, dead-code candidates, hotspots, change coupling, and ownership inferred from indexed git history |
search |
Find code and project knowledge by name, structure, or meaning |
knowledge |
Store and recall entities, relationships, facts, and documents |
codebase |
Configure projects, index code, inspect status, and read source |
query |
Run read-only Cypher queries against the graph |
Set CODEGRAPH_RAW_TOOLS=true to expose lower-level handlers alongside the five grouped tools.
Configuration
| Variable | Purpose |
|---|---|
CODEGRAPH_DRIVER |
falkordblite for embedded storage or falkordb for an external service; defaults by platform as described above |
CODEGRAPH_DATA_DIR |
MCP configuration directory, default ~/.codegraph; must be writable by the CodeGraph process |
CODEGRAPH_DB_PATH |
Embedded FalkorDBLite data path, default <current working directory>/.codegraph/falkordb; must be writable by the CodeGraph process |
FALKORDB_URL |
External FalkorDB host and port |
FALKORDB_HOST |
External FalkorDB host, default localhost |
FALKORDB_PORT |
External FalkorDB port, default 6379 |
FALKORDB_GRAPH |
Graph name, default codegraph |
CODEGRAPH_EMBEDDING_PROVIDER |
local, voyage, openrouter, or none; when unset, resolves Voyage key, then OpenRouter key, then local |
VOYAGE_API_KEY |
Voyage embeddings and optional reranking |
OPENROUTER_API_KEY |
OpenRouter embeddings or LLM features |
CEREBRAS_API_KEY |
Optional LLM-backed knowledge extraction |
API_PORT |
Dashboard and REST API port, default 3001; use the printed URL |
CODEGRAPH_BROWSE_ROOTS |
Additional absolute dashboard Browse roots, separated by commas |
CODEGRAPH_RAW_TOOLS |
Set to the literal value true to expose raw handlers alongside the five grouped MCP tools |
Never commit provider keys. Put secrets in the MCP client's protected environment configuration or a local ignored .env file.
Release verification
The canonical package command is:
pnpm pack:npm
It builds and validates one publishable tarball under tmp/release. The complete release gate is:
pnpm release:check
The basic installed-tarball smoke proves the package installs in a clean consumer, both binaries start, all five MCP tools are present, a fresh database is setup-safe, Browse and indexing work, data survives restarts, the dashboard and MCP process share one embedded server, and the exact tarball hash is reported. The release CI runs that installed artifact with embedded storage on Linux x64 and Apple silicon, and checks external FalkorDB guidance on Windows x64. An opt-in local-provider lane proves cold model download progress and a usable 768-dimension vector index.
A clean-consumer local tarball proof verifies that bare npx -y @agntk/codegraph-mcp selects the codegraph-mcp bin and that npx -y -p @agntk/codegraph-mcp codegraph-dashboard selects the dashboard bin. Both forms also resolve and boot from the public npm registry.
Development
pnpm install --frozen-lockfile
pnpm audit:prod
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm docker:db
pnpm test:integration
pnpm test:scripts
pnpm build:mcpb
pnpm release:check
See CONTRIBUTING.md for the pull request workflow and required evidence.
FalkorDBLite's Linux x64 and Apple silicon macOS binaries are installed with the workspace dependencies. Apple silicon also requires Homebrew libomp and openssl@3.
Packages
| Package | Responsibility |
|---|---|
@codegraph/core |
Indexing, search pipelines, services, and git synchronization |
@codegraph/graph |
FalkorDB and FalkorDBLite drivers, graph queries, and knowledge operations |
@codegraph/plugin-nlp |
Embeddings, reranking, entity resolution, and document ingestion |
@codegraph/mcp-server |
MCP transport and the five public tool groups |
@codegraph/cli |
Source-checkout command-line tools |
@agntk/codegraph-mcp |
Public npm distribution staging and entry point |
@codegraph/mcpb |
Platform-local MCPB desktop extension build |
@codegraph/api |
REST API consumed by the dashboard |
@codegraph/dashboard |
Static dashboard UI served by the API |
The marketing site lives in apps/web, and the reproducible search benchmark lives in benchmarks/cgbench-v1.
License
CodeGraph is available under the MIT License.
CodeGraph MCP 질문
CodeGraph MCP는 어떤 도구를 제공하나요?
5개 도구를 제공합니다. 예: analyze, search, knowledge, codebase, query.
지원되는 프로그래밍 언어는 무엇인가요?
TypeScript, JavaScript, Python, Go, Rust, Markdown을 지원하며, 그 외 다른 언어는 generic tree-sitter 지원을 통해 사용할 수 있습니다.
AI agent와 CodeGraph를 어떻게 함께 사용하나요?
npx를 사용하여 @agntk/codegraph-mcp를 실행하고, 해당 서버 설정을 MCP client에 추가하면 됩니다.
외부 데이터베이스가 필요한가요?
Linux x64 및 Apple silicon macOS에서는 내장된 FalkorDBLite로 실행할 수 있으며, 그 외 다른 플랫폼에서는 외부 FalkorDB 서비스에 연결할 수 있습니다.