Skip to main content
Glama
deenesjakoruzh
saitarrun

semantic-code-intelligence

by saitarrun
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

시맨틱 코드 인텔리전스

소프트웨어 저장소를 위한 로컬 우선 시맨틱 검색 및 인용 코드 워크스루.

시맨틱 코드 인텔리전스는 저장소를 심볼 인식 청크로 파싱하고, 해당 청크를 FAISS와 BM25로 인덱싱하며, 두 결과 집합을 융합하고, 크로스 인코더로 가장 강력한 후보를 재순위화합니다. 결과에는 정확한 파일 경로와 줄 범위가 포함됩니다. 모든 것이 로컬에서 실행되며 클라우드 API 키가 필요하지 않습니다.

제공 기능

  • 하이브리드 시맨틱 및 어휘 코드 검색

  • 정확한 심볼, 경로 및 컨텍스트 용어 부스팅

  • 검색 일치도 기반 신뢰도 라벨

  • Python AST 파싱 및 일반 프로그래밍 언어를 위한 구조적 파싱

  • src/auth.py:L42-L67와 같은 정확한 인용

  • 브라우저 대시보드 및 REST API

  • CLI, MCP 및 LSP 인터페이스

  • 결정적 증거 폴백을 갖춘 로컬 Ollama 기반 코드 워크스루

  • FAISS, BM25 및 SQLite 인덱스 영속성

  • 증분 파일 시스템 감시

  • 심볼 및 의존성 그래프

  • 재현 가능한 인덱싱 및 검색 벤치마크

Related MCP server: codebase-analyser

요구 사항

  • macOS 또는 Linux

  • Python 3.10 이상

  • Git

  • Python 의존성 및 로컬 모델 캐시를 위한 약 2–4GB의 여유 디스크 공간

  • 선택 사항: 더 빠른 환경 관리를 위한 uv

  • 선택 사항: 생성된 코드 워크스루를 위한 Ollama

첫 번째 인덱싱 및 재순위화 작업은 Hugging Face 모델 가중치를 다운로드하기 위해 인터넷 액세스가 필요합니다. 모델이 캐시된 후에는 검색이 오프라인으로 작동합니다.

깨끗한 머신에서 빠른 시작

1. 저장소 복제

git clone https://github.com/saitarrun/Semantic-code-intelligence.git
cd semantic-code-intelligence

2. 환경 생성 및 애플리케이션 설치

uv 사용:

uv venv
source .venv/bin/activate
uv pip install -e .

표준 Python 도구 사용:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

Windows는 현재 테스트 대상이 아니지만, 동등한 활성화 명령은 .venv\Scripts\activate입니다.

3. 검색 모델 다운로드 및 인덱스 생성

모델 다운로드는 기본적으로 의도적으로 비활성화되어 있어 일반 애플리케이션 요청이 예기치 않은 네트워크 트래픽을 유발하지 않습니다. 첫 번째 인덱스 및 쿼리 중에 다운로드를 명시적으로 활성화하세요:

export CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1

code-intel index .
code-intel query "Where is HybridRetrievalPipeline implemented?" --citations-only

unset CODE_INTEL_ALLOW_MODEL_DOWNLOADS

이것은 다음을 준비합니다:

  • 밀집 임베딩을 위한 sentence-transformers/all-MiniLM-L6-v2

  • 재순위화를 위한 cross-encoder/ms-marco-MiniLM-L-6-v2

저장소 인덱스는 .code_intel_index/에 저장됩니다. 이 디렉토리에는 FAISS 인덱스, BM25 데이터 및 SQLite 메타데이터가 포함되어 있으며 커밋해서는 안 됩니다.

4. 웹 애플리케이션 시작

code-intel serve --host 127.0.0.1 --port 8000

http://127.0.0.1:8000을 엽니다.

대시보드에는 다음이 포함됩니다:

  • 시맨틱 검색

  • 코드 워크스루

  • 의존성 맵

  • Diff 및 LSP 도구

  • 저장소 선택 및 재인덱싱 컨트롤

  • 단계별 지연 시간 및 검색 신뢰도 표시기

다른 저장소 인덱싱

인덱스 데이터는 기본적으로 대상 저장소 내부에 저장됩니다:

code-intel index /absolute/path/to/project

해당 저장소 검색:

