# Work Journal MCP Server

A hosted MCP server that lets any member of the team read their Simplified HR Work Journal through Claude — their own entries always, and colleagues' entries where their existing Work Journal permissions already allow.

Read-only. No tool here can create, change, or delete an entry.

## Connecting, from any Claude client

One flow, whichever client you use: add the server by URL, then sign in in the browser window that opens.

**Claude Desktop or claude.ai** — Settings → Connectors → Add custom connector →

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

**Claude Code**

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

Either way a browser window opens. Sign in with your Simplified HR email and password. On dev you also enter your workspace, for example `development-hr.dev.besimplified.net`.

If this is a device the accounts service has not seen before, you are sent a verification code by email or SMS. Enter it once; you will not be asked again from the same client.

Your password never reaches Claude, and this server never stores it.

### Signing in at the accounts service instead

`WJ_LOGIN_MODE=redirect` replaces the form above. `/authorize` sends the browser to the accounts sign-in page for the environment, the member signs in there, and the accounts service returns them to `/identifier` with a short-lived handoff token that this server exchanges for the session. Two things follow: no password is typed into a page this server renders, and the member is signed in to the BeSimplified web apps at the same time, because the session is the one the accounts service minted on its own origin.

It is off by default because it has prerequisites the form mode does not:

- **An `app_registrations` record in the accounts service** naming this server's host, as a verified `fqdn` or as a `workspace`, on every organisation whose members use it. The sign-in page takes the host out of the `referrer` it is given and looks it up; with no record it answers `valid_workspace: false` and returns the browser to the HR app rather than here. This is a record in the accounts service's own database — no code there changes.
- **`WJ_PUBLIC_BASE_URL` as https with no port.** The accounts service rebuilds the callback as `https://<host>/identifier` from the hostname alone, so a port or a plaintext scheme cannot receive it. The server refuses to start otherwise, rather than serving a login that can begin and never finish.
- **Read access to the accounts session store**, `WJ_REDIS_HOST` and `WJ_ACC_CACHE_PREFIX`. The handoff token names a key there; without it there is nothing to exchange the token for.

The callback host is checked against an allowlist in both modes. It matters more here: once the member authenticates at the accounts service, whoever named `redirect_uri` receives the authorization code, and PKCE does not help against an attacker who started the flow.

## Tools

### `work_journal_get_entries`

Entries with full task detail for a date or a range of up to 31 days.

| parameter | notes |
|---|---|
| `date` | single day, `YYYY-MM-DD` |
| `start_date`, `end_date` | inclusive range, used instead of `date` |
| `type` | optional, see the alias table below; omit for all types |
| `member` | optional, another member's id from `work_journal_find_member` |
| `include_tasks` | optional, default `true`; `false` returns statuses only, in a single request |

Ask: *"show my EOD entries for last week"*

### `work_journal_get_day`

One date in full: every task with notes and attachments, notified recipients, ETA, and submission time.

| parameter | notes |
|---|---|
| `date` | required, `YYYY-MM-DD` |
| `type` | optional, narrows to one entry type |
| `member` | optional, another member's id |

Ask: *"what did I log on 4 August?"*

### `work_journal_get_summary`

Counts by type and status over any period, with no per-day detail. Use this for anything longer than 31 days.

| parameter | notes |
|---|---|
| `start_date`, `end_date` | inclusive range |
| `year` | whole calendar year, used when no explicit range is given |
| `type` | optional |
| `member` | optional, another member's id |

Ask: *"how many EOW reports did I miss this year?"*

### `work_journal_find_member`

Finds a colleague by part of their name or email and returns their member id, for use as `member` on the tools above.

| parameter | notes |
|---|---|
| `query` | part of a name or email, at least two characters |

Ask: *"find Rahul's member id"*

### `work_journal_get_team_report`

One row per member with submitted, pending, and missed counts for a period.

| parameter | notes |
|---|---|
| `start_date`, `end_date` | required, inclusive range |
| `type` | optional, defaults to EOD |
| `team` | optional team id, or the literal `unassigned` |
| `status` | optional: `submitted`, `pending`, or `missed` |
| `member` | optional, narrows to one member |
| `limit`, `page` | optional; default 15 rows, maximum 50 |

Ask: *"who missed their EOD last week?"*

## Type aliases

| you can say | resolves to | shown as |
|---|---|---|
| `eod`, `daily`, `end of day` | `daily` | `EOD` |
| `eow`, `weekly`, `end of week` | `weekly` | `EOW` |
| `group eow`, `group weekly` | `group_weekly` | `Group EOW` |
| `eom`, `monthly`, `end of month` | `monthly` | `EOM` |

Matching ignores case and treats spaces, hyphens, and underscores as equivalent.

