Contributing Guide

Guidelines for contributing to Arch MCP Server

Contributing Guide

Help improve the Arch MCP Server! We welcome contributions of all kinds.

For end users: Use the simple uvx installation method. This guide is for developers who want to contribute code.

Before You Start

1. Set up development environment

   Follow the Development Setup guide to clone the repository and install dependencies.

2. Review code standards

   Read the Code Standards to understand our coding practices.

3. Check existing issues

   Browse GitHub Issues to find something to work on or report bugs.

Contribution Guidelines

Core Principles

1. Follow the Arch Way - Simplicity, correctness, transparency
2. Add tests - Test both Arch and non-Arch scenarios
3. Document changes - Update docstrings and user-facing docs
4. Keep it minimal - No unnecessary abstractions
5. Handle errors gracefully - Never crash the server

What to Contribute

Bug Fixes

• Fix crashes or incorrect behavior
• Improve error messages
• Fix documentation typos

New Features

• Add new MCP tools (search, analysis)
• Add new resources (URI schemes)
• Add new prompts (workflows)
• Enhance security analysis

Performance

• Optimize slow operations
• Add caching where appropriate
• Reduce network requests

Documentation

• Improve user guides
• Add examples
• Fix unclear explanations

Adding Features

New Tools

1. Create async function in appropriate module (wiki.py, aur.py, pacman.py)
2. Add @server.tool() decorator in arch_ops_server.py
3. Add to list_tools() with schema
4. Add handler in call_tool()
5. Document in examples

New Resources

1. Define URI scheme (e.g., newtype://identifier)
2. Add parsing in read_resource()
3. Implement fetch logic
4. Add to list_resources()
5. Document usage

New Prompts

1. Design workflow
2. Add @server.prompt() decorator
3. Implement in get_prompt()
4. Add to list_prompts()
5. Create example

Pull Request Process

1. Fork and Branch

   # Fork on GitHub, then clone
   git clone https://github.com/YOUR_USERNAME/arch-mcp.git
   cd arch-mcp
   
   # Create feature branch
   git checkout -b feature/my-awesome-feature
   
2. Make Changes

   • Follow Code Standards
   • Add type hints and docstrings
   • Include debug logging
   • Handle errors properly
3. Test Your Changes

   Run the full testing checklist:

   • uv run pytest - all unit tests pass
   • uv run pytest --cov - coverage maintained or improved
   • Add tests for new functionality
   • Test with MCP Inspector - tools work correctly
   • Test on Arch Linux (if available)
   • Test on non-Arch system
   • Check logs for errors (stderr)
   • Verify error handling works
   • Update documentation
4. Commit and Push

   # Stage changes
   git add .
   
   # Commit using conventional commits format
   git commit -m "feat(tools): add package dependency analyzer
   
   - Implements dependency tree analysis
   - Added tests for cyclic dependencies
   - Updated examples documentation"
   
   # Push to your fork
   git push origin feature/my-awesome-feature
   
5. Open Pull Request

   1. Go to the original repository
   2. Click “New Pull Request”
   3. Select your branch
   4. Fill in description:
      • What does this PR do?
      • Why is it needed?
      • How was it tested?
   5. Submit!

Commit Message Format

Follow Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation only
• style: - Code style changes (formatting, no logic change)
• refactor: - Code change that neither fixes a bug nor adds a feature
• perf: - Performance improvement
• test: - Adding or updating tests
• chore: - Maintenance tasks

Examples:

# Feature
git commit -m "feat(aur): add package popularity sorting

Implement sorting by vote count and popularity score for AUR search results."

# Bug fix
git commit -m "fix(wiki): increase API timeout to 10 seconds

The previous 5s timeout was causing failures for large Wiki pages.

Fixes #123"

# Documentation
git commit -m "docs(readme): add MCP Inspector usage examples"

# Breaking change
git commit -m "feat(api)!: change search_aur return format

BREAKING CHANGE: search_aur now returns dict with 'packages' and 'metadata' keys instead of plain list."

Bad examples:

git commit -m "fixed stuff"
git commit -m "updates"
git commit -m "WIP"

Getting Help

GitHub Discussions

Ask questions and discuss ideas

GitHub Issues

Report bugs and request features

Additional Resources

• MCP Specification - Protocol documentation
• Architecture Guide - System design deep dive
• Arch Wiki API - MediaWiki API docs
• AUR RPC Interface - AUR API documentation

---

Thank you for contributing! 🎉