code-intel query \
  "How are access tokens validated?" \
  --dir /absolute/path/to/project

소스 저장소를 변경하지 않아야 할 때 별도의 인덱스 디렉토리를 사용하세요:

code-intel index /absolute/path/to/project \
  --index-dir /absolute/path/to/index-storage

code-intel query \
  "Where is the database connection pool created?" \
  --dir /absolute/path/to/project \
  --index-dir /absolute/path/to/index-storage

파서 또는 임베딩 동작을 변경한 후 강제로 깨끗한 재빌드:

code-intel index /absolute/path/to/project --force

시맨틱 검색

하이브리드 모드를 권장합니다. 자연어 유사성과 정확한 식별자 일치를 결합합니다:

code-intel query "How does the application serve the web UI?"

정확한 심볼 검색:

code-intel query "Where is serve_ui implemented?"

더 많은 결과 반환:

code-intel query "authentication middleware" --top-k 10

코드를 출력하지 않고 인용 표시:

code-intel query "database transaction rollback" --citations-only

진단을 위해 개별 검색 전략 선택:

code-intel query "PaymentProcessor" --mode sparse
code-intel query "logic responsible for charging a customer" --mode dense
code-intel query "charge customer payment" --mode hybrid

정밀도보다 지연 시간이 더 중요할 때 크로스 인코더 재순위화 비활성화:

code-intel query "configuration loader" --no-rerank

순위화 작동 방식

기본 하이브리드 파이프라인은 다음 단계를 수행합니다:

  1. 일반적인 개발자 의도를 결정적 코드 도메인 용어로 확장합니다.

  2. 최대 50개의 밀집 FAISS 후보를 검색합니다.

  3. 최대 50개의 어휘 BM25 후보를 검색합니다.

  4. Reciprocal Rank Fusion으로 최대 60개의 고유 후보를 융합합니다.

  5. 로컬 크로스 인코더로 최대 40개의 후보를 재순위화합니다.

  6. 정확한 심볼, 경로 및 컨텍스트 용어 일치를 부스팅합니다.

  7. 중복 인용을 제거하고 반복적인 동일 파일 결과를 제한합니다.

  8. 근거와 함께 신뢰도 라벨을 반환합니다.

신뢰도는 LLM 신뢰 점수가 아닙니다. 밀집/어휘 일치, 정확한 심볼 일치, 경로 중복 및 시맨틱 유사성과 같은 관찰 가능한 검색 신호를 보고합니다.

코드 워크스루

결정적 증거 모드

이 모드는 Ollama가 필요하지 않습니다. 동작을 발명하지 않고 검색된 심볼, 범위, 의존성, 소스 블록 및 인용을 반환합니다:

code-intel ask \
  "How does the indexing pipeline persist metadata?" \
  --provider extractive

Ollama로 생성된 로컬 워크스루

Ollama를 설치하고 시작한 다음 기본 모델을 다운로드하세요:

ollama pull qwen2.5-coder:7b

인용된 워크스루 실행:

code-intel ask "Explain the hybrid retrieval control flow"

다른 로컬 모델 또는 Ollama 서버 사용:

export CODE_INTEL_OLLAMA_MODEL=deepseek-coder-v2:lite
export OLLAMA_BASE_URL=http://127.0.0.1:11434

Ollama에 연결할 수 없으면 애플리케이션은 응답을 extractive-fallback로 명확히 표시하고 결정적 소스 증거를 반환합니다.

대화형 CLI

연속 검색 세션 시작:

code-intel interactive --dir /absolute/path/to/project

인덱스 통계 검사:

code-intel stats --dir /absolute/path/to/project

모든 명령 표시:

code-intel --help
code-intel query --help

REST API

서버 시작:

code-intel serve --host 127.0.0.1 --port 8000

상태 확인:

curl http://127.0.0.1:8000/api/health

저장소 인덱싱:

curl -X POST http://127.0.0.1:8000/api/index \
  -H 'Content-Type: application/json' \
  -d '{
    "target_dir": "/absolute/path/to/project",
    "force": false
  }'

하이브리드 검색 실행:

curl -X POST http://127.0.0.1:8000/api/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Where is token validation implemented?",
    "repo_path": "/absolute/path/to/project",
    "top_k": 5,
    "mode": "hybrid",
    "rerank": true
  }'

워크스루 생성:

