Metadata-Version: 2.4
Name: chattermate-sdk
Version: 0.1.0
Summary: ChatterMate CLI and MCP server — sign up, authenticate, and configure agents, workflows and knowledge from the terminal or an AI agent.
Author: ChatterMate
License: AGPL-3.0-or-later
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: mcp>=1.2
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: respx>=0.21; extra == "test"
Dynamic: license-file

# ChatterMate CLI & MCP server

`chattermate-sdk` provides a command-line client and an MCP (Model Context Protocol)
server for ChatterMate. A human can sign up, log in and configure agents, workflows and
knowledge from the terminal; an AI agent can do the same through the MCP server.

This is an **enterprise** feature and depends on the enterprise backend's Personal Access
Tokens (PATs).

## Install

```bash
pip install -e .            # from this directory, for development
# or, once published:
pipx install chattermate-sdk
```

Console scripts installed: `chattermate` (alias `cmate`) and `chattermate-mcp`.

## Configure the API endpoint

By default the CLI talks to the hosted API at `https://api.chattermate.chat`. To target a
local or self-hosted backend, set `CHATTERMATE_API_URL=http://localhost:8000` (or pass
`--api-url`). Resolution order: `--api-url` flag → `CHATTERMATE_API_URL` env → stored config →
`https://api.chattermate.chat`.

## Quick start (human)

```bash
# Create an organization + admin (community signup), or log in to an existing one
chattermate signup
chattermate login --email you@acme.com

chattermate whoami

# Mint a long-lived Personal Access Token for CI / AI agents (shown once!)
chattermate token create laptop-cli
chattermate token list
chattermate token revoke <token-id>

# Configure resources
chattermate agent list
chattermate agent create --name "Support" --type CUSTOMER_SUPPORT -i "Be concise"
chattermate workflow get <agent-id>
chattermate workflow create --agent-id <agent-id> --name "Onboarding"
chattermate knowledge add-url --website https://docs.acme.com --agent-id <agent-id>
chattermate knowledge status <queue-id>
```

Every command accepts `--json` for machine-readable output.

## Authentication

Two credentials are supported:

- **Personal Access Token** (`cmat_...`) — preferred for non-interactive use. Pass it via
  the `CHATTERMATE_TOKEN` environment variable. Long-lived and revocable.
- **JWT login** — `chattermate login` stores access + refresh tokens in
  `~/.chattermate/config.json` (mode `600`) and refreshes automatically.

## MCP server (AI agents)

`chattermate-mcp` is a stdio MCP server. Point your MCP client at it with a PAT:

```json
{
  "mcpServers": {
    "chattermate": {
      "command": "uvx",
      "args": ["--from", "chattermate-sdk", "chattermate-mcp"],
      "env": {
        "CHATTERMATE_TOKEN": "cmat_...",
        "CHATTERMATE_API_URL": "https://your-chattermate-host"
      }
    }
  }
}
```

`chattermate token create` prints a ready-to-paste version of this snippet.

### Tools

Read-only: `whoami`, `list_agents`, `get_agent`, `get_workflow`, `get_workflow_nodes`,
`list_knowledge`, `get_ingestion_status`.

Mutating: `create_agent`, `update_agent`, `create_workflow`, `update_workflow`,
`update_workflow_nodes`, `add_knowledge_url`, `link_knowledge`, `unlink_knowledge`.

## Tests

```bash
pip install -e ".[test]"
pytest tests/
```
