PM-MCP (Portfolio Management MCP Server)

PM-MCP (Portfolio Manager MCP Agent)

개요: MCP 서버 기반 펀드 매니저 에이전트. 뉴스·재무·공시 데이터를 수집/요약/지식화하고, 후보군 랭킹과 리포트를 생성하여 옵시디언으로 정리합니다. Claude 호스트앱에서 도구 호출로 전 과정을 대화형으로 제어합니다.

• 타겟: 미국 주식 중심(확장 가능)

• 호스트앱: Claude (MCP 연동)

• 본 문서는 프로젝트 계획(project-plan.md)을 실행 가능한 README로 정리한 것입니다.

주요 프로세스

• 신규 투자 진행 프로세스:

  1. 전반적 시장/섹터/기업 동향 파악

  2. 사용자에게 종목 카테고리 추천

  3. 사용자 지정 종목·테마 정밀 파악

  4. 후보 기업/종목 리스트업 및 데이터 수집

  5. 분석·평가·랭킹 및 리포트 작성(예상 이익률·근거)

  6. 옵시디언으로 문서화·시각화·지식 그래프 활용

• 보유 종목 진단/알림 프로세스:

  1. 보유 종목 진단 및 페이즈(상승/유지/불안정/적신호) 알림

  2. 적신호 단계 시 정밀 분석 및 대응 제안

아키텍처 요약

• Claude 호스트앱 + MCP 서버(도구 제공)

• 데이터 소스:

  • 뉴스/동향: Perplexity MCP

  • 시세/재무: yfinance(우선), Alpha Vantage/Finnhub/Polygon.io(확장)

  • 공시/실적: SEC EDGAR API

• 분석/랭킹: 팩터 + 이벤트/모멘텀/리스크 스코어

• 스토리지: SQLite 캐시/운영, 옵시디언 Markdown, (선택) Neo4j

• 스케줄링: APScheduler (데일리/주간 잡)

디렉터리 구조 제안

환경 변수(.env)

사용 라이브러리

• 핵심: fastapi(선택), pydantic, requests, pandas, numpy, yfinance, python-dateutil, APScheduler, jinja2, diskcache, tqdm

• 선택: alpha_vantage, sec-api 또는 직접 EDGAR, ta, vectorbt, neo4j(옵션), langchain-core, pyyaml, markdownify

프롬프트 스키마(요약/엔티티)

핵심 MCP 도구(엔드포인트)

• market_data.get_prices(ticker, start, end, interval)

• market_data.get_fundamentals(ticker)

• news.search(query|tickers, lookback)

• filings.fetch(ticker, form, lookback)

• analytics.rank(candidates, criteria?)

• portfolio.evaluate(holdings)

• reports.generate(type, payload)

• obsidian.write(note_path, content, links)

옵시디언 출력 규칙

• 파일명: Companies/{TICKER} - {Company}.md, Markets/{Theme}.md

• Front matter 예시:

로드맵(마일스톤)

• M0: 환경 준비(.env, 폴더) 0.5d

• M1: 스캐폴딩/요구사항(README, requirements) 1d

• M2: 커넥터 구현(yfinance, Perplexity, SEC) 2d

• M3: 분석/랭킹/페이즈 2d

• M4: 리포트·옵시디언 1d

• M5: MCP 연동/테스트 1d

• M6: 스케줄러·운영 0.5d

• M7: 확장(Alpha Vantage/Finnhub, Neo4j, 백테스트)

차별점(Differentiators) & 사이드킥 기능(Sidekicks)

• 테마-그래프 인텔리전스: 뉴스/공시에서 추출한 엔티티를 "테마 그래프"로 연결(섹터→산업→밸류체인→키워드). 테마 강도 지수(TSI)와 자금 유입 시그널을 결합해 "테마 관성"을 측정.

• 이벤트-센서 네트워크: 실적 발표, 가이던스 상향/하향, 인수/규제, 제품 출시, 공급망 등 이벤트를 실시간 센서로 모델링. 종목·테마·경쟁사에 전파되는 2차, 3차 파급효과를 추정.

• 어썸 샘플링 리포트: 동일 테마 내 상위 3개/하위 3개 종목의 대비 리포트를 1페이지에 자동 생성. “왜 이 종목인가/아닌가” 근거를 구조화하여 의사결정 속도 향상.

• 포트폴리오 카운터팩추얼: 보유 종목 교체 시나리오(what-if) 자동 제안. 리밸런싱 후보와 기대 수익-리스크 변화량을 수치화.

• 이벤트 D-캘린더: 다음 2주 내 주요 캘린더(FDA, 실적, 제품 출하, 규제)를 요약하고 포트폴리오 민감도를 시뮬레이션.

• 옵시디언 지식 루프: 생성 리포트의 핵심 인사이트를 지속 누적, 재사용. 과거 결론 대비 현재 데이터 변화량을 하이라이트하여 회귀 평가 가능.

• 오퍼레이션 보호장치: 신뢰도 스코어(출처/신선도/일관성)로 저품질 정보를 차단. 편향·환각 방지를 위한 인용/교차검증 규칙 적용.

