akij-hr-data-mcp

프로덕션 준비가 된 읽기 전용 원격 Model Context Protocol (MCP) 서버로, 하나의 Google Drive 폴더 — AKIJ HR DATA 저장소 — 를 최신 Streamable HTTP 전송을 통해 MCP 호환 클라이언트에 노출합니다.

범용 Drive MCP입니다. XLSX, XLS, CSV, PDF, DOCX, TXT, 이미지, 네이티브 Google Docs/Sheets/Slides 파일을 처리하며 Excel 전용 도구가 아닙니다.

1. 이 프로젝트가 하는 일

• 서비스 계정을 사용해 Google Drive에 연결합니다(사용자 OAuth 흐름이나 브라우저 로그인 없음).

• 모든 작업을 구성된 하나의 폴더(GOOGLE_DRIVE_FOLDER_ID)와 그 하위 폴더로 제한합니다. 해당 트리 밖의 파일은 서비스 계정이 기술적으로 볼 수 있다 하더라도 절대 반환되지 않습니다.

• 파일 검색 및 읽기를 위한 11개의 MCP 도구를 제공합니다(목록, 검색, 메타데이터, 콘텐츠, Excel/CSV/PDF/DOCX용 형식별 추출).

• 표준 Node/Express HTTP 서버로 실행되며 단일 POST /mcp 엔드포인트(Streamable HTTP 전송)와 GET /health 엔드포인트를 갖습니다. Render(또는 모든 Node 호스트)에 배포할 수 있어 PC가 꺼져 있어도 계속 실행됩니다.

• 모든 MCP 요청에 API 키 인증을 적용합니다.

• 철저히 읽기 전용입니다 — Drive 파일을 업로드, 편집, 삭제, 이름 변경, 이동, 공유하거나 권한을 변경할 수 있는 코드 경로가 없습니다.

Related MCP server: Google Drive MCP Server

2. 아키텍처

Google Drive (AKIJ HR DATA folder)
        ↓ Drive API v3 (read-only scope)
Google Service Account (GCP_KEY_BASE64)
        ↓
GoogleDriveClient (src/google-drive.ts) — enforces folder-tree scope
        ↓
MCP Server (src/mcp-server.ts) — 11 tools, Zod-validated inputs
        ↓
Express app (src/index.ts) — API-key auth, Streamable HTTP transport
        ↓ POST /mcp  (stateless, one transport per request)
        ↓
Render (always-on host)
        ↓ HTTPS
Remote MCP Clients (Claude, other MCP-compatible clients)

서버는 상태 비저장(stateless) 입니다. 각 POST /mcp 요청은 고유한 McpServer + StreamableHTTPServerTransport 인스턴스(sessionIdGenerator: undefined)를 받으므로 세션 선호도 요구 사항이 없으며 Render에서 고정 세션 없이 수평 확장됩니다.

프로젝트 구조

src/
  index.ts            Express app: /health, /mcp, startup
  config.ts           Environment variable loading/validation
  auth.ts             API-key authentication middleware
  google-auth.ts      Decodes GCP_KEY_BASE64 → JWT auth client
  google-drive.ts      Drive API client with folder-scope enforcement
  mcp-server.ts        McpServer wiring: registers all 11 tools

  tools/
    files.ts           list_files, get_file_metadata, get_file_content, list_supported_files
    search.ts           search_files, search_repository
    excel.ts            inspect_excel, read_excel_sheet
    csv.ts               read_csv
    pdf.ts               extract_pdf_text
    docx.ts              extract_docx_text

  utils/
    errors.ts            Typed AppError hierarchy + safe error serialization
    limits.ts            Size/row/timeout/pagination limits
    mime-types.ts         MIME → file-category classification

tests/                  Jest test suite (46 tests, 10 suites)
.env.example
.gitignore
render.yaml             Render Blueprint (optional one-click deploy)
README.md
package.json
tsconfig.json
jest.config.cjs

3. 사전 요구 사항

• Node.js 20+ 및 npm

• Google Drive API가 활성화된 Google Cloud 프로젝트

• AKIJ HR DATA Drive 폴더에 뷰어(Viewer) 액세스 권한으로 공유된 Google 서비스 계정

• GitHub 계정(저장소에서 Render로 배포하기 위함)

• Render 계정

4. 설치

npm install

5. 환경 변수

템플릿은 .env.example을 참조하세요(실제 비밀은 커밋되지 않습니다).

6. Google Cloud 설정

1. console.cloud.google.com로 이동하여 프로젝트를 선택/생성합니다.

2. APIs & Services → Library에서 Google Drive API를 활성화합니다.

3. APIs & Services → Credentials → Create Credentials → Service Account로 이동합니다.

4. 이름을 지정합니다(예: akij-hr-data-mcp). 프로젝트 수준 IAM 역할은 필요 없습니다.

5. 새 서비스 계정을 열고 → Keys → Add Key → Create new key → JSON을 선택합니다. 그러면 gcp-key.json 파일이 다운로드됩니다 — 이 파일을 커밋하지 마세요.

