MCP 기반 금융 분석가

실제 MCP(Model Context Protocol) 서버를 기반으로 구축된 로컬 우선 AI 금융 분석가입니다. 하나의 챗봇이 주가 추세를 추측하는 대신, 두 에이전트가 함께 작동합니다.

• Validator 에이전트 — 인터넷에서 가져온 데이터(Yahoo Finance, 뉴스 API)에서 누락, 잘못된 값, 티커 불일치가 있는지 LLM에 도달하기 전에 검사합니다.

• Analyst 에이전트 — 검증된 데이터와 MCP 도구 출력을 바탕으로 추론하여 구조화된 요약(추세, 이동평균, 변동성, 관련 뉴스 감성)을 작성합니다.

두 에이전트 모두 사용자 정의 MCP 서버가 노출하는 도구를 호출합니다. 이것은 프로젝트의 핵심이지 단순한 LangChain 글루 코드가 아닙니다.

기본 튜토리얼 버전에서 추가한 내용

• 하나의 에이전트가 모든 것을 처리하는 대신 두 에이전트 분할(Validator → Analyst)

• 검증을 자체 도구로 포함하여 3개의 도구를 갖춘 실제 MCP 서버

• 두 에이전트 모두에 LangSmith 추적 적용

• Neon Postgres 캐싱 계층(요청 제한이 있는 API를 반복 호출하지 않도록 방지)

• 직접 계산한 ground truth를 사용하는 소규모 평가 스위트

• 배포된 웹 앱(Render의 FastAPI, Vercel의 정적 프론트엔드)

Related MCP server: MonteWalk

아키텍처

User query (ticker + date range)
        │
        ▼
  Validator agent ──calls──▶ MCP server ──▶ fetch_price_data (Yahoo Finance)
        │                                 ▶ validate_data
        │  (retries once on bad data)
        ▼
  Analyst agent ──calls──▶ MCP server ──▶ analyze_chart (moving averages, volatility)
        │                                ▶ get_news_sentiment
        ▼
  Structured summary + chart data → FastAPI → frontend

프로젝트 구조

backend/
  mcp_server/          # the MCP server + its 3 tools (this is the centerpiece)
  agents/               # Validator agent, Analyst agent
  orchestration/         # LangGraph wiring: Validator -> Analyst
  db/                    # Neon Postgres cache + eval result storage
  evals/                 # hand-checked test cases + eval runner
  main.py                # FastAPI app, deployed on Render
frontend/
  index.html             # single-page UI, deployed on Vercel
  vercel.json
render.yaml               # Render deployment config for the backend
requirements.txt
.env.example

설정

1. 클론 및 설치

   git clone <your-repo-url>
   cd financial-analyst-mcp
   python -m venv venv && source venv/bin/activate
   pip install -r requirements.txt

2. 환경 변수 — .env.example을 .env로 복사하고 다음을 입력하세요:

   • GROQ_API_KEY — 무료, 결제 불필요(console.groq.com에서 가입). Analyst 에이전트와 뉴스 관련성 확인에 사용됩니다.

   • DATABASE_URL — RDS Postgres 연결 문자열

   • NEWSAPI_KEY — newsapi.org의 무료 티어(하루 100회 요청, 카드 불필요)

   • LANGCHAIN_API_KEY, LANGCHAIN_PROJECT — LangSmith 추적용(선택 사항, 무료 티어)

3. 데이터베이스 테이블 설정

   python -m backend.db.database --init

4. 백엔드를 로컬에서 실행

   uvicorn backend.main:app --reload --port 8000

