한국장/미국장 현재 상태, 휴장 여부, 최근/다음 거래일을 한 번에 조회합니다.

종목 분석 전 데이터 기준시각을 확인할 때 사용합니다. KRX와 NYSE/NASDAQ의 주말, 정규 휴장일, 장전/정규장/시간외/장마감 상태를 함께 반환합니다.

종목검색 — 종목명 또는 종목코드로 한국 주식 종목을 조회합니다. "삼성전자 종목코드", "반도체 관련주", "005930 뭐야" 같은 질문에 사용합니다.

⚠️ 사용자가 종목명만 주고 코드를 모를 때 반드시 이 도구를 먼저 호출. 종목 코드를 추측하지 말 것. 상장폐지·재할당으로 코드가 바뀔 수 있음.

search_stock으로도 동일하게 호출 가능 (별명).

Args: query: 검색할 종목명 또는 코드 (예: "삼성전자", "005930", "알멕")

종목코드조회 (stock lookup) — 한국 주식 종목명/코드 조회 전용 도구.

search와 동일 기능. 도구 디스커버리에서 "stock"/"ticker"/"종목" 키워드로 빠르게 매칭되도록 명확한 이름을 갖는 별명입니다.

⚠️ 종목명만 있고 6자리 코드를 모를 때 이 도구를 먼저 호출해야 합니다. 코드 추측(guessing) 금지. 다른 도구(get_price, get_chart 등)에 잘못된 코드를 넣으면 엉뚱한 종목이 조회됩니다.

Args: query: 종목명(한/영) 또는 6자리 코드. 예: "알멕", "Samsung", "005930"

Returns: 매칭된 종목 리스트. 여러 개면 사용자에게 확인 요청 필요.

캔들차트 OHLCV — 종목의 시계열 캔들 데이터(시가/고가/저가/종가/거래량, candlestick OHLCV). "삼성전자 일봉", "3개월 주봉", "월봉 데이터", "price history" 같은 질문에 사용. 시계열 진입점(US는 get_us_chart).

보조지표(이평선·RSI·MACD 등)는 사용자가 명시 요청할 때만 get_indicators로 숫자만 받아 요약.

Args: code: 종목코드 6자리 (예: "005930") timeframe: "day"(일봉), "week"(주봉), "month"(월봉) count: 가져올 봉 개수 (기본 120 ≈ 6개월, 최대 500)

현재가 — 종목의 현재 시세 스냅샷 (오늘 하루치 OHLC + 거래량). "삼성전자 지금 얼마", "현재가", "오늘 시세", "주가 알려줘" 같은 질문에 사용합니다.

⚠️ 단일 시점 스냅샷. 과거 시계열 아님. 차트/히스토리 필요 시 get_chart 사용.

Args: code: 종목코드 6자리 (예: "005930")

투자자수급 — 투자자별 매매동향 (기관/외국인 순매매 주식 수)을 가져옵니다. 네이버 증권 소스 특성상 개인 순매매는 제공되지 않습니다 (기관·외국인만). "외국인 수급", "기관 순매수", "수급 분석", "누가 사고 있어" 같은 질문에 사용합니다.

Args: code: 종목코드 6자리 (예: "005930") days: 조회할 일수 (기본 20일)

이벤트반응 — 특정 날짜(event_date) 기준 전후 주가·거래량·수급 반응을 정렬합니다.

DartLens의 scan_earnings_season·list_disclosures에 나온 공시 접수일을 event_date로 넘김 (휴장일이면 다음 거래일 기준). "공시→주가/수급" 또는 "주가/수급 이상→해당 기간 공시 확인" 시간축 정렬용 — 원인 단정·매수/매도 판단 아님.

Args: code: 종목코드 6자리 (예: "005930") event_date: 기준 날짜 YYYY-MM-DD 또는 YYYYMMDD. DartLens 공시 접수일 권장 before: event_date 전 비교 거래일 수 (기본 5, 최대 60) after: event_date 후 비교 거래일 수 (기본 20, 최대 60)

