tracker-mcp 0.3.0__py3-none-any.whl

tracker_mcp/__init__.py

@@ -0,0 +1,8 @@
+"""MCP server over a job-application tracker: Excel, CSV or Google Sheets."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("tracker-mcp")
+except PackageNotFoundError:  # running from a source tree without installing
+    __version__ = "0.0.0"

tracker_mcp/config.py

@@ -0,0 +1,150 @@
+"""What the server needs to know about a particular tracker workbook.
+
+Nothing about one person's tracker lives in the code: the sheet, the column
+headers, the status words, the follow-up rule and the texts the server writes
+into the follow-up log all come from a TOML file. By default the file sits next
+to the workbook: `my-tracker.xlsx` -> `my-tracker.tracker-mcp.toml`.
+`TRACKER_CONFIG` points to another one. `examples/tracker-mcp.example.toml`
+describes every key.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator
+
+# Fields the server's logic understands. Any other key in [columns] is a custom
+# field: it is returned under its own key and can be set through add_application.
+REQUIRED_FIELDS = ("company", "role", "status")
+KNOWN_FIELDS = REQUIRED_FIELDS + (
+    "num", "link", "applied", "applied_on", "channel", "response", "notes",
+    "followup_on", "followup_contact", "followup_log", "reached",
+)
+
+
+class _Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Statuses(_Strict):
+    not_applied: str = "Not applied"
+    applied: str = "Applied"
+    closed: list[str] = ["Rejected", "Withdrawn", "No response", "Offer", "Closed"]
+    # Still waiting for the company: close_stale only touches these.
+    waiting: list[str] | None = None   # default: [applied]
+    no_response: str = "No response"   # what close_stale sets
+    # For the funnel. A rejection is a reply. Stages run in this order, and a status
+    # in a later stage means the application got through the earlier ones.
+    rejected: list[str] = ["Rejected"]
+    stages: dict[str, list[str]] = {"screening": ["Screening"], "interview": ["Interview"], "offer": ["Offer"]}
+    # Used only when the status column has no dropdown in the workbook.
+    fallback: list[str] = ["Not applied", "Applied", "Screening", "Interview", "Offer",
+                           "Rejected", "Withdrawn", "No response", "Closed"]
+    # Alternative spellings the model may use -> the value from the dropdown.
+    aliases: dict[str, str] = {}
+
+
+class Values(_Strict):
+    yes: str = "Yes"                 # «applied» column, when there is one
+    no: str = "No"
+    no_date: str = "—"               # written into the follow-up date when none is due
+    separator: str = " | "           # between entries appended to a text cell
+    stamp_format: str = "%Y-%m-%d"   # date prefix of appended entries (strftime)
+    # Extra formats for dates kept as text, tried after ISO and dd.mm.yyyy,
+    # e.g. ["%m/%d/%Y"] for US dates or ["%d/%m/%Y"] for UK ones. `init` detects them.
+    date_formats: list[str] = []
+
+
+class Followups(_Strict):
+    first_after_days: int = Field(10, ge=0)   # submitted -> follow-up 1
+    next_after_days: int = Field(14, ge=0)    # follow-up sent -> the next one
+    weekend_to_monday: bool = True
+
+
+class Messages(_Strict):
+    """Texts appended to the follow-up log. {date} and {status} are filled in."""
+    applied: str = "applied"
+    applied_with_followup: str = "applied, follow-up 1 on {date}"
+    followup_cancelled: str = "follow-up {date} cancelled: {status}"
+    stale_closed: str = "closed: no reply for {days} days"
+    followup_moved: str = "follow-up moved to {date}: {reason}"
+    followup_dropped: str = "no follow-up planned: {reason}"
+
+
+class Funnel(_Strict):
+    # group name -> substrings (any case). A value of the grouped column goes to the
+    # first group with a matching substring, otherwise to its own text up to the
+    # first bracket or dash: "Ashby (direct form)" -> "Ashby".
+    groups: dict[str, list[str]] = {}
+    # The same, for one column only: [funnel.by.source] "LinkedIn" = ["linkedin"].
+    # Used instead of `groups` when grouping by that column.
+    by: dict[str, dict[str, list[str]]] = {}
+
+
+class Safety(_Strict):
+    # Every write needs the user's yes: through the client's confirmation dialog
+    # (MCP elicitation) when it has one, otherwise through the token from a dry run.
+    confirm_writes: bool = True
+
+
+class Config(_Strict):
+    sheet: str
+    summary_sheet: str | None = None   # its formulas are stretched when rows are added
+    header_row: int | None = Field(None, ge=1)  # found automatically if not set
+    # field -> header text. Exact match wins, otherwise the first header
+    # (left to right) that starts with this text.
+    columns: dict[str, str]
+    date_columns: list[str] = ["applied_on", "followup_on"]
+    statuses: Statuses = Statuses()
+    values: Values = Values()
+    followups: Followups = Followups()
+    messages: Messages = Messages()
+    funnel: Funnel = Funnel()
+    safety: Safety = Safety()
+
+    @field_validator("columns")
+    @classmethod
+    def _required_columns(cls, cols: dict[str, str]) -> dict[str, str]:
+        missing = [f for f in REQUIRED_FIELDS if f not in cols]
+        if missing:
+            raise ValueError(f"[columns] must define {', '.join(missing)}")
+        return cols
+
+    def has(self, field: str) -> bool:
+        return field in self.columns
+
+    def custom_fields(self) -> list[str]:
+        return [f for f in self.columns if f not in KNOWN_FIELDS]
+
+
+class ConfigError(Exception):
+    pass
+
+
+def config_path(tracker: str | Path, explicit: str | Path | None = None) -> Path:
+    """The config file for a tracker: `explicit`, else next to the file
+    (my-tracker.xlsx -> my-tracker.tracker-mcp.toml), else for a Google Sheet
+    ~/.tracker-mcp/<sheet id>.tracker-mcp.toml."""
+    if explicit:
+        return Path(explicit).expanduser()
+    t = str(tracker)
+    if t.startswith(("https://docs.google.com/spreadsheets/", "gsheet:")):
+        from .gsheets import default_config_path
+        return default_config_path(t)
+    path = Path(t).expanduser()
+    return path.with_name(f"{path.stem}.tracker-mcp.toml")
+
+
+def load_config(tracker: str | Path, explicit: str | Path | None = None) -> Config:
+    path = config_path(tracker, explicit)
+    if not path.exists():
+        raise ConfigError(f"No config at {path}. Run `tracker-mcp init {tracker}` to write one from "
+                          "your tracker's headers, or `tracker-mcp example` for a commented template.")
+    try:
+        return Config.model_validate(tomllib.loads(path.read_text(encoding="utf-8")))
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigError(f"{path}: not valid TOML: {e}") from e
+    except ValidationError as e:
+        raise ConfigError(f"{path}: {e}") from e

