cclsp는 LLM 기반 코딩 에이전트(coding agents)를 언어 서버 프로토콜 (LSP) 서버와 원활하게 통합하는 모델 컨텍스트 프로토콜 (Model Context Protocol, MCP) 서버입니다. LLM 기반 코딩 에이전트는 종종 정확한 행/열 번호를 제공하는 데 어려움을 겪으며, 이는 LSP 서버와 통합하려는 단순한 시도들을 취약하고 답답하게 만듭니다. cclsp는 여러 위치 조합을 지능적으로 시도하고, AI 어시스턴트가 행을 어떻게 계산하든 상관없이 제대로 작동하는 강력한 심볼 해석 (symbol resolution)을 제공함으로써 이 문제를 해결합니다.

Kapture.2025-06-28.at.22.27.17.mp4

• 왜 cclsp인가?
• 주요 기능 (Features)
• 📋 사전 요구 사항 (Prerequisites)
• ⚡ 설정 (Setup)
• 🚀 사용법 (Usage)
• 🛠️ 개발 (Development)
• 🔧 MCP 도구 (MCP Tools)
• 💡 실제 사례 (Real-world Examples)
• 🔍 문제 해결 (Troubleshooting)
• 🤝 기여하기 (Contributing)
• 📄 라이선스 (License)

Claude와 같은 AI 기반 코딩 어시스턴트를 사용할 때, 심볼 관계를 이해하기 위해 코드베이스를 탐색해야 하는 경우가 많습니다. cclsp는 언어 서버 프로토콜 (Language Server Protocol, LSP)의 기능과 모델 컨텍스트 프로토콜 (Model Context Protocol, MCP) 사이의 간극을 메워 다음과 같은 기능을 가능하게 합니다:

• 🔍
  즉각적인 심볼 탐색 (Instant symbol navigation)- 수동 검색 없이 정의로 이동 - 📚
  완전한 참조 찾기 (Complete reference finding)- 함수, 변수 및 타입의 모든 사용처 찾기 - ✏️
  안전한 심볼 이름 변경 (Safe symbol renaming)- 전체 코드베이스에 걸쳐 확신을 가지고 이름 변경 - 🌍
  범용 언어 지원 (Universal language support)- LSP 호환이 가능한 모든 언어 서버와 작동 - 🤖
  AI 친화적 인터페이스 (AI-friendly interface)- LLM이 효과적으로 이해하고 사용할 수 있도록 설계됨

정의로 이동 (Go to Definition): 심볼이 정의된 위치 찾기
참조 찾기 (Find References): 심볼에 대한 모든 참조 위치 파악
다중 언어 지원 (Multi-language Support): 다양한 파일 유형에 대해 구성 가능한 LSP 서버
TypeScript: typescript-language-server를 통한 내장 지원
Python: python-lsp-server (pylsp)를 통한 지원
Go: gopls를 통한 지원
기타 다수: 광범위한 언어 서버 설정

• Node.js 18+ 또는 Bun 런타임
• 대상 언어에 대한 언어 서버 (별도 설치 필요)

cclsp는 전체 구성 프로세스를 자동화하는 대화형 설정 마법사를 제공합니다. 선호하는 방법을 선택하세요:

대화형 설정 마법사를 실행합니다:

일회성 설정 (설치 불필요)

npx cclsp@latest setup

사용자 전역 설정용

...

설정 마법사는 다음 작업을 수행합니다:

🔍 언어 자동 감지 프로젝트 파일을 스캔하여 언어를 감지합니다
📋 사전 선택된 LSP 서버 표시 감지된 언어를 기반으로 표시합니다
📦 설치 요구 사항 표시 상세 가이드와 함께 표시합니다
⚡ LSP 자동 설치(선택 사항, 사용자 확인 필요)
🔗 Claude MCP에 추가(선택 사항, 사용자 확인 필요)
✅ 설정 검증 및 사용 가능한 도구 표시

프로젝트 설정(기본값): 현재 디렉토리에 .claude/cclsp.json을 생성합니다
사용자 설정(--user): ~/.config/claude/cclsp.json에 전역 설정을 생성합니다

수동 설정을 선호하는 경우:

cclsp 설치: npm install -g cclsp

언어 서버 설치(Language Server Installation 참조)