curl -X POST http://127.0.0.1:8000/api/synthesize \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Explain token validation failure paths",
    "repo_path": "/absolute/path/to/project",
    "top_k": 8,
    "provider": "extractive"
  }'

중요 엔드포인트:

메서드

엔드포인트

목적

GET

/api/health

서비스 및 인덱스 상태

GET

/api/stats

파일, 줄, 청크 및 인덱스 매니페스트

GET

/api/index/stream

SSE 인덱싱 진행

POST

/api/index

동기식 저장소 인덱싱

POST

/api/search

밀집, 희소 또는 하이브리드 검색

POST

/api/synthesize

인용된 코드 답변

POST

/api/synthesize/stream

스트리밍 인용 답변

GET

/api/graph

심볼 및 의존성 그래프

POST

/api/watcher/toggle

증분 감시 시작 또는 중지

GET

/api/lsp/inspect

정의, 참조 및 호버 데이터

POST

/api/patch/generate

제안된 통합 diff 생성

POST

/api/patch/apply

선택한 저장소에 통합 diff 적용

원격 액세스가 의도적으로 필요한 경우가 아니면 127.0.0.1에 바인딩하세요. 패치 및 파일 열기 엔드포인트는 로컬 파일 시스템에서 작동하며 신뢰할 수 없는 네트워크에 노출해서는 안 됩니다.

MCP 통합

MCP 서버를 사용하면 VS Code, Cursor, Claude Code 및 기타 호환 코딩 에이전트가 인덱싱된 코드베이스를 검색하고 정확한 소스 범위를 검색할 수 있습니다. 먼저 프로젝트를 설치하고 인덱싱하세요:

git clone https://github.com/saitarrun/Semantic-code-intelligence.git
cd Semantic-code-intelligence
python -m venv .venv
source .venv/bin/activate
pip install -e .
code-intel index --dir /absolute/path/to/your/project

아래 예제에서 which code-intel로 출력된 절대 실행 파일 경로를 사용하세요.

VS Code

에이전트가 검색할 프로젝트에 .vscode/mcp.json을 생성하세요:

{
  "servers": {
    "semanticCodeIntelligence": {
      "type": "stdio",
      "command": "/absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel",
      "args": ["mcp", "--dir", "${workspaceFolder}"],
      "cwd": "${workspaceFolder}"
    }
  }
}

명령 팔레트에서 MCP: List Servers를 실행하고 semanticCodeIntelligence를 시작한 후 해당 도구를 승인하세요. 이전 도구 목록이 캐시된 경우 MCP: Reset Cached Tools를 실행하세요.

Cursor

대상 프로젝트에 .cursor/mcp.json을 생성하세요:

{
  "mcpServers": {
    "semantic-code-intelligence": {
      "command": "/absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel",
      "args": ["mcp", "--dir", "${workspaceFolder}"]
    }
  }
}

Claude Code

검색하려는 프로젝트에서 로컬 stdio 서버를 등록하세요:

claude mcp add --transport stdio --scope project semantic-code-intelligence -- \
  /absolute/path/to/Semantic-code-intelligence/.venv/bin/code-intel mcp --dir /absolute/path/to/your/project
claude mcp get semantic-code-intelligence

다른 MCP 호환 에이전트의 경우 동일한 실행 파일을 인수 mcp --dir /absolute/path/to/your/project와 함께 로컬 stdio 서버로 구성하세요. 서버는 stdio 클라이언트가 요구하는 대로 stdout에 JSON-RPC 메시지만 작성합니다.

사용 가능한 MCP 도구:

  • code_intel_search: 정확한 줄 및 신뢰도 메타데이터가 포함된 하이브리드, 밀집 또는 희소 검색

  • code_intel_symbol_graph: 저장소 또는 심볼에 대한 의존성 및 호출 그래프 데이터

  • code_intel_index: 코딩 에이전트에서 인덱스 구축 또는 새로 고침

  • code_intel_read_file: 구성된 저장소 내에서 최대 400줄을 안전하게 읽기

검색 요청 전에 대상 프로젝트가 인덱싱되어 있어야 합니다. 기본적으로 인덱스는 <project>/.code_intel_index에 저장됩니다. 별도의 인덱스 디렉토리를 사용하는 경우 MCP 명령에 --index-dir /path/to/index를 전달하세요. 모델 다운로드는 여전히 선택 사항입니다: 임베딩 또는 재순위화 모델이 아직 캐시되지 않은 경우 CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1을 설정하세요.

