jor-mcp: Instructions file for Codex

AI Agent Instructions for jor-mcp

Welcome, AI Agent. This AGENTS.md file defines the standard operating procedures, commands, and code style guidelines for the jor-mcp project. You must strictly adhere to these instructions to ensure high-quality, safe, and consistent contributions to this repository.

Project Context

• Name: jor-mcp
• Purpose: A Model Context Protocol (MCP) server for Ambiental Media, searching journalism content across WordPress and GitHub.
• Language: Python >= 3.12
• Core Libraries: fastmcp, uvicorn, httpx (async), pyjwt, opentelemetry
• Dependency Manager: uv

---

Prerequisite: Development Standards

Before making any changes, you must read and adhere to the rules defined in CONTRIBUTING.md. This includes:

• Language Constraint: All technical communication (commit messages, PR descriptions, code comments, variable names, and documentation) MUST be in English. (The only exception is the @mcp.tool() description parameter, which must remain in Portuguese).
• Using uv for all dependency management and task execution.
• Enforcing strict typing, linting (ruff), and formatting.
• Ensuring all new code maintains the 90% test coverage minimum.
• Validation: After writing or modifying code, use the make check command to run all linters, formatters, type checkers, and tests at once. Do not propose a Pull Request or consider a task finished until make check passes completely.
• Documentation Sync: For every proposed change, you MUST review and update the docs/ directory to ensure it accurately reflects the new code, new environment variables, or new architecture. Never submit code changes without checking if the technical, deployment, or usage documentation needs updating.

---

Code Style, Conventions & Python Best Practices

AI Agents operating in this repository must strictly adhere to the following community best practices and modern Python 3.12+ paradigms.

1. File Structure, Imports & Project Layout

• PEP 8: Style Guide for Python Code (The foundational aesthetic standard).
• PEP 20: The Zen of Python (Guiding philosophy for clean code).
• PEP 695: Type Parameter Syntax (Modern 3.12+ generics and type aliases).
• The "Src Layout": All source code must reside in src/. This forces tests to run against the installed package rather than the local folder, preventing accidental import leaks.
• Absolute Imports: Always use absolute imports anchored at src. Do not use relative imports (like from .config import ...).
  • Good: from src.config import GITHUB_TOKEN
  • Bad: from .config import GITHUB_TOKEN
• Import Ordering: Imports must be grouped and sorted. Run uv run ruff check . --fix to organize them automatically after writing code.
• Dependency Management: Use uv as the single source of truth for dependency management.
• Tooling: Use Ruff for all linting and formatting (rules: E, F, I, UP, S, B), replacing Flake8, Isort, and Black.