npm-mcp

npm-mcp는 공개 npm 레지스트리를 위한 작은 읽기 전용 Model Context Protocol 서버입니다. MCP 호환 AI 클라이언트가 npm 패키지를 검색하고 집중된 패키지 메타데이터를 검사할 수 있게 하며, 설치, 게시, 로그인, 셸, 파일시스템 또는 임의 가져오기 기능을 노출하지 않습니다.

Docker 시작하기

Docker 빠른 시작을 참조하여 새 체크아웃에서 서버와 MCP Inspector를 실행하세요. 필수 명령은 다음과 같습니다:

docker compose --profile inspector up --build -d

모델을 로컬에서 실행하지 않고 모델 기반 MCP 도구 사용을 테스트하려면 LibreChat과 OpenRouter의 무료 모델 라우터를 사용하세요:

docker compose -f compose.yaml -f compose.openrouter.yaml --profile openrouter up --build -d

그런 다음 http://127.0.0.1:3080을 여세요. 무료 모델에서도 OpenRouter API 키가 필요합니다. 설정 및 사용법은 OPENROUTER_QUICKSTART.md를 참조하세요. 로컬 Ollama 프로필은 선택적인 완전 로컬 대안으로 계속 사용할 수 있습니다.

Related MCP server: npm-mcp

도구

모든 도구는 광범위한 클라이언트 호환성을 위해 JSON을 텍스트로 반환하며, 동일한 값을 MCP 구조화 콘텐츠로 노출합니다. 패키지 응답은 레지스트리의 전체 메타데이터 문서를 반환하는 대신 의도적으로 필터링됩니다.

요구 사항 및 설치

• Node.js 20 이상 (네이티브 fetch 및 AbortSignal.timeout 지원)

• npm

git clone <repository-url>
cd npm-mcp
npm install

로컬에서 실행

npm start

프로세스는 stdin에서 MCP 메시지를 기다리며 stdout으로 프로토콜 응답을 작성합니다. 여기에 대화식으로 입력하지 마세요. MCP 클라이언트가 실행해야 합니다. 개발 감시 모드는 npm run dev로 사용할 수 있습니다.

배포

로컬 클라이언트의 경우 stdio 진입점을 사용하세요. Docker 및 클라우드 배포의 경우 /mcp의 무상태 Streamable HTTP 진입점을 사용하세요. 기본적으로 베어러 토큰이 필요하며 상태 프로브용 /healthz를 노출합니다. Docker Compose 및 Google Cloud Run, Azure Container Apps, AWS App Runner/ECS Fargate, Kubernetes 배포 지침은 Docker 및 클라우드 배포 가이드를 참조하세요.

Compose 파일에는 공식 MCP Inspector도 선택적 클라이언트로 포함되어 있습니다. docker compose --profile inspector up --build -d를 실행한 다음 http://127.0.0.1:6274를 여세요. 토큰 설정 및 CLI 사용법은 Docker에서 MCP 클라이언트 실행을 참조하세요.

테스트

npm test

테스트는 Node의 내장 테스트 러너와 모의 fetch 응답을 사용하므로 실제 npm 레지스트리가 필요하지 않습니다.

MCP Inspector로 서버를 대화식으로 검사하려면:

npx @modelcontextprotocol/inspector node src/index.js

Inspector가 출력한 URL을 열고 연결한 다음 도구를 선택하고 도구를 선택한 후 인수를 입력하고 실행하세요.

MCP 클라이언트 구성

클라이언트가 모든 작업 디렉터리에서 서버를 시작할 수 있도록 절대 경로를 사용하세요:

{
  "mcpServers": {
    "npm": {
      "command": "node",
      "args": ["/absolute/path/to/npm-mcp/src/index.js"]
    }
  }
}

정확한 외부 구성 키는 MCP 클라이언트에 따라 다를 수 있지만 명령과 인수는 동일합니다.

예제 호출

{"name":"npm_search_packages","arguments":{"query":"postgres orm","limit":10}}

{"name":"npm_get_package","arguments":{"packageName":"@nestjs/core"}}

{"name":"npm_get_latest_version","arguments":{"packageName":"react"}}

{"name":"npm_get_versions","arguments":{"packageName":"axios"}}

아키텍처

• src/index.js는 stdio 시작만 담당합니다.

• src/http.js 및 src/http-server.js는 컨테이너에서 사용되는 인증된 Streamable HTTP 진입점을 제공합니다.

• src/server.js는 MCP 서버를 생성하고 네 가지 도구를 등록합니다.

• src/tools/에는 스키마, 집중 응답 구성, 핸들러가 포함되어 있습니다.

• src/services/npm-registry.js는 npm과 통신하는 유일한 모듈입니다. 패키지 이름을 검증하고, URL을 공식 레지스트리 엔드포인트로 제한하며, 타임아웃을 적용하고, 네트워크/HTTP/응답 오류를 정규화합니다.

스코프 이름은 단일 레지스트리 경로 세그먼트로 인코딩됩니다. 서버는 상태를 저장하지 않으며 쓰기를 수행하지 않습니다.

향후 개선 사항

향후 추가 가능한 기능으로는 다운로드 통계, 의존성 분석, 패키지 보안 정보, 캐싱, OAuth 기반 원격 인증 등이 있습니다.