설정 파일 생성:

대화형 생성기 사용: cclsp setup

또는 수동 생성 (Configuration 섹션 참조)

Claude MCP에 추가: claude mcp add cclsp npx cclsp@latest --env CCLSP_CONFIG_PATH=/path/to/cclsp.json

설정 마법사는 각 LSP에 대한 설치 명령어를 보여주지만, 수동으로 설치할 수도 있습니다:

📦 일반적인 언어 서버 (Common Language Servers)

npm install -g typescript-language-server typescript

pip install "python-lsp-server[all]"
# 또는 기본 설치: pip install python-lsp-server

go install golang.org/x/tools/gopls@latest

rustup component add rust-analyzer
rustup component add rust-src

# Ubuntu/Debian
sudo apt install clangd
# macOS
...

gem install solargraph

npm install -g intelephense

더 많은 언어와 상세한 지침을 확인하려면 npx cclsp@latest setup을 실행하고 "Show detailed installation guides"를 선택하세요.

MCP 클라이언트(예: Claude Code)에서 설정하십시오:

{
"mcpServers": {
"cclsp": {
...

{
"mcpServers": {
"cclsp": {
...

간편한 설정을 위해 대화형 설정 생성기를 사용하세요:

# npx 사용 (일회성 설정에 권장)
npx cclsp@latest setup
# 전역 설치된 경우
...

대화형 도구는 다음과 같은 기능을 수행합니다:

• 사용 가능한 모든 언어 서버 (Language Server)를 보여줍니다.

• 직관적인 컨트롤을 사용하여 구성할 서버를 선택할 수 있습니다:
  탐색 (Navigation): ↑/↓ 화살표 키 또는 Ctrl+P/Ctrl+N (Emacs 스타일)
  선택 (Selection): Space로 토글, A로 전체 토글, I로 선택 반전
  확인 (Confirm): Enter를 눌러 진행

• 선택한 언어에 대한 설치 지침을 표시합니다.

• 구성 파일 (Configuration file)을 자동으로 생성합니다.

• 최종 구성을 보여줍니다.

또는, cclsp.json 구성 파일을 수동으로 생성할 수 있습니다:

{
"servers": [
{
...

구성 옵션 (Configuration Options):

extensions : 이 서버가 처리하는 파일 확장자 (File extensions) 배열
command : LSP 서버를 실행할 명령 (Command) 배열
rootDir : LSP 서버의 작업 디렉토리 (Working directory) (선택 사항, 기본값은 ".")
restartInterval : 자동 재시작 간격 (분 단위) (선택 사항)
initializationOptions : LSP 서버 초기화 옵션 (선택 사항)

initializationOptions 필드를 사용하면 각 LSP 서버가 초기화되는 방식을 사용자 정의할 수 있습니다. 이는 광범위한 플러그인 설정이 필요한 pylsp (Python)와 같은 서버나, 특정 설정이 필요한 devsense-php-ls와 같은 서버에 특히 유용합니다.

📋 추가 언어 서버 예시

{
"servers": [
{
...

# 개발 모드에서 실행
bun run dev
# 테스트 실행
...

서버는 다음과 같은 MCP 도구들을 노출합니다:

파일 내에서 이름과 종류(kind)를 기준으로 심볼(Symbol)의 정의를 찾습니다. 일치하는 모든 심볼에 대한 정의를 반환합니다.

매개변수 (Parameters):

file_path : 파일 경로
symbol_name : 심볼 이름
symbol_kind : 심볼의 종류 (함수, 클래스, 변수, 메서드 등) (선택 사항)

워크스페이스 전체에서 심볼에 대한 모든 참조(References)를 찾습니다. 일치하는 모든 심볼에 대한 참조를 반환합니다.

매개변수 (Parameters):

file_path : 심볼이 정의된 파일의 경로
symbol_name : 심볼 이름
symbol_kind : 심볼의 종류 (함수, 클래스, 변수, 메서드 등) (선택 사항)
include_declaration

: 선언을 포함할지 여부 (선택 사항, 기본값: true)

파일 내에서 이름과 종류(kind)를 기준으로 심볼을 이름 변경합니다. 이 도구는 이제 기본적으로 영향을 받는 모든 파일에 이름 변경을 적용합니다. 여러 심볼이 일치하는 경우, 후보 위치를 반환하며 rename_symbol_strict 사용을 제안합니다.

매개변수 (Parameters):

file_path
: 파일 경로
symbol_name
: 심볼 이름
symbol_kind
: 심볼의 종류 (함수, 클래스, 변수, 메서드 등) (선택 사항)
new_name
: 심볼의 새 이름
dry_run
: true인 경우, 변경 사항을 적용하지 않고 미리보기만 수행합니다 (선택 사항, 기본값: false)

참고 (Note): dry_run이 false(기본값)인 경우, 도구는 다음을 수행합니다:

• 영향을 받는 모든 파일에 이름 변경을 적용합니다.
• .bak 확장자를 가진 백업 파일을 생성합니다.
• 수정된 파일 목록을 반환합니다.

파일 내 특정 위치에 있는 심볼의 이름을 변경합니다. rename_symbol이 여러 후보를 반환할 때 사용하십시오. 이 도구는 이제 기본적으로 영향을 받는 모든 파일에 이름 변경을 적용합니다.

매개변수 (Parameters):

file_path
: 파일 경로
line
: 줄 번호 (1부터 시작)
character
: 줄 내 문자 위치 (1부터 시작)
new_name
: 심볼의 새 이름
dry_run
: true인 경우, 변경 사항을 적용하지 않고 미리보기만 수행합니다 (선택 사항, 기본값: false)

파일에 대한 언어 진단(diagnostics: 에러, 경고, 힌트)을 가져옵니다. 현재의 진단 정보를 가져오기 위해 LSP textDocument/diagnostic을 사용합니다.

매개변수 (Parameters):

file_path
: 진단을 가져올 파일 경로

LSP 서버를 수동으로 재시작합니다. 특정 파일 확장자에 대해 서버를 재시작하거나 실행 중인 모든 서버를 재시작할 수 있습니다.

매개변수 (Parameters):

extensions
: 서버를 재시작할 파일 확장자 배열 (예: ["ts", "tsx"]). 제공되지 않으면 모든 서버가 재시작됩니다 (선택 사항)

Claude가 함수의 작동 방식을 이해해야 할 때:

Claude: `processRequest` 함수의 정의를 찾아보겠습니다.
> cclsp.find_definition 사용 (symbol_name="processRequest", symbol_kind="function")
결과: src/handlers/request.ts:127:1 에서 정의를 찾았습니다.

코드의 영향도를 리팩터링하거나 이해할 때:

Claude: `CONFIG_PATH`가 사용된 모든 곳을 찾겠습니다.
> cclsp.find_references를 사용합니다 (symbol_name="CONFIG_PATH")
결과: 5개의 참조를 찾았습니다:
...

전체 코드베이스에 걸친 안전한 리팩터링 (이제 실제 파일 수정이 가능합니다!):

Claude: `getUserData`를 `fetchUserProfile`로 이름을 바꾸겠습니다.
> cclsp.rename_symbol을 사용합니다 (symbol_name="getUserData", new_name="fetchUserProfile")
결과: getUserData (function)를 "fetchUserProfile"로 성공적으로 이름을 변경했습니다.
...

적용하기 전에 변경 사항 미리보기 (dry_run 사용):

Claude: 무엇이 이름 변경될지 먼저 미리 살펴보겠습니다.
> cclsp.rename_symbol을 사용합니다 (symbol_name="getUserData", new_name="fetchUserProfile", dry_run=true)
결과: [DRY RUN] getUserData (function)를 "fetchUserProfile"로 변경할 예정입니다:
...

여러 심볼이 일치할 때:

Claude: `data` 변수의 이름을 `userData`로 바꾸겠습니다.
> cclsp.rename_symbol을 사용합니다 (symbol_name="data", new_name="userData")
결과: "data"와 일치하는 여러 심볼이 발견되었습니다. 다음 위치 중 하나를 사용하여 rename_symbol_strict를 사용해 주세요:
...

코드 품질을 분석할 때:

Claude: 이 파일에 오류나 경고가 있는지 확인하겠습니다.
> cclsp.get_diagnostics를 사용합니다
결과: 3개의 진단(diagnostics)을 찾았습니다:
...

LSP 서버가 응답하지 않거나 설정이 변경되었을 때:

Claude: TypeScript 서버가 응답하지 않는 것 같습니다. 재시작하겠습니다.
> cclsp.restart_server를 사용합니다 (extensions=["ts", "tsx"])
결과: 1개의 LSP 서버를 성공적으로 재시작했습니다.
...

또는 모든 서버 재시작:

Claude: 모든 LSP 서버가 제대로 작동하는지 확인하기 위해 모두 재시작하겠습니다.
> cclsp.restart_server를 사용합니다
결과: 2개의 LSP 서버를 성공적으로 재시작했습니다.
...

🐍 Python LSP Server (pylsp) 성능 저하

문제: Python Language Server (pylsp)는 장시간(수 시간) 사용 후 느려지거나 응답하지 않을 수 있으며, 이는 심볼 해석 (symbol resolution) 및 코드 탐색 (code navigation)에 영향을 미칩니다.

증상:

• Python 파일에 대한 "정의로 이동 (go to definition)" 결과가 느리거나 나타나지 않음
• 심볼 참조 (symbol references) 지연 또는 불완전함
• Python 코드 분석의 전반적인 응답성 문제

해결 방법: 자동 재시작 (auto-restart) 기능을 사용하여 주기적으로 pylsp 서버를 재시작하세요:

Python 서버 설정에 restartInterval을 추가하세요:

{
"servers": [
{
...

이렇게 하면 5분마다 Python LSP 서버가 자동으로 재시작되어, 긴 코딩 세션 동안 최적의 성능을 유지합니다.

대안: 필요한 경우 restart_server 도구를 사용하여 수동으로 서버를 재시작할 수도 있습니다:

• 특정 서버 재시작:
  restart_server를 extensions: ["py"]와 함께 사용

• 모든 서버 재시작:
  매개변수 없이 restart_server 사용

참고: 설정 마법사(setup wizard)는 Python 서버가 감지되면 이를 자동으로 구성합니다.

🔧 LSP 서버가 시작되지 않음

문제: LSP 서버를 찾을 수 없다는 오류 메시지

해결 방법: 언어 서버 (language server)가 설치되어 있는지 확인하세요:

# TypeScript의 경우
npm install -g typescript-language-server
# Python의 경우
...

🔧 설정이 로드되지 않음

문제: cclsp는 기본 TypeScript 설정만 사용함

해결 방법: 다음 사항을 확인하세요:

• 설정 파일 이름이 cclsp.json인지 확인 (cclsp.config.json이 아님)
• CCLSP_CONFIG_PATH 환경 변수가 올바른 파일을 가리키고 있는지 확인
• JSON 문법이 유효한지 확인

🔧 심볼을 찾을 수 없는 오류

문제: "정의로 이동 (Go to definition)" 결과가 없음

해결 방법:

• 파일이 저장되었고 프로젝트의 일부인지 확인
• 언어 서버가 해당 파일 형식을 지원하는지 확인
• 일부 언어 서버는 프로젝트를 인덱싱 (indexing)하는 데 몇 초 정도 시간이 필요할 수 있음

여러분의 기여를 환영합니다! 다음과 같은 방법으로 도움을 주실 수 있습니다:

버그를 발견했거나 기능 요청이 있으신가요? 다음 내용을 포함하여 이슈 (issue)를 생성해 주세요:

• 문제에 대한 명확한 설명
• 재현 단계 (Steps to reproduce)
• 예상되는 동작 vs 실제 동작
• 사용 중인 환경 (OS, Node 버전 등)

새로운 언어에 대한 지원을 추가하고 싶으신가요?

• 사용 중인 언어에 대한 LSP 서버를 찾으세요

• 설정을 로컬에서 테스트하세요

• 다음 내용을 포함하여 PR (Pull Request)을 제출하세요:

  • 업데이트된 README 예시
  • 가능한 경우 테스트 파일
  • 설정 문서

• 저장소를 Fork 하세요

• 기능 브랜치 (feature branch)를 생성하세요:
  git checkout -b feature/amazing-feature

• 변경 사항을 적용하세요

• 테스트를 실행하세요:
  bun test

• 커밋 (Commit):
  git commit -m '✨ feat: add amazing feature'

• 푸시 (Push):
  git push origin feature/amazing-feature

• Pull Request를 생성하세요

MIT