Locus MCP를 통해 AI 코딩 에이전트에 LSP 탐색 기능 부여하기

AI 코딩 에이전트는 파일을 빠르게 수정할 수 있지만, 여전히 코드베이스를 오해할 수 있습니다. 텍스트 검색(Text search)은 일치하는 문자열을 찾아내지만, 어떤 정의(definition)가 활성화되어 있는지, 어떤 호출자(callers)가 영향을 받는지, 또는 값의 타입(type)이 무엇인지 신뢰성 있게 알려주지는 못합니다.

이 튜토리얼에서는 MCP 지원 코딩 에이전트를 Locus MCP에 연결하는 방법을 보여줍니다. Locus MCP는 의미론적 코드 질문(semantic code questions)을 언어 서버(language servers)에 위임하는 오픈 소스 서버입니다. 여러분은 배포된 v0.1.5 패키지를 설치하고, 프로젝트 설정을 생성하며, 호스트 엔트리를 추가하고, 실제 프롬프트로 연결을 확인하게 될 것입니다.

요약 (TL;DR)

언어 서버(language server)를 설치하고, 프로젝트 루트에서 Locus 설정을 실행한 다음, cwd가 해당 프로젝트를 가리키도록 MCP 서버 엔트리를 추가하세요:

npm install -g typescript-language-server typescript
npx @paladini/locus-mcp init
npx @paladini/locus-mcp check

그런 다음 에이전트 호스트가 npx -y @paladini/locus-mcp@0.1.5 serve를 실행하도록 구성하세요. 에이전트에게 grep 출력 결과로 추측하는 대신 locate, refs, 또는 hover 도구를 사용하도록 요청하세요.

이 기능이 해결하는 문제는 무엇인가요?

에이전트가 parseConfig의 이름을 변경해야 한다고 가정해 봅시다. Grep은 주석, 문자열, 테스트, 생성된 파일 및 관련 없는 심볼(symbols)을 포함하여 해당 텍스트의 모든 발생 위치를 나열할 수 있습니다. LSP는 더 좁은 범위의 질문에 답할 수 있습니다: 이 식별자(identifier)가 어떤 선언(declaration)을 참조하는지, 그리고 어떤 소스 위치(source locations)가 해당 선언을 참조하는지 말입니다.

Locus는 에이전트 호스트와 이러한 언어 서버들 사이의 작은 MCP 레이어입니다. 출시된 문서에는 6가지 도구가 설명되어 있습니다:

• locate: 심볼을 찾거나 파일 내의 심볼 목록을 나열합니다.
• refs: 참조(references) 또는 구현(implementations)을 찾습니다.
• hover: 타입 정보(type information)와 문서(documentation)를 반환합니다.
• diagnostics: 오류(errors)와 경고(warnings)를 보고합니다.
• status: 언어 서버의 준비 상태(readiness)를 보고합니다.
• rename: 수정을 적용하지 않고 이름 변경(rename)의 영향을 미리 보여줍니다.

이러한 구분은 중요합니다. Locus는 코드 구조와 진단(diagnostics)을 읽으며, 에이전트는 여전히 편집(edits)을 수행하고, 로그, 주석, 설정 키와 같은 일반 텍스트에는 grep이 여전히 유용합니다. 지원되는 워크플로우(workflow)는 Locus 사용 가이드를 참조하세요.

사전 요구 사항 (Prerequisites)

다음이 필요합니다:

• Node.js 22 이상.
• Cursor, Codex 또는 Claude Code와 같은 MCP 지원 호스트(host).
• 검사하려는 언어에 대해 설치된 언어 서버(language server).
• 설정 파일을 생성할 수 있는 프로젝트 디렉토리.

TypeScript 또는 JavaScript 프로젝트의 경우, TypeScript 언어 서버와 컴파일러를 설치하세요:

bash
npm install -g typescript-language-server typescript

Python의 경우, 문서에 명시된 옵션은 pip install pyright입니다. 시작 가이드에는 Go를 위한 gopls와 Rust를 위한 rust-analyzer도 나열되어 있습니다.

Locus 설치 및 확인

에이전트가 이해하기를 원하는 프로젝트의 루트(root)에서 터미널을 엽니다. 예제가 안정적인 v0.1.5 릴리스와 연결되도록 게시된 패키지를 명시적으로 실행하세요:

bash
npx @paladini/locus-mcp init
npx @paladini/locus-mcp check

