소스 맵 파서

🌐语言: 영어 |简体中文

이 프로젝트는 JavaScript 오류 스택 추적을 소스 코드로 매핑하고 관련 컨텍스트 정보를 추출할 수 있는 WebAssembly 기반 소스 맵 파서를 구현합니다. 개발자는 JavaScript 오류 스택 추적을 소스 코드로 쉽게 매핑하여 문제를 신속하게 파악하고 해결할 수 있습니다. 이 문서는 개발자가 이 도구를 더 잘 이해하고 사용할 수 있도록 돕기 위해 작성되었습니다.

MCP 통합

참고: Node.js 18+ 지원이 필요합니다.

옵션 1: NPX로 직접 실행

지엑스피1

옵션 2: 빌드 아티팩트 다운로드

GitHub 릴리스 페이지에서 해당 버전의 빌드 아티팩트를 다운로드한 다음, 다음을 실행합니다.

node dist/main.es.js

런타임 매개변수 구성

시스템 런타임 매개변수는 다양한 시나리오의 요구 사항을 충족하도록 환경 변수를 통해 유연하게 구성될 수 있습니다.

SOURCE_MAP_PARSER_RESOURCE_CACHE_MAX_SIZE : 리소스 캐시가 차지하는 최대 메모리 공간을 설정합니다. 기본값은 200MB입니다. 이 값을 적절히 조정하면 성능과 메모리 사용량의 균형을 맞출 수 있습니다.
SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE : 오류 위치 주변에 표시할 컨텍스트 코드 줄 수를 정의합니다. 기본값은 1줄입니다. 이 값을 늘리면 더 많은 컨텍스트 정보가 제공되어 문제 진단이 용이해집니다.

예:

# Set 500MB cache and display 3 lines of context
export SOURCE_MAP_PARSER_RESOURCE_CACHE_MAX_SIZE=500
export SOURCE_MAP_PARSER_CONTEXT_OFFSET_LINE=3
npx -y source-map-parser-mcp@latest

기능 개요

스택 파싱 : 제공된 줄 번호, 열 번호 및 소스 맵 파일을 기반으로 해당 소스 코드 위치를 파싱합니다.
일괄 처리 : 여러 스택 추적을 동시에 구문 분석하고 일괄 결과를 반환합니다.
컨텍스트 추출 : 개발자가 오류가 발생한 환경을 더 잘 이해할 수 있도록 지정된 줄에 대한 컨텍스트 코드를 추출합니다.

MCP 서비스 도구 설명

`operating_guide`

MCP 서비스 사용 방법을 안내해 드립니다. 채팅을 통해 MCP 서비스 사용 방법을 안내해 드립니다.

`parse_stack`

스택 추적과 소스 맵 주소를 제공하여 스택 정보를 구문 분석합니다.

요청 예시

스택: 줄 번호, 열 번호, 소스 맵 주소를 포함한 스택 정보입니다.
- line: 줄 번호, 필수입니다.
- 열: 열 번호, 필수입니다.
- sourceMapUrl: 소스 맵 주소, 필수입니다.

{
  "stacks": [
    {
      "line": 10,
      "column": 5,
      "sourceMapUrl": "https://example.com/source.map"
    }
  ]
}

응답 예시

{
  "content": [
    {
      "type": "text",
      "text": "[{\"success\":true,\"token\":{\"line\":10,\"column\":5,\"sourceCode\":[{\"line\":8,\"isStackLine\":false,\"raw\":\"function foo() {\"},{\"line\":9,\"isStackLine\":false,\"raw\":\"  console.log('bar');\"},{\"line\":10,\"isStackLine\":true,\"raw\":\"  throw new Error('test');\"},{\"line\":11,\"isStackLine\":false,\"raw\":\"}\"}],\"src\":\"index.js\"}}]"
    }
  ]
}

구문 분석 결과 설명

success : 구문 분석이 성공했는지 여부를 나타냅니다.
token : 구문 분석이 성공했을 때 반환되는 토큰 객체로, 소스 코드 줄 번호, 열 번호, 컨텍스트 코드 및 기타 정보를 포함합니다.
error : 구문 분석에 실패했을 때 반환되는 오류 정보입니다.

