neuralmcp-mcp-adapter/README.md

Universal MCP adapter for Neural Memory MCP - Connect any IDE to persistent AI memory

# 🧠 Neural Memory MCP - Universal Adapter

A production-ready MCP (Model Context Protocol) adapter that connects any IDE to the Neural Memory MCP service for persistent AI memory.

[![NPM Version](https://img.shields.io/npm/v/neuralmcp-mcp-adapter.svg)](https://www.npmjs.com/package/neuralmcp-mcp-adapter)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 🚀 Quick Start

### Option 1: NPX (Recommended)
```bash
npx neuralmcp-mcp-adapter --header "Authorization:your-token-here"
```

### Option 2: Global Installation
```bash
npm install -g neuralmcp-mcp-adapter
neuralmcp-mcp --header "Authorization:your-token-here"
```

## 🎯 Get Your Token

1. Visit [https://neuralmcp.promptbetter.live/dashboard](https://neuralmcp.promptbetter.live/dashboard)
2. Click "Initialize Neural Network" to get your token
3. Copy your token (format: `ghz-ai-xxxxxxxx-xxxxxxxx`)

## ⚙️ IDE Configuration

### Cursor IDE

Add to your MCP settings (`Cmd/Ctrl + Shift + P` → "MCP Settings"):

```json
{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": [
        "neuralmcp-mcp-adapter@latest",
        "--header", "Authorization:your-token-here"
      ]
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "neuralmcp-mcp-adapter@latest", 
        "--header", "Authorization:your-token-here"
      ]
    }
  }
}
```

**Config file locations:**
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`

### VS Code (with MCP Extension)

Add to your MCP extension settings:

```json
{
  "mcp.servers": {
    "memory-mcp": {
      "command": "npx",
      "args": [
        "neuralmcp-mcp-adapter@latest",
        "--header", "Authorization:your-token-here"
      ]
    }
  }
}
```

## 🔧 Advanced Configuration

### Custom Backend URL
```bash
npx neuralmcp-mcp-adapter \
  --url "https://your-custom-backend.com" \
  --header "Authorization:your-token"
```

### Debug Mode
```bash
npx neuralmcp-mcp-adapter \
  --header "Authorization:your-token" \
  --debug
```

### Custom Timeout
```bash
npx neuralmcp-mcp-adapter \
  --header "Authorization:your-token" \
  --timeout 60000
```

## 🎮 Available MCP Commands

Once configured, use these commands in your IDE:

### Initialize Session
```
memory-mcp.getCurrentProject
memory-mcp.getMemory {"limitTokens": 4000}
```

### Store Memories
```
memory-mcp.addMemory {
  "type": "chat",
  "content": "User asked about React performance. Explained React.memo and useMemo usage."
}
```

### Memory Types
- `"chat"` - Conversation summaries
- `"code"` - Technical solutions and code snippets  
- `"task"` - Project tasks and todos
- `"summary"` - Session summaries

### Summarize Memories
```
memory-mcp.summarizeMemory
```

## 📋 Command Line Options

| Option | Description | Default |
|--------|-------------|---------|
| `--url <url>` | Backend server URL | `https://neuralmcp.promptbetter.live` |
| `--header <header>` | Authorization header (required) | - |
| `--timeout <ms>` | Request timeout in milliseconds | `30000` |
| `--debug` | Enable debug logging | `false` |
| `--help` | Show help information | - |
| `--version` | Show version number | - |

## 🔍 Troubleshooting

### Common Issues

**1. "Authorization header is required"**
```bash
# ❌ Wrong
npx neuralmcp-mcp-adapter

# ✅ Correct  
npx neuralmcp-mcp-adapter --header "Authorization:ghz-ai-your-token"
```

**2. "Backend health check failed"**
- Check your internet connection
- Verify the backend URL is correct
- Ensure your token is valid

**3. "Invalid JSON message"**
- Check IDE MCP configuration syntax
- Ensure command and args are properly formatted

### Debug Mode

Enable debug mode to see detailed logs:
```bash
npx neuralmcp-mcp-adapter --header "Authorization:your-token" --debug
```

## 🏗️ Architecture

```
IDE ←→ NPX Package ←→ Neural Memory MCP Service
    (stdin/stdout)     (HTTPS/REST API)
```

1. **IDE** communicates with local NPX package via MCP protocol
2. **NPX Package** translates MCP calls to REST API calls
3. **Neural Memory Service** processes and stores memories

## 🌍 Production Service

The Neural Memory MCP service runs at:
- **Dashboard**: https://neuralmcp.promptbetter.live/dashboard
- **Admin Panel**: https://neuralmcp.promptbetter.live/admin
- **API Health**: https://neuralmcp.promptbetter.live/health

## 📊 Features

- ✅ **Cross-Platform**: Works on Windows, macOS, Linux
- ✅ **IDE Agnostic**: Cursor, Claude Desktop, VS Code support
- ✅ **Production Ready**: HTTPS, SSL, high availability
- ✅ **Real-time**: Instant memory sync across IDEs
- ✅ **Secure**: Token-based authentication
- ✅ **Persistent**: Memories stored permanently
- ✅ **Intelligent**: AI-powered memory management

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## 📄 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🔗 Links

- **Homepage**: https://neuralmcp.promptbetter.live
- **GitHub**: https://github.com/gazzycodes/neural-memory-mcp
- **NPM**: https://www.npmjs.com/package/neuralmcp-mcp-adapter
- **Issues**: https://github.com/gazzycodes/neural-memory-mcp/issues

## 💡 Support

- Create an issue on GitHub
- Visit the dashboard for token management
- Check the admin panel for system status

---

Made with ❤️ by the Neural Memory MCP Team