Maxwell Bot MCP Server

Maxwell Bot: Skill-Agnostic AI Agent Framework

A sample project demonstrating a skill-agnostic AI agent that dynamically loads domain expertise from markdown skill definitions, with an example magnetics/electromagnetics SME skill.

Project Overview

This project showcases a generic agent framework that can work with any domain expertise by loading tool definitions and system prompts from skill.md files. The magnetics example demonstrates how to build an expert-level AI agent for electromagnetics and magnetic circuit design using real equations and precise numerical computations.

Key features:

• Skill-agnostic architecture - works with any domain by loading from skill.md files
• Hand-rolled agentic loop (no framework dependencies) for transparent agent reasoning
• Dynamic tool discovery - parses tool schemas directly from skill.md markdown
• Retrieval-augmented generation (RAG) - Chroma vector database with semantic search over domain knowledge
• Real physics equations with SI unit constants (e.g., μ₀ = 4π×10⁻⁷ H/m)
• 8 specialized magnetics tools for field calculations, circuit analysis, and unit conversions
• Configuration-driven design - change agent behavior by editing skill.md, no code changes needed
• Comprehensive test suite validating all tools and calculations

Architecture

┌──────────────────────────────────────┐
│   CLI (cli.py)                       │
│   - Skill selection & discovery      │
│   - Interactive chat interface       │
└────────────────┬─────────────────────┘
                 │
┌────────────────▼─────────────────────┐
│   SkillAgent (Anthropic SDK)         │
│   - Agentic loop                     │
│   - Tool orchestration               │
│   - skill.md parsing & loading       │
└────────────────┬─────────────────────┘
                 │
        ┌────────▼─────────┐
        │  Skills/         │
        │  <skill-name>/   │
        │  - skill.md      │
        │  - tool configs  │
        └────────┬─────────┘
                 │
     ┌───────────┴───────────┬──────────────┐
     │                       │              │
┌────▼─────┐  ┌─────────┐ ┌─┴──────────┐ ┌─┴──────┐
│ Fields   │  │Circuits │ │ Materials  │ │Convert │
│ (fields) │  │(circuits)│ │ (materials)│ │(units) │
└──────────┘  └─────────┘ └────────────┘ └────────┘

Project Structure

maxwell_bot/
├── agent/
│   ├── agent.py               # SkillAgent: generic, skill-agnostic framework
│   └── __init__.py
├── mcp_server/
│   ├── tools/
│   │   ├── fields.py          # B/H field calculations (solenoid, wire, flux, energy)
│   │   ├── circuits.py        # Reluctance, MMF calculations
│   │   ├── materials.py       # Material property lookup (6 materials)
│   │   ├── converters.py      # Unit conversions (T↔Gauss, Wb↔Maxwell, etc.)
│   │   └── __init__.py
│   └── __init__.py
├── skills/
│   └── maxwell_magnetics/
│       └── skill.md           # Skill definition: tool reference, use cases, boundaries
├── tests/
│   ├── test_fields.py         # Field calculation tests
│   ├── test_circuits.py       # Circuit calculation tests
│   ├── test_materials.py      # Material lookup tests
│   ├── test_converters.py     # Conversion tests
│   └── __init__.py
├── cli.py                     # Interactive CLI entry point
├── requirements.txt           # Python dependencies
├── .gitignore
└── README.md                  # This file

Installation & Setup

Prerequisites

• Python 3.9+
• pip package manager
• An Anthropic API key

Step 1: Clone or Download the Project

git clone https://github.com/jkearney126/maxwell_bot.git
cd maxwell_bot

Step 2: Create a Virtual Environment (Recommended)

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Set Your Anthropic API Key

export ANTHROPIC_API_KEY="sk-ant-..."  # On Windows: set ANTHROPIC_API_KEY=sk-ant-...

Or, for persistent setup, add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export ANTHROPIC_API_KEY="your-key-here"

Running the Agent

Interactive Chat Interface

python cli.py

This launches an interactive chat where you can:

• Select from available skills (if multiple exist)
• Choose from 5 example prompts (by number 1-5)
• Type your own custom questions
• See animated thinking spinner while Claude responds
• Type quit or exit to exit

The agent auto-discovers skills from the skills/ directory and loads tool definitions and expertise from each skill's skill.md file.

Skill Definition Files (skill.md)

Each skill lives in skills/<skill-name>/ with a skill.md file that defines:

• Use Case Decision Table: Maps problem types to appropriate tools
• Tool Reference: Complete tool specifications with:
  • Input/output schemas (parsed automatically by the agent)
  • Use cases and assumptions
  • Physics eq