# MCP Tutor Server (Python)

An AI tutoring system that runs as a Model Context Protocol (MCP) server, allowing Claude to access and interact with your local educational materials to provide personalized tutoring based on your actual course content.

## Features

- **Privacy First**: All your educational materials stay on your local machine
- **Universal Format Support**: Works with PDFs, Markdown, and text files
- **Smart Search**: Find concepts and explanations across all your materials
- **Interactive Learning**: Generate quizzes, summaries, and detailed explanations
- **Resource Access**: Claude can read full documents for comprehensive answers

## What It Does

The tutor server provides Claude with 5 powerful tools:

1. **explain_concept** - Search for and explain specific concepts from your materials
2. **search_materials** - Full-text search across all documents with context
3. **summarize_topic** - Generate brief or detailed summaries of topics
4. **generate_quiz** - Create practice questions at various difficulty levels
5. **list_topics** - Browse all available educational materials

All your documents are also exposed as resources, allowing Claude to read complete files when needed.

## Installation

### Prerequisites

- Python 3.10 or higher
- Claude Desktop app

### Setup

1. Clone or download this directory:
```bash
cd tutor-mcp-python
```

2. Install the package:
```bash
pip install -e .
```

Or using uv (recommended):
```bash
uv pip install -e .
```

3. Configure Claude Desktop:

Edit your Claude Desktop config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the tutor server:

```json
{
  "mcpServers": {
    "tutor": {
      "command": "python",
      "args": ["-m", "tutor_mcp.server"],
      "env": {
        "TUTOR_MATERIALS_PATH": "/absolute/path/to/materials"
      }
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "tutor": {
      "command": "tutor-mcp",
      "env": {
        "TUTOR_MATERIALS_PATH": "/absolute/path/to/materials"
      }
    }
  }
}
```

4. Add your educational materials:

Create a `materials` directory and add your files:

```
materials/
├── computer-science/
│   ├── algorithms.pdf
│   └── data-structures.md
├── mathematics/
│   └── calculus-notes.txt
└── physics/
    └── quantum-mechanics.pdf
```

5. Restart Claude Desktop

## Usage

Once configured, you can ask Claude questions about your materials:

- "Explain the concept of binary search trees based on my materials"
- "Search my notes for information about quantum entanglement"
- "Generate a quiz on recursion with 5 medium difficulty questions"
- "Summarize what my materials say about Big O notation"
- "What topics do I have materials for?"

Claude will use the tutor server to access your files and provide personalized answers based on your actual course content.

## Supported File Formats

- `.txt` - Plain text files
- `.md`, `.markdown` - Markdown files
- `.pdf` - PDF documents (text extraction)

## Configuration

### Environment Variables

- `TUTOR_MATERIALS_PATH` - Path to your educational materials directory (default: `./materials`)

### Materials Directory

Organize your materials however you like. The server will:
- Recursively scan all subdirectories
- Index all supported file types
- Make them searchable and accessible to Claude

## Development

### Running from Source

```bash
python -m tutor_mcp.server
```

### Running Tests

```bash
pip install -e ".[dev]"
pytest
```

### Project Structure

```
tutor-mcp-python/
├── src/
│   └── tutor_mcp/
│       ├── __init__.py
│       └── server.py          # Main server implementation
├── materials/                  # Your educational materials
├── pyproject.toml             # Project configuration
└── README.md
```

## How It Works

1. **Startup**: Server indexes all documents in your materials directory
2. **Connection**: Claude Desktop connects via stdio transport
3. **Queries**: You ask educational questions in Claude
4. **Tool Use**: Claude calls tutor tools to search/summarize/explain
5. **Response**: Server returns relevant content with context
6. **Answer**: Claude synthesizes the information into helpful responses

## Privacy & Security

- All data stays on your local machine
- No materials are sent to external services
- Claude only accesses files through the MCP protocol
- You control exactly which directory is accessible

## Troubleshooting

### Server not appearing in Claude Desktop

1. Check the config file syntax (valid JSON)
2. Verify Python is in your PATH
3. Check Claude Desktop logs for errors
4. Restart Claude Desktop completely

### No materials found

1. Verify `TUTOR_MATERIALS_PATH` is an absolute path
2. Check that the directory exists and contains supported files
3. Ensure file extensions are lowercase or supported (.txt, .md, .pdf)

### PDF text extraction issues

Some PDFs (especially scanned images) may not extract text properly. For best results:
- Use text-based PDFs, not scanned images
- Consider converting scanned PDFs using OCR
- Alternatively, extract text manually to .txt or .md files

## License

MIT

## Contributing

Contributions welcome! This is an open-source project to help students learn better with AI assistance.

## Acknowledgments

Built with:
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP SDK
- [pypdf](https://github.com/py-pdf/pypdf) - PDF text extraction
- [Claude](https://claude.ai/) - AI assistant by Anthropic