예제 실행

시스템 프롬프트

실제 필요에 따라 시스템 프롬프트를 사용하여 모델이 스택 정보를 파싱하는 방법을 안내할 수 있습니다. 보안 또는 성능상의 이유로 일부 팀은 파싱을 위해 소스 맵을 브라우저에 직접 노출하는 대신 소스 맵의 업로드 경로를 처리하기를 원할 수 있습니다. 예를 들어, bar-special.js 경로를 special/bar.js.map 경로로 변환하는 것입니다. 이 경우, 프롬프트 규칙을 통해 모델이 경로 변환을 수행하도록 지시할 수 있습니다.

다음은 그 예입니다.

# Error Stack Trace Parsing Rules

When performing source map parsing, please follow these rules:

1. If the URL contains `special`, the file should be parsed into the `special/` directory, while removing `-special` from the filename.
2. All source map files are stored in the following CDN directory:  
   `https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/`

## Examples

- Source map address for `bar-special.js`:  
  `https://cdn.jsdelivr.net/gh/MasonChow/source-map-parser-mcp@main/example/special/bar.js.map`

런타임 예제

오류 스택

Uncaught Error: This is a error
    at foo-special.js:49:34832
    at ka (foo-special.js:48:83322)
    at Vs (foo-special.js:48:98013)
    at Et (foo-special.js:48:97897)
    at Vs (foo-special.js:48:98749)
    at Et (foo-special.js:48:97897)
    at Vs (foo-special.js:48:98059)
    at sv (foo-special.js:48:110550)
    at foo-special.js:48:107925
    at MessagePort.Ot (foo-special.js:25:1635)

자주 묻는 질문

1. WebAssembly 모듈 로딩 실패

도구에서 다음과 같은 오류 메시지가 반환되면 다음과 같이 문제를 해결하세요.

파서 초기화 오류: WebAssembly.instantiate(): 잘못된 값 유형 'externref', --experimental-wasm-reftypes @+86으로 활성화하세요.

Node.js 버전 확인 : Node.js 버전이 18 이상인지 확인하세요. 18보다 낮으면 Node.js를 업그레이드하세요.
실험적 플래그 활성화 : Node.js 버전이 18 이상인데도 여전히 문제가 발생하는 경우 다음 명령을 사용하여 도구를 시작하세요.
npx --node-arg=--experimental-wasm-reftypes -y source-map-parser-mcp@latest

지역 개발 가이드

1. 종속성 설치

Node.js와 npm이 설치되어 있는지 확인한 후 다음 명령을 실행하여 프로젝트 종속성을 설치합니다.

npm install

2. MCP 서비스 연결

다음 명령을 실행하여 MCP 서버를 시작합니다.

npx tsx src/main.ts

내부 논리 개요

1. 주요 파일 설명

stack_parser_js_sdk.js : WebAssembly 모듈에 대한 JavaScript 래퍼로, 핵심 스택 파싱 기능을 제공합니다.
parser.ts : WebAssembly 모듈 초기화, 소스 맵 콘텐츠 검색, 스택 정보 구문 분석을 담당하는 파서의 주요 구현입니다.
server.ts : 외부 호출을 위한 parse_stack 도구 인터페이스를 제공하는 MCP 서버 구현입니다.

2. 구문 분석 논리 수정

구문 분석 논리를 수정하려면 parser.ts 파일에서 getSourceToken 메서드를 편집합니다.

3. 새로운 도구 추가

server.ts 파일에서 server.tool 메서드를 사용하여 새로운 도구 인터페이스를 추가할 수 있습니다.

노트

소스 맵 파일 : 제공된 소스 맵 파일 주소에 접근할 수 있는지, 파일 형식이 올바른지 확인하세요.
오류 처리 : 구문 분석 중에 네트워크 오류, 파일 형식 오류 및 기타 문제가 발생할 수 있습니다. 호출할 때 적절한 오류 처리를 구현하는 것이 좋습니다.

기여 지침

이 프로젝트를 개선하기 위해 이슈와 풀 리퀘스트를 통한 기여를 환영합니다.

특허

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.

Source Map Parser MCP Server

Integrations