Skip to content

AGENTS.md

Latest commit

 

History

History
37 lines (31 loc) · 2.48 KB

AGENTS.md

File metadata and controls

37 lines (31 loc) · 2.48 KB
Raw

Repository Guidelines

Project Structure & Module Organization

  • src/: Python package with core modules — mcp_server/ (MCP server), scanner/, parser/, query/, embeddings/, database/, domain/, indexer/, utils/.
  • tests/: Mirrors src/ by area with test_*.py files; includes unit/, integration/, and feature folders.
  • docs/, alembic.ini, docker-compose.yml, config.example.yaml, settings.toml support docs, DB migrations, and config.
  • Entry points (installed via uv): mcp-code-server, mcp-scanner, mcp-indexer.

Build, Test, and Development Commands

  • Install deps: make dev-install (dev + pre-commit) or make install (prod only).
  • Lint/format/type-check: make lint, make format, make type-check, full QA: make qa.
  • Run tests: make test (unit), make test-integration, make test-all, coverage HTML: make coverage-html.
  • Quick feedback loop (Just): just unveil-next-error, just see-what-you-did-there.
  • Run locally: uv run mcp-code-server or uv run python -m src.mcp_server.

Coding Style & Naming Conventions

  • Python 3.11+, Black (88 cols), Ruff, isort; 4-space indents.
  • Type hints required in code paths (mypy strict settings); prefer explicit return types.
  • Imports: prefer absolute; relative imports are lint-banned.
  • Naming: snake_case for functions/vars, PascalCase classes, lower_snake_case.py modules, package dirs lowercase.

Testing Guidelines

  • Framework: pytest with markers: unit, integration, slow, requires_db, requires_openai.
  • Structure: tests/<area>/test_*.py; keep tests close to the feature area.
  • Run examples: uv run pytest -m "unit" -q, uv run pytest -m "integration" -v.
  • Coverage is preconfigured (--cov=src); open report via make coverage-html.

Commit & Pull Request Guidelines

  • Use Conventional Commits: e.g., feat: …, fix: …, docs: …, refactor: …, ci: …, chore: ….
  • Scope when helpful: fix(scanner): handle rate limit.
  • PRs: follow .github/pull_request_template.md — clear description, linked issue (Fixes #123), tests, and any screenshots where relevant.
  • Keep changes focused and ensure make qa passes locally.

Security & Configuration Tips

  • Never commit secrets. Use env vars (e.g., OPENAI_API_KEY) or .env locally.
  • Start from config.example.yaml → create config.yaml (untracked) for repos, DB, embeddings, and server settings.
  • Optional containers: docker-compose up -d to bring up services; prefer local uv for dev.