Metadata-Version: 2.4
Name: majordomo
Version: 0.1.4
Summary: Read and report Google Chat task activity from the cache mirror.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13
Requires-Dist: pymysql>=1.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == "mcp"
Provides-Extra: nocache
Requires-Dist: google-api-python-client>=2; extra == "nocache"
Requires-Dist: google-auth-oauthlib>=1; extra == "nocache"
Requires-Dist: google-auth>=2; extra == "nocache"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# majordomo

A command-line tool that reads Google Chat and reports task activity. The command line is the primary interface; an MCP server is a secondary interface for AI agents. Both are thin front doors over one shared core.

## What it does

When someone creates a task through Google Chat's "Create a task for @Person (via Tasks)", that task cannot be retrieved through the Google Tasks API; the only durable signal is the chat message itself (see [GOOGLE_CHAT_TASKS_LIMITATIONS.md](GOOGLE_CHAT_TASKS_LIMITATIONS.md)). majordomo reconstructs task activity from those messages and reports who holds which tasks across spaces over a date range.

- **Tasks** by assignee, space, and date; "assigned to me" and "assigned by me".
- **Spaces**, **people** (participants with message and task counts), and raw **messages** by space or thread.
- **Three modes, one shape.** The fast path reads an existing server-side cache of Chat (the [data model](DATA-MODEL.md)). `--live` is up-to-dateness: it serves the cache and tops it up from the Chat API with anything newer. `--nocache` reads the Chat API directly and decodes tasks itself, so the tool also works without the cache. Every result is tagged with its source; an unforced read uses the cache and falls back to the direct API automatically when the cache is unreachable.
- **A privacy sieve** in the core drops blocked spaces (and assignees) before any caller (CLI or MCP) can see them.
- **Output** as a rich console table, `--json`, or `--csv`.

## Install

The simplest cross-platform install is from PyPI:

```bash
pip install majordomo                  # CLI, reads the Chat cache
pip install "majordomo[nocache,mcp]"   # plus the live Chat API path and the MCP server
```

With uv, `uvx majordomo ...` runs it without installing and `uv tool install majordomo` installs it permanently.

Homebrew (macOS or Linux):

```bash
brew tap overseers-desk/od
brew install majordomo
```

Python 3.11+.

**Run directly, no virtualenv, with Ubuntu/Debian packages:**

```bash
sudo apt-get install python3-typer python3-rich python3-pymysql
# for the API path (majordomo login, --live top-up, --nocache) also:
sudo apt-get install python3-googleapi python3-google-auth python3-google-auth-oauthlib
```

Then run from the repo without installing the package:

```bash
PYTHONPATH=src python3 -m majordomo spaces
```

**Or install the package** (puts `majordomo` on your PATH):

```bash
python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[nocache,mcp]"   # drop the extras you don't need
majordomo --help
```

The MCP server (`majordomo mcp`) needs the `mcp` PyPI package, which is not in apt; install it through the virtualenv above (the `mcp` extra).

## Configuration

majordomo reads two files from `~/.config/majordomo/`:

`config.toml` (hand-edited):

```toml
[me]
user_id = "users/1234567890"      # your Chat id, for --to-me / --by-me
                                   # (find it with `majordomo people`)

[sieve]
block_spaces = ["spaces/AAAA"]     # never shown through any front door
block_assignees = ["users/9999"]   # drop these assignees from every report

[nocache]                          # optional; defaults shown (OAuth for the API path)
token_file = "~/.config/majordomo/token.json"
client_file = "~/.config/majordomo/client_secret.json"
```

`.env` (the cache database connection, when using the cache path):

```
MYSQL_HOST=…
MYSQL_PORT=3306
MYSQL_USER=…
MYSQL_PASSWORD=…
MYSQL_DATABASE=…
```

## Authenticating (OAuth for the API path)

`majordomo login` opens a browser OAuth flow and writes `~/.config/majordomo/token.json` (read-only Chat scopes), used by `--live` (for the top-up) and `--nocache`. It needs a Desktop OAuth client with the Google Chat API enabled, saved as `client_secret.json` in the config directory.

```bash
majordomo login
```

## Commands

```bash
majordomo spaces
majordomo people --window year
majordomo tasks --to-me --window month
majordomo tasks --assignee-name '*Alice*' --since 2026-01-01
majordomo messages --space spaces/AAAA --window 7d
majordomo messages --thread spaces/AAAA/messages/BBBB
majordomo mcp                       # run the MCP server (stdio)
```

- Source: default cache with an automatic direct-API fallback. `--cache` forces the cache; `--live` adds a freshness top-up from the API; `--nocache` reads the API directly.
- Window: `7d | 30d | month | year | all`, or `--since` / `--until` (ISO dates).
- Output: default console, `--json`, or `--csv`.

## Not yet (deferred)

- **Task completion and stats.** Google Chat does not reliably carry task completion, so every task is reported as `open`; completion-rate reporting waits on a later signal.
- **Directory name resolution.** Names come from the chat message and the Chat API directly; a bare `users/<id>` with no name attached is shown as the id.

## License

See [LICENSE](LICENSE).
