Metadata-Version: 2.4
Name: unntak-mcp
Version: 0.1.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: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.28
Description-Content-Type: text/markdown

# unntak-mcp

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

mcp server for the [unntak.no](https://unntak.no) agent api. lets any mcp
client (claude code, claude desktop, cursor, ...) read, create and work on
unntak tasks with an agent token.

the server runs locally over stdio. the token stays in the local environment
and is only sent to `unntak.no` (or the explicitly configured `UNNTAK_URL`).

## setup

1. in unntak.no, open `:)` → settings → agents and create a token. the token
   is scoped to a tag path (like `agent;007`), so the agent only ever sees
   tasks under those tags.
2. add the server to your client:

```bash
claude mcp add unntak --env UNNTAK_TOKEN=unntak-agent-... -- uvx unntak-mcp
```

for a local unntak instance, add `--env UNNTAK_URL=http://localhost:8000`.

the token is a password. never commit it, paste it into issues, or include it
in logs. revoke it in unntak settings if it is exposed.

## connection check

check the production api and token before configuring an mcp client:

```bash
UNNTAK_TOKEN=unntak-agent-... uvx unntak-mcp --check
```

a successful check prints the agent name, scope, and open task count without
changing any tasks.

## agent flow

the server sends these rules to the model automatically on connect: check
list_tasks at session start (scheduled tasks appear when due), read a task's
comments before working on it, start_task before working (409 = someone else
has the timer, take another task), comment progress along the way, and always
complete_task or stop_task before ending a session so no timer is left
running.

## tools

- `list_tasks` — open tasks in the agent's scope
- `get_task` — one task with comments
- `add_task` — create a task (scope tags are always prepended)
- `start_task` / `stop_task` — run the focus timer; the owner sees it live
- `log_time` — log a block of seconds without the live timer
- `comment` — comment on a task under the agent's name
- `complete_task` — finish a task and archive it

## skill (no mcp needed)

`skill/SKILL.md` is an agent skill for clients that read skills instead of
running mcp servers (like claude code project skills). copy it into a
project's `.claude/skills/unntak/` and set `UNNTAK_TOKEN` in the environment;
the agent then works the same flow over plain http.

## development

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

test the built wheel rather than the editable source:

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

## release

the repository includes CI for Python 3.11 and 3.14. it builds and smoke-tests
both distribution formats on every pull request and push to `main`.

for publishing, create a `pypi` environment in the github repository and add
`L0JK/unntak-mcp` with workflow `publish.yml` as a trusted publisher in the
pypi project settings. no pypi token is stored in github.

make sure the package version is final, then create a matching tag:

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

the tag starts the publish workflow. it refuses to publish if the tag and
package versions differ.

after the pypi package is available, publish `server.json` separately to the
official mcp registry. the registry stores discovery metadata; pypi stores the
installable package.
