mvn-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file guides AI assistants working with the Maven MCP Server codebase.

Project Context

Maven MCP Server provides Model Context Protocol access to Maven Central repository for dependency management. It features intelligent caching, comprehensive version parsing, and security scanning capabilities optimized for AI-assisted development workflows.

Build/Test Commands

• Install dependencies: uv sync
• Install in dev mode: uv pip install -e ".[dev]"
• Run all tests: uv run pytest
• Run specific test: uv run pytest src/mvn_mcp_server/tests/tools/test_check_version.py
• Run specific test function: uv run pytest src/mvn_mcp_server/tests/tools/test_check_version.py::TestCheckVersion::test_success

Testing Guidelines & Troubleshooting

Async Test Requirements

• IMPORTANT: Async tests require pytest-asyncio plugin (included in dev dependencies)
• Verify async plugin is installed: uv run pytest --version should show asyncio-X.X.X
• If async tests fail with "async def functions are not natively supported", ensure dev dependencies are installed: uv pip install -e ".[dev]"

CI Environment Simulation

# Test with exact CI environment setup
uv sync --frozen                    # Use locked dependencies
uv pip install -e ".[dev]"         # Install with all dev dependencies
uv run pytest --cov=src/mvn_mcp_server --cov-report=xml --cov-report=term-missing --cov-fail-under=70 -v

Common CI Failures

1. Async test failures: Missing pytest-asyncio → Add to dev dependencies and update uv.lock
2. Coverage below 70%: Run coverage locally with exact CI command above
3. Import errors: Ensure all new dependencies are in pyproject.toml and uv.lock is updated

Code Style

• Use Python type hints for function parameters and return values
• Follow PEP 8 conventions for naming and formatting
• Use docstrings with Args/Returns/Raises sections in Google style
• Group imports: stdlib, third-party, local
• Error handling: Use specific exceptions from fastmcp.exceptions
• Class naming: PascalCase
• Function/variable naming: snake_case
• Use Pydantic models for data validation
• Validate input parameters and handle exceptions with appropriate error codes
• Tests should use pytest fixtures and mocks for external services