6. 서비스 계정의 이메일 주소를 기록해 둡니다(akij-hr-data-mcp@your-project.iam.gserviceaccount.com 형식).

7. Google Drive 권한

1. Google Drive에서 AKIJ HR DATA 폴더를 엽니다(폴더 ID 1oxYLPcC9MPVuxsbeP0kGgYhLmkxt0w2o).

2. Share를 클릭하고 서비스 계정의 이메일을 붙여넣은 후 Viewer 액세스 권한을 부여합니다.

3. 편집자/소유자 권한은 부여하지 마세요 — 이 서버는 Drive에 절대 쓰지 않으므로 Viewer면 충분하고 더 안전합니다.

8. 로컬 설정

npm install
cp .env.example .env
# fill in GOOGLE_DRIVE_FOLDER_ID, GCP_KEY_BASE64, API_KEYS in .env
npm run dev

npm run dev는 tsx watch로 TypeScript 서버를 직접 실행합니다(로컬 반복 작업에 빌드 단계가 필요 없습니다).

9. GCP_KEY_BASE64 생성

원시 서비스 계정 JSON을 채팅, 소스 코드 또는 .env.example에 붙여넣어서는 안 됩니다. 다운로드한 gcp-key.json에서 로컬로 base64 값을 생성하고 로컬 .env(gitignore됨) 또는 Render의 환경 변수 설정에만 넣으세요.

PowerShell:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\Downloads\gcp-key.json")) | Set-Clipboard

이 명령은 키 파일을 읽고 base64 문자열을 클립보드에 직접 복사합니다 — 로컬의 .env 또는 Render 대시보드(배포용)에서 GCP_KEY_BASE64 값으로 붙여넣으면 됩니다. gcp-key.json이 다운로드 폴더에 없다면 경로를 조정하세요.

클립보드 대신 터미널에 출력하려면:

[Convert]::ToBase64String([IO.File]::ReadAllBytes("$HOME\Downloads\gcp-key.json"))

10. 로컬 테스트

서버 시작:

npm run dev

상태 확인:

curl http://localhost:10000/health

curl로 initialize → tools/call 시퀀스를 사용하여 MCP 도구(예: list_files)를 호출하거나, Streamable HTTP를 지원하는 MCP 클라이언트를 X-Api-Key: <one of your API_KEYS> 헤더와 함께 http://localhost:10000/mcp로 연결하세요.

11. 빌드

npm run build

src/(TypeScript, NodeNext ESM)를 dist/로 컴파일합니다. 파일을 생성하지 않고 타입 검사만 하려면 npm run typecheck를 실행하세요.

테스트 스위트 실행:

npm test

