insights-mcp: Instructions file for Codex

Insights MCP - AI Coding Assistant Guide

This document provides AI coding assistants with specific guidance for working with the Insights MCP codebase. Start by reading README.md for project overview, authentication setup, and client integrations.

This guide supplements the README with development-specific information and workflow guidance for AI coding assistants.

Architecture

Core Components

1. InsightsMCPServer (src/insights_mcp/server.py)

   • Main unified server that mounts multiple service toolsets
   • Handles authentication and configuration for all mounted toolsets
   • Supports selective toolset registration via --toolset argument

2. InsightsMCP Base Class (src/insights_mcp/mcp.py)

   • Abstract base class for all Insights MCP toolsets
   • Manages authentication and client initialization
   • Provides common functionality for Red Hat Insights API integration

3. InsightsClient (src/insights_mcp/client.py)

   • HTTP client for Red Hat Insights APIs with OAuth2 support
   • Handles service account and refresh token authentication
   • Provides error handling and proxy support

4. OAuth Middleware (src/insights_mcp/oauth.py)

   • Starlette middleware for OAuth flows in HTTP/SSE transports
   • Dynamic client registration and metadata proxying

Toolset Architecture

The project uses a toolset-based architecture where each service is implemented as a separate toolset:

Toolset Implementation Pattern:

• Most toolsets: src/<toolset_name>_mcp/server.py (e.g., src/vulnerability_mcp/server.py)
• Legacy pattern: src/insights_mcp/servers/<name>.py (e.g., example toolset)

Example toolsets (see src/insights_mcp/toolsets.py MCPS list for complete current list):

• image-builder (src/image_builder_mcp/server.py): Linux image building tools
• vulnerability (src/vulnerability_mcp/server.py): Security vulnerability management
• inventory (src/inventory_mcp/server.py): System inventory management