pal-mcp-server: Instructions file for Codex

AGENTS.md

This file provides guidance to AI agents like claude-code, codex, and others, when working with this repository.

Quick Reference Commands

Code Quality Checks

Before making any changes or submitting PRs, always run the comprehensive quality checks:

# Activate virtual environment first
workon pal

# if pal virtualenv does not exist (workon | grep pal)
mkvirtualenv pal

# Run all quality checks (linting, formatting, tests)
./code_quality_checks.sh

This script automatically runs:

• Ruff linting with auto-fix
• Black code formatting
• Import sorting with isort
• Complete unit test suite (excluding integration tests)
• Verification that all checks pass 100%

Run Integration Tests (requires API keys):

# Run integration tests that make real API calls
./run_integration_tests.sh

# Run integration tests + simulator tests
./run_integration_tests.sh --with-simulator

Server Management

Setup/Update the Server

# Run setup script (handles everything)
./run-server.sh

This script will:

• Set up Python virtual environment
• Install all dependencies
• Create/update .env file
• Configure MCP with Claude
• Verify API keys

View Logs

# Follow logs in real-time
./run-server.sh -f

# Or manually view logs
tail -f logs/mcp_server.log

Log Management

View Server Logs

# View last 500 lines of server logs
tail -n 500 logs/mcp_server.log

# Follow logs in real-time
tail -f logs/mcp_server.log

# View specific number of lines
tail -n 100 logs/mcp_server.log

# Search logs for specific patterns
grep "ERROR" logs/mcp_server.log
grep "tool_name" logs/mcp_activity.log

Monitor Tool Executions Only

# View tool activity log (focused on tool calls and completions)
tail -n 100 logs/mcp_activity.log

# Follow tool activity in real-time
tail -f logs/mcp_activity.log

# Use simple tail commands to monitor logs
tail -f logs/mcp_activity.log | grep -E "(TOOL_CALL|TOOL_COMPLETED|ERROR|WARNING)"