ADR-0002: Technology Stack and Implementation

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("mail-mcp")

@server.list_tools()
async def list_tools():
    # Define MCP tools

@server.call_tool()
async def call_tool(name: str, arguments: dict):
    # Implement tool calls

import httpx

async with httpx.AsyncClient() as client:
    response = await client.get(
        "https://lists.apache.org/api/mbox.lua",
        params={"list": "dev@maven.apache.org", "date": "2024-10"}
    )
    mbox_content = response.content

from elasticsearch import AsyncElasticsearch

es = AsyncElasticsearch(
    hosts=["http://elasticsearch:9200"],
    request_timeout=30
)

# Index a message
await es.index(
    index="maven-dev",
    id=message_id,
    document=message_doc
)

# Search
results = await es.search(
    index="maven-dev",
    query={"match": {"body_effective": search_term}}
)

import mailbox
import email

mbox = mailbox.mbox("2024-10.mbox")
for message in mbox:
    msg = email.message_from_bytes(message.as_bytes())
    subject = msg["Subject"]
    from_addr = msg["From"]
    body = msg.get_payload(decode=True)

import re

# JIRA references
JIRA_PATTERN = re.compile(r'\b(MAVEN|MNG|MRESOLVER)-\d+\b')

# GitHub PR references
GITHUB_PR_PATTERN = re.compile(r'#(\d+)')

# Version numbers
VERSION_PATTERN = re.compile(r'\b\d+\.\d+\.\d+(-[A-Za-z0-9]+)?\b')

# Decision keywords
DECISION_KEYWORDS = ["decided", "consensus", "agreed", "RESOLVED",
                     "WONTFIX", "[VOTE]", "[RESULT]"]

import re

def extract_effective_content(body: str) -> str:
    """Remove quoted lines (starting with >, |, etc.)"""
    lines = body.split('\n')
    effective_lines = []

    for line in lines:
        # Skip quoted lines
        if line.strip().startswith(('>',  '|')):
            continue
        # Skip attribution lines
        if re.match(r'^On .* wrote:', line):
            continue
        effective_lines.append(line)

    return '\n'.join(effective_lines)

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    elasticsearch_url: str = "http://localhost:59200"
    elasticsearch_index_prefix: str = "maven"
    data_path: str = "./data"
    mbox_cache_enabled: bool = True

    class Config:
        env_prefix = "MAIL_MCP_"
        env_file = ".env"

tests/
├── unit/
│   ├── test_mbox_parser.py
│   ├── test_metadata_extractor.py
│   └── test_quote_detector.py
├── integration/
│   ├── test_elasticsearch_client.py
│   └── test_mcp_tools.py
└── fixtures/
    └── sample.mbox

import structlog

log = structlog.get_logger()

log.info("indexing_message",
         message_id=msg_id,
         list="dev@maven.apache.org",
         date=msg_date)

[project]
name = "mail-mcp"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "mcp>=0.9.0",
    "elasticsearch>=8.11.0",
    "pydantic-settings>=2.0.0",
    "structlog>=24.1.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0",
    "pytest-cov>=4.1.0",
    "pytest-mock>=3.12.0",
    "ruff>=0.1.0",
]

[project.scripts]
retrieve-mbox = "mail_mcp.cli.retrieve_mbox:main"

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "UP", "S", "B", "A"]

# Install poetry globally (isolated via pipx)
pipx install poetry

# Configure poetry to create .venv in project directory
poetry config virtualenvs.in-project true

# Clone/navigate to project
cd mail-mcp

# Create virtual environment and install dependencies
poetry install

# Verify virtual environment
poetry env info

# Option A: Enter virtual environment shell
poetry shell
pytest                              # Run tests
python -m mail_mcp.server          # Start server

# Option B: Run commands via poetry (no shell activation)
poetry run pytest
poetry run python -m mail_mcp.server

# Start Elasticsearch (separate terminal)
docker-compose up elasticsearch

# Retrieve test data (Python script)
retrieve-mbox --date 2024-10
# Or: poetry run retrieve-mbox --date 2024-10

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry install --no-dev

# Copy application
COPY src/ ./src/

CMD ["poetry", "run", "python", "-m", "mail_mcp.server"]

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.11.0
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
    ports:
      - "9200:9200"
    volumes:
      - es-data:/usr/share/elasticsearch/data

  mail-mcp:
    build: .
    environment:
      - MAIL_MCP_ELASTICSEARCH_URL=http://elasticsearch:9200
    volumes:
      - ./data:/app/data
    depends_on:
      - elasticsearch

volumes:
  es-data: