Reference: Python API

The logic is importable, so the package can be used without MCP at all — a script, a git hook, another server. Everything below is exported from the package root:

from worklog_mcp import AppendResult, CheckResult, Worklog, WorklogError, build_server

Worklog

worklog_mcp.Worklog dataclass

Worklog(
    directory: Path | None,
    pattern: Pattern[str] | None = None,
)

A directory of log files, plus an optional filter on their names.

Attributes:

Name	Type	Description
directory	Path | None	Where the log files live; None when it was never configured, which every operation reports as no_dir.
pattern	Pattern[str] | None	Applied to a candidate's file name with search; when it is None every non-hidden file in the directory is a candidate.

append

append(
    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.

Parameters:

Name	Type	Description	Default
description	str	What was done, as one sentence. Leading list and checkbox markers are stripped, and whitespace is collapsed.	required
dry_run	bool	Report the line that would be written without touching the file.	False

Returns:

Name	Type	Description
AppendResult	AppendResult	The outcome, the file's name and the line involved.

Raises:

Type	Description
WorklogError	The file is not valid UTF-8, or the write failed.

check

check() -> 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:

Name	Type	Description
CheckResult	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:

Type	Description
WorklogError	The file is not valid UTF-8.

AppendResult

worklog_mcp.AppendResult

Bases: BaseModel

What Worklog.append did.

CheckResult

worklog_mcp.CheckResult

Bases: BaseModel

What Worklog.check found.

WorklogError

worklog_mcp.WorklogError

Bases: 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.

build_server

worklog_mcp.build_server

build_server(
    directory: Path | None,
    pattern: 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.

Parameters:

Name	Type	Description	Default
directory	Path | None	Where the log files live, or None when it was never configured.	required
pattern	Pattern[str] | None	Optional filter on candidate file names.	None

Returns:

Name	Type	Description
MCPServer	MCPServer	A server exposing the append and check tools.