수급벌크 — 여러 종목의 투자자 수급(기관·외국인 순매매)을 한 번에 병렬 조회.

개별 get_flow를 N번 부르는 것보다 훨씬 빠릅니다 (서버 내부 asyncio.gather). "이 종목들 외국인 매수 같이 들어왔나", "관심종목 수급 비교" 같은 질문에 사용.

Args: codes: 종목코드 리스트 (최대 30개) days: 종목당 조회 일수 (기본 5, 최대 20). 토큰 절감 위해 단일 도구보다 짧음

수급스크리닝 — 거래대금/거래량 상위 N개 중 외국인·기관이 최근 며칠 연속 순매수한 종목만 추립니다.

"거래대금 상위 중 외국인·기관 동반 매수", "이틀 연속 수급 들어온 종목" 같은 스크리닝 전용. 랭킹+수급을 서버에서 join해 매치 종목만 반환 → 토큰·시간 절감.

Args: top_n: 상위 후보 수 (기본 100, 최대 500). 클수록 정확하나 느림(500≈20~50초) market: "KOSPI"/"KOSDAQ"/"ALL" (기본 ALL) foreign_days: 최근 N일 모두 외국인 순매수여야 매치 (0=미적용) inst_days: 최근 N일 모두 기관 순매수여야 매치 (0=미적용) exclude_etf: ETF/ETN 제외 (기본 True) sort_by: "trade_value"(거래대금, 기본)/"volume"(거래량)

재무지표 — 종목의 주요 재무지표(PER, PBR, 시가총액 등)를 가져옵니다. "PER", "PBR", "재무제표", "시가총액", "저평가" 같은 질문에 사용합니다.

Args: code: 종목코드 6자리 (예: "005930")

시장지수 — KOSPI, KOSDAQ 지수 현재값을 가져옵니다. "코스피", "코스닥", "시장 지수", "오늘 시장 어때" 같은 질문에 사용합니다.

테마목록 — 네이버 증권의 테마 목록을 가져옵니다. "어떤 테마가 있어?", "테마 리스트", "오늘 강세 테마" 같은 질문에 사용합니다. 총 7페이지가 있으며 한 페이지당 40개 테마가 있습니다. 전일대비 등락률 순으로 정렬되어 있어요.

Args: page: 페이지 번호 (1~7, 기본 1)

테마종목 — 특정 테마에 속한 종목 리스트를 가져옵니다. "반도체 테마 종목", "2차전지 관련주", "AI 테마주" 같은 질문에 사용합니다. 테마명 부분 매칭을 지원합니다.

Args: theme_name: 테마명 (예: "2차전지", "AI", "반도체") count: 반환할 최대 종목 수 (기본 30) include_reason: 편입사유 포함 여부. False로 하면 토큰 대폭 절감. "왜 이 테마에 들어갔는지" 필요 없으면 False 권장.

업종목록 — 네이버 증권의 업종(섹터) 목록을 가져옵니다. "업종별 현황", "섹터 리스트", "업종 등락률" 같은 질문에 사용합니다. 약 79개 업종이 전일대비 등락률 순으로 정렬됩니다.

업종종목 — 특정 업종에 속한 종목 리스트를 가져옵니다. "통신장비 업종 종목", "반도체 업종", "제약 섹터 종목" 같은 질문에 사용합니다. 업종명 부분 매칭을 지원합니다.

Args: sector_name: 업종명 (예: "통신장비", "반도체", "제약") count: 반환할 최대 종목 수 (기본 30)

거래량/거래대금 순위 — 상위 종목을 가져옵니다.

"거래량 많은 종목" → sort_by="volume" (기본, 주수 기준) "거래대금 많은 종목"/"거래 규모 큰 종목" → sort_by="trade_value" (원 기준)

대형 고단가 종목(삼전·하이닉스 등)은 거래량(주수)이 작아도 거래대금은 클 수 있어 스크리닝 시에는 sort_by="trade_value"가 더 적합한 경우가 많습니다.

Args: market: "KOSPI" / "KOSDAQ" / "ALL" (기본 ALL) count: 가져올 종목 수 (기본 50, 최대 500) sort_by: "volume"(거래량 주수) / "trade_value"(거래대금 원)