LSP 및 파일 시스템 감시자

stdio LSP 브리지 시작:

code-intel lsp --dir /absolute/path/to/project

증분 감시자 시작:

code-intel watch --dir /absolute/path/to/project

감시자는 지원되는 소스 파일을 관찰하고 변경 후 인덱스 상태를 새로 고칩니다. 두 프로세스를 중지하려면 Ctrl+C를 사용하세요.

구성

환경 변수:

변수

기본값

설명

CODE_INTEL_ALLOW_MODEL_DOWNLOADS

0

Hugging Face 모델 다운로드를 허용하려면 1로 설정

CODE_INTEL_OLLAMA_MODEL

qwen2.5-coder:7b

생성된 워크스루에 사용되는 Ollama 모델

OLLAMA_BASE_URL

http://127.0.0.1:11434

Ollama API 기본 URL

CODE_INTEL_CORS_ORIGINS

로컬호스트 출처

API가 허용하는 쉼표로 구분된 브라우저 출처

CODE_INTEL_PIPELINE_CACHE_SIZE

4

API가 캐시하는 최대 저장소 파이프라인 수

프로그래밍 방식 구성:

from pathlib import Path

from semantic_code_intel.config import CodeIntelConfig
from semantic_code_intel.indexing.engine import HybridIndexer
from semantic_code_intel.retrieval.pipeline import HybridRetrievalPipeline

project = Path("/absolute/path/to/project")
config = CodeIntelConfig(project_root=project)
config.retrieval.dense_top_k = 75
config.retrieval.sparse_top_k = 75
config.retrieval.final_top_k = 8

HybridIndexer(config).index_codebase(project)
response = HybridRetrievalPipeline(config).query(
    "Where is request authentication enforced?",
    top_k=8,
)

for result in response.results:
    print(result.citation, result.chunk.symbol_name, result.score)

print(response.reliability, response.reliability_reasons)

지원되는 파일

기본 스캐너에는 다음이 포함됩니다:

  • Python

  • JavaScript 및 TypeScript

  • Go

  • Rust

  • Java

  • C 및 C++

  • C#

  • Ruby

  • PHP

  • Swift

  • Kotlin 및 Scala

  • 셸 스크립트

  • SQL

  • HTML 및 CSS

  • JSON, YAML, TOML 및 Markdown

일반적인 생성 디렉토리, 가상 환경, 의존성 폴더, 잠금 파일, 바이너리, 축소된 자산, .git, .code_intel_index 및 oss_evaluation은 기본적으로 제외됩니다. 확장자 및 무시 패턴을 사용자 지정하려면 semantic_code_intel/config.py의 ParserConfig를 참조하세요.

아키텍처

flowchart LR
    A[Repository] --> B[Scanner and ignore rules]
    B --> C[Python AST or polyglot parser]
    C --> D[Symbol-aware chunks]
    D --> E[Local embedding model]
    E --> F[(FAISS)]
    D --> G[Code-aware tokenizer]
    G --> H[(BM25)]
    D --> I[(SQLite metadata)]

    Q[Query] --> X[Intent expansion]
    X --> F
    X --> H
    F --> R[Reciprocal Rank Fusion]
    H --> R
    R --> J[Cross-encoder reranker]
    J --> K[Exact symbol and path boosts]
    K --> L[Diversity and reliability]
    L --> M[CLI, API, Web, MCP, LSP]

핵심 모듈:

패키지

책임

parser

저장소 스캔 및 구조적 코드 청킹

indexing

임베딩, FAISS, BM25, SQLite 및 감시

retrieval

쿼리 확장, 융합, 재순위화, 신뢰도 및 인용

generation

근거 기반 프롬프트, Ollama 합성 및 결정적 폴백

api

FastAPI 엔드포인트 및 브라우저 대시보드

cli

명령줄 인터페이스

graph

심볼 및 의존성 그래프

mcp

Model Context Protocol 서버

lsp

Language Server Protocol 브리지

benchmark

합성 저장소 생성 및 검색 평가

테스트

전체 테스트 스위트 실행:

uv run pytest -q

또는 활성화된 환경에서:

pytest -q

