Skip to main content

​
Development Setup

Set up your environment for developing and testing the Arch MCP Server.
This guide is for developers who want to contribute to the project. For end users, use the simple uvx installation instead.

​
Prerequisites

  • Python 3.11+ - Check version: python --version
  • uv - Modern Python package manager
  • Git - Version control

​
Install uv

sudo pacman -S uv

​
Clone Repository

git clone https://github.com/nihalxkumar/arch-mcp.git
cd arch-mcp

​
Install Development Dependencies

uv sync
This installs all dependencies including development tools.

​
Testing

​
Run Test Suite

The project uses pytest for comprehensive automated testing: 
# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run with coverage report
uv run pytest --cov=arch_ops_server --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_utils.py -v
Current test coverage:
  • 92 tests covering core functionality
  • 59% overall coverage (90-98% on core modules)
  • Tests for utils, wiki, AUR, and pacman modules
  • Async test support via pytest-asyncio
Test modules:
  • test_utils.py - Platform detection, command execution (97% coverage)
  • test_wiki.py - Search, page retrieval, API/scraping (98% coverage)
  • test_pacman.py - Package info, updates, parsing (90% coverage)
  • test_aur.py - Security analysis, metadata risk scoring (52% coverage)

​
Test with MCP Inspector

Interactive browser-based testing - essential for development: 
./test_inspector.sh
This opens a web interface where you can:
  • Test tools interactively - Call any tool with custom parameters
  • Try resources - Test URI schemes with different inputs
  • Explore prompts - See prompt workflows in action
  • Debug responses - Inspect JSON responses and errors
Use MCP Inspector during development to quickly test changes without restarting your MCP client.

​
Testing Checklist

Before submitting code, verify:
  • Unit tests pass - uv run pytest (all tests green)
  • Coverage maintained - uv run pytest --cov (no significant drops)
  • New features tested - Add tests for any new functionality
  • MCP Inspector works - All tools return expected results
  • Arch Linux testing - Test on Arch if available
  • Non-Arch testing - Verify remote API fallbacks work
  • Error logs clean - No unexpected errors in stderr
  • Error handling - Test failure scenarios with pytest
  • Documentation updated - User-facing docs reflect changes
  • Pylance (type checking)
  • Ruff (linting)

​
Type Checking

# Install mypy for type checking
uv pip install mypy

# Run type checks
mypy arch_ops_server.py

​
Next Steps

Code Standards

Learn coding standards and best practices

Contributing Guide

Guidelines for submitting contributions