sn-mcp-server AGENTS.md

SignNow MCP Server

Stateless translation layer between AI agents and the SignNow API. Every tool response is curated through tools/models.py — never pass raw API JSON. Omit nulls, empty lists, and metadata the agent won't act on.

Agent-first

100% of the code is agent-written. When something comes out wrong, the fix belongs in automatic feedback (lint rules, type constraints, tests, import-linter contracts), not only in the code. Prose guidance in this file is the fallback, not the first line of defence.

Before closing a task where the human corrected you, ask: "what rule would have prevented this?" and propose adding it.

Self-check pyramid

Three layers, each bounded by what stays fast for its trigger. The point is to catch in the same conversation what CI would catch minutes later.

Trigger	What runs	Where defined	Budget
git commit	ruff-format + ruff on staged files; mypy src/ (~1 s); pytest tests/unit (~4 s)	.pre-commit-config.yaml (stages: [pre-commit])	<10 s
git push	full pytest (unit + integration + api) with coverage ≥70 %; lint-imports full-graph boundary check	.pre-commit-config.yaml (stages: [pre-push])	<30 s
PR / push to main	everything above + full-repo ruff + mypy + diff-coverage ≥80 % vs origin/main, posted as sticky PR comment	.github/workflows/ci.yml	<10 min

Install hooks with pre-commit install --install-hooks (SessionStart hook does this automatically in a fresh Claude Code session). Bypass with --no-verify only in genuine emergencies — if a hook is consistently wrong, fix the hook.

Enforced invariants

Rules in ## Boundaries below that can be checked mechanically, are — an edit that violates one fails immediately:

• signnow_client → sn_mcp_server is forbidden — import-linter contract in pyproject.toml.
• sn_mcp_server.tools → starlette/uvicorn is forbidden — same contract set.
• Every MCP tool returns a curated Pydantic model from sn_mcp_server.tools — tests/unit/sn_mcp_server/test_tool_response_shapes.py parametrizes over register_tools() and fails on raw dict/list/Any returns.
• Static types are clean — mypy src/ in strict mode, zero errors. New # type: ignore requires an inline reason.
• Lint is clean repo-wide — ruff check src/ tests/ (no diff-only escape hatch). New # noqa requires a reason.
• Coverage doesn't regress — global ≥70 % ([tool.coverage.report] fail_under), patch ≥80 % (CI diff-cover).