syntax-map-mcp

Tree-sitter 기반 코드 분석 MCP 서버입니다. 지정한 workspaceRoot 아래의 JavaScript, TypeScript, TSX, Python, Rust 소스 파일을 읽고 심볼, 정의, 참조, 요약, tree-sitter query, 컨텍스트 markdown을 제공합니다.

설치와 빌드

npm install
npm run build

개발 중 검증:

npm test
npm run typecheck

실행

npx -y syntax-map-mcp --workspace-root /path/to/workspace

workspaceRoot 결정 순서:

1. --workspace-root 인자
2. WORKSPACE_ROOT 환경 변수
3. 현재 작업 디렉터리

제공 도구

• list_symbols: 파일 하나의 top-level 심볼 목록 반환
• find_definition: 여러 파일에서 이름과 선택적 kind로 정의 검색
• find_references: 여러 파일에서 식별자 참조 검색
• summarize_file: 파일 언어, 라인 수, AST 기반 imports, exports, symbols 요약
• run_query: 파일 하나에 tree-sitter query 실행
• get_ast_tree: 파일 하나의 tree-sitter AST를 depth 제한 JSON 트리로 반환
• lsp_document_symbols: 파일 하나의 심볼을 LSP DocumentSymbol 형태로 반환
• lsp_diagnostics: 파일 하나의 tree-sitter parse error를 LSP Diagnostic 형태로 반환
• lsp_definition: 파일의 LSP 위치에 있는 식별자의 정의 위치를 반환
• lsp_references: 파일의 LSP 위치에 있는 식별자의 참조 위치를 반환
• lsp_hover: 파일의 LSP 위치에 있는 식별자의 hover markdown을 반환
• lsp_workspace_symbols: workspace 전체에서 LSP WorkspaceSymbol 형태의 심볼 검색 결과 반환
• lsp_completion: 파일의 LSP 위치 앞 prefix에 맞는 workspace 심볼 completion item 반환
• lsp_signature_help: 파일의 LSP 위치에서 활성 함수 호출 signature와 parameter 반환
• build_context: 여러 파일 요약을 markdown 컨텍스트로 구성
• index_workspace: 지원 소스 파일을 파싱해 SQLite 심볼/참조 인덱스 생성 또는 갱신
• search_symbols: SQLite 인덱스에서 심볼 이름 검색 및 snippet 반환
• find_indexed_definition: SQLite 인덱스에서 정확한 심볼 정의 검색 및 snippet 반환
• find_indexed_references: SQLite 인덱스에서 식별자 참조 검색 및 snippet 반환
• get_index_status: 인덱스 경로, 인덱싱된 파일 수, 심볼 수, 참조 수, stale 파일 수 반환
• clear_index: SQLite 인덱스 파일 삭제

lsp_definition, lsp_references, lsp_hover, lsp_workspace_symbols, lsp_completion, lsp_signature_help의 paths 입력은 선택 사항입니다. 생략하면 workspaceRoot 아래의 지원 소스 파일 전체를 대상으로 조회합니다.

SQLite 인덱스

index_workspace는 workspaceRoot 아래의 .syntax-map-mcp/index.sqlite에 인덱스를 저장합니다. 인덱싱 대상은 .js, .jsx, .ts, .tsx, .py, .rs 파일이며, .git, .syntax-map-mcp, dist, node_modules 디렉터리와 workspaceRoot 아래의 .gitignore 패턴에 매칭되는 파일은 제외합니다. 하위 디렉터리의 .gitignore는 해당 디렉터리 기준으로 적용합니다.

파일 변경 여부는 mtimeMs와 size로 판단합니다. 다시 index_workspace를 호출하면 변경된 파일만 재파싱하고, 삭제된 파일은 인덱스에서 제거합니다. MCP 서버를 실행하면 지원 소스 파일 변경을 감지하는 watcher가 함께 시작되어 SQLite 인덱스를 자동 갱신합니다. .syntax-map-mcp, .git, dist, node_modules와 지원하지 않는 확장자 변경은 watcher refresh 대상에서 제외합니다. get_index_status는 기본적으로 stale 파일 개수만 반환하고, 상세 목록이 필요하면 includeStaleReasons: true를 전달합니다. search_symbols, find_indexed_definition, find_indexed_references는 isStale, staleFiles, refreshed를 반환해 검색 결과가 최신 인덱스 기반인지 알려줍니다. 세 도구에 refreshIfStale: true를 전달하면 stale 파일이 있을 때 먼저 인덱스를 갱신한 뒤 검색합니다. 인덱스 검색 도구는 인덱스에 저장된 위치를 조회한 뒤 현재 파일에서 해당 줄 snippet을 읽어 반환합니다. contextBefore, contextAfter를 0-10 사이 정수로 전달하면 snippet 주변 라인도 함께 반환합니다. includePreview: true를 전달하면 path:line 헤더와 코드블록으로 구성된 previewMarkdown도 함께 반환합니다.

summarize_file은 sources 필드로 symbols, imports, exports가 어떤 방식으로 추출되었는지 반환합니다.

Python은 JavaScript/TypeScript처럼 명시적인 export 문법이 없으므로, top-level __all__에 선언된 문자열 이름을 exports로 반환합니다. __all__이 없으면 exports는 빈 배열입니다.

도구 레퍼런스

도구별 입력과 응답 예시는 docs/tools.md를 참고하세요.

변경 이력

버전별 변경 내용은 CHANGELOG.md를 참고하세요.

MCP 설정 예시

{
  "mcpServers": {
    "syntax-map-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "syntax-map-mcp",
        "--workspace-root",
        "/path/to/workspace"
      ]
    }
  }
}

보안 경계

서버는 workspaceRoot 내부 파일만 읽습니다. 지원 확장자는 .js, .jsx, .ts, .tsx, .py, .rs뿐이며, workspace 밖으로 나가는 경로나 지원하지 않는 확장자는 오류로 처리합니다.