# Member Directory

Independent deterministic MCP server for encrypted member profiles, nicknames,
solar/lunar birthdays, voice parts, and explicitly published responsible-person
contacts. It does not use an Agent, model, shell, network lookup, or arbitrary SQL.

Sensitive fields are encrypted with AES-GCM. Exact indexes for names, QQ IDs,
principal IDs, and nicknames use keyed HMAC digests. Database files, encryption
keys, service tokens, and backups are local secrets and must never be committed.

## Trust boundary

This server authenticates its host connection, but the integrating host must
perform role and conversation authorization. It also relies on the host to inject
trusted `invocationPrincipal` and, where required, `invocationContext` values.
These fields must never be accepted from a model or end user.

The six tools are:

- `member_get_self`
- `member_get_other`
- `member_get_responsible`
- `member_update_self`
- `member_update_other`
- `member_birthdays_between`

The validated IMBot policy limits these tools by role and conversation scope. An
Agent integrating this repository must reproduce those deterministic checks and
the Tool Gateway's trusted-context injection before enabling the service.

## Install and run

Python 3.11 or newer is required.

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
BOT_MEMBER_DIRECTORY_TOKEN=replace-me .venv/bin/bot-member-directory
```

Configuration:

- `BOT_MEMBER_DIRECTORY_TOKEN` (required)
- `BOT_MEMBER_DIRECTORY_URL` (default `http://127.0.0.1:3122/mcp`)
- `BOT_MEMBER_DIRECTORY_DB` (default `.data/member-directory.db`)
- `BOT_MEMBER_DIRECTORY_KEY_FILE` (default `.data/member-directory.key`)
- `BOT_AUTH_ISSUER_URL` (default `http://localhost/internal-auth`)
- `MEMBER_DIRECTORY_HOST` and `MEMBER_DIRECTORY_PORT`

Keep the database and its key together when backing up or restoring. Losing the
key makes existing encrypted rows unrecoverable; exposing it compromises the
database contents.

## Data behavior

Records keep separate mixed-choir and male-choir voice parts and membership
states. Birthday queries are limited to one calendar year, include only enabled
reminders, convert lunar occurrences to actual Gregorian dates, preserve leap
lunar months, and map a February 29 solar birthday to February 28 in non-leap
years.

Outer-Agent privacy and reply guidance is in
`skills/member-directory/SKILL.md`; component metadata is in `addon.toml`.

## Test

```bash
.venv/bin/python -m unittest discover -s tests
```