worklog-mcp 0.1.0__py3-none-any.whl

worklog_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""An MCP server that records finished work in a directory of log files.
+
+The public surface is small on purpose: build a :class:`Worklog` to use the
+logic directly, or :func:`build_server` to expose it over MCP.
+"""
+
+from worklog_mcp.logfile import AppendResult, CheckResult, Worklog, WorklogError
+from worklog_mcp.server import build_server
+
+__all__ = ["AppendResult", "CheckResult", "Worklog", "WorklogError", "build_server"]

worklog_mcp/cli.py

@@ -0,0 +1,111 @@
+"""Command line: serve the MCP server, or check the setup from a terminal.
+
+Both commands take the same two options, and each option can also be given as
+an environment variable — which is what makes the directory configurable
+without ever writing it into a client's config file.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from worklog_mcp.logfile import Worklog, WorklogError
+from worklog_mcp.server import build_server
+
+EXIT_ERROR = 1
+EXIT_NO_DIR = 2
+EXIT_NO_FILE = 3
+EXIT_NO_CHECKLIST = 4
+
+EXIT_CODES = {"no_dir": EXIT_NO_DIR, "no_file": EXIT_NO_FILE, "no_checklist": EXIT_NO_CHECKLIST}
+
+DirectoryOption = Annotated[
+    str | None,
+    typer.Option(
+        "--dir",
+        envvar="WORKLOG_DIR",
+        help="Directory holding the log files. Required, as an option or as the variable.",
+    ),
+]
+PatternOption = Annotated[
+    str | None,
+    typer.Option(
+        "--pattern",
+        envvar="WORKLOG_FILE_PATTERN",
+        help="Regular expression a file name must match. Omit to accept every file.",
+    ),
+]
+
+app = typer.Typer(
+    name="worklog-mcp",
+    help="Append what you did to the checklist of the newest file in a directory.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _directory(raw: str | None) -> Path | None:
+    """Turn the option's raw value into a directory, treating blank as unset.
+
+    An empty string is what a client's config produces when a variable it
+    interpolates is not set. It must not become ``Path(".")``, which is a real
+    directory and would put the log file somewhere surprising.
+
+    Returns:
+        Path | None: The directory, or ``None`` when nothing was configured.
+    """
+    if raw is None or not raw.strip():
+        return None
+    return Path(raw).expanduser()
+
+
+def _pattern(raw: str | None) -> re.Pattern[str] | None:
+    """Compile the file-name pattern.
+
+    Returns:
+        re.Pattern[str] | None: The compiled pattern, or ``None`` when the
+            option was omitted.
+
+    Raises:
+        BadParameter: The expression does not compile.
+    """
+    if raw is None:
+        return None
+    try:
+        return re.compile(raw)
+    except re.error as error:
+        message = f"not a valid regular expression: {error}"
+        raise typer.BadParameter(message) from error
+
+
+@app.command()
+def serve(directory: DirectoryOption = None, pattern: PatternOption = None) -> None:
+    """Run the MCP server on stdio. This is the command an MCP client starts."""
+    build_server(_directory(directory), _pattern(pattern)).run(transport="stdio")
+
+
+@app.command()
+def check(directory: DirectoryOption = None, pattern: PatternOption = None) -> None:
+    """Report which log file would be written to, and how many items it holds.
+
+    Raises:
+        Exit: With `1` when the file cannot be read, `2` when no directory is
+            configured, `3` when it holds no log file and `4` when that file
+            has no checklist.
+    """
+    worklog = Worklog(directory=_directory(directory), pattern=_pattern(pattern))
+    try:
+        result = worklog.check()
+    except WorklogError as error:
+        typer.echo(f"worklog-mcp: {error}", err=True)
+        raise typer.Exit(EXIT_ERROR) from error
+
+    if result.status != "ok":
+        typer.echo(f"worklog-mcp: {result.message}", err=True)
+        raise typer.Exit(EXIT_CODES[result.status])
+
+    typer.echo(f'ok: file="{result.file}" items={result.items}')

worklog_mcp/logfile.py

@@ -0,0 +1,492 @@
+"""Finding the log file, finding its checklist, and appending one item to it.
+
+This module is the whole behaviour of the package; ``server`` and ``cli`` are
+thin shells over it. Nothing here knows about MCP, and nothing here ever puts a
+filesystem path into a result: callers get the file's *name* and the line that
+was written, never the directory they live in.
+"""
+
+from __future__ import annotations
+
+import re
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+CHECKLIST_ITEM = re.compile(r"^(\s*)([-*+]) \[[ xX]\]\s*")
+LIST_ITEM = re.compile(r"^(\s*)(?:[-*+]|\d+[.)])\s")
+FENCE = re.compile(r"^\s*(```|~~~)")
+LEADING_MARKER = re.compile(r"^(?:[-*+]\s+)?(?:\[[ xX]\]\s*)?")
+
+AppendStatus = Literal["written", "created", "duplicate", "dry_run", "empty", "no_dir", "no_file"]
+"""Outcome of an append: what happened, or why nothing happened."""
+
+CheckStatus = Literal["ok", "no_dir", "no_file", "no_checklist"]
+"""Outcome of a check: the setup works, or the first thing that is missing."""
+
+MissingStatus = Literal["no_dir", "no_file"]
+"""The two ways reaching the log file can come up empty."""
+
+NO_DIR_MESSAGE = "the worklog directory is not configured or does not exist"
+
+NEW_MARKER = "-"
+"""Bullet used when a checklist has to be started; an existing one is copied instead."""
+
+
+class WorklogError(RuntimeError):
+    """The log file was found but could not be read or written.
+
+    Raised for a file that is not valid UTF-8 and for a failed write. Every
+    other outcome is a status on the result model, not an exception.
+    """
+
+
+class AppendResult(BaseModel):
+    """What ``Worklog.append`` did."""
+
+    status: AppendStatus = Field(
+        description=(
+            "What happened. 'written': the item was appended to an existing checklist. 'created': the "
+            "file had no checklist, so one was started at its end with this item. 'duplicate': the "
+            "checklist already had it, nothing was written. 'dry_run': nothing was written because "
+            "dry_run was set. 'empty': the description was blank. 'no_dir', 'no_file': the directory "
+            "or the log file is missing — report it and stop, never create either."
+        ),
+    )
+    file: str | None = Field(
+        default=None,
+        description="Name of the log file, without its directory. Null when no file was reached.",
+    )
+    line: str | None = Field(
+        default=None,
+        description="The exact line written, or that would have been written. Null when nothing was written.",
+    )
+    message: str = Field(description="One sentence describing the outcome, safe to repeat to the user.")
+
+
+class CheckResult(BaseModel):
+    """What ``Worklog.check`` found."""
+
+    status: CheckStatus = Field(
+        description=(
+            "'ok': a log file with a checklist was found. 'no_checklist': the file is there but has no "
+            "checklist yet, which the next append would start. 'no_dir', 'no_file': the directory or "
+            "the log file itself is missing."
+        ),
+    )
+    file: str | None = Field(
+        default=None,
+        description="Name of the log file, without its directory. Null when no file was reached.",
+    )
+    items: int | None = Field(
+        default=None,
+        description="How many items the checklist already holds. Null unless the status is 'ok'.",
+    )
+    message: str = Field(description="One sentence describing the outcome, safe to repeat to the user.")
+
+
+@dataclass(frozen=True)
+class _Checklist:
+    """Boundaries and shape of the checklist an item will be appended to."""
+
+    start: int
+    end: int
+    indent: str
+    marker: str
+
+
+@dataclass(frozen=True)
+class _Document:
+    """A log file split into lines, remembering how to put it back together."""
+
+    path: Path
+    lines: list[str]
+    newline: str
+    trailing: str
+
+
+@dataclass(frozen=True)
+class _Missing:
+    """Why the log file could not be reached, in a form both results accept."""
+
+    status: MissingStatus
+    message: str
+
+
+@dataclass(frozen=True)
+class Worklog:
+    """A directory of log files, plus an optional filter on their names.
+
+    Attributes:
+        directory: Where the log files live; ``None`` when it was never
+            configured, which every operation reports as ``no_dir``.
+        pattern: Applied to a candidate's file name with ``search``; when it is
+            ``None`` every non-hidden file in the directory is a candidate.
+    """
+
+    directory: Path | None
+    pattern: re.Pattern[str] | None = None
+
+    def append(self, description: str, *, dry_run: bool = False) -> AppendResult:
+        """Append one done item to the checklist of the newest log file.
+
+        The item is written as ``[x]``, reusing the indent and the bullet
+        marker of the checklist's first item. An item whose text is already in
+        the checklist is not written again, so retrying a workflow never
+        doubles a line.
+
+        A log file with no checklist at all gets one started at its end — the
+        file itself is never created, but an empty day is not a reason to
+        refuse the entry.
+
+        Args:
+            description: What was done, as one sentence. Leading list and
+                checkbox markers are stripped, and whitespace is collapsed.
+            dry_run: Report the line that would be written without touching
+                the file.
+
+        Returns:
+            AppendResult: The outcome, the file's name and the line involved.
+
+        Raises:
+            WorklogError: The file is not valid UTF-8, or the write failed.
+        """
+        text = _normalize(description)
+        if not text:
+            return AppendResult(status="empty", message="the description is empty, so there is nothing to write")
+
+        located = self._locate()
+        if isinstance(located, _Missing):
+            return AppendResult(status=located.status, message=located.message)
+        document, checklist = located
+
+        name = document.path.name
+        if checklist is None:
+            return self._start(document, text, dry_run=dry_run)
+
+        line = f"{checklist.indent}{checklist.marker} [x] {text}"
+        block = document.lines[checklist.start : checklist.end + 1]
+        if any(CHECKLIST_ITEM.match(item) and _item_text(item) == text for item in block):
+            return AppendResult(
+                status="duplicate",
+                file=name,
+                line=line,
+                message=f'"{name}" already has this item, so nothing was written',
+            )
+
+        if dry_run:
+            return AppendResult(
+                status="dry_run",
+                file=name,
+                line=line,
+                message=f'one item would be appended to the checklist in "{name}"',
+            )
+
+        document.lines.insert(checklist.end + 1, line)
+        _write_atomic(document)
+        return AppendResult(
+            status="written",
+            file=name,
+            line=line,
+            message=f'one item was appended to the checklist in "{name}"',
+        )
+
+    @staticmethod
+    def _start(document: _Document, text: str, *, dry_run: bool) -> AppendResult:
+        """Start a checklist at the end of a log file that has none.
+
+        Returns:
+            AppendResult: ``created``, or ``dry_run`` when nothing was written.
+        """
+        name = document.path.name
+        line = f"{NEW_MARKER} [x] {text}"
+        if dry_run:
+            return AppendResult(
+                status="dry_run",
+                file=name,
+                line=line,
+                message=f'"{name}" has no checklist; one would be started with this item',
+            )
+
+        # A list glued to the paragraph above it is not a list, so the blank
+        # line is part of writing a checklist, not cosmetics.
+        if document.lines and document.lines[-1].strip():
+            document.lines.append("")
+        document.lines.append(line)
+        _write_atomic(document)
+        return AppendResult(
+            status="created",
+            file=name,
+            line=line,
+            message=f'"{name}" had no checklist, so one was started with this item',
+        )
+
+    def check(self) -> CheckResult:
+        """Report whether a log file with a checklist can be found right now.
+
+        Reads nothing back to the caller beyond the file's name and how many
+        items its checklist already holds — it is a setup probe, not a way to
+        look at the file.
+
+        Returns:
+            CheckResult: ``ok`` plus the file name and item count, or the first
+                thing that is missing. Unlike :meth:`append`, this never starts
+                a checklist — it reports ``no_checklist`` and leaves the file
+                alone.
+
+        Raises:
+            WorklogError: The file is not valid UTF-8.
+        """
+        located = self._locate()
+        if isinstance(located, _Missing):
+            return CheckResult(status=located.status, message=located.message)
+        document, checklist = located
+
+        name = document.path.name
+        if checklist is None:
+            return CheckResult(
+                status="no_checklist",
+                file=name,
+                message=f'"{name}" has no checklist yet; the next append will start one',
+            )
+
+        block = document.lines[checklist.start : checklist.end + 1]
+        items = sum(1 for line in block if CHECKLIST_ITEM.match(line))
+        return CheckResult(status="ok", file=name, items=items, message=f'"{name}" has a checklist with {items} items')
+
+    def _locate(self) -> tuple[_Document, _Checklist | None] | _Missing:
+        """Find the newest log file, and the first checklist in it if it has one.
+
+        Returns:
+            tuple[_Document, _Checklist | None] | _Missing: The file and its
+                checklist — ``None`` when the file has none — or which
+                prerequisite is absent.
+        """
+        if self.directory is None or not self.directory.is_dir():
+            return _Missing(status="no_dir", message=NO_DIR_MESSAGE)
+
+        path = _latest_file(self.directory, self.pattern)
+        if path is None:
+            missing = (
+                "no file in the worklog directory matches the configured pattern"
+                if self.pattern is not None
+                else "the worklog directory holds no files"
+            )
+            return _Missing(status="no_file", message=missing)
+
+        document = _read(path)
+        return document, _find_checklist(document.lines)
+
+
+def _created_at(path: Path) -> float:
+    """Creation time where the platform records one, last modification otherwise.
+
+    Returns:
+        float: Seconds since the epoch, for ordering candidates only.
+    """
+    stat = path.stat()
+    # float() because st_birthtime is untyped: the platform may not have it.
+    return float(getattr(stat, "st_birthtime", stat.st_mtime))
+
+
+def _latest_file(directory: Path, pattern: re.Pattern[str] | None) -> Path | None:
+    """Newest matching file in the directory itself, ignoring subdirectories.
+
+    Today's date is never computed: the file for today is the one created last,
+    so the newest file is the right one — and work finished after midnight
+    lands where its author expects to find it.
+
+    Args:
+        directory: Searched without recursion; hidden files are skipped.
+        pattern: Matched against the file name with ``search``, or ``None`` to
+            accept every candidate.
+
+    Returns:
+        Path | None: The newest candidate, or ``None`` when there is none.
+    """
+    candidates = [item for item in directory.iterdir() if item.is_file() and not item.name.startswith(".")]
+    if pattern is not None:
+        candidates = [item for item in candidates if pattern.search(item.name)]
+    if not candidates:
+        return None
+    return max(candidates, key=_created_at)
+
+
+def _read(path: Path) -> _Document:
+    """Read a log file, remembering its line ending and whether it ends in one.
+
+    Returns:
+        _Document: The file's lines and how to write them back.
+
+    Raises:
+        WorklogError: The file is not valid UTF-8.
+    """
+    try:
+        # newline="" keeps CRLF intact; the default would translate it away and
+        # the file would silently come back with its line endings rewritten.
+        text = path.read_text(encoding="utf-8", newline="")
+    except UnicodeDecodeError as error:
+        message = f'"{path.name}" is not valid UTF-8'
+        raise WorklogError(message) from error
+    newline = "\r\n" if "\r\n" in text else "\n"
+    trailing = newline if text.endswith("\n") else ""
+    return _Document(path=path, lines=text.splitlines(), newline=newline, trailing=trailing)
+
+
+def _write_atomic(document: _Document) -> None:
+    """Replace the file in one step, through a temporary file beside it.
+
+    Editors watch these files, so none of them may ever observe a truncated
+    one. A failure at any point leaves the original untouched and removes the
+    temporary file.
+
+    Raises:
+        WorklogError: The temporary file could not be created, written or
+            moved into place.
+    """
+    text = document.newline.join(document.lines) + document.trailing
+    try:
+        handle = tempfile.NamedTemporaryFile(  # ruff: ignore[open-file-with-context-handler]  # closed below, then renamed over the original
+            "w",
+            encoding="utf-8",
+            dir=document.path.parent,
+            prefix=".worklog-",
+            suffix=".tmp",
+            delete=False,
+            newline="",
+        )
+    except OSError as error:
+        raise WorklogError(_write_failed(document.path, error)) from error
+
+    temporary = Path(handle.name)
+    try:
+        with handle:
+            handle.write(text)
+        temporary.replace(document.path)
+    except OSError as error:
+        temporary.unlink(missing_ok=True)
+        raise WorklogError(_write_failed(document.path, error)) from error
+
+
+def _write_failed(path: Path, error: OSError) -> str:
+    """Phrase a write failure without naming the directory.
+
+    Returns:
+        str: The message carried by the raised :class:`WorklogError`.
+    """
+    return f'cannot write "{path.name}": {error.strerror}'
+
+
+def _skip_frontmatter(lines: list[str]) -> int:
+    """Index of the first line after a YAML frontmatter block.
+
+    Returns:
+        int: Where the document's body starts; ``0`` when there is no
+            frontmatter.
+    """
+    if not lines or lines[0].rstrip() != "---":
+        return 0
+    for index in range(1, len(lines)):
+        if lines[index].rstrip() in {"---", "..."}:
+            return index + 1
+    return 0
+
+
+def _toggle_fence(fence: str | None, token: str, line: str) -> str | None:
+    """Track whether the document is currently inside a fenced code block.
+
+    A fence is closed only by its own token, so backticks inside a tilde block
+    leave it open.
+
+    Returns:
+        str | None: The token holding the block open, or ``None`` outside one.
+    """
+    if fence is None:
+        return token
+    if line.strip().startswith(fence):
+        return None
+    return fence
+
+
+def _find_checklist(lines: list[str]) -> _Checklist | None:
+    """Locate the FIRST checklist in the document.
+
+    A file may hold several checklists; the first one from the top wins and the
+    rest are left alone. Fenced code blocks are skipped, so a markdown example
+    inside triple backticks is not mistaken for a checklist.
+
+    Returns:
+        _Checklist | None: Boundaries and shape of the block, or ``None`` when
+            the document has no checklist.
+    """
+    index = _skip_frontmatter(lines)
+    fence: str | None = None
+
+    while index < len(lines):
+        line = lines[index]
+        opening = FENCE.match(line)
+        if opening:
+            fence = _toggle_fence(fence, opening.group(1), line)
+        elif fence is None:
+            item = CHECKLIST_ITEM.match(line)
+            if item:
+                indent, marker = item.group(1), item.group(2)
+                end = _block_end(lines, index, indent)
+                return _Checklist(start=index, end=end, indent=indent, marker=marker)
+        index += 1
+
+    return None
+
+
+def _block_end(lines: list[str], start: int, indent: str) -> int:
+    """Index of the last line belonging to the checklist that starts at ``start``.
+
+    The block runs to the last sibling or nested item, keeping the blank lines
+    and continuation lines inside it, and stops at the first line that returns
+    to a shallower level or opens a code fence.
+
+    Returns:
+        int: Index of that last line; the new item goes right after it.
+    """
+    end = start
+    index = start + 1
+    base = len(indent)
+    while index < len(lines):
+        line = lines[index]
+        if not line.strip():
+            index += 1
+            continue
+        if FENCE.match(line):
+            break
+        current = len(line) - len(line.lstrip())
+        if LIST_ITEM.match(line) and current >= base:
+            end = index
+        elif current > base:
+            end = index  # a continuation line of the item above
+        else:
+            break
+        index += 1
+    return end
+
+
+def _item_text(line: str) -> str:
+    """Text of a checklist item, without its marker and with collapsed spaces.
+
+    Returns:
+        str: The comparable form used to recognise a duplicate.
+    """
+    return " ".join(CHECKLIST_ITEM.sub("", line, count=1).split())
+
+
+def _normalize(raw: str) -> str:
+    """Reduce a description to the single line that will be written.
+
+    Returns:
+        str: One line without a leading list or checkbox marker; empty when
+            nothing is left to write.
+    """
+    description = " ".join(raw.split())
+    return LEADING_MARKER.sub("", description, count=1).strip()

worklog_mcp/server.py

@@ -0,0 +1,162 @@
+"""The MCP server: two tools over one :class:`~worklog_mcp.logfile.Worklog`.
+
+The directory and the file-name pattern are fixed when the server starts, so a
+client never passes them — and never sees them.
+
+Every field of both tool descriptors is spelled out below rather than inferred,
+because the descriptor is the only thing a model has to go on. The descriptions
+in particular are part of the wire protocol: they are written as instructions to
+a model — when to call, what comes back, what the tool will not do — not as
+notes to a maintainer.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Annotated
+
+from mcp.server import MCPServer
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from worklog_mcp.logfile import AppendResult, CheckResult, Worklog
+
+SERVER_NAME = "worklog"
+
+DOCS_URL = "https://feodor-ra.github.io/worklog-mcp/"
+
+APPEND_DESCRIPTION = """\
+Record ONE finished piece of work in the user's log for today.
+
+Call this the moment a task is actually done — a fix landed, a change was
+pushed, a question was answered — and once per piece of work. Do not call it to
+plan something, to take a note, or to save a partial result.
+
+The item is appended as a completed entry to the checklist of the newest file in
+the log directory. That directory is configured when the server starts: you do
+not choose it, you cannot pass it, and you will not be told what it is.
+
+Write `description` as one plain sentence in the past tense, in the language the
+user writes their log in, naming what changed and — for a bug — why it happened.
+Leave out issue keys, links and branch names unless the user asks for them.
+
+The call is idempotent: repeating the same sentence returns `duplicate` and
+writes nothing, so retrying after an error is safe.
+
+If today's file has no checklist yet, one is started at the end of it and you
+get `created` instead of `written` — say so when you report back, since the
+file gained a list it did not have.
+
+The log file itself is never created. If the directory or the file is missing
+you get `no_dir` or `no_file`: report that to the user in one line and stop — do
+not create a file, do not look for the log yourself, and do not ask the user for
+the path.
+
+Returns the status, the log file's NAME (never its path) and the exact line
+written. Set `dry_run` to see that line without writing it."""
+
+CHECK_DESCRIPTION = """\
+Check that a log file with a checklist can be found right now.
+
+Use it to diagnose an `append` that came back `no_dir` or `no_file`: it tells
+you whether the server is misconfigured or the user has simply not started
+today's log yet. It takes no arguments and changes nothing — a file with no
+checklist is reported as `no_checklist` here, not started, which only `append`
+does.
+
+Returns the log file's NAME and how many items its checklist already holds. It
+is not a way to read the log — the items themselves are never returned, and no
+other tool returns them either. Do not call it before every append; the append
+reports the same conditions by itself."""
+
+
+def build_server(directory: Path | None, pattern: re.Pattern[str] | None = None) -> MCPServer:
+    """Create the MCP server for one worklog directory.
+
+    The directory is not validated here. A server that refused to start on a
+    missing directory would show up in a client as a broken connection with no
+    tools; instead every call reports ``no_dir``, which a caller can act on.
+
+    Args:
+        directory: Where the log files live, or ``None`` when it was never
+            configured.
+        pattern: Optional filter on candidate file names.
+
+    Returns:
+        MCPServer: A server exposing the ``append`` and ``check`` tools.
+    """
+    worklog = Worklog(directory=directory, pattern=pattern)
+    mcp = MCPServer(SERVER_NAME)
+
+    @mcp.tool(
+        name="append",
+        title="Append to today's work log",
+        description=APPEND_DESCRIPTION,
+        annotations=ToolAnnotations(
+            title="Append to today's work log",
+            read_only_hint=False,
+            # It only ever adds a line; no item is edited, reordered or removed.
+            destructive_hint=False,
+            # The same description twice leaves one line, not two.
+            idempotent_hint=True,
+            # One local directory, fixed at startup — no network, no discovery.
+            open_world_hint=False,
+        ),
+        meta={"docs": f"{DOCS_URL}reference/tools/"},
+        structured_output=True,
+    )
+    def append(
+        description: Annotated[
+            str,
+            Field(
+                description=(
+                    "What was done, as ONE sentence in the past tense, in the user's own language. "
+                    "Name the change and, for a bug, its cause. No issue keys, links or branch names. "
+                    "Line breaks are collapsed and a leading '- ' or '- [ ]' marker is stripped."
+                ),
+                min_length=1,
+            ),
+        ],
+        *,
+        dry_run: Annotated[
+            bool,
+            Field(
+                description=(
+                    "Return the line that would be written without touching the file. "
+                    "Use only when the user asked to preview the entry."
+                ),
+            ),
+        ] = False,
+    ) -> AppendResult:
+        """Append one done item; see :data:`APPEND_DESCRIPTION` for the model-facing text.
+
+        Returns:
+            AppendResult: The outcome, the log file's name and the line.
+        """
+        return worklog.append(description, dry_run=dry_run)
+
+    @mcp.tool(
+        name="check",
+        title="Check the work log setup",
+        description=CHECK_DESCRIPTION,
+        annotations=ToolAnnotations(
+            title="Check the work log setup",
+            # Reads one file and returns a count; writes nothing.
+            read_only_hint=True,
+            destructive_hint=False,
+            idempotent_hint=True,
+            open_world_hint=False,
+        ),
+        meta={"docs": f"{DOCS_URL}reference/tools/"},
+        structured_output=True,
+    )
+    def check() -> CheckResult:
+        """Probe the setup; see :data:`CHECK_DESCRIPTION` for the model-facing text.
+
+        Returns:
+            CheckResult: Whether the setup works, or the first thing missing.
+        """
+        return worklog.check()
+
+    return mcp

worklog_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: worklog-mcp
+Version: 0.1.0
+Summary: MCP server that appends what you did to the checklist of the newest log file in a directory
+Keywords: mcp,model-context-protocol,worklog,markdown,checklist
+Author: Fedor Ratschew
+Author-email: Fedor Ratschew <feodor.ra@me.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Information Technology
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Russian
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Editors :: Text Processing
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Dist: mcp~=2.1
+Requires-Dist: typer~=0.27
+Requires-Python: >=3.13
+Project-URL: Homepage, https://feodor-ra.github.io/worklog-mcp/
+Project-URL: Documentation, https://feodor-ra.github.io/worklog-mcp/
+Project-URL: Repository, https://github.com/feodor-ra/worklog-mcp
+Project-URL: Issues, https://github.com/feodor-ra/worklog-mcp/issues
+Description-Content-Type: text/markdown
+
+# worklog-mcp
+
+🇺🇸 **English** · 🇷🇺 [Русский](README.ru.md)
+
+[![PyPI - Version](https://img.shields.io/pypi/v/worklog-mcp)](https://pypi.org/project/worklog-mcp/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/worklog-mcp)](https://pypi.org/project/worklog-mcp/)
+![PyPI - Status](https://img.shields.io/pypi/status/worklog-mcp)
+![PyPI - Wheel](https://img.shields.io/pypi/wheel/worklog-mcp)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/worklog-mcp)
+![PyPI - Format](https://img.shields.io/pypi/format/worklog-mcp)
+[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
+[![Typed](https://img.shields.io/badge/typing-py.typed-261230)](https://peps.python.org/pep-0561/)
+
+[![CI](https://github.com/feodor-ra/worklog-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/feodor-ra/worklog-mcp/actions/workflows/ci.yml)
+[![Docs](https://github.com/feodor-ra/worklog-mcp/actions/workflows/docs.yml/badge.svg)](https://github.com/feodor-ra/worklog-mcp/actions/workflows/docs.yml)
+[![Coverage Status](https://coveralls.io/repos/github/feodor-ra/worklog-mcp/badge.svg?branch=main)](https://coveralls.io/github/feodor-ra/worklog-mcp?branch=main)
+[![Documentation](https://img.shields.io/badge/docs-mkdocs-blue)](https://feodor-ra.github.io/worklog-mcp/)
+![GitHub Release](https://img.shields.io/github/v/release/feodor-ra/worklog-mcp)
+![GitHub last commit](https://img.shields.io/github/last-commit/feodor-ra/worklog-mcp)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/m/feodor-ra/worklog-mcp)
+[![GitHub issues](https://img.shields.io/github/issues/feodor-ra/worklog-mcp)](https://github.com/feodor-ra/worklog-mcp/issues)
+![GitHub Repo stars](https://img.shields.io/github/stars/feodor-ra/worklog-mcp?style=flat)
+[![License: MIT](https://img.shields.io/github/license/feodor-ra/worklog-mcp)](LICENSE)
+
+**An MCP server that records finished work in your daily log.** Point it at a directory of log files; it appends one done item to the checklist of the newest one.
+
+If you keep a note per day with a checklist of what got done, the assistant that did the work can write the line itself. The directory is configured once, when the server starts, so it never travels through the conversation — the model sees the file's name and the line it wrote, and nothing else.
+
+```json
+{
+  "mcpServers": {
+    "worklog": {
+      "command": "worklog-mcp",
+      "args": ["serve", "--dir", "/path/to/your/notes"]
+    }
+  }
+}
+```
+
+That is the whole setup. The assistant now has `append` and `check`.
+
+## Install
+
+```bash
+uv tool install worklog-mcp
+```
+
+Requires Python **3.13+**. No editor, vault format or note-taking app is assumed: a log file is any text file with a markdown checklist in it.
+
+## Add it to your agent
+
+<details open>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add worklog -- worklog-mcp serve --dir /path/to/notes
+```
+
+Add `--scope user` to make it available in every project.
+</details>
+
+<details>
+<summary><b>Claude Desktop</b> · <code>claude_desktop_config.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "worklog": {
+      "command": "worklog-mcp",
+      "args": ["serve", "--dir", "/path/to/notes"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Cursor</b> · <code>~/.cursor/mcp.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "worklog": {
+      "command": "worklog-mcp",
+      "args": ["serve", "--dir", "/path/to/notes"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>VS Code</b> · <code>.vscode/mcp.json</code> — note the <code>servers</code> key</summary>
+
+```json
+{
+  "servers": {
+    "worklog": {
+      "type": "stdio",
+      "command": "worklog-mcp",
+      "args": ["serve", "--dir", "/path/to/notes"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Windsurf</b> · <code>~/.codeium/windsurf/mcp_config.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "worklog": {
+      "command": "worklog-mcp",
+      "args": ["serve", "--dir", "/path/to/notes"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Zed</b> · <code>settings.json</code> — <code>context_servers</code></summary>
+
+```json
+{
+  "context_servers": {
+    "worklog": {
+      "command": "worklog-mcp",
+      "args": ["serve", "--dir", "/path/to/notes"],
+      "env": {}
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Cline</b> · <code>cline_mcp_settings.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "worklog": {
+      "command": "worklog-mcp",
+      "args": ["serve", "--dir", "/path/to/notes"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Codex CLI</b> · <code>~/.codex/config.toml</code></summary>
+
+```toml
+[mcp_servers.worklog]
+command = "worklog-mcp"
+args = ["serve", "--dir", "/path/to/notes"]
+```
+
+Or: `codex mcp add worklog -- worklog-mcp serve --dir /path/to/notes`
+</details>
+
+<details>
+<summary><b>Gemini CLI</b> · <code>~/.gemini/settings.json</code></summary>
+
+```json
+{
+  "mcpServers": {
+    "worklog": {
+      "command": "worklog-mcp",
+      "args": ["serve", "--dir", "/path/to/notes"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>OpenCode</b> · <code>opencode.json</code></summary>
+
+```json
+{
+  "mcp": {
+    "worklog": {
+      "type": "local",
+      "command": ["worklog-mcp", "serve", "--dir", "/path/to/notes"]
+    }
+  }
+}
+```
+</details>
+
+## How to use it
+
+**1. Keep the path out of the config file, if you like.** Both options read an environment variable — `WORKLOG_DIR` and `WORKLOG_FILE_PATTERN` — so the snippet can carry no path at all:
+
+```json
+{
+  "mcpServers": {
+    "worklog": {
+      "command": "worklog-mcp",
+      "args": ["serve"],
+      "env": { "WORKLOG_DIR": "/path/to/notes" }
+    }
+  }
+}
+```
+
+**2. Narrow down which files count, if the directory holds more than logs.** `--pattern` is a regular expression matched against the file name:
+
+```bash
+worklog-mcp serve --dir ~/notes --pattern '^\d{4}-\d{2}-\d{2}\.md$'
+```
+
+Without a pattern, every non-hidden file in the directory is a candidate, and the newest one wins.
+
+**3. Check the setup from a terminal** whenever a call reports something missing:
+
+```bash
+worklog-mcp check --dir ~/notes
+# ok: file="2026-09-06.md" items=3
+```
+
+Exit codes are `0` ok, `2` no directory, `3` no log file, `4` no checklist.
+
+## Why it's cool
+
+- **The path stays out of the conversation.** It is a launch argument, read by the local process. Results carry a file name, never a directory.
+- **It never creates a log file.** A missing file or directory is reported and the call stops, so the assistant cannot reorganize your notes. The one thing it does add is a checklist, when today's file has none yet.
+- **Repeating a call is safe.** An item whose text is already in the checklist is not written twice, so a retried workflow does not double a line.
+- **Your formatting survives.** The new item reuses the indent and bullet marker of the checklist's first item, and the file keeps its line endings; the write is atomic, so an editor watching the file never sees it truncated.
+
+## Documentation
+
+📖 **[Full documentation](https://feodor-ra.github.io/worklog-mcp/)** — configuration, ready-made client snippets, exactly how the file and the checklist are picked, the tool contracts and an API reference. Available in English and Russian.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![ty](https://img.shields.io/badge/types-ty-261230)](https://github.com/astral-sh/ty)
+[![pytest](https://img.shields.io/badge/tested%20with-pytest-0A9EDC?logo=pytest&logoColor=white)](https://docs.pytest.org)
+[![Material for MkDocs](https://img.shields.io/badge/docs-Material%20for%20MkDocs-526CFE?logo=materialformkdocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
+[![Semantic Versions](https://img.shields.io/badge/SemVer-2.0.0-3F4551)](https://semver.org)
+[![Keep a Changelog](https://img.shields.io/badge/Keep%20a%20Changelog-1.1.0-E05735?logo=keepachangelog&logoColor=white)](https://keepachangelog.com)

worklog_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+worklog_mcp/__init__.py,sha256=FbHyuFbiXMjadCZduOYb4fI6A6eyMQ2xeZX5Gi3cPfo,429
+worklog_mcp/cli.py,sha256=sbwRCM6Tkr3NPDZQxVukwrOV-km4dy02dFjxa1Zk7kQ,3458
+worklog_mcp/logfile.py,sha256=NgiG_Oe1Tg-ARaTfaSSBeNvmWu4dIdvJF-0ccqxhmRs,17771
+worklog_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+worklog_mcp/server.py,sha256=BvSPxZhh5xlIgC7s8gt2KuI5mJeHtUYvt7IdfEuk7Fs,6386
+worklog_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=jk6A0Q6YhMNLgQ5cwUN53lUvDCp1ybOGMVJXtu1BYww,1071
+worklog_mcp-0.1.0.dist-info/WHEEL,sha256=Kot-FOXwz2no6rGIg4et79Z7m6vcKPAXr2Y6fTFpZuI,81
+worklog_mcp-0.1.0.dist-info/entry_points.txt,sha256=VOoKVlAAObGv1R7U2KcIBV2C6QRiAjvyANMHPgnJQPk,53
+worklog_mcp-0.1.0.dist-info/METADATA,sha256=v2YAEHtZzp-ATpDrYG-ytswlaiZ0GZXdpqGQfVbsJqg,10223
+worklog_mcp-0.1.0.dist-info/RECORD,,

worklog_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.10
+Root-Is-Purelib: true
+Tag: py3-none-any

worklog_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+worklog-mcp = worklog_mcp.cli:app
+

worklog_mcp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fedor Ratschew
+
+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.