Finance Crawl - Naver Finance Stock Crawler

네이버 금융 종목 상세 페이지를 크롤링하여 주식 정보를 수집하는 TypeScript 기반 프로젝트입니다.

기능

Finance Crawl - Naver Finance Stock Crawler

네이버 금융 종목 상세 페이지를 크롤링하여 주식 정보를 수집하는 TypeScript 기반 프로젝트입니다.

주요 기능

• 네이버 금융 종목 상세 페이지 크롤링 및 파싱
• RESTful API 서버 제공 (단일/다중 종목 조회)
• MCP (Model Context Protocol) 서버 도구 제공 (optional)
• TypeScript로 작성되어 타입 안정성 제공
• 테스트 스위트(Vitest) 포함

프로젝트 구조 (요약)

finance-crawl/
├── src/
│   ├── api/                      # API 서버
│   ├── crawler/                  # 크롤러 구현
│   ├── mcp/                      # MCP server (optional runtime)
│   ├── utils/                    # 유틸리티
│   └── types/                    # 타입 정의
├── tests/                        # 테스트
├── docs/                         # 문서
└── dist/                         # 컴파일된 결과

설치

# pnpm 설치 (없는 경우)
npm install -g pnpm

# 의존성 설치
pnpm install

빠른 시작

개발: API 서버 실행

pnpm dev:api

빌드 및 프로덕션

pnpm build
pnpm start:api

서버는 기본적으로 http://localhost:3000에서 실행됩니다.

라이브러리로 사용 예

import { NaverStockCrawler } from 'finance-crawl';

const crawler = new NaverStockCrawler();
const result = await crawler.crawl({ url: 'https://finance.naver.com/item/main.naver?code=005930' });
if (result.success && result.data) console.log(result.data);

npm 패키지

패키지는 npm에 공개 배포되어 있습니다: https://www.npmjs.com/package/finance-crawl

설치:

npm install finance-crawl
# or
pnpm add finance-crawl

MCP(Server) 통합 가이드

이 프로젝트는 MCP 서버 실행을 지원합니다. MCP 기능은 런타임에서 선택적으로 로드되도록 구현되어 있어, MCP SDK나 commander가 설치되어 있지 않아도 패키지를 빌드할 수 있습니다.

두 가지 실행 방식이 있습니다:

• stdio (기본): MCP 클라이언트가 표준 입출력을 통해 통신
• http: HTTP 엔드포인트(/mcp)로 요청을 수신

CLI 예시:

# stdio transport (기본)
pnpm start -- --transport stdio

# http transport on port 5000
pnpm start -- --transport http --port 5000

참고: 런타임에 @modelcontextprotocol/sdk 또는 commander가 설치되어 있어야 MCP 서버 관련 기능이 활성화됩니다. 이 패키지들은 optional dependency입니다.

MCP 클라이언트 통합 예 (Cursor)

Cursor 설정 예:

{
  "mcpServers": {
    "finance-crawl": {
      "command": "npx",
      "args": ["-y", "finance-crawl", "--transport", "stdio"]
    }
  }
}

MCP 클라이언트 통합 예 (VS Code)

"mcp": {
  "servers": {
    "finance-crawl": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "finance-crawl", "--transport", "stdio"]
    }
  }
}

MCP 진단 출력 (Cursor에서 "No tools..."가 보일 때)

이 저장소의 MCP 서버는 런타임에서 @modelcontextprotocol/sdk와 commander를 선택적으로 임포트합니다. 따라서 해당 패키지들이 실행 환경에 없으면 MCP 툴이 등록되지 않아 Cursor 같은 클라이언트에서 "No tools, prompts, or resources" 메시지가 나타날 수 있습니다.

대신 이 프로젝트는 진단 편의를 위해 런타임에서 다음 동작을 수행합니다:

• MCP SDK 또는 HTTP 전송(streamableHttp)이 없을 때, 서버는 표준 출력(stdout)에 머신-판독 가능한 진단 JSON을 쓰고 HTTP /mcp 엔드포인트에 진단 정보를 담은 500 응답을 반환합니다. 이렇게 하면 Cursor나 다른 클라이언트가 "왜 툴이 없는지" 자동으로 파악할 수 있습니다.

