Log-Analyzer-with-MCP: Instructions file for Codex

AGENTS.md

This file provides guidance for AI coding agents working with this codebase.

Project Overview

Log-Analyzer-with-MCP is an MCP (Model Context Protocol) server providing AI assistants access to AWS CloudWatch Logs for searching, analysis, and cross-service correlation.

Tech Stack: Python 3.12+, uv (package manager), FastMCP, boto3, ruff

Build & Development Commands

# Installation
uv sync                      # Install all dependencies
source .venv/bin/activate    # Activate virtual environment

# Running the Server (local development)
python -m cw_mcp_server.server [--profile PROFILE] [--region REGION] [--stateless]
uv run python -m cw_mcp_server.server  # Alternative

# Via uvx (recommended for users)
uvx --from git+https://github.com/awslabs/Log-Analyzer-with-MCP cw-mcp-server [--profile PROFILE] [--region REGION] [--stateless]

# Linting & Formatting (run before committing)
pre-commit run --all-files   # Preferred - runs ruff lint and format
ruff check --fix .           # Lint with auto-fix
ruff format .                # Format code

# Manual Testing (no pytest configured yet)
python src/client.py list-groups [--prefix PREFIX]
python src/client.py search LOG_GROUP "query" [--hours N]
python src/client.py find-errors LOG_GROUP

Code Style Guidelines

File Headers

All Python files must start with the Apache-2.0 license header:

#!/usr/bin/env python3

# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0

Import Order (ruff-enforced)

1. Standard library imports
2. Third-party imports (boto3, mcp, etc.)
3. Local imports (relative imports with .)

import asyncio
import json
from typing import List, Optional, Callable

import boto3
from mcp.server.fastmcp import FastMCP

from .tools.search_tools import CloudWatchLogsSearchTools

Type Hints

Use type hints consistently. For Python 3.12+, prefer modern syntax but the codebase currently uses typing module imports for compatibility:

async def search_logs(
    self,
    log_group_name: str,
    query: str,
    hours: int = 24,
    start_time: str = None,
    end_time: str = None,
) -> str: