Work Journal MCP 서버

팀의 모든 구성원이 Simplified HR Work Journal을 Claude를 통해 읽을 수 있게 해주는 호스팅형 MCP 서버입니다. 본인의 항목은 항상, 동료의 항목은 기존 Work Journal 권한이 허용하는 범위 내에서 읽을 수 있습니다.

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

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

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

Claude Desktop 또는 claude.ai — 설정 → 커넥터 → 사용자 지정 커넥터 추가 →

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 이메일과 비밀번호로 로그인하세요. 개발 환경에서는 워크스페이스도 입력해야 합니다(예: development-hr.dev.besimplified.net).

계정 서비스가 이전에 본 적 없는 기기라면 이메일 또는 SMS로 인증 코드를 받게 됩니다. 한 번만 입력하면 되며, 같은 클라이언트에서는 다시 요청하지 않습니다.

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

대신 계정 서비스에서 로그인하기

WJ_LOGIN_MODE=redirect는 위의 양식을 대체합니다. /authorize는 브라우저를 해당 환경의 계정 로그인 페이지로 보내고, 멤버가 거기서 로그인하면 계정 서비스는 멤버를 /identifier로 돌려보내며 단기 핸드오프 토큰을 제공합니다. 이 서버는 그 토큰을 세션으로 교환합니다. 두 가지 결과가 따릅니다. 이 서버가 렌더링하는 페이지에 비밀번호를 입력하지 않으며, 세션이 계정 서비스가 자체 오리진에서 발급한 것이므로 멤버는 동시에 BeSimplified 웹 앱에도 로그인됩니다.

양식 모드에는 없는 전제 조건이 있기 때문에 기본적으로 꺼져 있습니다.

• 계정 서비스의 app_registrations 레코드 — 이 서버의 호스트를 검증된 fqdn 또는 workspace로 명명하며, 해당 서버를 사용하는 모든 조직에 있어야 합니다. 로그인 페이지는 전달받은 referrer에서 호스트를 추출하여 조회합니다. 레코드가 없으면 valid_workspace: false로 응답하고 브라우저를 여기 대신 HR 앱으로 돌려보냅니다. 이는 계정 서비스 자체 데이터베이스의 레코드입니다. 코드 변경은 없습니다.

• WJ_PUBLIC_BASE_URL은 포트 없는 https여야 합니다. 계정 서비스는 호스트 이름만으로 콜백을 https://<host>/identifier로 재구성하므로 포트나 평문 스킴은 이를 받을 수 없습니다. 그렇지 않으면 서버는 시작을 거부하며, 시작은 되지만 끝나지 않는 로그인을 제공하지 않습니다.

• 계정 세션 저장소에 대한 읽기 액세스, WJ_REDIS_HOST 및 WJ_ACC_CACHE_PREFIX. 핸드오프 토큰은 그곳의 키를 가리키며, 그것 없이는 토큰을 교환할 대상이 없습니다.

콜백 호스트는 두 모드 모두에서 허용 목록으로 검사됩니다. 여기서는 더 중요합니다. 멤버가 계정 서비스에서 인증하면 redirect_uri를 지정한 사람이 인증 코드를 받게 되며, PKCE는 흐름을 시작한 공격자에게는 도움이 되지 않습니다.

Related MCP server: zulip-mcp

도구

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의 멤버 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은 모든 작업에서 동일해야 하며, 가볍게 교체해서는 안 됩니다. 각 멤버의 안정적인 기기 지문을 파생하며, 변경하면 팀 전체가 인증 코드로 다시 인증을 받게 됩니다.

배포 참고 사항

• /authorize의 쿠키 고정(stickiness)은 WJ_LOGIN_MODE=form 요구 사항에서만 필요합니다. redirect 모드에서는 두 단계 사이에 프로세스 메모리에 아무것도 보관되지 않습니다. 인증 요청은 암호화된 redirect_page 토큰에 담겨 계정 서비스에서 다시 전달되므로 /authorize와 /identifier는 모두 무상태(stateless)이며 고정이 필요 없습니다.

• 쿠키 고정은 /authorize에서만 필요합니다. OTP 제출은 로그인을 시작한 태스크에 도달해야 합니다. 진행 중인 로그인이 해당 프로세스의 메모리에 5분간 보관되기 때문입니다. /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 암호화 봉투(envelope)로 전달됩니다. Simplified HR JWT는 Claude나 모델에 도달하지 않습니다.

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

• 로그인 시도는 이메일 주소별로 비율 제한(rate limit)이 적용됩니다.

• 모든 도구 호출은 호출자, 도구, 저널을 읽은 멤버와 함께 로깅되어, 멤버 간 읽기가 감사 가능합니다. 토큰과 항목 내용은 절대 로그에 기록되지 않습니다.

테스트

npm test