등락률순위 — 등락률 상위/하위 종목을 가져옵니다. "상한가 종목", "급등주", "급락주", "상승률 상위" 같은 질문에 사용합니다.

Args: direction: "up"(상승률 상위) / "down"(하락률 상위) market: "KOSPI" / "KOSDAQ" / "ALL" (기본 ALL) count: 가져올 종목 수 (기본 50, 최대 500)

시가총액순위 — 시가총액 상위 종목을 가져옵니다. "대형주", "시가총액 TOP", "코스피 대장주" 같은 질문에 사용합니다.

Args: market: "KOSPI" / "KOSDAQ" (기본 KOSPI, ALL 미지원) count: 가져올 종목 수 (기본 50, 최대 500)

벌크조회 — 여러 종목의 기본 정보(가격/등락률/거래량)를 한 번에 가져옵니다. "이 종목들 현재가 보여줘", "리스트 종목 시세 한번에" 같은 질문에 사용합니다. 개별 get_price를 여러 번 호출하는 것보다 훨씬 토큰 효율적입니다. 스크리닝 결과 N개 종목을 비교 분석할 때 필수 도구.

Args: codes: 종목코드 리스트 (최대 30개, 예: ["005930", "000660", "005380"])

차트통계벌크 — 여러 종목의 기간 집계 통계(현재가/최고가/최저가/낙폭/기간수익률)를 한 번에 병렬 조회.

⚠️ 시계열 아님 — 집계값만 반환(캔들·OHLCV는 get_chart). 개별 get_chart N번 대신 이걸로. ⭐ 스크리닝 필수: "52주 고점 대비 -30% 종목" 등 drawdown_pct·period_return_pct 필터에 사용.

Args: codes: 종목코드 리스트 (최대 100개) days: 과거 조회 일수 (기본 260 = 52주)

기술지표 — 이평선·RSI·MACD·볼린저·스토캐스틱 등 종합 판정 (JSON).

스크리닝·조건 필터·상태 판정 등 숫자 비교가 필요할 때만 호출. 차트 시각화용 아님(시각화는 get_chart). OHLCV 대신 판정 결과만 반환해 토큰 절약. 반환값의 라벨 필드(phase_label, type_label, position 등)는 그대로 인용할 것.

Args: code: 종목코드 (예: "005930") days: 조회 일수 (기본 260, 30~500). 구조 분석 지표는 500+ 권장. include: 지표 키. 기본 ["ma", "ma_phase", "volume", "candle"]. 스냅샷: ma ma_phase ma_slope ma_cross rsi macd bollinger stochastic obv volume position candle 구조: support_resistance volume_profile price_channel timeframe: "day"/"week"/"month" (분봉 미지원) params: 비표준 파라미터 오버라이드(사용자 명시 요청 시만). 예: {"rsi":{"period":21}}

기술지표벌크 — 여러 종목(최대 100개)의 지표를 병렬 판정. 스크리닝 핵심.

⚠️ 시계열·캔들 아님 — 집계 판정값만(시각화는 get_chart). get_indicators N번 대신 이걸로.

Args: codes: 종목코드 리스트 (최대 100개) days: 조회 일수 (기본 260) include: 지표 키 (기본 ["ma_phase","volume"]). get_indicators 참조. timeframe: "day"/"week"/"month" params: 지표 파라미터 오버라이드(전 종목 공통). get_indicators 참조.

엑셀내보내기 — 단일 종목의 데이터를 Excel 파일로 저장합니다.

Gemini/GPT 같은 다른 AI에 파일 업로드로 넘기거나, 엑셀에서 직접 분석/차트 작성할 때 사용합니다.

Args: data_type: "chart"(일봉 OHLCV) / "flow"(투자자별 수급) / "financial"(재무지표) code: 종목코드 6자리 (예: "005930") days: chart/flow의 경우 과거 일수 (기본 180) filename: 파일명 (비우면 자동 생성)

Returns: 저장된 파일 경로

