Python MCP Agent Workshop

A workshop for building AI agents using the Model Context Protocol (MCP) in Python. This project walks through implementing MCP server fundamentals (JSON-RPC framing, tool discovery, and tool execution) and ships two fully working tools:

1. Performance Profiler - Semantic Python code analysis using Astroid AST parsing to detect performance anti-patterns (N+1 queries, blocking I/O in async, inefficient loops, memory issues)
2. Keyword Search - Async file system search with statistical analysis

Link to Presentation Slides

Presentation Slides

Features

Performance Profiler

The performance profiler uses Astroid for semantic AST analysis, detecting:

• N+1 Query Detection - Identifies Django and SQLAlchemy ORM queries inside loops
• Blocking I/O in Async - Finds synchronous operations (open, time.sleep, requests) in async functions
• Inefficient Loop Patterns - Detects string concatenation in loops, deep nesting
• Memory Inefficiency Detection - Flags loading entire files into memory (read(), json.load, pickle.load)

Keyword Search

• Asynchronous file system search across multiple directories
• Multi-format text file support
• Statistical analysis and reporting

Why Astroid over Standard AST?

Unlike general linters (Pylint, Flake8), the performance profiler uses Astroid for semantic analysis:

• Type Inference: Understands what types variables hold, not just their names
• Call Resolution: Knows which function is actually being called (e.g., Django ORM vs. regular method)
• Cross-module Analysis: Can resolve imports and understand relationships
• Pattern Context: Detects patterns like "ORM query inside a loop" that require understanding code structure

Quick Start

# Clone and install
git clone <repository-url>
cd python-mcp-agent-workshop
poetry install

# Verify setup
python verification.py

# Start the MCP server
poetry run workshop-mcp-server

# Run tests (102 tests)
poetry run pytest

# Use the performance profiler agent (requires Qodo)
qodo performance_analysis --set file_path="path/to/code.py"

# Use the keyword search agent (requires Qodo)
qodo keyword_analysis --set keyword="{KEYWORD_HERE}"

Testing the Performance Profiler via MCP

# Start the server and send a JSON-RPC request
echo '{"jsonrpc":"2.0","id":1,"method":"call_tool","params":{"name":"performance_check","arguments":{"file_path":"src/workshop_mcp/server.py"}}}' | poetry run python -m workshop_mcp.server

Learning Path (From-Scratch MCP Server)

Start with the protocol fundamentals and build up the server step by step:

1. 00 - Introduction
2. 01 - Transport: Framing MCP Messages Over stdio
3. 02 - JSON-RPC 2.0: Validating and Routing Requests
4. 03 - Initialize: Capability Handshake
5. 04 - Tools: Advertising and Invoking Capabilities

Prerequisites

Before starting the workshop, ensure you have the following installed:

Required Software

1. Python 3.11+

   • Download from python.org
   • Verify: python --version

2. Poetry (Python dependency management)

   • Install: curl -sSL https://install.python-poetry.org | python3 -
   • Or via pip: pip install poetry
   • Verify: poetry --version

Key Dependencies

The project uses these core libraries (installed via poetry install):

• Astroid - Advanced AST analysis for semantic Python parsing (powers performance profiler)
• aiofiles - Async file I/O operations

Optional Tools

• Git for version control
• VS Code or your preferred IDE
• Docker (for containerized deployment)
• Qodo Command (optional, for agent execution)
  • Install: `npm install -g @qodo/command

... View full README on GitHub