Contributing to OpenSIPS MCP Server

April 28, 2026 ยท View on GitHub

Thank you for considering a contribution to the OpenSIPS MCP Server. This guide covers the development workflow, coding standards, and pull request process.

Development Setup

  1. Clone the repository and create a virtual environment:
git clone https://github.com/your-org/opensips-mcp-server.git
cd opensips-mcp-server
python -m venv .venv
source .venv/bin/activate
  1. Install in development mode with all extras:
pip install -e ".[dev]"
  1. Copy the example environment file and adjust values as needed:
cp .env.example .env

Running Tests

Run the full test suite:

make test

Run only unit tests (no external dependencies required):

make test-unit

Run integration tests (requires a running OpenSIPS and database):

make test-int

Code Style

This project enforces consistent style through tooling:

  • Linter: Ruff with rules E, F, I, N, W, UP, B, SIM enabled.
  • Formatter: Ruff formatter with a 100-character line length.
  • Type checking: mypy in strict mode with the Pydantic plugin.
  • Target version: Python 3.10+.

Run the linter and formatter before submitting:

make lint
make format
make type-check

Guidelines

  • Add type hints to all function signatures and return types.
  • Write docstrings for all public functions, classes, and modules.
  • Keep imports organized: standard library, third-party, then local (ruff handles this via isort rules).
  • Use async/await for all I/O-bound operations.

Adding New MCP Tools

  1. Create a new file in src/opensips_mcp/tools/ or add to an existing module.
  2. Import and use the shared mcp instance from opensips_mcp.server.
  3. Decorate with @mcp.tool() and apply RBAC via @require_permission("scope").
  4. Register the import in src/opensips_mcp/server.py.
  5. Add unit tests in tests/unit/.

Adding New Templates

  1. Add the .cfg.j2 file under src/opensips_mcp/cfg/templates/scenarios/ (for full scenarios) or partials/ (for reusable fragments).
  2. Register the scenario metadata in src/opensips_mcp/cfg/builder.py in the SCENARIOS dict.
  3. Add default parameters in scripts/validate_all_templates.py.
  4. Run python scripts/validate_all_templates.py to verify rendering.

Pull Request Process

  1. Create a feature branch from main:

    git checkout -b feature/my-feature

  2. Make your changes, ensuring tests pass and linting is clean.

  3. Write a clear PR description explaining what changed and why.

  4. PRs require at least one approval before merging.

  5. Squash-merge is preferred for a clean commit history.

Reporting Issues

Open an issue on GitHub with:

  • A clear description of the problem or feature request.
  • Steps to reproduce (for bugs).
  • OpenSIPS version and MCP server version.
  • Relevant logs or error messages.

License

By contributing, you agree that your contributions will be licensed under the Apache License 2.0.