시장스캔 — 여러 종목의 기본정보+차트통계+재무지표를 한 번에 수집해 Excel로 저장.

로컬 캐시 패턴: 한 번 스캔 → 이후 query_excel(파일경로, 조건)로 즉시 반복 필터링.

Args: codes: 종목코드 리스트 (최대 500개) days: 차트 통계 과거 일수 (기본 260 = 52주) include_financial: 재무지표(PER/PBR) 포함 여부 filename: 파일명 (비우면 자동 생성)

엑셀쿼리 — 저장된 Excel 스냅샷(scan_to_excel 산출)에서 조건에 맞는 종목을 로컬 필터링. HTTP 없이 빠름.

필터 형식(둘 다 지원): 간단: {"per_max": 10, "pbr_max": 1.5, "drawdown_pct_max": -30} 상세: {"per": {"max": 10, "min": 0}, "drawdown_pct": {"max": -30}}

Args: file_path: scan_to_excel로 만든 파일 경로 filters: 필터 조건 (컬럼명_max / 컬럼명_min 형식) sort_by: 정렬 기준 컬럼 (예: "market_cap", "drawdown_pct") descending: 내림차순 (기본 True) limit: 반환 최대 개수 (기본 30)

사용량통계 — 최근 N일간 MCP 도구 사용량을 집계해서 보여줍니다.

디버깅/최적화용. 도구별로:

• 호출 횟수

• 평균/p50/p95 실행 시간

• 평균 토큰 소모량

• 캐시 히트율

• 에러 발생 횟수 를 보여줍니다.

로그 파일 위치: ~/Downloads/kstock/logs/metrics_YYYYMMDD.jsonl

Args: days: 조회할 일수 (기본 1, 오늘만. 최대 30)

ETF목록 — ETF 전체 목록 조회 및 카테고리별 필터링.

category: 카테고리 필터 (빈 문자열=전체). 가능한 값: "국내 시장지수", "국내 업종/테마", "국내 파생", "해외 주식", "원자재", "채권/금리", "단기자금" sort_by: 정렬 기준 — "marketSum"(시가총액), "quant"(거래량), "threeMonthEarnRate"(3개월수익률) limit: 반환 개수 (기본 20, 최대 50)

ETF정보 — ETF 상세 정보 (기초지수, 보수율, 수익률, 구성종목 TOP10).

code: ETF 종목코드 (예: "069500" KODEX 200, "360750" TIGER 미국S&P500)

US stock price — NYSE/NASDAQ 미국 주식 현재가 스냅샷 (US market via yfinance). "AAPL price", "Tesla 현재가", "MSFT quote", "Nvidia 얼마" 같은 질문에 사용합니다.

현재가 + 전일대비 + 시/고/저 + 거래량 + 52주 고저 + 베타 + 시가총액 + 마켓 상태 (정규장/프리/포스트) 반환. Yahoo Finance 데이터는 최대 15분 지연 가능.

Args: ticker: US 티커 (예: "AAPL", "TSLA", "BRK.B", "SPY")

US stock info — 미국 주식 기업 정보 (섹터, 산업, 시총, 사업 요약 · US company profile). "Apple 어떤 회사", "NVDA 사업 설명", "TSLA sector", "기업 정보" 같은 질문에 사용합니다.

Args: ticker: US 티커 (예: "AAPL", "NVDA")

US stock chart OHLCV — 미국 주식 시계열 캔들 데이터 (US historical price data). "AAPL 차트", "Tesla 1년 주가", "NVDA history" 같은 질문에 사용. US 시계열 진입점(한국은 get_chart).

Args: ticker: US 티커 (예: "AAPL") period: "1d","5d","1mo","3mo","6mo","1y","2y","5y","10y","ytd","max" (기본 3mo) interval: "1m","5m","15m","30m","1h","1d","1wk","1mo" (기본 1d) prepost: 프리/포스트 마켓 포함 (intraday에서만 유효) limit: 최대 행수 (기본 500, 최대 5000). 큰 데이터는 export_us_to_excel 권장(토큰 0).

