Metadata-Version: 2.4
Name: dataz-client
Version: 0.2.2
Summary: CLI and MCP client for hosted dataz.md Discord and Telegram accounts
Author: Dataz LLC
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://dataz.md
Project-URL: Documentation, https://dataz.md/mcp
Project-URL: Portal, https://dataz.md/portal
Project-URL: Repository, https://github.com/jsindy/dataz.md
Project-URL: Issues, https://github.com/jsindy/dataz.md/issues
Keywords: dataz,discord,telegram,mcp,cli
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp<2,>=1.27
Dynamic: license-file

# dataz-client

`dataz-client` is the read-only CLI and local MCP stdio bridge for hosted
dataz.md Discord and Telegram accounts.

## Install and connect

Install the isolated command-line package:

```sh
pipx install dataz-client
# alternative: uv tool install dataz-client
```

Complete this installation step before using any of the CLI or MCP client
options below.

In the dataz.md portal, open an active account and choose **Connect CLI/MCP**,
or copy its HTTPS endpoint. Then add a protected local profile:

```sh
dataz account add work-discord \
  --url https://YOUR_ACCOUNT_ENDPOINT
```

The command infers the provider, securely prompts for the one-time-visible
`DATAZ_API_KEY`, calls the provider's status operation, and saves only after
verification succeeds. For a noncanonical endpoint, add `--provider discord`
or `--provider telegram`.

Verify and use the account:

```sh
dataz --profile work-discord status
dataz account test work-discord
dataz --profile work-discord doctor --json
```

## Install into an MCP client

One command creates a user-level entry. The MCP client receives the absolute
`dataz-mcp` path and profile name, never the endpoint or API key:

```sh
dataz mcp install codex --profile work-discord
```

For the Codex surfaces, choose the matching entry in the portal: **Codex CLI**
or **ChatGPT/Codex App**. Both use the command above. After running it for the
app, fully quit and reopen ChatGPT/Codex so it reloads the MCP configuration.

Supported clients:

```sh
dataz mcp install claude-code --profile work-discord
dataz mcp install claude-desktop --profile work-discord
dataz mcp install cursor --profile work-discord
dataz mcp install vscode --profile work-discord
```

The default server name is `dataz-PROFILE`. Use `--name NAME` to choose another
name. Repeating an identical installation is a no-op; a conflicting existing
entry requires `--replace`. Codex uses `~/.codex/config.toml`, Claude Code uses
user scope in `~/.claude.json`, Cursor uses `~/.cursor/mcp.json`, and the
desktop installers always target user-level configuration.

## Multiple accounts

Create one profile per account. Two Telegram and two Discord accounts become
four isolated profiles and four independently named MCP servers:

```sh
dataz account add telegram-personal --url https://.../telegram
dataz account add telegram-team --url https://.../telegram-2
dataz account add discord-primary --url https://.../discord
dataz account add discord-community --url https://.../discord-2

dataz mcp install codex --profile telegram-personal
dataz mcp install codex --profile telegram-team
dataz mcp install codex --profile discord-primary
dataz mcp install codex --profile discord-community
```

Each MCP process resolves exactly one profile and exposes only that provider's
tools. Keys and endpoints cannot cross between accounts.

## Safe message discovery

For broad Discord message discovery, use `discord_search_messages`. Unscoped
searches process four guilds per API page and return an opaque cursor. The MCP
client follows up to five pages within its time budget, merges results, and
returns a remaining cursor when more guilds are available. Do not fan out
`discord_logs`, DM-message, forum-message, or other history tools with
`Promise.all` or an equivalent parallel batch.

Search responses distinguish incomplete coverage (`partial`) from a result cap
(`truncated`). When `truncated` is true, `truncated_guilds` identifies guilds
known to have more matching messages than the per-guild limit.

`telegram_search_messages` searches every accessible chat in one request when
`chat_id` is omitted. Page a chat-scoped search with `before` and a cross-chat
search with `before_date`; the response reports which one to send back in
`cursor_field`, and `scope` reports whether the run covered one chat or all of
them. `before_date` has one-second resolution, so de-duplicate page boundaries
on `chat_id` and `id`.

Filtering by `author_id` or `author_username` requires `chat_id`. Telegram's
cross-chat search has no sender field, so an author filter without a chat is
rejected with `422` rather than silently returning unfiltered results.

Do not fan out `discord_logs`, `telegram_messages`, DM-message, forum-message,
or other history tools with `Promise.all` or an equivalent parallel batch. If
individual history reads are required, run no more than four concurrently and
paginate.

On `429` or `503`, honor `Retry-After` and never retry in parallel. The CLI
prints the stable error code, request ID, and retry delay when the gateway
returns them.

## Profile security

Profiles are stored in a platform-native `profiles.json`:

- macOS: `~/Library/Application Support/Dataz/profiles.json`
- Linux: `${XDG_CONFIG_HOME:-~/.config}/dataz/profiles.json`
- Windows: `%APPDATA%\Dataz\profiles.json`

The client writes atomically. POSIX files must be owned by the current user and
have mode `0600`; insecure files are refused. On Windows, inherited access is
removed and the ACL is restricted to the current user. The profile store is
plaintext protected by filesystem permissions, not an OS keychain.

If permissions were changed outside the CLI, repair them before retrying:

```sh
chmod 600 "/path/to/profiles.json"
```

```bat
icacls "%APPDATA%\Dataz\profiles.json" /inheritance:r /grant:r "%USERNAME%:(F)"
```

Never commit this file, paste a key into a command argument, or place a
plaintext key in shell history, logs, screenshots, issues, or MCP client
configuration. Rotate exposed keys under **Portal → API keys**.

## Servers, containers, and CI

Environment configuration remains supported where a profile file is not
appropriate:

```text
DATAZ_API_URL=https://YOUR_ACCOUNT_ENDPOINT
DATAZ_API_KEY=dz_live_...
```

`DATAZ_PROVIDER` is optional for canonical endpoints ending in `discord`,
`discord-N`, `telegram`, or `telegram-N`; otherwise set it explicitly. Do not
mix `DATAZ_PROFILE` or `--profile` with direct hosted variables.

Safe diagnostics:

```sh
dataz doctor --json
dataz-mcp --check --json
```

Exit `0` means healthy, `1` means a network/auth/remote failure, and `2` means
local configuration is invalid. Reports use stable codes and never include the
key or remote account payload.

## Local contributor compatibility

When no profile or hosted variables are present, the commands preserve the
legacy contributor defaults:

- `DATAZ_DISCORD_URL` defaults to `http://localhost:8000`.
- `DATAZ_TELEGRAM_URL` defaults to `http://localhost:8001`.
- provider-specific legacy keys remain supported.

Local mode prints a warning so a hosted user can immediately recognize missing
configuration.

- Documentation: https://dataz.md/mcp
- Portal: https://dataz.md/portal
- Terms: https://dataz.md/terms
