mcp-deadmansnitch: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Dead Man's Snitch MCP Server

This MCP server provides tools to interact with Dead Man's Snitch, a monitoring service for scheduled tasks and cron jobs.

Essential Commands

# Run tests (uses pytest-asyncio in auto mode)
uv run pytest -v
uv run pytest tests/test_client.py::TestClass::test_method  # Run single test

# Type checking and linting
uv run mypy src/
uv run ruff check
uv run ruff format

# Run server (requires DEADMANSNITCH_API_KEY env var)
DEADMANSNITCH_API_KEY=your_key uv run mcp-deadmansnitch

Nix Development

# Enter dev shell (provides Python 3.12, uv, ruff, gcc)
nix develop

# Run directly
nix run .

# Build package
nix build .

See NIX.md for NixOS/Home Manager integration and secrets management.

Release Process

We use a beta release workflow to test on TestPyPI before production:

1. Beta releases (e.g., v0.1.2-beta1) publish to TestPyPI only for testing
2. Production releases (e.g., v0.1.2) require TestPyPI to succeed first, then publish to PyPI

See RELEASING.md for detailed release instructions.

Architecture Overview

The codebase follows a standard MCP server structure:

• src/mcp_deadmansnitch/server.py: Main MCP server implementation using FastMCP. Handles tool registration and request routing. Entry point is main().
• src/mcp_deadmansnitch/client.py: HTTP client for Dead Man's Snitch API using httpx. Implements all API interactions with proper authentication and error handling.

Key Design Patterns

1. API Authentication: Uses HTTP Basic Auth with API key as username (no password)
2. Response Format: All tools return consistent {"success": bool, "data": ..., "error": ...} format
3. Error Handling: API errors are caught and wrapped with context via @handle_errors decorator
4. Check-in URLs: Check-ins use separate URLs (https://nosnch.in/{token}) not the main API
5. Testability: Each action has a separate _impl function (e.g., list_snitches_impl) that can be unit tested directly without FastMCP decorator overhead
6. Unified Tool Design: Single snitch tool with action parameter reduces context usage (10 actions → 1 tool definition)