Metadata-Version: 2.5
Name: tasqr-mcp
Version: 0.1.0
Summary: Tasqr MCP server — task state management for AI agents
Project-URL: Homepage, https://tasqr.ai
Project-URL: Repository, https://github.com/tasqrai/tasqr-mcp-python
Author-email: Tasqr <hello@tasqr.ai>
License: MIT
License-File: LICENSE
Keywords: agents,mcp,model-context-protocol,tasks,tasqr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: anyio<5,>=4.0
Requires-Dist: boto3<2,>=1.34
Requires-Dist: cryptography<50,>=42
Requires-Dist: httpx2<3,>=2.5
Requires-Dist: mcp<3,>=2
Provides-Extra: dev
Requires-Dist: anyio[trio]>=4; extra == 'dev'
Requires-Dist: httpx2>=2.5; extra == 'dev'
Requires-Dist: moto[kms]>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# tasqr-mcp (Python)

[![ci](https://github.com/tasqrai/tasqr-mcp-python/actions/workflows/ci.yml/badge.svg)](https://github.com/tasqrai/tasqr-mcp-python/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/tasqr-mcp)](https://pypi.org/project/tasqr-mcp/)

Tasqr MCP server — task state management for AI agents.

Runs as a local stdio process that reads your API key from `~/.config/tasqr/credentials` and proxies tool calls to the Tasqr Lambda MCP server. Your MCP client config holds no secrets — the API key lives only in the credentials file (written `0600` on Mac/Linux; on Windows it relies on your profile directory's ACLs).

## Install

Requires Python 3.11 or newer.

```bash
uvx tasqr-mcp        # run once without installing
# or
pip install tasqr-mcp
```

## MCP client config

```json
{
  "mcpServers": {
    "tasqr": {
      "command": "uvx",
      "args": ["tasqr-mcp"]
    }
  }
}
```

## Credentials

**First run — no setup needed.** Run the proxy once in a terminal:

```bash
uvx tasqr-mcp
```

With no API key on disk, it starts GitHub device-flow signup: it opens your browser to GitHub, copies the device code to your clipboard to paste in, and (if your account has more than one workspace) asks which to use. It then writes the credentials file for you. You only need the manual steps below if you'd rather create it yourself.

Your MCP client never sees a secret — it just launches `uvx tasqr-mcp`, and the key is read from:

```
~/.config/tasqr/credentials   (Mac/Linux)
%APPDATA%\tasqr\credentials   (Windows)
```

```ini
[default]
api_key = tasqr_abc123...
```

On Mac/Linux the file is written `0600` (owner read/write only); on Windows it inherits your profile directory's ACLs. Sign up at [tasqr.ai](https://tasqr.ai) if you'd prefer to grab a key from the web instead.

Because the signup is interactive, it only runs when stdin is a TTY. An MCP client launching the proxy headlessly with no key will exit and tell you to run `uvx tasqr-mcp` in a terminal first.

## Logging

**Logging is off by default** — nothing is written to disk unless you turn it on. When enabled, the proxy keeps an append-only JSON-lines event log recording metadata only: tool names and field names, never task content, never key material.

Turn it on in the credentials file:

```ini
[default]
api_key   = tasqr_abc123...
log_level = info                        # off (default) | info | debug
log_path  = ~/.config/tasqr/tasqr-mcp.log
```

| Level | Logs |
|---|---|
| `off` *(default)* | nothing — no file is created |
| `info` | session lifecycle: `dek_loaded`, `kms_decrypt` — roughly one line per session |
| `debug` | the above plus one `encrypt`/`decrypt` line per tool call |

There is no rotation or size cap, so `debug` is for troubleshooting, not for leaving on.

## Environment variables

Env vars win over the credentials file, which wins over the defaults.

| Variable | Purpose |
|---|---|
| `TASQR_PROFILE` | Which `[section]` of the credentials file to use (default: `default`) |
| `TASQR_MCP_URL` | Point at a different server, e.g. `http://localhost:8000/mcp` |
| `TASQR_LOG` | Override `log_path` |
| `TASQR_LOG_LEVEL` | Override `log_level` |

## Client-side encryption (BYOK)

Encrypt task fields (title, description, metadata, output, note) locally before they reach Tasqr servers. Requires an AWS KMS key you control.

Add `kms_key_id` to your credentials file to turn it on — nothing else to install:

```ini
[default]
api_key      = tasqr_abc123...
kms_key_id   = arn:aws:kms:us-east-1:123456789012:key/your-key-id
aws_profile  = default
```

**Your Tasqr org must be enrolled in client-side BYOK.** At startup the proxy asks the server which mode your org uses. If the org is server-managed, it refuses to start rather than encrypt — the server would otherwise encrypt your ciphertext a second time, leaving the data unreadable to the dashboard, the REST API, and any other agent, and unrecoverable if you lost your KMS key. The error tells you which profile to fix.

Once enrolled, the proxy fetches or generates a data encryption key (DEK), wraps it with KMS, and stores the wrapped key in the Tasqr API. Later runs unwrap the cached DEK with a single KMS call. All AES-256-GCM encryption happens in memory — the plaintext DEK never leaves the process.

Every ciphertext is additionally **bound to its context**: the GCM associated data ties each encrypted value to your org, its task, and the field it was written for. A blob moved to any other slot — a different field, task, or org — fails decryption outright instead of decrypting in the wrong place. To make this possible the proxy mints each new task's id itself and sends it with the create call.

See the [client-side encryption guide](https://tasqr.ai/docs#client-encryption) for the full setup walkthrough.

## Local development

```bash
pip install -e ".[dev]"
pytest
tasqr-mcp --version
```
