build: introduce python type checking (#81)

* build: introduce python type checking

* docs: document make typecheck in the maintainers guide

The other make targets are listed under "Running the tests" but
typecheck was missing, even though CI runs it on every PR.

---------

Co-authored-by: Michael Brooks <mbrooks@slack-corp.com>

Author: WilliamBergamin

.github/maintainers_guide.md

@@ -83,6 +83,7 @@ make test-eval   # LLM-judged skill evaluations (local only)
 make test        # both
 make lint        # Ruff linter (line-length 120)
 make format      # Ruff auto-format + fix
+make typecheck   # Mypy static type checks
 ```
 
 ### Testing in Claude Code

.github/workflows/ci-build.yml

@@ -32,6 +32,27 @@ jobs:
       - name: Run lint
         run: make lint
 
+  typecheck:
+    name: Typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Set up Python ${{ env.SUPPORTED_PY }}
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ env.SUPPORTED_PY }}
+      # mypy resolves imports, so it needs the runtime/test deps (deepeval, mcp,
+      # pydantic — all typed) as well as the tools, not just ruff/mypy.
+      - name: Install dependencies
+        run: make install
+      - name: Run typecheck
+        run: make typecheck
+
   test:
     name: Unit tests
     runs-on: ubuntu-latest
@@ -78,6 +99,7 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - lint
+      - typecheck
       - test
       - eval
     if: ${{ !success() && github.ref == 'refs/heads/main' && github.event_name != 'workflow_dispatch' }}

AGENTS.md

@@ -21,6 +21,7 @@ Requires Python 3.14+. Run `make install` before first use to set up the virtual
 | `make install` | Full setup: venv + deps |
 | `make lint` | Ruff linter (line-length=120) |
 | `make format` | Ruff auto-format + fix |
+| `make typecheck` | Mypy static type checks |
 | `make test-unit` | Fast validation tests (pytest) |
 | `make test-eval` | LLM-judged tests (runs DeepEval against Gemini) |
 | `make test` | Both unit + eval tests |
@@ -55,6 +56,7 @@ To add an eval scenario, append a `Scenario` (prompt + expected tool) to `SCENAR
 GitHub Actions (`.github/workflows/ci-build.yml`) gates every PR with:
 
 - **Lint** — `make lint` (Ruff)
+- **Typecheck** — `make typecheck` (mypy)
 - **Test** — `make test-unit` (pytest)
 - **Eval** — `make test-eval` (DeepEval + Gemini)
 

Makefile

@@ -2,9 +2,10 @@ VENV := .venv
 PYTHON := $(VENV)/bin/python
 PIP := $(VENV)/bin/pip
 RUFF := $(VENV)/bin/ruff
+MYPY := $(VENV)/bin/mypy
 DEEPEVAL := $(VENV)/bin/deepeval
 
-TARGETS := help install install-test install-tools clean lint format test test-unit test-eval cursor-install cursor-uninstall
+TARGETS := help install install-test install-tools clean lint format typecheck test test-unit test-eval cursor-install cursor-uninstall
 
 .PHONY: $(TARGETS)
 
@@ -42,6 +43,9 @@ format: ## Auto-format code with ruff
 	$(RUFF) format .
 	$(RUFF) check --fix .
 
+typecheck: ## Run mypy static type checks
+	$(MYPY)
+
 test: ## Run all tests (set testdir=<path> to route to the matching runner)
 ifdef testdir
 	@if echo "$(testdir)" | grep -q "tests/eval"; then \

pyproject.toml

@@ -16,7 +16,7 @@ test = [
     "pyyaml>=6.0,<7.0",
     "mcp>=1.13,<2.0",
 ]
-tools = ["ruff>=0.11,<1.0"]
+tools = ["ruff>=0.11,<1.0", "mypy>=1.11,<2.0", "types-PyYAML>=6.0,<7.0"]
 
 # This project is installed only to run the test suite; the importable package
 # is `tests`. Scope discovery to it so setuptools' flat-layout autodiscovery
@@ -39,3 +39,12 @@ known-first-party = ["tests"]
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"
+
+[tool.mypy]
+python_version = "3.14"
+files = ["tests", "scripts"]
+plugins = ["pydantic.mypy"]
+disallow_untyped_defs = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_return_any = true

scripts/cursor.py

@@ -31,11 +31,11 @@
 MARKETPLACE_NAME = "local"
 
 
-def get_plugin_key(plugin_name: str):
+def get_plugin_key(plugin_name: str) -> str:
     return f"{plugin_name}@{MARKETPLACE_NAME}"
 
 
-def get_target_path(plugin_key: str):
+def get_target_path(plugin_key: str) -> Path:
     return CURSOR_PLUGINS_PATH / plugin_key
 
 
@@ -44,7 +44,8 @@ def plugin_name() -> str:
     cursor_plugin = json.loads(
         (REPO_ROOT / ".cursor-plugin" / "plugin.json").read_text()
     )
-    return cursor_plugin["name"]
+    name: str = cursor_plugin["name"]
+    return name
 
 
 def plugin_files() -> set[Path]:
@@ -61,7 +62,8 @@ def plugin_files() -> set[Path]:
 def load_json(path: Path) -> dict:
     if not path.exists() or not path.read_text().strip():
         return {}
-    return json.loads(path.read_text())
+    data: dict = json.loads(path.read_text())
+    return data
 
 
 def save_json(path: Path, data: dict) -> None:

scripts/sync_versions.py

@@ -15,7 +15,8 @@
 
 def read_version(package_path: Path) -> str:
     """Return the ``version`` field from ``package.json``."""
-    return json.loads(package_path.read_text())["version"]
+    version: str = json.loads(package_path.read_text())["version"]
+    return version
 
 
 def write_version(plugin_path: Path, version: str) -> None:

tests/eval/test_tool_selection.py

@@ -188,7 +188,7 @@ class TestToolSelection:
     available_tools: list[ToolCall]
 
     @classmethod
-    def setup_class(cls):
+    def setup_class(cls) -> None:
         if not GEMINI_API_KEY:
             pytest.fail("GEMINI_API_KEY not set")
         if not SLACK_MCP_TOKEN:
@@ -198,7 +198,7 @@ def setup_class(cls):
         cls.model = make_judge_model()
         cls.available_tools = get_slack_mcp_tools() + get_all_skill_tools()
 
-    def teardown_method(self):
+    def teardown_method(self) -> None:
         # Gemini's free tier allows only 15 requests/minute. Each scenario makes one
         # model.generate() call, so sleep between scenarios to stay well under the
         # limit (~12 req/min) and avoid HTTP 429 / RESOURCE_EXHAUSTED.
@@ -209,7 +209,7 @@ def teardown_method(self):
         SCENARIOS,
         ids=[s["id"] for s in SCENARIOS],
     )