## Who can see whose journal

This server enforces no permissions of its own. Every request carries your own Simplified HR session, and the Work Journal API applies exactly the permissions it applies in the web UI:

- **Instance permission** — you can read any member of your company
- **Group permission** — you can read members in your reporting subtree
- **Neither** — you can read only your own journal, and any attempt at another member's is refused

Two things to know when reading a colleague's entries: the request can be refused outright, and an admin view excludes drafts, scheduled, and private entries. An absent entry therefore does not prove nothing was logged.

## Limits

- `work_journal_get_entries` rejects ranges longer than 31 days and points you at `work_journal_get_summary`
- At most 4 requests run concurrently per tool call, so a wide range stays gentle on the API
- Relative dates such as "last week" are resolved by Claude before the call; the tools accept `YYYY-MM-DD` only

## Running it locally

```bash
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` should answer `{"status":"ok"}`. Running `node src/index.js` with no environment must exit immediately, listing every missing variable.

### Environment

| variable | required | purpose |
|---|---|---|
| `WJ_ENV` | yes | selects the host preset: `dev` or `prod`. There is no default, so an empty value cannot silently point production at the dev hosts |
| `WJ_PUBLIC_BASE_URL` | yes | externally reachable origin, published in the OAuth discovery documents |
| `WJ_TOKEN_KEY` | yes | 64 hex characters; encrypts the session envelope |
| `WJ_FINGERPRINT_SECRET` | yes | at least 32 characters; derives each member's device fingerprint |
| `WJ_API_BASE_URL` | no | plugin API host, when it differs from the preset for `WJ_ENV` |
| `WJ_AUTH_BASE_URL` | no | accounts service origin, when it differs from the preset |
| `WJ_PORT` | no, defaults to `8080` | listen port |
| `WJ_REQUEST_TIMEOUT_MS` | no, defaults to `15000` | per-request timeout |
| `WJ_EXTRA_REDIRECT_HOSTS` | no | extra callback hosts, comma separated, beyond `claude.ai`, `anthropic.com` and loopback |
| `WJ_LOGIN_MODE` | no, defaults to `form` | `form` or `redirect`; see below |
| `WJ_REDIS_HOST` | only when `WJ_LOGIN_MODE=redirect` | the accounts session store |
| `WJ_REDIS_PORT` | no, defaults to `6379` | |
| `WJ_REDIS_TLS` | no | `true` to connect over TLS, with the certificate verified |
| `WJ_REDIS_TLS_SERVERNAME` | no | the name the Redis certificate was issued for, when it differs from the host dialled |
| `WJ_REDIS_TLS_INSECURE` | no | `true` drops certificate verification; last resort only |
| `WJ_ACC_CACHE_PREFIX` | only when `WJ_LOGIN_MODE=redirect` | the accounts service's own `CACHE_PREFIX`, which it also returns as `sso_prefix` |

**`WJ_FINGERPRINT_SECRET` must be identical across every task, and must not be rotated casually.** It derives each member's stable device fingerprint; changing it re-challenges the whole team with a verification code.

## Deployment notes

- Cookie stickiness on `/authorize` is a `WJ_LOGIN_MODE=form` requirement only. In `redirect` mode nothing is held in process memory between the two legs — the authorization request rides back from the accounts service in an encrypted `redirect_page` token — so `/authorize` and `/identifier` are both stateless and need no stickiness.
- Cookie stickiness is required on `/authorize` only. An OTP submission must reach the task that began the login, because the in-progress login is held in that process's memory for five minutes. `/mcp` and `/token` are stateless and must not be sticky.
- Both secrets belong in SSM Parameter Store as `SecureString`, referenced from the task definition's `secrets` block — never as environment literals. Create them once per environment before the first deploy; nothing else in the platform uses the `/hr/work-journal-mcp/` prefix, so they will not already exist:

  ```bash
  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` needs `ssm:GetParameters` and `kms:Decrypt` on both, or the task fails at start with `ResourceInitializationError`, before any of this code runs.
- Production rejects the `workspace` login field that dev requires, so the login page hides it outside dev.

## Security

- Passwords are never stored, never logged, and never returned to the browser in any form. They exist only in memory, for the seconds a login takes.
- Session state travels in an AES-256-GCM encrypted envelope that only this server can open. The Simplified HR JWT never reaches Claude or the model.
- Access, refresh, and authorization-code envelopes are cryptographically bound to their kind, so one cannot be spent as another.
- Login attempts are rate limited per email address.
- Every tool call is logged with the caller, the tool, and the member whose journal was read, so cross-member reads are auditable. Tokens and entry content are never logged.

## Tests

```bash
npm test
```