스위트는 파서, FAISS, BM25, 쿼리 확장, 정확 일치 부스팅, 융합, 인용, API 엔드포인트, 로컬 합성 동작, MCP, LSP, 패칭, 감시 및 벤치마크 생성을 다룹니다.

벤치마킹

재현 가능한 합성 벤치마크 실행:

code-intel benchmark \
  --workspace ./benchmark_workspace \
  --loc 40000 \
  --queries 30

실행기는 다음을 포함하는 benchmark_report.json을 작성합니다:

  • 데이터셋 및 인덱스 크기

  • 인덱싱 처리량

  • 밀집, 희소, 재순위화 및 종단 간 지연 시간 백분위수

  • 히트율 및 평균 역순위

  • 실행된 쿼리 레코드

  • Python, 플랫폼, 하드웨어, 패키지 및 모델 메타데이터

벤치마크 결과는 하드웨어, 모델 캐시 상태, 저장소 구성 및 쿼리 집합에 따라 달라집니다. 과거 수치를 보장이 아닌 측정값으로 취급하세요.

문제 해결

모델이 로컬에서 사용할 수 없음

다운로드를 활성화한 상태에서 실패한 작업을 한 번 실행하세요:

CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1 code-intel index /absolute/path/to/project --force
CODE_INTEL_ALLOW_MODEL_DOWNLOADS=1 code-intel query "warm up reranker" --dir /absolute/path/to/project

인덱스를 찾을 수 없음

쿼리에 사용된 --dir 및 --index-dir 값은 인덱싱에 사용된 값과 일치해야 합니다.

code-intel stats --dir /absolute/path/to/project

워크스루가 Ollama를 사용할 수 없다고 표시

로컬 서버 및 설치된 모델을 확인하세요:

ollama list
curl http://127.0.0.1:11434/api/tags

항상 결정적 증거 모드를 사용할 수 있습니다:

code-intel ask "your question" --provider extractive

검색 결과가 약함

  • 알려진 경우 정확한 클래스, 함수, 메서드, 엔드포인트 또는 구성 이름을 사용하세요.

  • 일반적인 사용에는 하이브리드 모드를 선호하세요.

  • 답변이 여러 파일에 걸쳐 있는 경우 --top-k를 늘리세요.

  • 파서 또는 임베딩 구성을 변경한 후 --force로 다시 인덱싱하세요.

  • 신뢰도 라벨을 확인하세요. 신뢰도가 낮다는 것은 검색 신호가 강하게 일치하지 않는다는 뜻입니다.

서버 포트가 이미 사용 중입니다

다른 포트를 선택하세요:

code-intel serve --host 127.0.0.1 --port 8010

프로젝트 상태

이 프로젝트는 활발히 개발 중입니다. 생성된 패치를 적용하기 전에 검토하고, 일반적인 사용을 위해 API를 localhost에 바인딩된 상태로 유지하며, 벤치마크 주장을 자체 대상 리포지토리에서 검증하세요.

라이선스

아직 오픈소스 라이선스가 추가되지 않았습니다. 리포지토리에 대한 공개 접근 자체가 코드를 복사, 수정 또는 재배포할 권한을 부여하는 것은 아닙니다.

Available Tools

4 tools
code_intel_indexC

Build or refresh the semantic and lexical indexes for a local repository.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNo
index_dirNoOptional index storage directory.
repo_pathNoRepository root; defaults to the server --dir.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full behavioral burden. It doesn't disclose cost/duration (indexing can be slow), whether it blocks, whether it overwrites existing indexes, or what happens on failure. 'Refresh' hints at mutation but no depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single clear sentence with verb and scope front-loaded, zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations, no output schema, and an undocumented 'force' parameter, the description is too thin. It leaves the agent guessing about cost, prerequisites, and the effect of force.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, with index_dir and repo_path already documented in the schema. The 'force' parameter (schema has no description) is undocumented anywhere, and the description doesn't compensate. Baseline 3 given partial coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Build or refresh') and resource ('semantic and lexical indexes for a local repository'). It's distinct from siblings like code_intel_search, though it doesn't explicitly name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to run this versus using existing indexes, nor prerequisites like whether search requires prior indexing. Purely descriptive, no when-to-use direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_intel_read_fileB

