<div align="center">

# 🎓 Discrete Structures MCP Server

[![PyPI version](https://img.shields.io/pypi/v/discrete-structures-mcp.svg)](https://pypi.org/project/discrete-structures-mcp/)
[![Python Version](https://img.shields.io/pypi/pyversions/discrete-structures-mcp.svg)](https://pypi.org/project/discrete-structures-mcp/)
[![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=ZohaibCodez)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Downloads](https://img.shields.io/pypi/dm/discrete-structures-mcp.svg)](https://pypi.org/project/discrete-structures-mcp/)

**Professional-grade AI tools for discrete mathematics, algorithms, and cryptography**

[Installation](#-installation) • [Features](#-features) • [Quick Start](#-quick-start) • [Documentation](#-usage-with-claude-desktop) • [Examples](#-example-tool-calls)

</div>

---

<!-- mcp-name: io.github.ZohaibCodez/discrete-structures -->

## 🚀 Overview

**Discrete Structures MCP Server** is a comprehensive [Model Context Protocol](https://modelcontextprotocol.io) server that brings **21 powerful mathematical tools** to AI assistants like Claude Desktop, Cline, and Zed. Perfect for students, educators, and developers working with discrete mathematics, data structures, algorithms, and cryptography.

### Why Choose This Server?

- 🎯 **21 Production-Ready Tools** across 4 categories
- 📚 **Educational Focus** with step-by-step visualizations
- 🔒 **Enterprise Cryptography** (RSA, AES, Caesar, Vigenere)
- 📊 **Algorithm Visualizations** for sorting and graph algorithms
- 🧮 **Boolean Logic** with CNF/DNF conversion
- 🔢 **Number Theory** including prime factorization and modular arithmetic
- ⚡ **Fast Installation** via `uvx discrete-structures-mcp`
- 🌐 **MCP Registry Listed** for easy discovery

## ✨ Features

<table>
<tr>
<td width="50%">

### 🧮 Logic Tools (5 tools)
- **`evaluate_boolean`** - Evaluate boolean expressions with truth tables
- **`generate_truth_table`** - Complete truth table generation
- **`simplify_boolean`** - Boolean algebra simplification
- **`convert_to_cnf`** - Conjunctive Normal Form conversion
- **`convert_to_dnf`** - Disjunctive Normal Form conversion

### 🔢 Number Theory Tools (5 tools)
- **`is_prime`** - Primality testing with explanations
- **`prime_factors`** - Complete prime factorization
- **`gcd_lcm`** - Greatest Common Divisor & Least Common Multiple
- **`modular_arithmetic`** - Modular operations (add, multiply, power)
- **`euler_totient`** - Euler's φ function calculation

</td>
<td width="50%">

### 📊 Algorithm Visualizers (6 tools)
- **`visualize_bubble_sort`** - O(n²) sorting with comparisons
- **`visualize_quick_sort`** - O(n log n) divide-and-conquer
- **`visualize_merge_sort`** - Stable merge sort visualization
- **`visualize_binary_search`** - O(log n) search algorithm
- **`visualize_dijkstra`** - Shortest path in weighted graphs
- **`visualize_bfs_dfs`** - Graph traversal algorithms

### 🔐 Cryptography Tools (5 tools)
- **`caesar_cipher`** - Classical shift cipher (educational)
- **`vigenere_cipher`** - Polyalphabetic substitution
- **`rsa_encrypt_decrypt`** - RSA public-key cryptography
- **`aes_encrypt_decrypt`** - AES-256 symmetric encryption
- **`generate_rsa_keys`** - Secure RSA key pair generation

</td>
</tr>
</table>

## 📦 Installation

### ⚡ Quick Install (Recommended)

```bash
# Install and run directly with uvx
uvx discrete-structures-mcp
```

### 📥 Install with pip

```bash
# Install globally
pip install discrete-structures-mcp

# Run the server
discrete-structures-mcp
```

### 🛠️ Development Installation

```bash
# Clone the repository
git clone https://github.com/ZohaibCodez/discrete-structures-ai-platform.git
cd discrete-structures-ai-platform/mcp-server

# Install with uv
uv sync

# Run locally
uv run discrete-structures-mcp
```

## 🎯 Quick Start

### Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "discrete-structures": {
      "command": "uvx",
      "args": ["discrete-structures-mcp"]
    }
  }
}
```

### Usage with Other MCP Clients

Compatible with any MCP client:
- **[Cline](https://github.com/cline/cline)** - VS Code extension
- **[Zed](https://zed.dev/)** - Modern code editor
- **[Continue](https://continue.dev/)** - AI code assistant
- Custom MCP clients via Python SDK

## 💻 Example Tool Calls

```python
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

server_params = StdioServerParameters(
    command="uvx",
    args=["discrete-structures-mcp"]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # List available tools
        tools = await session.list_tools()
        print([tool.name for tool in tools.tools])
        
        # Call a tool
        result = await session.call_tool("gcd_lcm", {"numbers": "48,18"})
        print(result)
```

## 💻 Example Tool Calls

### 🔢 Number Theory Examples

#### Calculate GCD and LCM
```python
# Find greatest common divisor and least common multiple
result = await session.call_tool("gcd_lcm", {
    "numbers": "48,18,24"
})
# Output: {"gcd": 6, "lcm": 144, "explanation": "..."}
```

#### Prime Factorization
```python
result = await session.call_tool("prime_factors", {
    "number": "84"
})
# Output: {"factors": [2, 2, 3, 7], "factorization": "2² × 3 × 7"}
```

#### Modular Arithmetic
```python
result = await session.call_tool("modular_arithmetic", {
    "operation": "power",
    "base": "3",
    "exponent": "5",
    "modulus": "7"
})
# Output: {"result": 5, "explanation": "3^5 mod 7 = 5"}
```

### 🧮 Boolean Logic Examples

#### Generate Truth Table
```python
result = await session.call_tool("generate_truth_table", {
    "expression": "(A & B) | (~A & C)"
})
# Returns: Complete truth table with all input combinations
```

#### Simplify Boolean Expression
```python
result = await session.call_tool("simplify_boolean", {
    "expression": "(A & B) | (A & ~B)"
})
# Output: {"simplified": "A", "steps": ["..."]}
```

#### Convert to CNF
```python
result = await session.call_tool("convert_to_cnf", {
    "expression": "(A | B) & (C | D)"
})
# Output: Expression in Conjunctive Normal Form
```

### 📊 Algorithm Visualization Examples

#### Visualize Bubble Sort
```python
result = await session.call_tool("visualize_bubble_sort", {
    "array": "64,34,25,12,22,11,90"
})
# Returns: Step-by-step sorting with comparisons and swaps
```

#### Binary Search
```python
result = await session.call_tool("visualize_binary_search", {
    "array": "1,3,5,7,9,11,13,15",
    "target": "7"
})
# Output: Search path with index calculations
```

#### Dijkstra's Algorithm
```python
result = await session.call_tool("visualize_dijkstra", {
    "graph": "A-B:4,A-C:2,B-C:1,B-D:5,C-D:8",
    "start": "A",
    "end": "D"
})
# Returns: Shortest path with distances
```

### 🔐 Cryptography Examples

#### RSA Encryption
```python
# Generate keys
keys = await session.call_tool("generate_rsa_keys", {
    "key_size": "2048"
})

# Encrypt message
encrypted = await session.call_tool("rsa_encrypt_decrypt", {
    "action": "encrypt",
    "message": "Hello World",
    "public_key": keys["public_key"]
})

# Decrypt message
decrypted = await session.call_tool("rsa_encrypt_decrypt", {
    "action": "decrypt",
    "ciphertext": encrypted["ciphertext"],
    "private_key": keys["private_key"]
})
```

#### AES Encryption
```python
result = await session.call_tool("aes_encrypt_decrypt", {
    "action": "encrypt",
    "text": "Sensitive Data",
    "key": "my-secret-key-32-characters-long"
})
# Output: {"ciphertext": "...", "iv": "...", "tag": "..."}
```

#### Caesar Cipher
```python
result = await session.call_tool("caesar_cipher", {
    "action": "encrypt",
    "text": "HELLO",
    "shift": "3"
})
# Output: {"result": "KHOOR", "explanation": "Each letter shifted by 3"}
```

## 🎓 Use Cases

- **Computer Science Education** - Teach algorithms and data structures
- **Cryptography Learning** - Understand encryption methods
- **Mathematics Research** - Number theory and discrete math
- **Algorithm Analysis** - Visualize complexity and performance
- **Code Interviews** - Practice common algorithmic problems
- **Academic Projects** - Implement mathematical concepts

## 🏗️ Technical Stack

- **Language**: Python 3.11+
- **Framework**: Model Context Protocol (MCP)
- **Math Libraries**: SymPy, NumPy
- **Crypto**: Python Cryptography library
- **Graphs**: NetworkX
- **Build**: UV package manager

## 📊 Performance

- **Startup Time**: < 2 seconds
- **Response Time**: < 100ms for most operations
- **Memory**: < 50MB baseline
- **Concurrency**: Async/await support

## 🔒 Security Note

**Educational Purpose**: Caesar and Vigenere ciphers are for learning only. Use AES or RSA for real-world encryption.

## 🤝 Contributing

We welcome contributions! Here's how to get started:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** changes (`git commit -m 'Add amazing feature'`)
4. **Push** to branch (`git push origin feature/amazing-feature`)
5. **Open** a Pull Request

See [CONTRIBUTING.md](../CONTRIBUTING.md) for detailed guidelines.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links & Resources

### Official Links
- 🏠 **Homepage**: [GitHub Repository](https://github.com/ZohaibCodez/discrete-structures-ai-platform)
- 📦 **PyPI Package**: [discrete-structures-mcp](https://pypi.org/project/discrete-structures-mcp/)
- 🌐 **MCP Registry**: [Official Listing](https://registry.modelcontextprotocol.io/v0.1/servers?search=ZohaibCodez)
- 📝 **Documentation**: [README](https://github.com/ZohaibCodez/discrete-structures-ai-platform#readme)
- 🐛 **Issue Tracker**: [Report Bugs](https://github.com/ZohaibCodez/discrete-structures-ai-platform/issues)

### Community
- 💬 **Discussions**: [GitHub Discussions](https://github.com/ZohaibCodez/discrete-structures-ai-platform/discussions)
- 📢 **Announcements**: Watch repository for updates
- 🤝 **Contributing**: See [contribution guide](../CONTRIBUTING.md)

### MCP Resources
- 📖 **MCP Documentation**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- 🛠️ **MCP SDK**: [Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- 🌟 **MCP Servers**: [Community Servers](https://github.com/modelcontextprotocol/servers)

## 📈 Project Stats

![GitHub stars](https://img.shields.io/github/stars/ZohaibCodez/discrete-structures-ai-platform?style=social)
![GitHub forks](https://img.shields.io/github/forks/ZohaibCodez/discrete-structures-ai-platform?style=social)
![GitHub issues](https://img.shields.io/github/issues/ZohaibCodez/discrete-structures-ai-platform)
![GitHub pull requests](https://img.shields.io/github/issues-pr/ZohaibCodez/discrete-structures-ai-platform)

## 🙏 Acknowledgments

- Model Context Protocol team at Anthropic
- SymPy and NumPy communities
- Python Cryptography developers
- NetworkX graph library maintainers
- All contributors and users

## 📞 Support

- 📧 **Email**: Open an issue for support
- 💬 **Discussions**: Use GitHub Discussions
- 🐛 **Bugs**: Report via Issues
- 💡 **Features**: Request via Issues with enhancement label

---

<div align="center">

**Made with ❤️ for the discrete mathematics and computer science community**

⭐ **Star this repo** if you find it useful! ⭐

[Report Bug](https://github.com/ZohaibCodez/discrete-structures-ai-platform/issues) · [Request Feature](https://github.com/ZohaibCodez/discrete-structures-ai-platform/issues) · [Contribute](https://github.com/ZohaibCodez/discrete-structures-ai-platform/pulls)

</div>
