Repository Guidelines

Project Structure & Module Organization

Core application code lives in src/aegis_gitea_mcp/:

server.py contains FastAPI routes and MCP/SSE endpoints.
auth.py, config.py, audit.py, and gitea_client.py handle security, settings, logging, and Gitea API access.
tools/ contains MCP tool implementations (for example tools/repository.py).

Tests are in tests/ and follow module-level coverage for auth, config, server, and integration flows. Utility scripts (key generation/rotation checks) are in scripts/. Container assets are in docker/ with runtime orchestration in docker-compose.yml.

Build, Test, and Development Commands

make install: install runtime dependencies.
make install-dev: install dev dependencies and pre-commit hooks.
make run: run the server locally (python -m aegis_gitea_mcp.server).
make test: run pytest with coverage output.
make lint: run ruff + mypy.
make format: run black and auto-fix lint issues.
make docker-up / make docker-down: start/stop local container stack.

Coding Style & Naming Conventions

Use Python 3.10+ with 4-space indentation and type hints for production code. Keep lines within 100 chars (Black/Ruff setting). Modules and functions use snake_case; classes use PascalCase; constants use UPPER_SNAKE_CASE. Prefer explicit exceptions and preserve exception chaining (raise ... from exc) when wrapping errors.

Testing Guidelines

Framework: pytest with pytest-asyncio and coverage (--cov=aegis_gitea_mcp). Place tests under tests/ using test_*.py naming and test_* function names. Add or update tests for behavior changes, especially around authentication, API error paths, and MCP tool responses.

Commit & Pull Request Guidelines

Prefer Conventional Commit style used in history (feat:, fix:, docs:, test:). Keep subjects imperative and specific (avoid messages like update or quick fix). PRs should include:

what changed and why,
linked issue(s) if available,
test/lint evidence (make test, make lint),
notes for config/security impact when touching auth, keys, or .env behavior.

Security & Configuration Tips

Never commit secrets. Use .env (see .env.example) for GITEA_TOKEN and MCP_API_KEYS. Use scripts/generate_api_key.py, scripts/rotate_api_key.py, and scripts/check_key_age.py for API key lifecycle management.

2.4 KiB Raw Blame History