mcp-docs-ask AGENTS.md

Agent Instructions

Rules AI agents must follow when working in this repository.

---

Commit messages

Use Conventional Commits.

Header

• Format: <type>(optional scope): summary
• Use lowercase types (feat, fix, ci, chore, docs)
• Use scopes when relevant
• Write summaries in lowercase, imperative mood

Body

• Leave a blank line after the header
• Explain why, not what
• Use imperative, present tense
• Wrap lines at ~72 characters

The body is optional for trivial changes.

---

Release tags

• Use the bare version as the tag name — no v prefix (e.g. 0.1.0a4, not `v0.1.0a4``)
• Tags must be annotated (git tag -a) with a structured release-notes message

---

Commits

When generating commits via a shell:

• Do not pass generated messages directly to git commit -m
• Write the commit message to a file or standard input
• Use git commit -F <file> or git commit -F -
• Disable shell expansion when writing commit messages

This avoids issues with backticks, quotes, and other shell-expanded characters in generated commit messages.

---

Code style

Follow existing project conventions.

• Match formatting, naming, and file structure already in use
• Do not reformat unrelated code
• Prefer small, focused changes
• Avoid introducing new patterns without clear benefit

Language-specific rules

• Respect .editorconfig when present
• Do not disable lint rules without justification
• Prefer explicit, readable code over clever abstractions
• Ensure all changes pass ruff check ., ruff format --check ., pyright, and pytest

---

uv Workflow Rules

• Use uv exclusively for dependency management instead of pip
• Always prefix tool and script invocations with uv run so they execute inside the managed environment
• Do not manually create, activate, or delete .venv directories
• Use uv version <new-version> to bump the project version — do not edit pyproject.toml directly
• After bumping, update server.json so top-level version and packages[].version match
• Always commit pyproject.toml, uv.lock, and server.json together after a version bump