🧙‍♂️ MCP MAGMA Handbook Server

An intelligent MCP (Model Context Protocol) server that provides AI assistants with comprehensive access to the MAGMA computational algebra system handbook through advanced vector search and semantic understanding.

✨ Features

• 🔍 Semantic Search: Natural language queries across the entire MAGMA handbook

• 📚 Smart Examples: Retrieve code examples categorized by complexity and topic

• 🧠 Code Explanation: Get detailed, contextual explanations of MAGMA code

• 🏷️ Category Filtering: Search within specific categories (syntax, functions, algorithms, examples, theory)

• ⚡ Vector Database: Powered by Supabase pgvector for lightning-fast similarity search

• 🎯 MAGMA-Optimized: Specialized parsing and understanding of MAGMA syntax and concepts

🎯 Perfect For

• 🔬 Researchers working with computational algebra

• 👨‍🎓 Students learning MAGMA and algebraic computation

• 💻 Developers building mathematical software

• 📖 Anyone needing quick access to MAGMA documentation

🚀 Quick Start

Installation

Prerequisites

• Node.js 18+

• OpenAI API key (for embeddings)

• Supabase account (free tier works great!)

• MAGMA Handbook PDF

Setup

1. Place your MAGMA handbook PDF in the data/pdfs/ directory:

   mkdir -p data/pdfs cp /path/to/MAGMA_HANDBOOK.pdf data/pdfs/

2. Index the handbook:

   npm run index

3. Configure your MCP client (e.g., Claude Desktop):

   { "mcpServers": { "magma-handbook": { "command": "npx", "args": ["mcp-magma-handbook"], "env": { "OPENAI_API_KEY": "your-api-key-here" } } } }

Usage

Once configured, the AI assistant can use these tools:

search_magma

Search for specific topics in the MAGMA handbook:

get_magma_example

Get code examples for mathematical topics:

explain_magma_code

Get explanations for MAGMA code:

💬 Example Conversations

Once configured, you can ask Claude questions like:

Basic Syntax:

"How do I define a finite field in MAGMA?"

Code Examples:

"Show me examples of computing with elliptic curves over finite fields"

Code Explanation:

"Explain this MAGMA code: G := PerfectClosure(GF(8)); H := AutomorphismGroup(G);"

Advanced Topics:

"Find algorithms for computing Galois groups of polynomials"

Research Help:

"What are the available functions for working with algebraic curves in MAGMA?"

Environment Variables

• OPENAI_API_KEY: Required for embedding generation (uses text-embedding-3-small)

• CHROMA_SERVER_HOST: Optional, for remote ChromaDB instance

• CHROMA_SERVER_PORT: Optional, for remote ChromaDB instance

Development

🛠️ Technical Details

Architecture

• Backend: Node.js with TypeScript

• Vector DB: Supabase with pgvector extension

• Embeddings: OpenAI text-embedding-3-small

• Document Processing: LangChain with optimized chunking

• Protocol: MCP (Model Context Protocol) 1.0

Performance

• 8,730+ indexed document chunks

• ~175 batches for efficient processing

• Sub-second search responses

• Semantic similarity scoring

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• MAGMA Team for the comprehensive computational algebra system

• Anthropic for the Model Context Protocol

• Supabase for the excellent vector database platform

• OpenAI for powerful embedding models

Made with ❤️ for the computational algebra community