nexus-mcp AGENTS.md

AGENTS.md - Guidelines for AI Coding Agents

Project Overview

Nexus MCP is a Python 3.13+ MCP server that enables AI models to invoke agent runners and integrations (Claude Code, Codex, OpenCode, OpenCode server) as tools. Built with FastMCP 3.1+.

OpenCode Gemini-family model names are OpenCode provider/model configuration, not support for a separate command-line runner.

Build, Lint, Test Commands

# Setup (first time)
uv sync
uv run pre-commit install

# Run all tests (unit + e2e, fast)
uv run pytest

# Run single test file
uv run pytest tests/unit/test_types.py

# Run single test function
uv run pytest tests/unit/test_types.py::test_prompt_request_valid

# Run with coverage (threshold: 90%)
uv run pytest --cov=nexus_mcp -v

# Integration tests (slow - real CLI binaries, run before PR only)
uv run pytest -m integration

# Type check
uv run mypy src/nexus_mcp

# Lint
uv run ruff check .

# Format
uv run ruff format .

# Auto-fix lint issues
uv run ruff check --fix .

# Run all pre-commit hooks
uv run pre-commit run --all-files

Branch and Commit Guidance

• Never commit to main unless explicitly directed.
• For issue or feature work, create a branch or worktree from origin/main, keep all changes there, and prepare the result as a PR.
• Never commit spec or plan documents unless explicitly asked.
• Do not use git add -A or git add .; stage explicit paths.
• Ask before adding new dependencies or making destructive changes.

Release Workflow Guidance

• Keep PyPI and TestPyPI Trusted Publishing jobs caller-owned in .github/workflows/release.yml. Do not replace them with j7an/shared-workflows/.github/workflows/publish-pypi.yml; PyPI does not authorize cross-repo reusable workflows as trusted-publisher workflows.
• When porting fixes from shared-workflows, use the caller-owned PyPI Trusted Publishing template and preserve Nexus-specific safeguards: VERIFY_PYTHON: "3.13", VERIFY_COMMAND: nexus-mcp --version, scripts/derive-published-version.sh before upload, TestPyPI and PyPI environment URLs, and MCP Registry publishing gated on GitHub release success.
• Keep setup-uv caching disabled in the TestPyPI verification job while it intentionally skips checkout and creates the throwaway .verify project later. If caching is re-enabled, the job must first provide real dependency files for setup-uv to hash so release runs do not emit empty-workdir or cache-dependency warnings.
• Pin reusable shared-workflows callers to immutable commit SHAs with a version comment, but keep PyPI publishing inline unless PyPI explicitly supports cross-repo reusable workflows for Trusted Publishing.