MCP Handley Lab Toolkit

⚠️ BETA SOFTWARE: This toolkit is in active development. While functional, APIs may change and some features may have rough edges. Issues and pull requests are welcome!

A toolkit that bridges AI assistants with command-line tools and services. Built on the Model Context Protocol (MCP), it enables AI models like Claude, Gemini, or GPT to interact with your local development environment, manage calendars, analyze code, and automate workflows through a standardized interface.

Requirements

• Python: 3.10 or higher
• MCP CLI: pip install mcp[cli] (for Claude Desktop integration)

System Dependencies (Optional)

Some tools require additional system packages:

• code2prompt tool: cargo install code2prompt
• word tool: pandoc for document conversion
• email tools: msmtp, mutt, notmuch for email management

Quick Start

Get up and running in 5 minutes:

# 1. Clone and enter the project
git clone [email protected]:handley-lab/mcp-handley-lab.git
cd mcp-handley-lab

# 2. Set up Python environment (requires Python 3.10+)
python3 -m venv venv
source venv/bin/activate

# 3. Install the toolkit (includes mcp[cli] automatically)
pip install -e .

# 4. Set up API keys and authentication
# Export in your .bashrc/.zshrc, a .env file, or the current session
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="AIza..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GROK_API_KEY="grok-..."
export GOOGLE_MAPS_API_KEY="AIza..."
# Note: Google Calendar requires OAuth setup (see tool description below)

# 5. Register essential tools with Claude (add others as needed)
# Note: Registering too many MCP tools can cause context bloat and reduce tool calling accuracy
# Only register the tools you actively need to maintain optimal performance
claude mcp add gemini --scope user mcp-gemini
claude mcp add openai --scope user mcp-openai
claude mcp add arxiv --scope user mcp-arxiv
claude mcp add google-maps --scope user mcp-google-maps
claude mcp add word --scope user mcp-word

# Add additional tools as needed:
# claude mcp add claude --scope user mcp-claude
# claude mcp add grok --scope user mcp-grok
# claude mcp add py2nb --scope user mcp-py2nb
# claude mcp add code2prompt --scope user mcp-code2prompt
# claude mcp add google-calendar --scope user mcp-google-calendar
# claude mcp add vim --scope user mcp-vim
# claude mcp add email --scope user mcp-email
# claude mcp add mathematica --scope user mcp-mathematica

# 6. Verify tools are working
# Use /mcp command in Claude to check tool status

Available Tools

🤖 AI Integration (gemini, openai, claude, grok)

Connect with major AI providers

• Persistent conversations with memory
• Image analysis and generation
• Claude, Gemini, OpenAI, and Grok support
• Claude example: > ask gemini to review the changes you just made

📚 ArXiv (arxiv)

Search and download academic papers from ArXiv

• Search by author, title, or topic
• Download source code, PDFs, or LaTeX files
• Claude example: > find all papers by Harry Bevins on arxiv

📓 Python/Notebook Conversion (py2nb)

Convert between Python scripts and Jupyter notebooks

• Bidirectional Python ↔ Jupyter notebook conversion
• Preserve markdown comments and cell structure
• Claude example: > convert this Python script to a Jupyter notebook

🔍 Code Flattening (code2prompt)

Convert codebases into structured, AI-readable text

• Flatten project structure and code into markdown format
• Include git diffs for review workflows
• Claude example: > use code2prompt and gemini to look for refactoring opportunities in my codebase
• Requires: code2prompt CLI tool (cargo install code2prompt)

📅 Google Calendar (google-calendar)

Manage your calendar programmatically

• Create, update, and search events
• Find free time slots for meetings
• Claude example: > when did I last meet with Jiamin Hou?, and when would be a good slot to meet with her again this week?
• Requires: OAuth2 setup

🗺️ Google Maps (google-maps)

Get directions and routing information

• Multi-modal directions (driving, walking, cycling, transit)
• Real-time traffic awareness with departure times
• Alternative routes and waypoint support
• Claude example: > what time train do I need to get from Cambridge North to get to Euston in time for 10:30 on Sunday?
• Requires: Google Maps API key (GOOGLE_MAPS_API_KEY)

📄 Word Documents (word)

Process Word documents for analysis and conversion

• Extract comments with referenced text context
• Analyze tracked changes and revision history
• Convert between DOCX ↔ Markdown, HTML, plain text
• Document metadata and structure analysis
• Claude example: > extract all the comments from this feedback document and show me the author breakdown
• Requires: pandoc for document conversion

🧮 Mathematica (mathematica)

Execute Mathematica code and computations

• Run WolframScript commands and notebooks
• Perform symbolic and numerical calculations
• Generate plots and visualizations
• Export results in various formats
• Claude example: > use Mathematica to solve this differential equation and plot the solution
• Requires: WolframScript installed and licensed

✏️ Interactive Editing (vim)

Open vim for user input when needed

• Create or edit content interactively
• Useful for drafting emails or documentation
• Claude example: > use vim to open a draft of a relevant email

📧 Email Management (email)

Comprehensive email workflow integration

• Send emails with msmtp
• Compose, reply, and forward with Mutt
• Search and manage emails with Notmuch
• Contact management and OAuth2 setup
• Claude example: > compose an email to the team about the project update
• Requires: msmtp, mutt, and notmuch installed and configured

Using AI Tools Together

You can use AI tools to analyze outputs from other tools. For example:

# 1. Use code2prompt to summarize your codebase
# Claude will run: mcp__code2prompt__generate_prompt path="/your/project" output_file="/tmp/summary.md"

# 2. Then ask Gemini to review it
# Claude will run: mcp__gemini__ask prompt="Review this codebase" files=[{"path": "/tmp/summary.md"}]

This pattern works because:

• code2prompt creates a structured markdown file with your code
• AI tools like Gemini can read files as context
• The AI gets a view of your codebase without hitting token limits

Testing

This project uses pytest for testing. The tests are divided into unit and integration categories.

1. Install development dependencies:

   pip install -e ".[dev]"

2. Run all tests:

   pytest

3. Run only unit or integration tests:

   # Run unit tests (do not require network access or API keys)
   pytest -m unit
   
   # Run integration tests (require API keys and network access)
   pytest -m integration

Contributing

We welcome contributions! See CONTRIBUTING.md for detailed guidelines.

Quick start for contributors:

1. Fork and clone the repository
2. Create a feature branch
3. Make your changes following existing patterns
4. Run tests and linting: pytest && ruff check .
5. Bump version: python scripts/bump_version.py
6. Submit a pull request

License

MIT License - see LICENSE for details.