-    def test_tool_selection(self, scenario: Scenario):
+    def test_tool_selection(self, scenario: Scenario) -> None:
         accepted_tools = scenario["accepted_tools"]
         available_names = {t.name for t in self.available_tools}
         for accepted_tool in accepted_tools:

tests/unit/test_cross_skill_references.py

@@ -5,17 +5,17 @@
 
 
 class TestCrossSkillReferences:
-    def setup_method(self):
+    def setup_method(self) -> None:
         self.skills = discover_skills()
         self.skill_names = {skill.frontmatter.name for skill in self.skills}
 
-    def test_plugin_skill_references_target_real_skills(self):
+    def test_plugin_skill_references_target_real_skills(self) -> None:
         pattern = re.compile(rf"`{re.escape(PLUGIN_NAME)}:([a-z0-9-]+)`")
         for skill in self.skills:
             for target in pattern.findall(skill.body):
                 assert target in self.skill_names, f"{skill.path} references unknown skill `{PLUGIN_NAME}:{target}`"
 
-    def test_no_markdown_anchor_links(self):
+    def test_no_markdown_anchor_links(self) -> None:
         for skill in self.skills:
             # .find() returns -1 if the substring is not found
             anchor_index = skill.body.find("](#")
@@ -27,7 +27,7 @@ def test_no_markdown_anchor_links(self):
                 "cross-skill references must not use `[text](#anchor)` links"
             )
 
-    def test_no_bare_skill_file_paths(self):
+    def test_no_bare_skill_file_paths(self) -> None:
         for skill in self.skills:
             # .find() returns -1 if the substring is not found
             path_index = skill.body.find("SKILL.md")

tests/unit/test_discovery.py

@@ -3,13 +3,13 @@
 
 
 class TestSkillDiscovery:
-    def setup_method(self):
+    def setup_method(self) -> None:
         self.skills = discover_skills()
 
-    def test_skills_discovered(self):
+    def test_skills_discovered(self) -> None:
         assert len(self.skills) > 0, "No skills found"
 
-    def test_expected_skills_exist(self):
+    def test_expected_skills_exist(self) -> None:
         found = [s.frontmatter.name for s in self.skills]
         for expected in EXPECTED_SKILLS:
             assert expected in found