US stock financials — 미국 주식 재무지표 (PER, PBR, PEG, ROE, 배당률 · US valuation ratios). "AAPL PER", "Apple 재무", "NVDA valuation", "forward P/E" 같은 질문에 사용합니다.

Trailing / Forward P/E, PEG, P/B, P/S, EPS, ROE, ROA, 부채비율, 마진, 성장률, 배당수익률, 배당성향을 반환합니다.

Args: ticker: US 티커 (예: "AAPL")

US earnings calendar — 다음 실적 발표일 + 최근 EPS 서프라이즈 이력 (US earnings date / EPS surprise). "AAPL 실적 언제", "NVDA earnings date", "Tesla 다음 실적" 같은 질문에 사용합니다.

미국 시장은 분기 실적(10-Q)이 주가 변동의 핵심 이벤트입니다.

Args: ticker: US 티커 (예: "NVDA")

US analyst ratings — 미국 주식 애널리스트 목표주가 + 투자의견 (US analyst price target / rating). "AAPL 목표가", "NVDA analyst rating", "Tesla buy/hold", "Wall Street 의견" 같은 질문에 사용합니다.

목표주가(mean/high/low) + buy/hold/sell 분포 + 최근 업·다운그레이드를 반환합니다.

Args: ticker: US 티커 (예: "NVDA")

US dividends — 미국 주식 배당 이력 + ex-date + yield (US dividend history / yield). "AAPL 배당", "KO dividend yield", "SCHD 배당 이력", "ex-date" 같은 질문에 사용합니다.

Args: ticker: US 티커 (예: "KO", "JNJ", "SCHD") limit: 표시할 최근 배당 건수 (기본 12)

US options chain — 미국 주식 옵션 체인 (calls/puts, IV, OI · US equity options). "AAPL options", "Tesla 콜옵션", "NVDA implied volatility", "옵션 체인" 같은 질문에 사용합니다.

기본: 최근접 만기의 현재가 근처 strike. Greeks (delta/gamma/theta)는 미포함.

Args: ticker: US 티커 (예: "AAPL") expiration: 만기일 "YYYY-MM-DD". 미지정 시 가장 가까운 만기. strikes_around_spot: 현재가 기준 좌우 strike 개수 (기본 10)

US insider trading — 내부자 거래 Form 4 + 최근 6개월 순매수 요약 (US insider Form 4). "AAPL insider trading", "NVDA 내부자 매수", "CEO stock sale" 같은 질문에 사용합니다.

Args: ticker: US 티커

US institutional holders — 기관·뮤추얼펀드 보유 현황 (13F holdings). "AAPL institutional holders", "Vanguard 보유", "13F holdings", "who owns" 같은 질문에 사용합니다.

Args: ticker: US 티커

US short interest — 공매도 잔고 + % of float + days to cover (US short interest). "AAPL short interest", "GME 공매도", "short squeeze" 같은 질문에 사용합니다.

⚠️ FINRA bi-monthly 공시라 데이터가 2~4주 stale합니다. 반드시 'date_short_interest'를 확인하세요.

Args: ticker: US 티커

US SEC filings — 10-K, 10-Q, 8-K 공시 목록 + EDGAR URL (US SEC EDGAR filings). "AAPL 10-K", "NVDA latest filings", "8-K", "SEC filing" 같은 질문에 사용합니다.

Args: ticker: US 티커 limit: 표시할 공시 건수 (기본 15)

US stock news — 미국 주식 관련 뉴스 헤드라인 (US stock news feed). "AAPL 뉴스", "Tesla news", "NVDA headlines" 같은 질문에 사용합니다.

Args: ticker: US 티커 limit: 헤드라인 개수 (기본 10)

컨센서스 — 증권사 투자의견, 목표주가, 실적 추정치 (매출액/영업이익 컨센서스).

"목표가 얼마야", "컨센서스", "증권사 의견", "적정가", "실적 전망" 같은 질문에 사용합니다.

Args: code: 종목코드 6자리 (예: "005930")

증권사리포트 — 종목의 최근 증권사 분석 리포트 (목표가, 투자의견, 본문 요약, PDF).

