Development Tools & Utilities¶
Essential tools and utilities for Agentic AI Security project development
This directory contains documentation for tools that make developing, testing, and maintaining the project easier. Whether you're setting up your environment, checking documentation quality, or managing Python dependencies, you'll find the resources you need here.
🎯 Quick Navigation¶
-
Python Environment Management
Fast, modern Python package management with UV - the recommended tool for this project.
-
Documentation Quality Tools
Scripts to find and fix broken links in markdown documentation.
-
Ubuntu/Linux Setup
Specific guidance for Ubuntu and Linux development environments.
Python Environment Management (UV)¶
Why UV? UV is a blazing-fast Python package manager (10-100x faster than pip) written in Rust. It's the recommended tool for managing Python dependencies in this project.
Available Resources¶
Quick References: - 📋 UV Quick Reference Card - Single-page cheat sheet (1 minute) - 📝 UV Cheat Sheet - Common commands and workflows (5 minutes)
Comprehensive Guides: - 📖 UV Complete Guide - Overview of all UV documentation (10 minutes) - 📘 UV Guide - Full usage guide with examples (20 minutes) - 🔄 pip vs UV Comparison - Migration guide from pip
Automation Scripts: - 🚀 Setup with UV - Automated MCP server setup demo - 🏗️ Complete Project Setup - Full project scaffolding
Quick Start with UV¶
# Install UV
pip install uv --break-system-packages
# Create virtual environment for this project
cd agentic-security-education
uv venv
source .venv/bin/activate
# Install project dependencies
uv pip install -r requirements.txt
# Speed comparison: UV is 10-100x faster than pip!
Common UV Commands for This Project¶
# Create environment
uv venv # Create .venv/
# Install packages
uv pip install mcp httpx pydantic # Install MCP dependencies
uv pip install -r requirements.txt # Install from requirements
# Manage dependencies
uv pip list # List installed packages
uv pip freeze > requirements.txt # Save current state
# Work with examples
cd examples/a2a_crypto_example
uv venv # Separate environment per example
source .venv/bin/activate
uv pip install -r requirements.txt
When to Use UV vs pip¶
| Scenario | Recommended Tool | Why |
|---|---|---|
| New project setup | UV | 10-100x faster |
| Installing dependencies | UV | Better resolution |
| CI/CD pipelines | UV | Faster builds |
| Legacy projects | pip | If UV not available |
| Documentation building | Either | Speed less critical |
Bottom line: Use UV for all Python development in this project unless you have a specific reason not to.
Documentation Quality Tools¶
These tools help maintain high-quality documentation by finding and fixing broken links.
Link Checker Scripts¶
Located in utils/ directory (not docs/supplementary/tools):
Primary Tool: - 🔍 markdown_link_checker.py - All-in-one checker with fix suggestions - Finds broken links - Suggests similar files as fixes - Calculates relative paths - Generates detailed reports
Supporting Tools: - ✅ check_markdown_links.py - Basic link validation - 🔧 fix_markdown_links.py - Fix suggester with auto-fix for 100% matches
Documentation: - 📖 Link Checker README - Complete usage guide - 📋 Fix Links Guide - Auto-fix documentation
Using Link Checkers¶
# From project root
# Check all documentation
python3 utils/markdown_link_checker.py docs/
# Check specific directory
python3 utils/markdown_link_checker.py docs/a2a/
# Auto-fix 100% matches (dry run first!)
python3 utils/fix_markdown_links.py docs/ --fix-100 --dry-run
# Actually fix
python3 utils/fix_markdown_links.py docs/ --fix-100
When to Run Link Checkers¶
- ✅ Before committing documentation changes
- ✅ After restructuring documentation
- ✅ Before major releases
- ✅ When adding new examples
- ✅ Periodically (monthly) to catch link rot
Ubuntu/Linux Specific Tools¶
Special resources for Ubuntu and Linux development environments.
Available Resources¶
- 🐧 Ubuntu Quickstart Guide - Getting started on Ubuntu
- 🛠️ MCP Testing on Ubuntu - Testing MCP servers without Claude Desktop
Ubuntu-Specific Notes¶
Package Installation:
# Use --break-system-packages for UV
pip install uv --break-system-packages
# Or use pipx (recommended for Ubuntu 24.04+)
sudo apt install pipx
pipx install uv
pipx ensurepath
MCP Server Testing: - Claude Desktop is not available for Linux - Use MCP Inspector (web-based) instead - See MCP Testing Ubuntu Guide
Tools by Use Case¶
Setting Up Development Environment¶
- UV Complete Guide - Modern Python environment
- Ubuntu Quickstart - Ubuntu-specific setup
- Complete Project Setup Script - Automated scaffolding
Working with Examples¶
- UV Quick Card - Fast dependency management
- Example-specific requirements.txt files
- Virtual environment per example (recommended)
Maintaining Documentation¶
- Markdown Link Checker - Find broken links
- Fix Markdown Links - Suggest/apply fixes
- Link Checker README - Full documentation
Contributing to the Project¶
- UV Guide - Dependency management
- Link Checker - Validate documentation
- Contributing Guidelines - Contribution process
Tool Comparison¶
Python Package Managers¶
| Feature | pip | UV | Recommendation |
|---|---|---|---|
| Speed | Baseline | 10-100x faster | ⭐ Use UV |
| Dependency resolution | Basic | Advanced | ⭐ Use UV |
| Lock files | Manual | Built-in | ⭐ Use UV |
| Python version management | No | Yes | ⭐ Use UV |
| Legacy support | Excellent | Good | Use pip if needed |
Link Checkers¶
| Script | Purpose | Best For |
|---|---|---|
| markdown_link_checker.py | All-in-one | ⭐ Most users |
| check_markdown_links.py | Basic checking | Simple validation |
| fix_markdown_links.py | Auto-fixing | Bulk updates |
Recommended Workflow¶
Initial Setup¶
# 1. Install UV
pip install uv --break-system-packages
# 2. Create project environment
cd agentic-security-education
uv venv
source .venv/bin/activate
# 3. Install dependencies
uv pip install -r requirements.txt
# 4. Verify installation
python -c "import mcp; print('MCP installed successfully')"
Daily Development¶
# Activate environment
source .venv/bin/activate
# Install new packages as needed
uv pip install <package>
# Update requirements
uv pip freeze > requirements.txt
# Check documentation links before committing
python3 utils/markdown_link_checker.py docs/
Before Committing¶
# Check for broken links
python3 utils/markdown_link_checker.py docs/
# Fix 100% matches
python3 utils/fix_markdown_links.py docs/ --fix-100 --dry-run
# Update requirements if dependencies changed
uv pip freeze > requirements.txt
# Git commit
git add .
git commit -m "Your changes"
Additional Resources¶
Official Documentation¶
- UV Documentation - Official UV repository
- Python Virtual Environments - Python venv docs
Project Documentation¶
- Installation Guide - Complete installation instructions
- Quick Start - Get running fast
- A2A Documentation - Protocol documentation
Related Tools¶
- MCP Examples - MCP server examples
- A2A Examples - A2A implementation examples
Contributing¶
Found a bug in these tools? Have a suggestion for improvement?
- Documentation issues: Edit the relevant guide
- Tool enhancements: Submit improvements via pull request
- New tools: Propose in GitHub Discussions
See Contributing Guidelines for details.
Questions?¶
For UV/Python questions: - Read the UV Complete Guide - Check the UV Cheat Sheet - See pip vs UV Comparison
For link checker questions: - Read the Link Checker README - See Fix Links Guide
For general setup: - See Installation Guide - Ubuntu users: Ubuntu Quickstart
Still stuck? - Email: robert@fischer3.org - GitHub: Open an issue
Last Updated: January 2026
Maintainer: Robert Fischer
Status: Active Maintenance