Contributing

Contributing

Thank you for your interest in contributing to MailAfrica Agent!

Agent Repository

The main agent code lives at github.com/cameltech/MailAfrica-Agent.

Development Setup

git clone https://github.com/cameltech/MailAfrica-Agent.git
cd MailAfrica-Agent
cp .env.example .env
# Fill in your API keys
uv sync

Running Locally

# MCP server (for testing with AI assistants)
uv run mailafrica-agent mcp
 
# Webhook server (for testing HTTP endpoints)
uv run mailafrica-agent webhook
 
# Connectivity check
uv run mailafrica-agent check

Code Style

  • Formatter/Linter: Ruff (configured in pyproject.toml)
  • Type hints: Required for all functions
  • Async: All I/O is async (httpx, aiosqlite, OpenAI SDK)
  • Tests: Add tests for new features

Adding a New MCP Tool

  1. Add the tool function to mailafrica_agent/mcp_server.py
  2. Use the @mcp.tool() decorator
  3. Add the corresponding API method to mailafrica_agent/mailafrica.py if needed
  4. Update the documentation

Example:

@mcp.tool()
async def my_new_tool(param1: str, param2: int = 10) -> str:
    """Description of what this tool does.
 
    Args:
        param1: Description of param1
        param2: Description of param2 (default: 10)
    """
    # Implementation
    return result

Documentation Repository

This documentation site lives at github.com/cameltech/MailAfrica-agent-docs.

Development Setup

git clone https://github.com/cameltech/MailAfrica-agent-docs.git
cd MailAfrica-agent-docs
npm install
npm run dev

The site runs at http://localhost:3000 with hot reload.

Adding or Editing Docs

All documentation content is in content/docs/ as MDX files. Edit them directly — changes appear instantly in dev mode.

File structure:

content/docs/
  meta.json            # Sidebar navigation order
  index.mdx            # Introduction
  quickstart.mdx       # Quickstart guide
  configuration.mdx    # Configuration reference
  mcp-server.mdx       # MCP server docs
  mcp-tools.mdx        # MCP tools reference
  auto-reply-agent.mdx # Agent docs
  webhooks.mdx         # Webhook setup
  architecture.mdx     # Architecture overview
  deployment.mdx       # Deployment guide
  api-reference.mdx    # API reference
  contributing.mdx     # This file

MDX Format

MDX files support standard Markdown plus JSX components:

---
title: Page Title
description: Page description for SEO
---
 
# Page Title
 
Content here with **bold**, *italic*, and `code`.
 
import { Callout } from "nextra-theme-docs"
 
<Callout type="info">
  This is an info callout.
</Callout>
 
## Code Blocks
 
```python
def hello():
    print("Hello, world!")

### Building

```bash
npm run build

The output is a standalone Next.js site that can be deployed to Vercel, Netlify, or any static hosting provider.

Reporting Issues

API Reference