init은 locus.toml과 locus.json을 생성합니다. check는 언어 서버 바이너리(binaries)가 PATH에서 사용 가능한지 확인합니다. TypeScript 체크가 성공하면 typescript-language-server를 식별해야 합니다. 바이너리가 누락되었다면 이는 MCP 문제가 아니라 설정 문제입니다.

프로젝트에서 하나 이상의 언어를 사용하는 경우, 필요한 서버만 설치하고 locus.toml에서 웜 언어(warm languages)를 구성하세요:

toml
root = "."
warm = ["typescript", "python"]

설정 참조(configuration reference)에 파일 우선순위와 사용자 정의 서버 필드가 문서화되어 있습니다. Locus는 현재 디렉토리에서 상위로 올라가며 locus.toml, locus.json, .lsp.json 순서로 찾습니다.

호스트에 MCP 서버 추가하기

호스트는 필요할 때 서버를 시작합니다. 일반적으로 터미널에서 serve를 수동으로 실행하지는 않습니다.

Cursor의 경우, 프로젝트 내에 .cursor/mcp.json을 생성합니다:

{
  "mcpServers": {
    "locus": {
      "command": "npx",
      "args": ["-y", "@paladini/locus-mcp", "serve"],
      "cwd": "/your/project/absolute/path"
    }
  }
}

Codex의 경우, 이에 상응하는 프로젝트 범위(project-scoped) 설정은 TOML 형식입니다:

[mcp_servers.locus]
command = "npx"
args = ["-y", "@paladini/locus-mcp", "serve"]
cwd = "/your/project/absolute/path"

플레이스홀더를 프로젝트의 절대 경로로 교체하세요. cwd 값은 매우 중요한데, 이는 Locus에게 어떤 코드베이스(codebase)와 설정(configuration)을 검사할지 알려주기 때문입니다. 파일을 저장한 후, MCP 서버를 다시 로드하거나 호스트를 재시작하세요.

공식 설정 가이드에서는 그에 상응하는 Claude Code 형태와 호스트별 재로드 단계를 보여줍니다.

전체 경로 확인하기

먼저 에이전트에게 status를 호출하도록 요청하세요:

Locus MCP 도구인 status를 호출하여 어떤 언어 서버(language servers)가 준비되었는지 알려줘.

준비 완료(readiness) 응답이 오면 호스트가 Locus를 시작할 수 있고, Locus가 설정된 언어 서버를 볼 수 있음을 확인한 것입니다. 만약 응답이 server_starting이라고 나오면 잠시 기다렸다가 다시 시도하세요. 만약 server_unavailable이라고 나오면 check를 다시 실행하고 바이너리 경로(binary path)를 점검하세요.

그 다음, 기호(symbol)를 알고 있는 프로젝트에서 의미론적 탐색(semantic lookup)을 테스트합니다:

Locus의 locate를 사용하여 UserService.authenticate가 어디에 정의되어 있는지 찾아줘. grep은 사용하지 마.

리팩터링 검토(refactor review)를 위해서는 두 단계로 구성된 요청을 사용하세요:

parseConfig를 변경하기 전에, Locus를 사용하여 해당 정의를 찾고 모든 참조(reference)를 나열해줘. 아무것도 수정하기 전에 파일과 줄 번호를 보여줘.

마지막으로, 변경된 파일에 대한 진단(diagnostics)을 요청합니다:

src/api/handler.ts에 대해 Locus 진단을 실행하고 에러와 경고를 보고해줘.

이러한 프롬프트들은 서버 준비 상태(server readiness), 심볼 해석(symbol resolution), 참조 탐색(reference discovery), 그리고 진단(diagnostics) 등 서로 다른 경계들을 테스트합니다. 또한, 에이전트가 의도한 도구(tool)를 대화 과정에서 가시화합니다.

작동 원리

Locus는 모든 언어에 대한 파서(parser)를 직접 구현하지 않습니다. 대신 설정된 언어 서버(language-server) 프로세스를 시작하고, MCP 도구 호출(tool calls)을 언어 서버 요청(requests)으로 변환합니다. 이를 통해 에이전트는 MCP 인터페이스를 집중력 있게 유지하면서도, IDE가 제공하는 것과 동일한 일반적인 시맨틱 서비스(semantic services)를 사용할 수 있습니다.

설정은 프로젝트 설정과 서버 정의를 분리합니다. locus.toml은 루트(root) 및 자주 사용하는 언어(warm languages)에 편리하며, locus.json은 명령(commands), 인자(arguments), 언어 ID(language IDs), 파일 확장자(file extensions)를 기술할 수 있습니다. 사용자 정의 servers 배열이 제공되지 않으면, Locus는 TypeScript, Python, Go, Rust에 대해 내장된 기본값(defaults)을 사용합니다.