위 기능은 일반적인 스크레이핑·요약형 프로젝트 대비, "테마/이벤트/포트폴리오"의 삼각 결합과 옵시디언 기반 메모리 축적을 핵심 차별점으로 삼습니다.

성과 지표(KPIs) & 평가

• 알파 지표: 벤치마크 대비 초과수익(월/분기), 정보비율(IR)

• 의사결정 속도: 신규 테마→후보 리스트업→리포트 생성까지 소요 시간

• 신호 품질: 이벤트 후 5/20/60 거래일 수익률 분포, 히트율

• 리포트 활용도: 옵시디언 조회수, 재인용/링크 백 비율

• 신뢰도 스코어: 출처 다양성, 신선도, 교차검증 일치도

• 운영 안정성: 실패율, API 한도 초과율, 재시도 성공률

보안·프라이버시 & 운영 원칙

• API 키/인증: .env/키관리, 최소권한, 로테이션. SEC EDGAR User-Agent 명시.

• 데이터 거버넌스: 출처·저작권 준수, 요약/발췌 규칙 문서화.

• 로깅/모니터링: 구조화 로그(JSON), 주요 도구의 latency/오류율 대시보드화.

• 캐시/한도 관리: diskcache + 백오프/재시도. 요약·랭킹은 idempotent 설계.

• 재현성: 프롬프트 버저닝, 샘플 셋 고정, 회귀 테스트.

• 안전장치: 과도한 레버리지/테마 집중 경고, 리스크 점수 상한.

랭킹 스코어 보강: 저점매수 가산점

• 목적: 최근 고점 대비 딥이 존재하면서 단기 모멘텀(10일)이 회복되는 종목을 가중 반영하여 저점매수 알파를 노림.

• 산식(요약):

  • 딥 점수 dd_score = clamp((recent_high - last)/recent_high ÷ 0.30, 0..1)

  • 모멘텀 점수 mom_score = clamp((ret10 + 5%) ÷ 10%, 0..1)

  • 가산점 dip_bonus = dip_weight × [0.5×dd_score + 0.5×(dd_score×mom_score)]

• 옵션:

  • dip_weight(기본 0.12)로 영향도 조절

  • dip_score를 사전 계산해 후보 입력에 직접 주입 가능(없으면 가격데이터로 자동 계산)

• 주의: 급락 추세 지속에는 모멘텀 항이 낮아 보너스 자연 감소. 리스크 관리(손절·포지션 한도) 병행 권장.

Claude 자연어 예시 프롬프트

• 테마 리포트: "AI 테마 주간 리포트 만들어줘. 티커는 AAPL, MSFT, NVDA 사용해."

  • 내부 호출: create_theme_report(theme='AI', tickers_csv='AAPL,MSFT,NVDA')

• 포트폴리오 페이즈: "내 보유종목 AAPL, MSFT, NVDA의 페이즈 리포트 만들어줘."

  • 내부 호출: create_portfolio_phase_report(tickers_csv='AAPL,MSFT,NVDA')

• 뉴스: "최근 일주일 AI 칩과 클라우드 성장 관련 뉴스 5개만 요약해줘."

  • 내부 호출: news_search(queries=['AI chips','cloud growth'], lookback_days=7, max_results=5)

• 공시: "AAPL의 최근 10-Q/8-K 3건 보여줘."

  • 내부 호출: filings_fetch_recent(ticker='AAPL', forms=['10-Q','8-K'], limit=3)

시각화/프레젠테이션 기본값(.env)

• PRESENT_THEME_CHART_DAYS: 테마 차트 기간(일) 기본값

• PRESENT_PORTFOLIO_HISTORY_DAYS: 포트폴리오 차트 기간(일)

• PRESENT_YSCALE: y축 스케일(linear|log)

• PRESENT_MA_WINDOWS: 이동평균 윈도우(쉼표 구분)

• PRESENT_COLORS: 기본 색상 팔레트(쉼표 구분 hex)

• PRESENT_NEWS_MAX: 뉴스 항목 수

• PRESENT_FILINGS_MAX: 공시 항목 수

Claude에서는 옵션을 생략하면 위 기본값이 적용됩니다.

점수 산정 고도화(설정)

• SCORE_WEIGHTS: 예) growth=0.2,profitability=0.3,valuation=0.3,quality=0.2

• SCORE_SECTOR_NEUTRAL: true/false (섹터별 상대 정규화 적용)

• 티커 제안: 테마→ETF(BOTZ/AIQ, SMH/SOXX, CLOU/WCLD, HACK/CIBR, ICLN/TAN, XBI/IBB, FINX/ARKF, DRIV/KARS) 보유종목 상위 10 추출, 실패 시 폴백

• Perplexity JSON 파싱: 응답이 마크다운/텍스트를 포함해도 대괄호 구간만 추출해 복구 후 파싱 시도

저장형 도구(Obsidian 연동)

• present_theme_save(theme, tickers_csv, with_images): Markets/{theme}/Overview {date}.md

• present_portfolio_save(tickers_csv, with_images): Portfolios/Overview {date}.md

• news_search_log_tool(queries, lookback_days, max_results, theme?): Markets/{theme}/News Logs/News {date}.md

• dip 후보: analyze_dip_candidates_tool → 노트/CSV/이미지 경로 반환