YNAB MCP 스타터

읽기 전용 YNAB MCP 서버를 위한 프로덕션 스타일의 TypeScript 스타터 저장소입니다.

이 스타터는 의도적으로 작고 명확하게 구성되었습니다:

• Node.js 18+ 버전

• 엄격한 컴파일러 설정을 적용한 TypeScript

• Zod로 검증된 도구 입력 및 출력

• 재시도 및 타임아웃 처리가 포함된 읽기 전용 YNAB API 클라이언트

• YNAB 응답을 모킹(mocking)한 단위 테스트

• MCP 전송 연결을 위한 명확한 TODO 마커

이 저장소에 포함된 내용

src/
  clients/   YNAB API client, environment config, and error types
  schemas/   strict Zod schemas for tool contracts
  server/    MCP server composition and transport TODO placeholders
  tools/     read-only business logic for each YNAB capability
  types/     shared API and service types
tests/       unit tests with mocked API responses

구현된 읽기 전용 기능:

• 예산 목록 조회

• 계정 목록 조회

• 카테고리 목록 조회

• 최근 거래 목록 조회

• 분류되지 않은 거래 찾기

• 카테고리별 월간 지출

쓰기 권한은 의도적으로 구현되지 않았습니다.

Related MCP server: MCP Server Starter

설정

1. 의존성 설치:

npm install

2. 예제 환경 파일 복사:

cp .env.example .env

3. .env 파일에 YNAB 토큰 설정:

YNAB_TOKEN=your-token-here

4. 로컬 개발 모드 실행:

npm run dev

스크립트

• npm run build: TypeScript를 dist/로 컴파일

• npm run dev: 파일 감시 기능과 함께 스타터 진입점 실행

• npm run lint: ESLint 실행

• npm run test: Vitest를 사용한 단위 테스트 실행

• npm run typecheck: no-emit 모드로 TypeScript 실행

MCP 연결

이 저장소에는 서버 구성 계층이 포함되어 있지만, 특정 전송 방식에 종속되지 않습니다.

다음 파일의 TODO 주석을 확인하세요:

• src/server/index.ts

• src/server/registerTools.ts

이곳에서 다음 작업을 수행해야 합니다:

1. MCP 서버 인스턴스화

2. 도구 정의 및 스키마 등록

3. stdio, SSE 또는 기타 전송 방식 연결

4. 구조화된 로깅 및 운영 훅 추가

보안 참고 사항

• 이 스타터는 환경 변수에 YNAB_TOKEN 개인 액세스 토큰이 필요합니다.

• 소스 파일, 테스트, 프롬프트 또는 로그에 토큰을 하드코딩하지 마십시오.

• 토큰은 읽기 전용 운영 용도로만 제한하고, 노출된 경우 즉시 교체하십시오.

• 프로덕션 환경에서는 거래 메모나 기타 민감한 재무 메타데이터가 포함될 수 있으므로 원시 YNAB API 응답을 로깅하지 마십시오.

• 이 스타터는 YNAB API에 대해 GET 요청만 수행합니다. 쓰기 엔드포인트는 구현되지 않았습니다.

설계 참고 사항

• YNAB 클라이언트는 재시도, 타임아웃 처리 및 오류 정규화를 중앙 집중화합니다.

• 도구 모듈은 HTTP 세부 정보로부터 격리되어 있으며 작은 서비스 인터페이스 위에서 작동합니다.

• Zod 스키마는 도구 입력과 출력을 모두 검증하여 변경 사항을 조기에 감지합니다.

• 금액은 YNAB 밀리유닛(milliunits)과 사람이 읽기 쉬운 십진수 금액으로 모두 노출됩니다.

• 카테고리별 월간 지출은 요청된 월의 유출액만 계산합니다.

예제 프롬프트

• "내 YNAB 예산 목록을 보여줘."

• "예산 budget-id-123의 계정을 보여줘."

• "예산 budget-id-123의 카테고리 목록을 보여줘."

• "예산 budget-id-123의 최근 거래 20개를 보여줘."

• "2026-04-01 이후 예산 budget-id-123에서 분류되지 않은 거래를 찾아줘."

• "2026-04 예산 budget-id-123의 카테고리별 월간 지출을 요약해줘."

테스트

테스트는 YNAB API 응답을 모킹하므로 실제 토큰 없이도 동작을 검증할 수 있습니다:

npm run test

프로덕션 강화 아이디어

• 요청 상관관계 ID(correlation ID) 및 구조화된 로그 추가

• 재시도, 속도 제한 및 지연 시간에 대한 메트릭 추가

• 모킹된 HTTP 계층에 대한 통합 테스트 추가

• MCP 클라이언트가 더 큰 결과 집합을 예상하는 경우 결과 페이지네이션 제어 추가

• 배포를 위해 로컬 .env 파일 대신 비밀 관리자(secrets manager) 통합 추가