이러한 아키텍처는 한계점 또한 설명해 줍니다. 결과는 언어 서버, 해당 서버의 프로젝트 설정, 인덱싱 상태(indexing state), 그리고 선택된 루트에서 접근 가능한 파일들에 따라 달라집니다. check 결과가 녹색으로 표시되는 것은 실행 파일이 PATH에 존재함을 의미하며, 모든 워크스페이스(workspace)가 즉시 유용한 답변을 생성할 수 있음을 보장하는 것은 아닙니다.

실패 모드 및 안전 경계

MCP 서버가 나타나지 않는다면, 호스트 설정이 유효한지, cwd가 절대 경로인 프로젝트 경로인지, 그리고 호스트가 재로드되었는지 확인하십시오. 특정 언어가 누락된 경우, 해당 서버를 설치하고 check를 다시 실행하십시오. 인덱싱이 여전히 진행 중이라면, 이를 확정적인 실패로 간주하기보다는 server_starting 이후에 다시 시도하십시오.

프로젝트를 신뢰하기 전에 locus.json과 .lsp.json을 검토하십시오. Locus는 언어 서버를 자식 프로세스(child processes)로 실행하며, 설정된 명령과 인자를 생성(spawn)합니다. Locus의 보안 정책은 사용 전 설정을 반드시 검토해야 한다고 명시적으로 경고합니다. 또한 언어 서버는 자체적인 보안 및 신뢰 경계(trust boundary)를 가진 별도의 의존성(dependency)입니다.

Locus는 코드를 수정하거나, 에이전트 메모리를 저장하거나, grep을 대체하거나, 완전한 IDE 커버리지를 보장하지 않습니다. rename은 프리뷰(preview) 기능이며, 에이전트가 실제 변경 사항을 적용합니다. 심볼릭 편집(symbolic editing), 지속성 메모리(persistent memory) 또는 훨씬 더 광범위한 툴킷이 필요한 경우, 프로젝트 문서는 Serena와 같은 대안을 안내합니다.

FAQ

LSP를 이해해야 하나요?

아니요. 호환 가능한 언어 서버(language server)와 문서화된 설정 명령어가 필요합니다. Locus는 에이전트용 MCP 도구들을 노출하며, 언어 서버가 의미 분석(semantic analysis)을 처리합니다.

Locus를 전역(globally)으로 설치해야 하나요?

아니요. 문서에 권장된 방식은 npx를 사용하는 것이므로, 호스트는 Locus를 전역으로 설치하지 않고도 패키지를 시작할 수 있습니다.

grep을 계속 사용할 수 있나요?

네. 심볼(symbols), 참조(references), 타입(types) 및 진단(diagnostics)에는 Locus를 사용하세요. 문자열, 주석, 로그 및 설정 텍스트에는 grep을 사용하세요.

사용 중인 언어가 목록에 없다면 어떻게 하나요?

사용 중인 언어 서버를 locus.json 또는 .lsp.json에 기술할 수 있는지 확인하세요. 설정 참조 문서에 커스텀 서버 항목이 문서화되어 있지만, 호환성은 여전히 언어 서버의 동작에 따라 달라집니다.

핵심 요약 (Takeaway)

유용한 변화는 에이전트에 또 다른 검색 명령어를 추가하는 것이 아닙니다. 에이전트에게 텍스트 검색과 의미론적 코드 탐색(semantic code navigation) 사이의 의도적인 경계를 제공하는 것입니다. 언어 서버를 설치하고, init 및 check를 실행한 뒤, MCP 호스트를 올바른 프로젝트 루트로 지정하세요. 그리고 locate, refs, hover 또는 diagnostics에 의존하기 전에 status를 먼저 확인하십시오.

이 기사는 AI의 도움을 받아 작성되었습니다. 저장소, v0.1.5 패키지 메타데이터, 릴리스 태그가 지정된 문서, 보안 정책 및 --help 출력 결과는 발행 전에 검토되었습니다. 이 기사는 해당 소스 및 스모크 테스트(smoke checks)를 벗어난 결과를 주장하지 않습니다.

MCP 서버에 위임할 첫 번째 코드 탐색 작업은 무엇인가요: 정의 찾기(finding definitions), 리팩터링 전 참조 검토(reviewing references), 또는 수정 후 진단 확인(checking diagnostics)인가요?