5. 프론트엔드를 로컬에서 실행 — 브라우저에서 frontend/index.html을 열거나 다음 명령으로 서빙하세요:

   cd frontend && python -m http.server 5500

   index.html 상단 근처의 API_BASE_URL 상수를 백엔드를 가리키도록 업데이트하세요 (http://localhost:8000 로컬, 배포 후에는 Render URL).

6. 평가 스위트 실행

   python -m backend.evals.run_evals

배포 (AWS 프리 티어)

아래의 모든 내용은 AWS 12개월 프리 티어 범위 내에 있습니다(명시된 프리 티어 인스턴스 크기를 선택하는 한). 여기서 코드 변경은 필요 없습니다. 동일한 FastAPI 앱과 MCP 서버가 그대로 실행됩니다.

1. 데이터베이스 → RDS(Postgres)

1. AWS 콘솔 → RDS → 데이터베이스 생성.

2. 엔진: PostgreSQL. 템플릿: 프리 티어.

3. 인스턴스 클래스: db.t3.micro(또는 콘솔에서 프리 티어로 제공하는 db.t4g.micro).

4. 마스터 사용자 이름/암호를 설정하고 기록해 두세요.

5. "Connectivity"에서 퍼블릭 액세스: 예로 설정하세요(EC2 인스턴스와 사용자 머신이 접근할 수 있도록 필요합니다. 포트폴리오 프로젝트에서는 괜찮지만, 원한다면 나중에 보안을 강화하세요).

6. 생성된 후 엔드포인트(xxxx.rds.amazonaws.com 형태)를 복사하고 연결 문자열을 만드세요:

   DATABASE_URL=postgresql://<username>:<password>@<endpoint>:5432/postgres

7. RDS 인스턴스의 보안 그룹에서 인바운드 규칙을 추가하세요: PostgreSQL(포트 5432), 소스 = 사용자 IP(로컬 테스트용), 나중에는 EC2 인스턴스의 보안 그룹.

2. 백엔드 → EC2

1. AWS 콘솔 → EC2 → 인스턴스 시작.

2. AMI: Amazon Linux 2023(또는 Ubuntu 22.04). 인스턴스 유형: t2.micro(프리 티어 자격 있음).

3. 키 페어(.pem 파일)를 생성/다운로드하세요 — SSH 접속에 필요합니다.

4. 보안 그룹: 인바운드 SSH(포트 22, 사용자 IP)와 어디에서나(0.0.0.0/0) 접근 가능한 사용자 지정 TCP 포트 8000을 허용하여 프론트엔드가 API에 도달할 수 있게 하세요.

5. 인스턴스를 시작한 후 SSH로 접속하세요:

   ssh -i your-key.pem ec2-user@<instance-public-ip>

6. 인스턴스에서:

   git clone <your-repo-url> financial-analyst-mcp
   cd financial-analyst-mcp
   nano .env          # paste in GROQ_API_KEY (free, from console.groq.com), DATABASE_URL (from RDS), NEWSAPI_KEY, etc.
   bash aws/ec2-setup.sh

   이 명령은 Python과 의존성을 설치하고 데이터베이스 테이블을 생성하며 백엔드를 systemd 서비스(financial-analyst)로 시작합니다. 이 서비스는 연결을 끊어도 계속 실행되고, 인스턴스가 재부팅되면 자동으로 다시 시작됩니다.

7. 실행 중인지 확인: curl http://<instance-public-ip>:8000/health

3. 프론트엔드 → S3 정적 웹사이트

1. frontend/index.html 상단 근처의 API_BASE_URL을 http://<your-ec2-public-ip>:8000으로 업데이트하세요.

2. 사용자 머신에서(AWS CLI가 설치되어 있고 aws configure를 자격 증명으로 한 번 실행한 상태에서):

   BUCKET_NAME=your-unique-bucket-name bash aws/deploy-frontend-s3.sh

3. 이 스크립트는 버킷을 생성하고 정적 웹사이트 호스팅을 켠 다음 index.html을 업로드합니다. 마지막에 실제 URL(http://<bucket>.s3-website-<region>.amazonaws.com)을 출력합니다.

4. 프론트엔드를 변경할 때마다 같은 스크립트를 다시 실행하여 재업로드하면 됩니다.

참고 사항

• EC2의 퍼블릭 IP는 인스턴스를 중지/시작하면 변경됩니다(실행 중인 인스턴스에 연결되어 있는 한 무료인 Elastic IP를 연결하지 않은 경우). IP가 변경되면 API_BASE_URL을 업데이트하고 S3 배포 스크립트를 다시 실행하세요.

• 비용을 0으로 유지하려면 t2.micro/db.t3.micro 프리 티어 크기를 고수하고, AWS 프리 티어가 처음 12개월만 적용된다는 점을 기억하세요.

AWS 프리 티어에서 비용이 발생하나요?

아니요, 다음 한도 내에 머무르는 한 말이죠(모두 신규 계정을 위한 AWS 12개월 프리 티어에 포함됩니다):

비용이 발생하는 항목이므로 피하세요:

• 동시에 두 번째 EC2 인스턴스나 RDS 데이터베이스를 실행하는 경우(서비스별 첫 프리 티어 시간만 무료입니다 — 두 개를 실행하면 시간이 두 배로 소모됩니다)

• t2.micro/t3.micro(EC2) 또는 db.t3.micro/db.t4g.micro(RDS)보다 큰 인스턴스 유형을 사용하는 경우

• Elastic IP를 요청하고 실행 중인 인스턴스에 연결하지 않는 경우 — AWS는 연결되지 않은 Elastic IP에 대해 요금을 부과하여 이를 방지합니다

• AWS 계정이 완전히 새 계정이 아닌 경우 — 프리 티어는 계정 생성 후 12개월이므로 계정 보유 기간이 그보다 길다면 이러한 서비스는 정상 청구됩니다

어떤 경우든 설정해 둘 가치가 있는 안전장치 하나: AWS 콘솔 → Billing → Budgets → $1 예산 알림을 만드세요. 비용이 발생하기 시작하는 즉시 이메일로 알려 주므로 예상치 못한 요금을 받지 않습니다.

MCP 계층에 관한 참고 사항

MCP 서버(backend/mcp_server/server.py)는 stdio를 통해 Model Context Protocol을 사용하는 독립형 프로세스입니다. 에이전트는 langchain-mcp-adapters를 사용하여 MCP 클라이언트로 이 서버에 연결하며, 이 어댑터는 MCP 도구를 LangChain 호환 도구로 자동 변환합니다. 즉, 동일한 MCP 서버를 코드 변경 없이 Claude Desktop, Cursor 또는 다른 MCP 호환 호스트에 연결할 수 있습니다. 이것이 도구 스키마를 에이전트에 하드코딩하는 대신 이렇게 구축하는 이유입니다.