Jest를 인밴드로 실행합니다(10개 스위트에 걸쳐 46개 테스트: config, auth, Google auth, Drive 폴더 범위 강제, 11개 전체 도구, /health//mcp HTTP 엔드포인트).

12. GitHub 설정

git init
git add .
git commit -m "Initial commit: akij-hr-data-mcp"
git branch -M main
git remote add origin https://github.com/<your-username>/akij-hr-data-mcp.git
git push -u origin main

.env, gcp-key.json, *.pem, *.key는 이미 gitignore되어 있습니다 — 커밋 전에 git status로 비밀 파일이 스테이징되지 않았는지 확인하세요.

13. Render 배포

1. render.com으로 이동 → New → Web Service.

2. GitHub 저장소(akij-hr-data-mcp)를 연결합니다.

3. Render가 render.yaml(Blueprint)을 자동으로 감지하거나, 수동으로 구성합니다:

   • Build Command: npm install && npm run build

   • Start Command: npm start

   • Health Check Path: /health

4. Render 대시보드에서 환경 변수(14절)를 추가합니다 — 절대 커밋하지 마세요.

5. 배포합니다. Render가 빌드하고 서비스를 시작하며 PC와 무관하게 계속 실행합니다.

14. Render 환경 변수

다음을 Render → your service → Environment에서 설정하세요:

PORT=10000
GOOGLE_DRIVE_FOLDER_ID=1oxYLPcC9MPVuxsbeP0kGgYhLmkxt0w2o
GCP_KEY_BASE64=<paste the base64 string from step 9>
API_KEYS=<comma-separated production keys, e.g. key-abc123,key-def456>

강력한 임의의 API 키를 생성하세요, 예:

[Convert]::ToBase64String([Guid]::NewGuid().ToByteArray()) -replace '[+/=]',''

15. 상태 엔드포인트

GET /health

{ "status": "ok", "timestamp": "2026-08-17T12:00:00.000Z" }

인증이 필요 없으며 비밀이나 내부 상태를 노출하지 않습니다.

16. MCP 엔드포인트

POST /mcp

• MCP Streamable HTTP 전송(@modelcontextprotocol/sdk StreamableHTTPServerTransport)을 구현하며 상태 비저장(sessionIdGenerator: undefined)입니다 — SSE 전용 폴백은 없습니다.

• 인증이 필요합니다: Authorization: Bearer <API_KEY> 또는 X-Api-Key: <API_KEY> 헤더.

• GET /mcp 및 DELETE /mcp는 405를 반환합니다 — 이 서버는 세션을 유지하지 않으며 선택적 SSE 스트림을 지원하지 않습니다.

17. 원격 MCP를 클라이언트에 연결

배포 후 MCP 엔드포인트는 다음과 같습니다:

https://<your-render-service>.onrender.com/mcp

원격/HTTP 서버를 지원하는 MCP 클라이언트의 경우 다음으로 서버 항목을 추가하세요:

• URL: https://<your-render-service>.onrender.com/mcp

• 전송(Transport): Streamable HTTP

• 헤더(Headers): X-Api-Key: <one of your API_KEYS> (또는 Authorization: Bearer <API_KEY>)

일반적인 클라이언트 구성 예시:

{
  "mcpServers": {
    "akij-hr-data": {
      "url": "https://<your-render-service>.onrender.com/mcp",
      "headers": {
        "X-Api-Key": "<API_KEY>"
      }
    }
  }
}

18. 보안

• 읽기 전용: 이 코드베이스에는 업로드/삭제/편집/이름 변경/이동/공유/권한 도구가 존재하지 않습니다.

• 폴더 범위 제한: GoogleDriveClient.assertFileInScope는 메타데이터나 콘텐츠가 반환되기 전에 각 파일의 parents 체인을 구성된 루트까지 탐색합니다. 트리 밖의 파일은 ForbiddenError를 발생시킵니다.

• API 키 인증: 모든 POST /mcp 요청은 타이밍 안전 비교(crypto.timingSafeEqual)로 API_KEYS와 대조됩니다. 누락되거나 잘못된 키는 401을 받습니다.

• 자격 증명은 절대 기록되거나 반환되지 않음: 디코딩된 서비스 계정 JSON은 google-auth.ts 내부에 유지됩니다. 어떤 도구, 로그 줄, 오류 메시지도 이를 표면화할 수 없습니다. 오류 응답은 스택 트레이스와 원시 업스트림 오류 본문을 제거하는 toSafeErrorMessage를 통과합니다.

• 크기/출력 제한: 다운로드가 제한되고(LIMITS.MAX_DOWNLOAD_BYTES / MAX_PARSE_BYTES), 텍스트 추출은 잘리며(MAX_TEXT_OUTPUT_CHARS), 행은 페이지네이션되고(DEFAULT_ROW_LIMIT/MAX_ROW_LIMIT), 모든 외부 Google API 호출에는 타임아웃이 있습니다(GOOGLE_API_TIMEOUT_MS).

• 확장 가능한 인증: req.identity는 작고 안정적인 형태({ keyId })로, 향후 사용자별 키, OAuth 또는 역할 기반 인증 계층이 모든 호출 지점을 변경하지 않고 더 풍부한 클레임을 첨부할 수 있도록 설계되었습니다.

• 알려진 종속성 권고: 레거시 .xls 파싱에 사용되는 xlsx(SheetJS) 패키지에는 게시된 높은 심각도 권고(프로토타입 오염 / ReDoS)가 있습니다. 이 패키지는 자신의 Drive 폴더에서 가져온 내부의 액세스 제어된 파일(임의의 인터넷 업로드가 아님)에만 사용되며, 파싱 전에 파일 크기가 제한됩니다. 정기적으로 npm audit을 실행하고 패치된 릴리스가 제공되면 교체를 고려하세요.

보안 체크리스트

• gcp-key.json이 git에 커밋되지 않음

• .env가 git에 커밋되지 않음

• API_KEYS가 Render에서 강력한 임의 값으로 설정됨(로컬 개발 값이 아님)

• 서비스 계정이 Drive 폴더에 대해 Viewer 전용 권한을 가짐

• GOOGLE_DRIVE_FOLDER_ID가 의도한 저장소 폴더와 일치함

• Render 환경 변수가 대시보드에서 직접 설정되며 render.yaml의 커밋된 값에는 절대 설정되지 않음

19. 문제 해결

남은 수동 단계 (오직 당신만 할 수 있음)

1. 다운로드한 gcp-key.json(섹션 9)에서 GCP_KEY_BASE64를 생성하고, 테스트를 위해 로컬 .env 파일에 넣으세요.

2. 서비스 계정 이메일을 Viewer로 하여 AKIJ HR DATA Drive 폴더를 공유하세요(섹션 7).

3. 로컬에서 실행하고(npm run dev), GET /health와 실제 list_files 호출이 실제 Drive 폴더에서 작동하는지 확인하세요.

4. GitHub에 푸시하세요(섹션 12).

5. Render 웹 서비스를 생성하고, 저장소를 연결한 다음, Render 대시보드에서 네 가지 환경 변수를 설정하세요(섹션 13–14) — Render가 자동으로 빌드 및 배포합니다.

6. 프로덕션 API_KEYS를 생성하고(로컬 개발 키와 다른 값으로), MCP 클라이언트를 위해 안전하게 저장하세요.

7. https://<your-render-service>.onrender.com/mcp에 MCP 클라이언트를 연결하세요(섹션 17).