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.

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

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