purple-mcp: Instructions file for Codex

AI Agent Guidelines for Purple MCP

This document provides essential guidelines for AI agents contributing to the Purple MCP codebase. For comprehensive details, see CONTRIBUTING.md.

Quick Reference

• Language: Python >=3.10
• Package Manager: uv (never use pip install or uv pip)
• Code Quality: Must pass uv run ruff format, uv run ruff check --fix, and uv run mypy
• Testing: Comprehensive tests required (unit + integration)
• Architecture: Strict separation between libs/ (business logic) and tools/ (MCP adapters)

Project Overview

Purple MCP is a Model Context Protocol (MCP) server providing access to SentinelOne Purple AI and Singularity Data Lake capabilities. The project emphasizes:

• Simplicity, readability, maintainability over cleverness
• Clean separation of concerns (Tools vs Libraries)
• Security-first development (HTTPS required, no secrets in code)
• Comprehensive testing (unit + integration with real API validation)

Current Tools and Libraries

The project provides the following MCP tools (in src/purple_mcp/tools/):

• purple_ai: Natural language queries to Purple AI
• sdl: Singularity Data Lake query execution and timestamp utilities
• alerts: Security alerts management (list, search, get details, notes, history)
• misconfigurations: Cloud/Kubernetes misconfiguration management
• vulnerabilities: Vulnerability management and tracking
• inventory: Unified Asset Inventory management
• purple_utils: Utility tools for Purple AI (status checks, available tools)

Each tool has a corresponding library in src/purple_mcp/libs/ with standalone, reusable business logic.

Critical Architecture Pattern: Tools vs Libraries

This is the most important architectural concept in the codebase:

Libraries (src/purple_mcp/libs/)

Libraries implement standalone, reusable business logic:

# ✅ CORRECT: Library with explicit configuration
import uuid
from purple_mcp.libs.purple_ai import (
    PurpleAIConfig,
    PurpleAIUserDetails,
    PurpleAIConsoleDetails,
    ask_purple,
)

user_details = PurpleAIUserDetails(
    account_id="account-123",
    team_token="team-token",
    session_id=uuid.uuid4().hex,
    email_address="[email protected]",
    user_agent="purple-mcp/1.0",
    build_date="2024-01-01",
    build_hash="abc123",
)

console_details = PurpleAIConsoleDetails(
    base_url="https://your-console.sentinelone.net",
    version="1.0.0",
)

config = PurpleAIConfig(
    graphql_url="https://your-console.sentinelone.net/web/api/v2.1/graphql",
    auth_token="your-auth-token",
    timeout=120.0,
    user_details=user_details,
    console_details=console_details,
)

response_type, message = await ask_purple(config, "Is Salt Typhoon in my environment?")