hidennsim 1.1.4
MCP server with JAX-based numerical tools
License: MIT
Requires Python: >=3.10
Keywords: mcp, jax, numerical, llm, claude

# HIDENNSIM - MCP Server with JAX Integration

A Model Context Protocol (MCP) server providing JAX-based numerical computation tools.

## Features

- MCP server with JAX-powered numerical tools (`add_jax`, `subtract_jax`, `multiply_jax`)
- Cython binary compilation for optimized performance
- Cross-platform support (Windows, macOS, Linux)
- Available on PyPI - simple `pip install` installation
- Integration guides for Claude Desktop and Cursor IDE

## Quick Start

### Installation Checklist

Follow these steps in order for successful setup:

- [ ] **Step 1:** Create virtual environment (`python -m venv hidennsim-env`)
- [ ] **Step 2:** Activate virtual environment
- [ ] **Step 3:** Install hidennsim (`pip install hidennsim`)
- [ ] **Step 4:** Install JAX (`pip install "jax[cpu]"`)
- [ ] **Step 5:** Verify JAX works (`python -c "import jax"`)
- [ ] **Step 6:** Configure your LLM (Claude Desktop or Cursor IDE) with full path to `hidennsim.exe`
- [ ] **Step 7:** Restart your LLM application

### 1. Create Virtual Environment (Recommended)

Creating a virtual environment isolates HIDENNSIM and its dependencies from your system Python.

**macOS/Linux:**
```bash
python3 -m venv hidennsim-env
source hidennsim-env/bin/activate
```

**Windows (PowerShell):**
```powershell
python -m venv hidennsim-env
.\hidennsim-env\Scripts\Activate.ps1
```

**Windows (Command Prompt):**
```cmd
python -m venv hidennsim-env
hidennsim-env\Scripts\activate.bat
```

> **Note:** Your terminal prompt should now show `(hidennsim-env)` indicating the virtual environment is active.

### 2. Install HIDENNSIM

> **Important:** Ensure your virtual environment is activated before running pip install commands.

```bash
pip install hidennsim
```

### 3. Install JAX (REQUIRED)

> **CRITICAL:** JAX must be installed in the same virtual environment as HIDENNSIM. The MCP server will fail to start without it.

**CPU-Only (Recommended for most users):**
```bash
pip install "jax[cpu]"
```

**GPU-Accelerated (Linux or WSL2 only):**

> **WINDOWS USERS:** JAX GPU (CUDA) support does **NOT** work on native Windows. GPU acceleration requires either:
> - **Linux** (native installation)
> - **WSL2** (Windows Subsystem for Linux 2)

For **Linux or WSL2** with NVIDIA GPU and CUDA 12:
```bash
pip install "jax[cuda12]"
```

**Verify Installation:**
```bash
python -c "import jax; print('JAX', jax.__version__, 'installed successfully')"
```

### 4. Configure LLM

#### Claude Desktop Configuration

1. **Open Settings:** Click Claude icon → **Settings** → **Developer** tab → **Edit Config**

2. **Add MCP Server Configuration:**

   **macOS/Linux:**
   ```json
   {
     "mcpServers": {
       "hidennsim": {
         "command": "/full/path/to/hidennsim-env/bin/hidennsim",
         "args": []
       }
     }
   }
   ```

   **Windows:**
   ```json
   {
     "mcpServers": {
       "hidennsim": {
         "command": "C:\\full\\path\\to\\hidennsim-env\\Scripts\\hidennsim.exe",
         "args": []
       }
     }
   }
   ```

   > **Important:** Replace the path with the actual absolute path to your virtual environment.

3. **Save and Restart** Claude Desktop

#### Cursor IDE Configuration

1. Press `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS)
2. Type "Settings" and select **Preferences: Open Settings (UI)**
3. Search for "MCP" and add the same configuration as above
4. Save and restart Cursor IDE

<details>
<summary>Configuration File Locations</summary>

**Claude Desktop:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

**Cursor IDE:**
- macOS: `~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- Windows: `%APPDATA%\Cursor\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
- Linux: `~/.config/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

</details>

## Available Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `add_jax` | Floating-point addition using JAX | `a`, `b` (numbers) |
| `subtract_jax` | Floating-point subtraction (a - b) | `a`, `b` (numbers) |
| `multiply_jax` | Floating-point multiplication (a * b) | `a`, `b` (numbers) |

## Troubleshooting

### MCP Server Fails to Start

**Error: "ModuleNotFoundError: No module named 'jax'"**

JAX is not installed. Fix:
```bash
# Activate virtual environment first, then:
pip install "jax[cpu]"
```

**Error: "spawn ... hidennsim.exe ENOENT"**

The executable path is incorrect. Verify:
1. Check the path exists:
   - Windows: `C:\path\to\hidennsim-env\Scripts\hidennsim.exe`
   - macOS/Linux: `/path/to/hidennsim-env/bin/hidennsim`
2. Use absolute paths (not relative) in your config
3. Restart your LLM application after config changes

### Verify Installation

```bash
# Check hidennsim
pip show hidennsim

# Check JAX
pip show jax

# Test MCP server
hidennsim --help
```

## System Requirements

- **Python:** 3.10 or higher
- **Operating System:** Windows 10+, macOS 12+, or Linux (Ubuntu 20.04+)
- **RAM:** 4GB minimum (8GB recommended for GPU acceleration)

## Documentation

- [Installation Guide](docs/installation.md)
- [Configuration Guide](docs/configuration.md)
- [Troubleshooting](docs/troubleshooting.md)

## License

MIT License - See LICENSE file for details.

## Support

- **Issues:** https://github.com/yourusername/hidennsim/issues