Metadata-Version: 2.4
Name: unntak-mcp
Version: 0.3.0
Summary: mcp server for the unntak.no agent api
Project-URL: Homepage, https://unntak.no
Project-URL: Repository, https://github.com/L0JK/unntak-mcp
Project-URL: Issues, https://github.com/L0JK/unntak-mcp/issues
Author: L0JK
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,mcp,model-context-protocol,task-management
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: cryptography<50,>=44
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.28
Description-Content-Type: text/markdown

# unntak-mcp

<!-- mcp-name: io.github.l0jk/unntak-mcp -->

local MCP server for the [unntak.no](https://unntak.no) agent API. it lets an
MCP client read, create, time, comment on, and complete tasks inside an agent's
tag scope.

all supported accounts are end-to-end encrypted. encrypted task content is
decrypted only inside this local process. unntak.no receives the inner scoped
API credential and ciphertext; the master key from the combined token is never
sent to the server.

## setup

1. in unntak.no, open `:)` → settings → agents and create an agent token. copy
   the complete token once. encrypted tokens start with `unntak-agent-v2.`.
2. add the local server to your MCP client:

```bash
read -s "UNNTAK_TOKEN?Agent token: "
echo
claude mcp add --scope user unntak \
  -e UNNTAK_TOKEN="$UNNTAK_TOKEN" \
  -- uvx unntak-mcp
unset UNNTAK_TOKEN
```

for a local Unntak instance, also add
`-e UNNTAK_URL=http://localhost:8000` before `--`.

the complete token is a password and, for encrypted accounts, also contains
the key needed to read the agent's task content. never commit it, paste it into
issues, or include it in logs. revoke it in Unntak settings if it is exposed.

only combined `unntak-agent-v2.` tokens are accepted.

## upgrade an existing installation

`uvx` installs published versions on demand. force it to refresh the cached
package, then verify the token and E2EE decryption:

```bash
read -s "UNNTAK_TOKEN?Agent token: "
echo
export UNNTAK_TOKEN
uvx --refresh-package unntak-mcp unntak-mcp --check
unset UNNTAK_TOKEN
```

restart the MCP client afterwards. to replace a revoked token:

```bash
read -s "UNNTAK_TOKEN?New agent token: "
echo
claude mcp remove --scope user unntak
claude mcp add --scope user unntak \
  -e UNNTAK_TOKEN="$UNNTAK_TOKEN" \
  -- uvx unntak-mcp
unset UNNTAK_TOKEN
```

then confirm the connection:

```bash
claude mcp list
```

## connection check

the check is read-only. success prints the decrypted agent name, scope, and
open task count:

```json
{"agent":"007","open_tasks":0,"scope":"agent;007"}
```

## agent flow

the server sends these rules to the model automatically on connect: check
`list_tasks` at session start, read a task and its comments before working,
start the timer, comment progress, and always complete or stop the task before
ending the session.

## tools

- `whoami` — agent name, scope, and open task count
- `list_tasks` — open tasks in the agent's scope
- `get_task` — one task with comments
- `add_task` — create a scoped task
- `start_task` / `stop_task` — operate the live focus timer
- `log_time` — log a block of seconds without the live timer
- `comment` — comment under the agent's name
- `complete_task` — finish a task and archive it

## encryption

combined v2 tokens use AES-256-GCM task and comment payloads, authenticated
agent metadata, and HMAC-SHA-256 blind scope tokens. plaintext tokens and
responses are rejected.

the combined token is split locally. only its inner API token is used as the
HTTP bearer credential. ciphertext, keys, and combined tokens are removed from
MCP tool results and error messages.

`skill/SKILL.md` documents the agent workflow for clients with skill support.
encrypted accounts must use this MCP package or another compatible local E2EE
client because the combined token must never be sent whole as an HTTP bearer.

## development

```bash
uv sync --locked --dev
uv run pytest
uv build --no-sources
```

test the built wheel instead of the editable source:

```bash
UNNTAK_TOKEN=unntak-agent-v2... \
  uvx --from ./dist/unntak_mcp-0.3.0-py3-none-any.whl unntak-mcp --check
```

## release

CI tests Python 3.11 and 3.14, builds both distributions, and smoke-tests the
built artifacts. publishing uses the `pypi` GitHub environment and PyPI trusted
publishing, so no PyPI password is stored in GitHub.

create a tag matching the package version only after CI passes:

```bash
uv run pytest
uv build --no-sources
git tag -a v0.3.0 -m v0.3.0
git push origin v0.3.0
```

the tag publishes to PyPI. `server.json` can then be published separately to
the official MCP registry for discovery.
