Work Journal MCP Server

호스팅형 MCP 서버로, 팀 구성원이면 누구나 Simplified HR Work Journal을 Claude를 통해 읽을 수 있습니다 — 항상 자신의 항목을, 그리고 기존 Work Journal 권한이 허용하는 경우 동료의 항목도 읽을 수 있습니다.

읽기 전용입니다. 이 도구 중 어떤 것도 항목을 생성, 변경 또는 삭제할 수 없습니다.

연결: 모든 Claude 클라이언트에서

어떤 클라이언트를 사용하든 흐름은 하나입니다. URL로 서버를 추가한 다음 열리는 브라우저 창에서 로그인하면 됩니다.

Claude Desktop 또는 claude.ai — Settings → Connectors → Add custom connector →

https://wj-mcp.dev.besimplified.net/mcp

Claude Code

claude mcp add work-journal --transport http https://wj-mcp.dev.besimplified.net/mcp

어느 쪽이든 브라우저 창이 열립니다. Simplified HR 이메일과 비밀번호로 로그인하세요. dev 환경에서는 작업 공간도 입력합니다(예: development-hr.dev.besimplified.net).

계정 서비스가 처음 보는 기기라면 이메일이나 SMS로 인증 코드가 전송됩니다. 한 번 입력하면 같은 클라이언트에서는 다시 요청하지 않습니다.

비밀번호는 Claude에 도달하지 않으며, 이 서버에도 저장되지 않습니다.

도구

work_journal_get_entries

특정 날짜 또는 최대 31일 범위의 항목을 전체 작업 세부 정보와 함께 반환합니다.

요청 예: "지난주 EOD 항목을 보여줘"

work_journal_get_day

하루 전체: 메모와 첨부 파일이 포함된 모든 작업, 알림 받은 사람, ETA, 제출 시간.

요청 예: "8월 4일에 기록한 내용은 뭐야?"

work_journal_get_summary

특정 기간 동안 유형 및 상태별 개수를 일별 세부 정보 없이 반환합니다. 31일보다 긴 기간에는 이것을 사용하세요.

요청 예: "올해 EOW 보고서를 몇 번 놓쳤지?"

work_journal_find_member

이름이나 이메일의 일부로 동료를 찾아 해당 멤버 id를 반환합니다. 위 도구에서 member로 사용합니다.

요청 예: "Rahul의 member id를 찾아줘"

work_journal_get_team_report

기간 동안 제출됨, 보류 중, 놓침 개수를 멤버당 한 행으로 반환합니다.

요청 예: "지난주 EOD를 놓친 사람은 누구?"

유형 별칭

일치 검색은 대소문자를 무시하고 공백, 하이픈, 밑줄을 동일하게 취급합니다.

누가 누구의 저널을 볼 수 있나

이 서버는 자체 권한을 적용하지 않습니다. 모든 요청은 사용자 자신의 Simplified HR 세션을 포함하며, Work Journal API는 웹 UI에서 적용하는 것과 정확히 동일한 권한을 적용합니다.

• 인스턴스 권한 — 회사의 모든 구성원을 읽을 수 있습니다.

• 그룹 권한 — 보고 체계 하위의 구성원을 읽을 수 있습니다.

• 둘 다 없음 — 자신의 저널만 읽을 수 있으며, 다른 구성원의 저널에 대한 모든 시도는 거부됩니다.

동료의 항목을 읽을 때 알아야 할 두 가지: 요청이 완전히 거부될 수 있고, 관리자 보기에는 임시 저장, 예약, 비공개 항목이 제외됩니다. 따라서 항목이 없다고 해서 아무것도 기록되지 않았다는 뜻은 아닙니다.

제한

• work_journal_get_entries는 31일보다 긴 범위를 거부하며 work_journal_get_summary를 사용하도록 안내합니다.

• 도구 호출당 최대 4개의 요청이 동시에 실행되므로 넓은 범위도 API에 부담을 주지 않습니다.

• "지난주"와 같은 상대 날짜는 호출 전에 Claude가 확인합니다. 도구는 YYYY-MM-DD만 허용합니다.

로컬에서 실행

npm install
cp .env.example .env      # then fill in the two secrets
WJ_ENV=dev \
WJ_PUBLIC_BASE_URL=http://localhost:8080 \
WJ_TOKEN_KEY=$(openssl rand -hex 32) \
WJ_FINGERPRINT_SECRET=$(openssl rand -hex 32) \
npm start

GET /healthz는 {"status":"ok"}로 응답해야 합니다. 환경 변수 없이 node src/index.js를 실행하면 누락된 모든 변수를 나열하고 즉시 종료되어야 합니다.

환경 변수

WJ_FINGERPRINT_SECRET은 모든 태스크에서 동일해야 하며, 가볍게 교체해서는 안 됩니다. 각 구성원의 안정적인 기기 지문을 유도합니다. 변경하면 전체 팀이 인증 코드를 다시 요구받습니다.

배포 참고 사항

• 쿠키 고정(stickiness)은 /authorize에서만 필요합니다. 진행 중인 로그인이 해당 프로세스 메모리에 5분간 보관되므로 OTP 제출은 로그인을 시작한 태스크에 도달해야 합니다. /mcp와 /token은 상태가 없으며 고정되지 않아야 합니다.

• 두 비밀 모두 SSM Parameter Store에 SecureString으로 저장해야 하며, 태스크 정의의 secrets 블록에서 참조해야 합니다 — 절대 환경 리터럴로 사용하지 마세요. 첫 배포 전에 환경당 한 번 생성하세요. 플랫폼의 다른 어떤 것도 /hr/work-journal-mcp/ 접두어를 사용하지 않으므로 이미 존재하지 않을 것입니다:

  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/token_key           --value "$(openssl rand -hex 32)"
  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/fingerprint_secret  --value "$(openssl rand -hex 32)"

  ecsTaskExecutionRole에는 두 항목에 대한 ssm:GetParameters와 kms:Decrypt 권한이 필요합니다. 그렇지 않으면 이 코드가 실행되기 전에 태스크가 시작 시 ResourceInitializationError로 실패합니다.

• 프로덕션은 dev에서 요구하는 workspace 로그인 필드를 거부하므로 로그인 페이지는 dev 외부에서 이를 숨깁니다.

보안

• 비밀번호는 절대 저장되지 않으며, 절대 로그에 남지 않고, 어떤 형태로든 브라우저에 반환되지 않습니다. 로그인이 진행되는 몇 초 동안 메모리에만 존재합니다.

• 세션 상태는 이 서버만 열 수 있는 AES-256-GCM 암호화 봉투로 전달됩니다. Simplified HR JWT는 Claude나 모델에 도달하지 않습니다.

• 액세스, 리프레시, 인증 코드 봉투는 각각의 종류에 암호화 방식으로 바인딩되므로 하나를 다른 것으로 사용할 수 없습니다.

• 로그인 시도는 이메일 주소별로 비율 제한됩니다.

• 모든 도구 호출은 호출자, 도구, 저널이 읽힌 멤버와 함께 기록되므로 멤버 간 읽기를 감사할 수 있습니다. 토큰과 항목 내용은 절대 기록되지 않습니다.

테스트

npm test