mcp-magma-handbook/docs/USAGE.md

Enhanced MCP server with multi-query search, hybrid search, and collections for MAGMA computational algebra system

# MAGMA Handbook MCP Server - Usage Guide

## Quick Start

### 1. Installation
```bash
npm install -g mcp-magma-handbook
```

### 2. Setup PDF
```bash
# Create data directory
mkdir -p data/pdfs

# Copy your MAGMA handbook PDF
cp /path/to/MAGMA_HANDBOOK.pdf data/pdfs/
```

### 3. Index the Handbook
```bash
npm run index
```

### 4. Configure MCP Client
Add to your Claude Desktop configuration:
```json
{
  "mcpServers": {
    "magma-handbook": {
      "command": "npx",
      "args": ["mcp-magma-handbook"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}
```

## Available Tools

### search_magma
Search for information in the MAGMA handbook.

**Parameters:**
- `query` (required): Search query
- `limit` (optional): Maximum results (default: 5)
- `category` (optional): Filter by category

**Categories:**
- `syntax`: Language syntax and grammar
- `function`: Built-in functions and intrinsics
- `algorithm`: Mathematical algorithms
- `example`: Code examples and usage
- `theory`: Mathematical theory and background
- `all`: All categories (default)

**Example:**
```
Search for "elliptic curve point addition" in the MAGMA handbook
```

### get_magma_example
Get code examples for specific mathematical topics.

**Parameters:**
- `topic` (required): Mathematical topic or function name
- `complexity` (optional): Complexity level (basic, intermediate, advanced)

**Example:**
```
Show me basic examples of working with finite fields in MAGMA
```

### explain_magma_code
Explain what a piece of MAGMA code does.

**Parameters:**
- `code` (required): MAGMA code to explain
- `context` (optional): Additional context

**Example:**
```
Explain this MAGMA code:
E := EllipticCurve([GF(101) | 1, 2]);
P := RandomPoint(E);
```

## Common Use Cases

### 1. Learning MAGMA Syntax
```
"How do I define a polynomial ring in MAGMA?"
"What's the syntax for creating a permutation group?"
```

### 2. Finding Functions
```
"Find functions for computing Galois groups"
"Search for elliptic curve functions"
```

### 3. Code Examples
```
"Show me examples of factoring polynomials"
"Get examples for computing with matrices over finite fields"
```

### 4. Understanding Code
```
"Explain this MAGMA code: [paste code here]"
"What does the IsIrreducible function do?"
```

## Best Practices

### Search Queries
- Use specific mathematical terms
- Include context about the mathematical area
- Try different phrasings if first search doesn't find what you need

### Getting Examples
- Start with basic complexity for learning
- Specify the mathematical context clearly
- Ask for multiple examples if needed

### Code Explanation
- Include the full code context
- Provide background about what you're trying to achieve
- Ask follow-up questions about specific parts

## Troubleshooting

### No Results Found
- Try broader search terms
- Check different categories
- Verify the PDF was indexed correctly

### Code Explanation Issues
- Make sure the code syntax is correct
- Include more context about the mathematical problem
- Break down complex code into smaller parts

### Performance Issues
- Large PDFs may take time to index initially
- Search results are cached for better performance
- Consider using more specific queries to reduce search time

## Environment Variables

Set these in your environment or `.env` file:

```bash
# Required: OpenAI API key for embeddings
OPENAI_API_KEY=your-api-key

# Optional: ChromaDB configuration
CHROMA_SERVER_HOST=localhost
CHROMA_SERVER_PORT=8000
```

## Development Mode

For development and testing:

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Build for production
npm run build
```