tracker_mcp/example.tracker-mcp.toml

@@ -0,0 +1,98 @@
+# tracker-mcp config. You rarely write it by hand: on first start the server, or
+# `tracker-mcp init <tracker>`, writes one from your headers and dropdowns and marks
+# its guesses with CHECK. This file explains every key.
+#
+# Where it lives: next to the tracker as <name>.tracker-mcp.toml
+# (my-tracker.xlsx or my-tracker.csv -> my-tracker.tracker-mcp.toml). For a Google
+# Sheet: ~/.tracker-mcp/<sheet id>.tracker-mcp.toml. TRACKER_CONFIG points elsewhere.
+# Check how it maps your tracker:  tracker-mcp --check --tracker /path/my-tracker.xlsx
+# Edits apply on the server's next call; no restart needed.
+
+sheet ="Applications"          # the sheet with one row per application (a CSV file has one: its name)
+# summary_sheet = "Summary"     # optional: its formulas are stretched when rows are added
+# header_row = 1                # optional: found automatically (the row with the company header)
+# Columns that hold dates (read in any common format, written as yyyy-mm-dd).
+# Top-level keys go before the first [table]: below [columns] this would become a column.
+date_columns = ["applied_on", "followup_on"]
+
+# field = header text in the header row. Exact match wins, otherwise the first
+# header (left to right) that starts with this text, so "Follow-up" matches
+# "Follow-up date (1st)". company, role and status are required; the server
+# skips what a missing column would need (no follow-up column -> no follow-up tools).
+[columns]
+company = "Company"
+role = "Role"
+status = "Status"
+link = "Link"
+applied_on = "Applied on"
+channel = "Channel"
+response = "Response"
+notes = "Notes"
+followup_on = "Follow-up date"
+followup_contact = "Contact"
+followup_log = "Follow-up log"
+# num = "#"                     # running number, filled in for new rows
+# applied = "Applied?"          # a yes/no column; without it "applied" means status is not not_applied
+# reached = "Furthest stage"    # the furthest funnel stage; set_status moves it forward, never back
+# Any other key is a custom field, returned as is and settable via add_application's `extra`:
+# salary = "Salary"
+
+[statuses]
+# Allowed statuses come from the status column's dropdown (Excel data validation,
+# or a Google Sheets dropdown). fallback is used when there is none, as in a CSV file.
+not_applied = "Not applied"
+applied = "Applied"
+closed = ["Rejected", "Withdrawn", "No response", "Offer", "Closed"]   # no follow-ups for these
+fallback = ["Not applied", "Applied", "Screening", "Interview", "Offer", "Rejected", "Withdrawn", "No response", "Closed"]
+aliases = { "ghosted" = "No response" }   # other spellings -> the dropdown value
+waiting = ["Applied"]           # still waiting for the company; close_stale only touches these
+no_response = "No response"     # the status close_stale sets
+rejected = ["Rejected"]         # the company said no: counts as a reply in the funnel
+
+# Funnel stages after a reply, in order. A status in a later stage means the
+# application got through the earlier ones.
+[statuses.stages]
+screening = ["Screening"]
+interview = ["Interview", "Technical", "Final"]
+offer = ["Offer"]
+
+[values]
+yes = "Yes"
+no = "No"
+no_date = "—"                   # follow-up date when none is due
+separator = " | "               # between entries appended to a text cell
+stamp_format = "%Y-%m-%d"       # date prefix of appended entries and {date} in messages
+# Dates kept as text are read as ISO (2026-10-19) and dd.mm.yyyy; list other formats
+# here, tried in order. `init` detects them. US: ["%m/%d/%Y"]; UK: ["%d/%m/%Y"].
+date_formats = []
+
+[followups]
+first_after_days = 10           # applied -> follow-up 1
+next_after_days = 14            # follow-up sent -> the next one
+weekend_to_monday = true
+
+[messages]                      # appended to the follow-up log
+applied = "applied"
+applied_with_followup = "applied, follow-up 1 on {date}"
+followup_cancelled = "follow-up {date} cancelled: {status}"
+stale_closed = "closed: no reply for {days} days"
+followup_moved = "follow-up moved to {date}: {reason}"     # reschedule_followup
+followup_dropped = "no follow-up planned: {reason}"
+
+[funnel.groups]
+# For `funnel(by=...)` over a free-text column. A value goes to the first group
+# with a matching substring (any case), otherwise to its text up to the first
+# bracket or dash: "Ashby (direct form)" -> "Ashby".
+"Referral" = ["referral", "referred", "via a friend"]
+"Recruiter" = ["recruiter", "agency"]
+
+[funnel.by.source]
+# Groups for one column only, used instead of the ones above when grouping by it.
+"LinkedIn" = ["linkedin"]
+"Job boards" = ["hiring.cafe", "himalayas", "wellfound", "remote"]
+"Referral" = ["referral", "referred"]
+
+[safety]
+# Every write needs the user's yes: the client's confirmation dialog (MCP elicitation)
+# when it has one, otherwise the confirm token from a dry run the user saw.
+confirm_writes = true