예: 표준 출력에 다음과 같은 JSON 블록이 찍힐 수 있습니다.

{
  "diagnostic": "mcp-sdk-missing",
  "reason": "@modelcontextprotocol/sdk not installed",
  "tools": [
    { "name": "fetchPopularStocks", "input": { "limit": "number (optional)" } },
    { "name": "fetchStockByCode", "input": { "code": "string (6-digit)" } }
  ],
  "remediation": "install @modelcontextprotocol/sdk and commander, or run this package in an environment that includes them; alternatively run the MCP server with --transport http on a host that has the SDK installed"
}

대응 방법:

• 빠른 해결: 실행 환경에 런타임 의존을 설치합니다.

  pnpm add -D @modelcontextprotocol/sdk commander
  # 또는 전역/호스트 환경에 설치
  npm install -g @modelcontextprotocol/sdk commander

• 대안: HTTP 전송을 사용하여 MCP를 호스트(예: Railway, Heroku)하고 Cursor에 HTTP 엔드포인트를 사용하도록 설정합니다. HTTP 방식은 서버에 SDK가 설치되어 있어야 합니다.

• 이미 이 저장소의 동작(진단 출력)이 적용되어 있으므로, Cursor에서 "No tools"가 보이면 stdout 로그 또는 /mcp 응답의 진단 JSON을 확인해 주세요. 진단 JSON은 왜 툴이 등록되지 않았는지(누락된 패키지 또는 전송 미지원 등)를 알려줍니다.

원하시면 제가 이 리포지토리에 런타임 의존을 추가하여(즉 @modelcontextprotocol/sdk와 commander를 dependencies로 넣고) 재배포해 드릴 수 있습니다 — 그러면 npx finance-crawl로 실행했을 때 MCP 툴이 자동으로 등록됩니다. 이 방식은 패키지 용량과 런타임 의존이 늘어나는 영향을 미칩니다. (원하시면 진행할게요.)

MCP 툴 (Tools exposed)

이 MCP 서버는 다음 도구들을 제공합니다 (MCP가 활성화된 경우):

• fetchPopularStocks: 네이버 인기종목 목록을 크롤링하여 코드와 이름 목록을 반환합니다.

  • 입력: { limit?: number }
  • 출력: [{ code: string, name: string }]

• fetchStockByCode: 6자리 종목코드로 종목 상세 정보를 크롤링합니다.

  • 입력: { code: string }
  • 출력: NaverStockData (이 저장소의 타입)

예: MCP 요청 바디 (fetchStockByCode)

{ "code": "005930" }

사용 예시

1. 인기 종목 목록을 가져와서 각 종목 크롤링 (간단한 스크립트 예)

import { NaverPopularStocksCrawler, NaverStockCrawler } from 'finance-crawl';

const popular = new NaverPopularStocksCrawler();
const list = await popular.crawl({ url: NaverPopularStocksCrawler.getUrl() });
if (list.success && list.data) {
  const codes = list.data.slice(0, 5).map(s => s.code);
  const crawler = new NaverStockCrawler();
  const results = await crawler.crawlMultiple(codes.map(c => ({ url: `https://finance.naver.com/item/main.naver?code=${c}` })));
  console.log(results.filter(r => r.success).map(r => r.data));
}

Docker

간단한 Dockerfile 예:

FROM node:18-alpine
WORKDIR /app
RUN npm install -g finance-crawl
EXPOSE 3000
CMD ["finance-crawl", "--transport", "http", "--port", "3000"]

테스트

프로젝트는 Vitest 기반의 테스트를 포함합니다.

pnpm test

스크립트

# 빌드
pnpm build

# 개발
pnpm dev:api

# 테스트
pnpm test

아키텍처 (간단)

• src/crawler: 네이버 금융 페이지 크롤러
• src/api: Express 기반 HTTP API
• src/mcp: MCP 서버(선택적, 런타임 로드)
• src/utils: 공용 유틸리티 (HTTP, parser, logger)

기여

기여 환영합니다. PR을 보내주세요.

라이선스

MIT