semantic-code MCP server
2026년 10월 30일 커밋tree-sitter와 ONNX 기반 임베딩을 사용하여 AI 에이전트가 의미론적 및 키워드 기반 검색을 수행할 수 있도록 코드베이스를 인덱싱합니다.
다른 이름 vrppaul/semantic-code-mcp
- 스타
- 4
- Tools
- 9
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 10월 30일
- 라이선스
- MIT
semantic-code MCP란?
semantic-code은(는) MCP server입니다. tree-sitter와 ONNX 기반 임베딩을 사용하여 AI 에이전트가 의미론적 및 키워드 기반 검색을 수행할 수 있도록 코드베이스를 인덱싱합니다. 9개 도구를 제공합니다. 예: query, project_path, limit.
프로젝트 README에서 생성된 요약
semantic-code MCP server 정보
semantic-code-mcp는 AI 에이전트가 의미론적 및 키워드 기반 검색을 수행할 수 있도록 코드베이스를 인덱싱하는 기능을 제공합니다. Claude Code 또는 기타 MCP 클라이언트를 사용하는 개발자가 반복적인 grep이나 glob 명령에 의존하지 않고도 특정 함수, 클래스 및 섹션을 찾을 수 있도록 돕습니다. 이 MCP server는 tree-sitter를 사용하여 소스 파일을 구조화된 청크로 파싱하고 이를 SQLite 데이터베이스에 저장하며, LanceDB를 대안으로 사용할 수도 있습니다.
사용자는 특정 단어로 검색하거나, 특정 설정을 활성화하여 ONNX 기반 임베딩을 통한 코드의 의미 단위 검색을 수행할 수 있습니다. 이 MCP server는 Python, Rust, Markdown을 지원하며, inotify, FSEvents 또는 ReadDirectoryChangesW와 같은 시스템 수준의 와처를 통해 파일 변경을 감지하여 증분 인덱싱을 관리합니다. 이를 통해 변경된 파일만 다시 인덱싱하므로 검색 프로세스의 효율성을 유지합니다. 의미론적 검색을 사용하려면 Hugging Face hub에서 all-MiniLM-L6-v2 모델을 가져오기 위한 추가 설치가 필요합니다.
활용 사례
- 1특정 코드 정의 찾기AI 에이전트가 키워드 검색을 통해 함수나 클래스의 이름을 빠르게 찾아낼 수 있습니다.
- 2코드 의미로 검색하기개발자가 단순한 단어 일치가 아닌 코드의 의도를 바탕으로 관련 코드 블록을 찾을 수 있습니다.
- 3최신 인덱스 유지MCP server가 파일 변경 사항을 자동으로 추적하므로 수동 재인덱싱 없이도 최신 인덱스를 유지합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
semantic-code MCP 도구 9
README에서 감지됨queryproject_pathlimitchunk_kindslanguagespath_globexclude_globinclude_debugforce
| query | — | |
| project_path | — | |
| limit | — | |
| chunk_kinds | — | |
| languages | — | |
| path_glob | — | |
| exclude_glob | — | |
| include_debug | — | |
| force | — |
구성
SEMANTIC_CODE_MCP_DEBUGSEMANTIC_CODE_MCP_LOCAL_INDEX
| 이름 | 설명 | 유형 |
|---|---|---|
| SEMANTIC_CODE_MCP_DEBUG | — | |
| SEMANTIC_CODE_MCP_LOCAL_INDEX | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능vrppaul/semantic-code-mcp is public and reachablegithub.com/vrppaul/semantic-code-mcp ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-10-30github.com/vrppaul/semantic-code-mcp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음9 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에서 보기semantic-code-mcp
MCP server that provides code search for Claude Code. Instead of iterative grep/glob, it indexes your codebase's words in seconds and returns ranked functions, classes and sections, a definition first when you ask its name. A setting adds a search by meaning, which embeds the code; agents measured with and without it found no gain from it.
Supports Python, Rust, and Markdown — more languages planned.
How It Works
Claude Code ──(MCP/STDIO)──▶ semantic-code-mcp server
│
┌───────────────┼───────────────┐
▼ ▼ ▼
AST Chunker Embedder SQLite
(tree-sitter) (onnxruntime) (words, vectors)
- Chunking — tree-sitter parses source files into functions, classes, methods, structs, traits, markdown sections, etc.; a repository of 8 MiB of source or more is parsed in up to four processes beside the server, half its cores, for the seconds of its first index
- Storage — the chunks and a full-text index of their words in one SQLite database per index (LanceDB, an optional extra, in its place)
- Search — by words (BM25), the chunks named as the query first
- Meaning, by a setting — with the extra
semantic-code-mcp[meaning]andSEMANTIC_CODE_MCP_SEARCH_MODE=words_and_meaningthe server embeds each chunk once with onnxruntime and the model's ONNX export (all-MiniLM-L6-v2, 384d, no torch), keeps each model's vectors beside the chunks, and fuses every search by meaning with one by words by rank
Indexing is incremental: the index records each file's modification time and size, and re-indexes the files that differ. Between searches the server follows each repository's files with the system's own watcher (inotify on Linux, FSEvents on macOS, ReadDirectoryChangesW on Windows), so a search reads only what changed; it scans every file where no watcher can tell, and every 5 minutes as a check. Each chunker version and storage layout keeps an index of its own, so a new version builds a new index once, and switching back finds the old one; each model's vectors are kept apart inside it, so another model embeds again without chunking again; an index no session used for a week is removed. In a git repository, git lists the files to index — tracked ones and untracked ones .gitignore does not exclude; elsewhere the server walks the file system. The embedding model loads on the first search of a server set to search by meaning, never for a search by words.
Installation
One command on every platform, about 95 MB installed. A search by meaning needs the model's libraries, the extra semantic-code-mcp[meaning] (190 MB in all: uvx --from 'semantic-code-mcp[meaning]' semantic-code-mcp), and SEMANTIC_CODE_MCP_SEARCH_MODE=words_and_meaning; such a server fetches the model's ONNX file (90 MB) from the Hugging Face hub once, on its first search:
uvx semantic-code-mcp
Claude Code, as a plugin — the server and the skill that tells the agent how to word a search and when to Grep instead, in one install (Claude Code 2.1.275 or later):
/plugin install semantic-code --marketplace vrppaul/semantic-code-mcp
On an earlier Claude Code, add the marketplace first:
/plugin marketplace add vrppaul/semantic-code-mcp
/plugin install semantic-code@semantic-code-marketplace
Claude Code, the server alone:
claude mcp add --scope user semantic-code -- uvx semantic-code-mcp
The skill alone, for an agent that has the server some other way:
npx skills add vrppaul/semantic-code-mcp
{
"mcpServers": {
"semantic-code": {
"command": "uvx",
"args": ["semantic-code-mcp"]
}
}
}
Updating
uvx caches the installed version. To get the latest release:
uvx --upgrade semantic-code-mcp
Or pin a specific version in your MCP config:
claude mcp add --scope user semantic-code -- uvx semantic-code-mcp@<version>
MCP Tools
search_code
Search code by the words it uses. Auto-indexes on first search.
| Parameter | Type | Default | Description |
|---|---|---|---|
query |
str |
required | The words to find, as code would write them, or a name (Stack.push), whose chunks come first |
project_path |
str |
the client's workspace root, inside a git repository | Absolute path to the project, or to a directory inside its git repository: the repository is indexed once, and a search keeps to the directory; not a repository that ignores the directory or holds the user's home directory, where the directory is a project of its own |
limit |
int |
10 |
Maximum number of results, at most 50 |
chunk_kinds |
list[str] |
all | Only chunks of these kinds: module, function, method, class, section |
languages |
list[str] |
all | Only chunks of files in these languages: python, rust, markdown |
path_glob |
str |
none | Only files this glob names, as in a .gitignore: without a slash a name at any depth below the directory project_path names (*.rs, and tests/, as a trailing slash does not count), with one before a name a path from that directory (src/**/*.py, /tests); * stays within a directory, ** crosses any number, even inside a name (src**.py, where a .gitignore reads it as *), ? is one character, a directory takes what it holds; a character class ([ab]), braces, escapes, a leading !, .. or more than 1000 characters is refused with the reason |
exclude_glob |
str |
none | No file this glob names, read as path_glob is |
include_debug |
bool |
False |
Also return timings and counts of the search |
Returns project_root (the project's root: its repository's, or the directory itself outside git; given as project_path, it searches all of it), searched_directory (the directory the search kept to: project_root, or a directory under it) and ranked results with file_path (absolute), line_start, line_end, name, kind (module, function, method, class, section; Rust's structs, enums, traits and impls are classes), parent (the class, impl, module or heading the chunk sits in, as Stack for Stack.push), content (cut to 50 lines, truncated says so); results come best first. A failure — a missing or relative path, an index that cannot be written — comes back as a tool error with its cause.
index_codebase
Index a codebase's words for search; it embeds nothing, and a server set to search by meaning embeds the chunks on its next search. Only processes new and changed files unless force=True.
| Parameter | Type | Default | Description |
|---|---|---|---|
project_path |
str |
the client's workspace root, inside a git repository | Absolute path to the project, or to a directory inside its git repository: the repository is indexed once, and a search keeps to the directory; not a repository that ignores the directory or holds the user's home directory, where the directory is a project of its own |
force |
bool |
False |
Re-index all files regardless of changes |
Returns project_root (a directory inside a repository indexes the repository from its root), files_indexed, chunks_indexed, files_deleted and duration_seconds.
index_status
Check indexing status for a project.
| Parameter | Type | Default | Description |
|---|---|---|---|
project_path |
str |
the client's workspace root, inside a git repository | Absolute path to the project, or to a directory inside its git repository: the repository is indexed once, and a search keeps to the directory; not a repository that ignores the directory or holds the user's home directory, where the directory is a project of its own |
Returns project_root (a directory inside a repository reports the repository's root), is_indexed, last_updated, files_count, chunks_count, embedded_chunks_count (the chunks with the server's model's vectors, which a server set to search by meaning reads without embedding first), model (the model, its revision and the embedder version whose vectors embedded_chunks_count counts), stale_files_count, manifest (the chunker and storage versions that built the index) and being_built (a run, this session's or another's, holds the index now: until it ends, the counts may be what it has written so far).
Configuration
All settings are environment variables with the SEMANTIC_CODE_MCP_ prefix (via pydantic-settings):
| Variable | Default | Description |
|---|---|---|
SEMANTIC_CODE_MCP_CACHE_DIR |
~/.cache/semantic-code-mcp |
Where indexes are stored |
SEMANTIC_CODE_MCP_INDEX_STORE |
sqlite |
What keeps the indexes: sqlite, or lancedb, whose libraries come with the extra semantic-code-mcp[lancedb] (uvx --from 'semantic-code-mcp[lancedb]' semantic-code-mcp). Each keeps indexes of its own, so a change builds the index again once |
SEMANTIC_CODE_MCP_LOCAL_INDEX |
false |
Store index in .semantic-code/ at the root of each project's repository; it holds a .gitignore, so git never shows it |
SEMANTIC_CODE_MCP_EMBEDDING_MODEL |
all-MiniLM-L6-v2 |
A sentence-transformers model that pools by the mean, with an ONNX export in one file (onnx/model.onnx), by hub name or directory. Only the default model's vectors are tested against sentence-transformers'; another is read from its configs as well as the embedder can, and refused where it can see the vectors would differ |
SEMANTIC_CODE_MCP_DEBUG |
false |
Enable debug logging |
SEMANTIC_CODE_MCP_PROFILE |
false |
Enable pyinstrument profiling (a development checkout only: pyinstrument is a dev dependency) |
SEMANTIC_CODE_MCP_USE_GITIGNORE |
true |
Let .gitignore decide what is indexed. Set false for a repo whose .gitignore hides source on purpose (an allowlist such as /*); the server then walks the file system and applies the ignore patterns only |
SEMANTIC_CODE_MCP_GIT_TIMEOUT_SECONDS |
10 |
How long git may take to list the files before discovery walks the file system instead |
SEMANTIC_CODE_MCP_WATCH_FILES |
true |
Follow each repository's files with the system's own watcher, so a search reads what changed since the last one instead of every file, with a full scan every 5 minutes as a check: inotify on Linux, which takes a watch for each directory git does not ignore, from the limit your editor shares (fs.inotify.max_user_watches), and an inotify instance per project; FSEvents on macOS, a stream for the project's root and one for each of git's directories outside it; ReadDirectoryChangesW on Windows, a handle of the project's root, which keeps a directory holding it from being moved meanwhile. Past those limits, outside a repository, with submodules, and on a network or FUSE file system (on macOS and Windows, the one the project's root lies on) each search scans the files, as with false |
SEMANTIC_CODE_MCP_SEARCH_MODE |
words |
How every search ranks: words, BM25 over the chunks' words, no model loaded; or words_and_meaning, the model's vectors searched too and fused with the words by rank. The first search of a project by meaning embeds every chunk inside the call, minutes at 20k chunks and about an hour at 90k; later ones embed what changed. Meaning needs the extra semantic-code-mcp[meaning]: without it a server set to it stops as it starts, naming the extra |
SEMANTIC_CODE_MCP_MIN_SIMILARITY |
0.35 |
In a search by meaning, how close in meaning to the query, a cosine similarity, a result no keyword matched must be to come back; set for the default model, whose scale another model does not share. Below 0.25, lower MIN_SIMILARITY_WHEN_WORDS_MATCH with it, or the server refuses to start |
SEMANTIC_CODE_MCP_MIN_SIMILARITY_WHEN_WORDS_MATCH |
0.25 |
The same, for a result whose words match the query's; at most MIN_SIMILARITY. A result named as the query comes back however far |
SEMANTIC_CODE_MCP_IGNORE_PATTERNS |
caches, virtualenvs, node_modules, top-level build/, dist/, target/ |
JSON list of patterns skipped in every mode. A pattern without / matches a name at any depth (node_modules); one with / matches from the project root (docs/**) |
Every session on one project should run with the same IGNORE_PATTERNS and USE_GITIGNORE: an index keeps the files its last run found, so two sessions that find different files delete each other's at every search.
Pass environment variables via the env field in your MCP config:
{
"mcpServers": {
"semantic-code": {
"command": "uvx",
"args": ["semantic-code-mcp"],
"env": {
"SEMANTIC_CODE_MCP_DEBUG": "true",
"SEMANTIC_CODE_MCP_LOCAL_INDEX": "true"
}
}
}
}
Or with Claude Code CLI:
claude mcp add --scope user semantic-code \
-e SEMANTIC_CODE_MCP_DEBUG=true \
-e SEMANTIC_CODE_MCP_LOCAL_INDEX=true \
-- uvx semantic-code-mcp
Tech Stack
| Component | Choice | Rationale |
|---|---|---|
| MCP Framework | mcp 2.x (MCPServer) |
The official Python SDK, STDIO transport |
| Embeddings | onnxruntime over the model's ONNX export | Local, no API costs, no torch |
| Index | SQLite with FTS5 | In Python's standard library: one file, a write in one transaction, no server; LanceDB as an optional extra |
| Chunking | tree-sitter | AST-based, respects code structure |
Development
uv sync # Install dependencies
uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
uv run python -m semantic_code_mcp # Run server
uv run pytest # Run tests
uv run pre-commit run --all-files # Every gate a commit runs
The gates are one list, .pre-commit-config.yaml: ruff (lint and format), ty (types), import-linter (the package's layers), vulture (code nothing calls), the project's code rules (nested functions, short names, models taken apart by field names), bandit (security), deptry (dependencies as declared), typos, a check that every test module loads, a check of the agent instruction files, the skill's gate (the skill and the server's instructions name what the server has), validate-pyproject, and the file checks of pre-commit-hooks; commit messages are held to Conventional Commits. CI runs the same hooks and the tests on every push to master and every pull request. See CONTRIBUTING.md.
Releasing
Versions are derived from git tags automatically (hatch-vcs) — there's no hardcoded version in pyproject.toml.
git tag v0.2.0
git push origin v0.2.0
CI runs the whole suite on the tagged commit, then builds the package, publishes to PyPI, and creates a GitHub Release with auto-generated notes. A required reviewer on the pypi environment would add the owner's approval before publishing; until the repository's settings name one, a green CI publishes at once.
Adding a New Language
The chunker system is designed to make adding languages straightforward. Each language needs:
- A tree-sitter grammar package (e.g.
tree-sitter-javascript) - A chunker subclass that walks the AST and extracts meaningful chunks
Steps:
uv add tree-sitter-mylang
Add the language to Language in src/semantic_code_mcp/domain/models.py, and the separator its qualified names are written with (Stack.push, outer::Stack) to PARENT_SEPARATORS beside it; then create src/semantic_code_mcp/chunkers/mylang.py:
from enum import StrEnum, auto
from typing import override
import tree_sitter
import tree_sitter_mylang as tsmylang
from tree_sitter import Node
from semantic_code_mcp.chunkers.base import BaseTreeSitterChunker, ChunkCollector, field_text
from semantic_code_mcp.domain.models import ChunkKind, Language
class NodeType(StrEnum):
function_definition = auto()
# ... other node types
class FieldName(StrEnum):
name = auto()
class MyLangChunker(BaseTreeSitterChunker):
language = Language.mylang
grammar = tree_sitter.Language(tsmylang.language())
extensions = (".ml",)
@override
def _extract_chunks(self, root: Node, collector: ChunkCollector) -> None:
for node in root.children:
match node.type:
case NodeType.function_definition:
name = field_text(node, FieldName.name)
if name is not None:
collector.add(node, node, ChunkKind.function, name, parent=None)
# ... other node types
Register it in src/semantic_code_mcp/app.py, and bump CHUNKER_VERSION in src/semantic_code_mcp/chunkers/composite.py, so indexes built before it are built again:
from semantic_code_mcp.chunkers.mylang import MyLangChunker
def build_chunker() -> CompositeChunker:
return CompositeChunker([PythonChunker(), RustChunker(), MarkdownChunker(), MyLangChunker()])
Project Structure
src/semantic_code_mcp/server/— the MCP tools, their answers and presenterssrc/semantic_code_mcp/services/— indexing, search, the registry of projectssrc/semantic_code_mcp/discovery.py— which files get indexed (git or a file-system walk, ignore patterns)src/semantic_code_mcp/watching/— each system's watcher of a project's files (inotify, FSEvents, ReadDirectoryChangesW)src/semantic_code_mcp/pools.py— the pool of processes that chunks a first index of much sourcesrc/semantic_code_mcp/chunkers/— language chunkers (base.py,composite.py,python.py,rust.py,markdown.py)src/semantic_code_mcp/embedding/,src/semantic_code_mcp/storage/— the embedder and the model it loads from themeaningextra, and the stores (SQLite, LanceDB) behind one contractsrc/semantic_code_mcp/domain/— models and interfacesevals/— search quality and speed on pinned corpora (uv run python -m evals quality,speed), speed also on a repository of Sentry's shape made where it runs (evals/generated/, which CI'sSpeedworkflow times on three systems), and agents' sessions with and without the search (agents, on corpora it names)docs/decisions/— architecture decision recordsTODO.md— epics and planningCHANGELOG.md— completed work (Keep a Changelog format).claude/rules/— context-specific coding rules for AI agents
License
MIT
semantic-code MCP 질문
semantic-code MCP는 어떤 도구를 제공하나요?
9개 도구를 제공합니다. 예: query, project_path, limit, chunk_kinds, languages.
지원되는 프로그래밍 언어는 무엇인가요?
현재 이 MCP server는 Python, Rust, Markdown을 지원하며, 향후 더 많은 언어를 지원할 예정입니다.
파일 변경 사항은 어떻게 처리하나요?
증분 인덱싱 방식을 사용하며, Linux의 inotify, macOS의 FSEvents, Windows의 ReadDirectoryChangesW와 같은 시스템 와처를 통해 변경된 파일만 다시 인덱싱합니다.