"리포트", "증권사 분석", "애널리스트 의견", "리서치" 같은 질문에 사용합니다.

Args: code: 종목코드 6자리 (예: "005930") count: 가져올 리포트 수 (기본 5, 최대 10)

공시목록 — 종목의 최근 공시 (DART 전자공시) 목록.

"공시", "IR", "실적 발표", "공정공시" 같은 질문에 사용합니다.

Args: code: 종목코드 6자리 (예: "005930")

US stock search — 미국 주식 종목명/티커 검색 (US stock search, ticker lookup). "Apple 티커", "Tesla symbol", "반도체 ETF", "Nvidia 찾아줘" 같은 질문에 사용합니다.

⚠️ 사용자가 "애플"·"테슬라" 같은 회사명만 주면 이 도구를 먼저 호출하세요. 결과가 여러 개면 사용자에게 확인 요청. 추측 금지.

Args: query: 검색어 (회사명·티커, 한/영 무관)

US market indices — 미국 주요 지수 스냅샷 (S&P 500, Dow, Nasdaq, VIX). "시장 지수", "S&P 지금", "Nasdaq 얼마", "VIX" 같은 질문에 사용합니다.

US stock screener — 미국 주식 프리셋 스크리너 (US predefined screener). "오늘 급등주", "top gainers", "가장 많이 거래된 종목", "저평가 성장주" 같은 질문에 사용합니다.

사용 가능 preset: day_gainers, day_losers, most_actives, most_shorted_stocks, aggressive_small_caps, growth_technology_stocks, undervalued_growth_stocks, undervalued_large_caps, small_cap_gainers, conservative_foreign_funds

Args: preset: 스크리너 ID (기본 day_gainers) count: 반환 종목 수 (기본 20)

US financial statements — 미국 주식 재무제표 3종 (income/balance/cash_flow). "AAPL 손익계산서", "NVDA 현금흐름표", "Apple balance sheet quarterly" 같은 질문에 사용합니다.

핵심 row만 추출 (Total Revenue, Net Income, Total Assets, Free Cash Flow 등).

Args: ticker: US 티커 statement_type: "income" / "balance" / "cash_flow" (기본 income) period: "annual" / "quarterly" (기본 annual)

US sector overview — 미국 섹터별 top 기업 + 시장 비중 (US sector top companies). "기술주 섹터", "healthcare top companies", "technology 대장주", "섹터 비중" 같은 질문에 사용합니다.

Args: sector_key: technology, healthcare, financial-services, consumer-cyclical, consumer-defensive, communication-services, industrials, energy, basic-materials, utilities, real-estate top_n: top 기업 수 (기본 20)

US ETF info — ETF 전용 상세 (top holdings, 섹터 비중, 자산 배분 · US ETF details). "SPY 구성종목", "QQQ holdings", "VOO 섹터", "ETF 보수" 같은 질문에 사용합니다.

Args: ticker: ETF 티커 (예: "SPY", "QQQ", "VOO", "SCHD")

US multi-ticker prices — 여러 미국 주식 일괄 가격 조회 (US multi-ticker snapshot). "AAPL MSFT NVDA 동시", "big tech 가격", "내 포트폴리오 현재가" 같은 질문에 사용합니다.

Args: tickers: 티커 리스트 (예: ["AAPL", "MSFT", "NVDA"]). 최대 20개 권장.

US Excel export — 미국 주식 장기 데이터를 Excel 파일로 저장 (토큰 소비 없음). "AAPL 10년치 CSV 저장", "TSLA 5년 일봉 엑셀" 같은 질문에 사용. get_us_chart는 500행 상한이라 장기 데이터는 잘림 — 백테스트·CSV·다른 AI 업로드용이면 이 도구로(행 수 무제한).

Args: ticker: US 티커 (예: "AAPL", "SPY", "BRK.B") period: "1d","5d","1mo","3mo","6mo","1y","2y","5y","10y","ytd","max" (기본 10y) interval: "1d","1wk","1mo" (기본 1d) filename: 파일명 (비우면 자동)