mcp-tasker 1.0.0__tar.gz

mcp_tasker-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [Evgeniy A. Cymbalyuk <cimbaluk@gmail.com>]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_tasker-1.0.0/PKG-INFO

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: mcp-tasker
+Version: 1.0.0
+Summary: Simple file-based task tracker for git repos
+License: MIT License
+         
+         Copyright (c) [2026] [Evgeniy A. Cymbalyuk <cimbaluk@gmail.com>]
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+License-File: LICENSE
+Author: Evgeniy A. Cymbalyuk
+Author-email: cimbaluk@gmail.com
+Requires-Python: >=3.10
+Classifier: License :: Other/Proprietary License
+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: Programming Language :: Python :: 3.14
+Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
+Requires-Dist: mcp (>=1.26.0,<2.0.0)
+Requires-Dist: pydantic (>=2.0)
+Requires-Dist: typer (>=0.12.0)
+Requires-Dist: typer-di (>=0.1.0)
+Project-URL: Repository, https://github.com/greendwin/mcp-tasker
+Description-Content-Type: text/markdown
+
+# Tasker
+
+[![tests](https://github.com/greendwin/mcp-tasker/actions/workflows/ci.yml/badge.svg)](https://github.com/greendwin/mcp-tasker/actions/workflows/ci.yml)
+
+A simple file-based task tracker for git repositories. Tasks are stored as plain Markdown files inside a `tasker/` directory, tracked alongside your code with git.
+
+## Installation
+
+Install with [pipx](https://pipx.pypa.io/) (recommended — installs in an isolated environment):
+
+```bash
+pipx install mcp-tasker
+```
+
+Or with pip:
+
+```bash
+pip install mcp-tasker
+```
+
+For development (requires [Poetry](https://python-poetry.org/)):
+
+```bash
+git clone https://github.com/greendwin/mcp-tasker.git
+cd mcp-tasker
+poetry install --with dev
+```
+
+## Quick Start
+
+```bash
+# Create a story
+tasker new "Build authentication"
+
+# Add subtasks
+tasker add s01 "Design login flow"
+tasker add s01 "Implement JWT tokens" --details "Use RS256 signing"
+
+# Work on a task
+tasker start s01t01
+
+# View what's on your plate
+tasker list
+
+# Mark tasks done
+tasker done s01t01
+
+# Edit a task in your editor
+tasker edit s01t02
+```
+
+Tasks are stored as Markdown in `tasker/` and committed with your code:
+
+```
+tasker/
+  s01-build-authentication/
+    README.md
+    s01t01-design-login-flow.md
+    s01t02-implement-jwt-tokens.md
+```
+
+## Usage
+
+### Create tasks
+
+```bash
+tasker new <title>                          # new root story
+tasker new <title> --details "..." --slug <slug>  # with description and slug
+tasker add <parent-id> <title>              # inline subtask
+tasker add <parent-id> <title> --details "..."    # subtask with description
+tasker add-many <parent-id>                 # add multiple subtasks interactively
+```
+
+### Update status
+
+```bash
+tasker start <task-id>...     # mark in-progress
+tasker done <task-id>...      # mark done
+tasker cancel <task-id>...    # cancel
+tasker reset <task-id>...     # reset to pending
+
+# Force-close a parent with open subtasks
+tasker done <task-id> --force
+```
+
+### View tasks
+
+```bash
+tasker list                   # all open root tasks
+tasker list -a                # include closed tasks
+tasker list <task-id>         # subtasks of a specific task
+tasker view <task-id>         # full task details
+```
+
+### Edit tasks
+
+```bash
+tasker edit <task-id>                    # open in $EDITOR
+tasker edit <task-id> --title "New title"
+tasker edit <task-id> --details "New description"
+tasker edit <task-id> --slug new-slug
+```
+
+### Organize
+
+```bash
+tasker move <task-id> --parent <new-parent>  # reparent
+tasker move <task-id> --root                 # promote to story
+tasker archive <task-id>                     # archive completed story
+tasker archive --closed                      # archive all closed stories
+tasker unarchive <task-id>                   # restore from archive
+```
+
+### Shortcuts
+
+Reference recent tasks without typing full IDs:
+
+| Shortcut | Meaning |
+|---|---|
+| `q` | Last referenced task |
+| `q01` | Subtask 01 of recent |
+| `p` | Parent of recent |
+| `p03` | Sibling 03 via parent |
+
+```bash
+tasker view s01t02   # sets recent = s01t02
+tasker start q       # starts s01t02
+tasker view p        # views s01 (parent)
+tasker done q01      # marks s01t0201 done
+```
+
+## MCP Server
+
+`tasker` can run as a [Model Context Protocol](https://modelcontextprotocol.io/) server, allowing AI agents to manage your tasks directly.
+
+### Configure in Claude Code
+
+```bash
+claude mcp add tasker -- tasker mcp
+```
+
+### Configure per-project (`.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "tasker": {
+      "command": "tasker",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+If running from a Poetry project:
+
+```json
+{
+  "mcpServers": {
+    "tasker": {
+      "command": "poetry",
+      "args": ["run", "tasker", "mcp"]
+    }
+  }
+}
+```
+
+### HTTP transport
+
+For network-accessible clients, start with `--port`:
+
+```bash
+tasker mcp --port 8080
+```
+
+### Available tools
+
+Once connected, the MCP server exposes:
+
+| Tool | Description |
+|---|---|
+| `create_task` | Create a root task or subtask |
+| `list_tasks` | List all root tasks |
+| `view_task` | View task details and subtasks |
+| `start_task` | Mark task in-progress |
+| `reset_task` | Reset task to pending |
+| `finish_task` | Mark task done |
+
+## Development
+
+```bash
+poetry install --with dev
+
+# Run all checks (lint + tests)
+poetry run tox
+
+# Run tests only
+poetry run tox -e test
+
+# Lint (black, isort, flake8, mypy)
+poetry run tox -e lint
+
+# Format code
+black src tests
+isort src tests
+```
+
+## Requirements
+
+- Python >= 3.10
+
+## Release Notes
+
+### 1.0.0
+- `pip` release

mcp_tasker-1.0.0/README.md

@@ -0,0 +1,215 @@
+# Tasker
+
+[![tests](https://github.com/greendwin/mcp-tasker/actions/workflows/ci.yml/badge.svg)](https://github.com/greendwin/mcp-tasker/actions/workflows/ci.yml)
+
+A simple file-based task tracker for git repositories. Tasks are stored as plain Markdown files inside a `tasker/` directory, tracked alongside your code with git.
+
+## Installation
+
+Install with [pipx](https://pipx.pypa.io/) (recommended — installs in an isolated environment):
+
+```bash
+pipx install mcp-tasker
+```
+
+Or with pip:
+
+```bash
+pip install mcp-tasker
+```
+
+For development (requires [Poetry](https://python-poetry.org/)):
+
+```bash
+git clone https://github.com/greendwin/mcp-tasker.git
+cd mcp-tasker
+poetry install --with dev
+```
+
+## Quick Start
+
+```bash
+# Create a story
+tasker new "Build authentication"
+
+# Add subtasks
+tasker add s01 "Design login flow"
+tasker add s01 "Implement JWT tokens" --details "Use RS256 signing"
+
+# Work on a task
+tasker start s01t01
+
+# View what's on your plate
+tasker list
+
+# Mark tasks done
+tasker done s01t01
+
+# Edit a task in your editor
+tasker edit s01t02
+```
+
+Tasks are stored as Markdown in `tasker/` and committed with your code:
+
+```
+tasker/
+  s01-build-authentication/
+    README.md
+    s01t01-design-login-flow.md
+    s01t02-implement-jwt-tokens.md
+```
+
+## Usage
+
+### Create tasks
+
+```bash
+tasker new <title>                          # new root story
+tasker new <title> --details "..." --slug <slug>  # with description and slug
+tasker add <parent-id> <title>              # inline subtask
+tasker add <parent-id> <title> --details "..."    # subtask with description
+tasker add-many <parent-id>                 # add multiple subtasks interactively
+```
+
+### Update status
+
+```bash
+tasker start <task-id>...     # mark in-progress
+tasker done <task-id>...      # mark done
+tasker cancel <task-id>...    # cancel
+tasker reset <task-id>...     # reset to pending
+
+# Force-close a parent with open subtasks
+tasker done <task-id> --force
+```
+
+### View tasks
+
+```bash
+tasker list                   # all open root tasks
+tasker list -a                # include closed tasks
+tasker list <task-id>         # subtasks of a specific task
+tasker view <task-id>         # full task details
+```
+
+### Edit tasks
+
+```bash
+tasker edit <task-id>                    # open in $EDITOR
+tasker edit <task-id> --title "New title"
+tasker edit <task-id> --details "New description"
+tasker edit <task-id> --slug new-slug
+```
+
+### Organize
+
+```bash
+tasker move <task-id> --parent <new-parent>  # reparent
+tasker move <task-id> --root                 # promote to story
+tasker archive <task-id>                     # archive completed story
+tasker archive --closed                      # archive all closed stories
+tasker unarchive <task-id>                   # restore from archive
+```
+
+### Shortcuts
+
+Reference recent tasks without typing full IDs:
+
+| Shortcut | Meaning |
+|---|---|
+| `q` | Last referenced task |
+| `q01` | Subtask 01 of recent |
+| `p` | Parent of recent |
+| `p03` | Sibling 03 via parent |
+
+```bash
+tasker view s01t02   # sets recent = s01t02
+tasker start q       # starts s01t02
+tasker view p        # views s01 (parent)
+tasker done q01      # marks s01t0201 done
+```
+
+## MCP Server
+
+`tasker` can run as a [Model Context Protocol](https://modelcontextprotocol.io/) server, allowing AI agents to manage your tasks directly.
+
+### Configure in Claude Code
+
+```bash
+claude mcp add tasker -- tasker mcp
+```
+
+### Configure per-project (`.mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "tasker": {
+      "command": "tasker",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+If running from a Poetry project:
+
+```json
+{
+  "mcpServers": {
+    "tasker": {
+      "command": "poetry",
+      "args": ["run", "tasker", "mcp"]
+    }
+  }
+}
+```
+
+### HTTP transport
+
+For network-accessible clients, start with `--port`:
+
+```bash
+tasker mcp --port 8080
+```
+
+### Available tools
+
+Once connected, the MCP server exposes:
+
+| Tool | Description |
+|---|---|
+| `create_task` | Create a root task or subtask |
+| `list_tasks` | List all root tasks |
+| `view_task` | View task details and subtasks |
+| `start_task` | Mark task in-progress |
+| `reset_task` | Reset task to pending |
+| `finish_task` | Mark task done |
+
+## Development
+
+```bash
+poetry install --with dev
+
+# Run all checks (lint + tests)
+poetry run tox
+
+# Run tests only
+poetry run tox -e test
+
+# Lint (black, isort, flake8, mypy)
+poetry run tox -e lint
+
+# Format code
+black src tests
+isort src tests
+```
+
+## Requirements
+
+- Python >= 3.10
+
+## Release Notes
+
+### 1.0.0
+- `pip` release

mcp_tasker-1.0.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "mcp-tasker"
+version = "1.0.0"
+description = "Simple file-based task tracker for git repos"
+readme = "README.md"
+license = {file = "LICENSE"}
+urls = {repository = "https://github.com/greendwin/mcp-tasker"}
+authors = [
+    {name = "Evgeniy A. Cymbalyuk", email = "cimbaluk@gmail.com"}
+]
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.12.0",
+    "typer-di>=0.1.0",
+    "jinja2 (>=3.1.6,<4.0.0)",
+    "pydantic (>=2.0)",
+    "mcp (>=1.26.0,<2.0.0)",
+]
+
+[project.scripts]
+tasker = "tasker.main:app"
+
+[[tool.poetry.packages]]
+include = "tasker"
+from = "src"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8.0"
+pytest-cov = ">=5.0"
+tox = ">=4.0"
+mypy = ">=1.10"
+black = ">=24.0"
+isort = ">=5.13"
+flake8 = ">=7.0"
+pyfakefs = ">=6.1"
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mcp_tasker-1.0.0/src/tasker/__init__.py

@@ -0,0 +1,3 @@
+"""tasker — file-based task tracker for git repos."""
+
+__version__ = "0.1.0"

mcp_tasker-1.0.0/src/tasker/base_types.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+EXTENDED_TASK_FILENAME = "README.md"
+
+
+class TaskStatus(str, Enum):
+    PENDING = "pending"
+    IN_PROGRESS = "in-progress"
+    DONE = "done"
+    CANCELLED = "cancelled"
+
+
+class Task(BaseModel):
+    id: str  # unique id that can be used to reference a task
+    title: str  # short summary of a task
+    status: TaskStatus = TaskStatus.PENDING
+
+    # file-task fields (None/defaults for inline tasks)
+    slug: str | None = None
+    extended: bool = False
+    description: str | None = None
+    extra_sections: str | None = None
+    subtasks: list[Task] = []
+
+    @property
+    def is_inline(self) -> bool:
+        return self.slug is None
+
+    @property
+    def is_closed(self) -> bool:
+        return self.status in (TaskStatus.DONE, TaskStatus.CANCELLED)
+
+    @property
+    def ref(self) -> str:
+        if self.slug is not None:
+            return build_task_ref(self.id, self.slug)
+        return self.id
+
+
+def build_task_ref(task_id: str, slug: str) -> str:
+    return f"{task_id}-{slug}"
+
+
+def is_root_task_id(task_id: str) -> bool:
+    assert "-" not in task_id, "task id must be provided, not task ref"
+    # HACK: tasks are in form s123t4567, root tasks are always s123 without `t` suffix
+    return "t" not in task_id
+
+
+def is_nonleaf_task(task: Task) -> bool:
+    if not task.is_inline and task.subtasks:
+        return True
+    return False

mcp_tasker-1.0.0/src/tasker/cli/__init__.py

@@ -0,0 +1,8 @@
+__all__ = ["app"]
+
+from . import _create_commands as _create_commands  # noqa: F401
+from . import _mcp_commands as _mcp_commands  # noqa: F401
+from . import _organize_commands as _organize_commands  # noqa: F401
+from . import _task_commands as _task_commands  # noqa: F401
+from . import _view_commands as _view_commands  # noqa: F401
+from ._common import app