Read a bounded line range from a source file inside the configured repository.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesRepository-relative or absolute file path.
end_lineNoInclusive; at most 400 lines are returned.
repo_pathNoRepository root; defaults to the server --dir.
start_lineNo

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose two useful traits: reads are bounded to a line range and restricted to the configured repository. However, it never states that the operation is read-only/side-effect free, nor how it behaves on a missing file, an out-of-repo absolute path, or a range exceeding the cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the core action and its two constraints are stated immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter read tool with no annotations and no output schema, the description is adequate but thin: it omits read-only confirmation, error/edge-case behavior, and any hint of the return shape (raw lines vs numbered lines). An agent can call it, but cannot fully predict its behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 75%, so the schema already documents path, end_line, and repo_path; only start_line's default relies on the schema's default keyword. The description's 'bounded line range' and 'inside the configured repository' echoes rather than extends the end_line cap and repo_path semantics, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Read a bounded line range from a source file') and scopes it to the configured repository, which is enough for an agent to distinguish it from code_intel_search, code_intel_symbol_graph, and code_intel_index. It stops short of explicitly naming which sibling to use when, but the purpose itself is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as code_intel_search for locating content versus this tool for reading it. An agent must infer the read-content use case purely from the verb.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_intel_symbol_graphC

Return repository dependency/call-graph data, optionally centered on a symbol.

ParametersJSON Schema
NameRequiredDescriptionDefault
symbolNoOptional function, class, or symbol name.
index_dirNoOptional index storage directory.
repo_pathNoRepository root; defaults to the server --dir.

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does state that symbol centering is optional and that graph data is returned, but says nothing about output format, graph depth/limits, whether an index must exist first (relevant given index_dir), or cost/size of the result.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with no waste, front-loading the resource (dependency/call-graph data) before the optional scoping. Very brief, which is efficient but leaves little room for behavioral detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read tool with no annotations and no output schema, the description is minimally adequate. It should mention whether an index is required beforehand and what the returned graph looks like, since an agent has no other source for that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so parameters are already documented. The description only adds that symbol centering is optional, which is already reflected in the schema's 'Optional' prefix; baseline 3 applies when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Return) and resources (dependency/call-graph data) with a scoping qualifier (optionally centered on a symbol). Clear enough to distinguish from siblings like code_intel_search or code_intel_read_file, though it doesn't explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus code_intel_search (symbol lookup) or code_intel_index (index building). The optional symbol scoping is implied but no conditions or prerequisites are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedcode_intel_index
    • First observedcode_intel_read_file
    • First observedcode_intel_search
    • First observedcode_intel_symbol_graph
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: indexing, hybrid search, dependency/call-graph retrieval, and bounded file reading. Although search and read_file both return code, their boundaries are clear from descriptions (retrieval vs direct file access).

Naming Consistency4/5

All tools share the consistent code_intel_ prefix, which provides a predictable namespace. However, suffixes mix verb forms (search, index) and noun forms (symbol_graph), so the pattern is mostly but not perfectly consistent.

Tool Count5/5

Four tools is well-scoped for a code intelligence server, covering the essential operations of indexing, searching, graph exploration, and reading without redundancy or bloat.

Completeness4/5

The core lifecycle (index → search → explore graph → read file) is covered, but missing operations such as listing indexed repositories, retrieving symbol definitions, or index management could create minor dead ends for some agent workflows.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Qurio MCP Server

    irahardianto
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI coding assistants to search and retrieve information from a locally ingested knowledge base using hybrid search, grounded in user-curated documentation.
    16
    MIT

  • codebase-analyser

    akshith120
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents and IDEs to ingest and search code repositories using hybrid retrieval (dense + sparse) with exact line-level citations for precise code analysis.
    1
    -

  • shelfmark

    LucasSantana-Dev
    A
    license
    A
    quality
    A
    maintenance
    Enables coding agents to query local notes, decisions, docs, and code with hybrid retrieval (BM25 + embeddings + reranking) and get path:line citations. It provides tools like rag_query for full-corpus search and search_knowledge for project-scoped knowledge recall.
    2
    1
    MIT

  • LexiconLocal

    alexeymohr
    A
    license
    A
    quality
    B
    maintenance
    Enables coding agents to search a local, offline archive of past sessions and repository Markdown docs using hybrid lexical and semantic retrieval, and read matching records to ground new work in prior knowledge without external calls.
    2
    MIT