LSP 도구

LSP 도구 (LSP Tool)

에이전트를 어떤 Language Server Protocol(LSP) 서버와 연결해서 정의로 이동, 참조 찾기, 진단 같은 코드 인텔리전스를 제공하는 방법을 설명해요.

출처: 문서

본문

LSP 도구는 에이전트를 어떤 LSP(Language Server Protocol) 서버에든 연결해 줘요. 정의로 이동, 참조 찾기, 진단 등 포괄적인 코드 인텔리전스 기능을 제공하죠.

참고 LSP가 뭔가요? Language Server Protocol은 자동완성, 정의로 이동, 진단 같은 언어 기능을 제공하기 위한 표준이에요. 대부분의 프로그래밍 언어에 LSP 서버가 있어요.

사용 가능한 도구

LSP 도구셋은 에이전트에 다음 도구들을 제공해요:

도구 설명 읽기 전용
lsp_workspace 워크스페이스 정보와 사용 가능한 기능 얻기 ✓
lsp_hover 심볼의 타입 정보와 문서 얻기 ✓
lsp_definition 심볼이 정의된 위치 찾기 ✓
lsp_references 심볼의 모든 참조 찾기 ✓
lsp_document_symbols 파일의 모든 심볼 나열 ✓
lsp_workspace_symbols 워크스페이스 전체에서 심볼 검색 ✓
lsp_diagnostics 파일의 오류와 경고 얻기 ✓
lsp_code_actions 사용 가능한 빠른 수정과 리팩터링 얻기 ✓
lsp_rename 워크스페이스 전체에서 심볼 이름 바꾸기 ✗
lsp_format 파일 포맷팅 ✗
lsp_call_hierarchy 들어오는/나가는 호출 찾기 ✓
lsp_type_hierarchy 슈퍼타입/서브타입 찾기 ✓
lsp_implementations 인터페이스 구현 찾기 ✓
lsp_signature_help 호출 지점에서 함수 시그니처 얻기 ✓
lsp_inlay_hints 타입 주석과 파라미터 이름 얻기 ✓

구성

agents:
  developer:
    model: anthropic/claude-sonnet-4-5
    description: Code developer with LSP support
    instruction: You are a software developer.
    toolsets:
      - type: lsp
        command: gopls
        args: []
        file_types: [".go"]
      - type: filesystem
      - type: shell

속성

속성 타입 필수 설명
command string ✓ LSP 서버 실행 커맨드
args array ✗ LSP 서버용 커맨드라인 인수
env object ✗ LSP 프로세스용 환경 변수
file_types array ✗ 이 LSP가 처리하는 파일 확장자(예: [".go", ".mod"])
working_dir string ✗ LSP 서버 프로세스의 작업 디렉터리. 상대 경로는 에이전트의 작업 디렉터리 기준으로 해석. 생략하면 에이전트 작업 디렉터리 기본값
version string ✗ 커맨드 바이너리 자동 설치용 패키지 참조

흔한 LSP 서버

인기 있는 언어의 구성입니다:

Go (gopls)

toolsets:
  - type: lsp
    command: gopls
    version: "golang/[email protected]" # 선택: PATH에 없으면 자동 설치
    file_types: [".go"]

Go 모듈이 하위 디렉터리에 있다면(예: go.mod가 ./backend 아래에 있는 모노레포) gopls가 모듈 루트에서 시작되도록 working_dir을 설정하세요:

toolsets:
  - type: lsp
    command: gopls
    file_types: [".go"]
    working_dir: ./backend # gopls는 모듈 루트에서 시작해야 함

TypeScript/JavaScript (typescript-language-server)

toolsets:
  - type: lsp
    command: typescript-language-server
    args: ["--stdio"]
    file_types: [".ts", ".tsx", ".js", ".jsx"]

Python (pylsp)

toolsets:
  - type: lsp
    command: pylsp
    file_types: [".py"]

Rust (rust-analyzer)

toolsets:
  - type: lsp
    command: rust-analyzer
    file_types: [".rs"]

C/C++ (clangd)

toolsets:
  - type: lsp
    command: clangd
    file_types: [".c", ".cpp", ".h", ".hpp"]

여러 LSP 서버

파일 유형별로 여러 LSP 서버를 구성할 수 있어요:

agents:
  polyglot:
    model: anthropic/claude-sonnet-4-5
    description: Multi-language developer
    instruction: You are a full-stack developer.
    toolsets:
      - type: lsp
        command: gopls
        file_types: [".go"]
      - type: lsp
        command: typescript-language-server
        args: ["--stdio"]
        file_types: [".ts", ".tsx", ".js", ".jsx"]
      - type: lsp
        command: pylsp
        file_types: [".py"]
      - type: filesystem
      - type: shell

워크플로 지침

LSP 도구에는 에이전트가 효과적으로 사용하는 법을 안내하는 내장 지침이 있어요. 에이전트는 다음을 배워요:

  • lsp_workspace로 시작해 사용 가능한 기능 이해
  • lsp_workspace_symbols로 관련 코드 찾기
  • 심볼 수정 전에 lsp_references 사용
  • 코드 변경 후마다 lsp_diagnostics 확인
  • 편집이 끝나면 lsp_format 적용

팁 모범 사례 항상 LSP와 함께 filesystem 도구를 포함하세요. 에이전트는 코드 파일을 읽고 쓰려면 filesystem 접근이 필요하고, LSP는 코드에 대한 인텔리전스를 제공해요.

기능 감지

모든 LSP 서버가 모든 기능을 지원하진 않아요. initialize 핸드셰이크 중에 Docker Agent가 서버의 ServerCapabilities를 읽고 서버가 광고하지 않는 lsp_* 도구를 걸러내요. 예를 들어 모델은 지원하지 않는 서버에서 lsp_inlay_hints를 절대 보지 못하므로, 실패할 도구 호출에 턴을 낭비하지 않아요.

에이전트는 lsp_workspace로 무엇이 가능한지 발견해요:

Workspace Information:
- Root: /path/to/project
- Server: gopls v0.14.0
- File types: .go

Available Capabilities:
- Hover: Yes
- Go to Definition: Yes
- Find References: Yes
- Rename: Yes
- Code Actions: Yes
- Formatting: Yes
- Call Hierarchy: Yes
- Type Hierarchy: Yes
...

자동 재시작과 생명주기

LSP 도구셋은 MCP 도구셋과 같은 감독자로 관리돼서, 충돌한 gopls(또는 다른 언어 서버)는 지수 백오프로 자동 재연결돼요. lifecycle 블록으로 도구셋별 정책을 조정할 수 있어요 — 예를 들어 CI 흐름에서 gopls가 필요하면 strict로 표시하거나, 서버가 막히면 TUI에서 /toolset-restart gopls를 사용해 재연결을 강제할 수 있어요.

toolsets:
  - type: lsp
    command: gopls
    file_types: [".go"]
    lifecycle:
      profile: resilient # 기본: 충돌 시 지수 백오프로 자동 재시작

위치 형식

모든 LSP 도구는 1-기반 줄과 문자 위치를 사용해요:

  • 줄 1은 파일의 첫 줄
{
  "file": "/path/to/file.go",
  "line": 42,
  "character": 15
}

팁 자동 설치 Docker Agent는 PATH에서 찾을 수 없는 LSP 서버를 자동으로 내려받아 설치할 수 있어요. version 속성으로 패키지를 지정하거나, 커맨드 이름에서 자동 감지하게 할 수 있어요. 자세한 내용은 Auto-Installing Tools 문서를 참고하세요.

더 알아보기 (Learn more)