npm package: @neomint-pst/mintapp-mcp-bridge
Description: MINTapp MCP Bridge - Connects Claude Desktop to MINTapp's HTTP MCP gateway via stdio
Author: NEOMINT
Latest version: 1.0.0

# @neomint-pst/mintapp-mcp-bridge

**MINTapp MCP Bridge** - Connects Claude Desktop directly to your MINTapp's HTTP MCP gateway via stdio

This package is specifically designed for MINTapp users who want to use their gateway's connected MCP servers directly in Claude Desktop. It acts as a bridge between Claude Desktop's stdio interface and MINTapp's HTTP MCP gateway.

## ✨ Features

- ✅ **Purpose-Built for MINTapp** - Specifically designed for MINTapp's HTTP MCP gateway
- ✅ **Claude Desktop Integration** - Uses Claude Desktop's native stdio transport
- ✅ **No Setup Required** - Distributed as standalone npm package
- ✅ **Auto-Discovery** - Automatically connects to MINTapp's default gateway port (3001)
- ✅ **All Your Tools** - Access tools from all your MINTapp-connected servers in Claude
- ✅ **Error Handling** - Comprehensive error handling with helpful messages

## 🚀 Quick Start

### Prerequisites

- Node.js 16+ installed
- MINTapp running with connected MCP servers

### Usage with Claude Desktop

1. **Start MINTapp** and connect to any MCP servers (the HTTP gateway starts automatically on port 3001)

2. **Configure Claude Desktop** by adding this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mintapp-gateway": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge"]
    }
  }
}
```

3. **Restart Claude Desktop** - All your MINTapp gateway tools are now available!

## 📁 Config File Locations

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

## 🔧 Configuration Options

### Basic Usage (Default Port 3001)
```json
{
  "mcpServers": {
    "mintapp-gateway": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge"]
    }
  }
}
```

### Custom Port
```json
{
  "mcpServers": {
    "mintapp-gateway": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge", "--port", "3002"]
    }
  }
}
```

### With Debug Logging
```json
{
  "mcpServers": {
    "mintapp-gateway": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge", "--debug"]
    }
  }
}
```

## 🔧 Command Line Options

```bash
npx @neomint-pst/mintapp-mcp-bridge [options]

Options:
  --host <host>      Host to connect to (default: localhost)
  --port <port>      Port to connect to (default: 3001)
  --timeout <ms>     Connection timeout in ms (default: 30000)
  --debug            Enable debug logging
  --help, -h         Show help message
```

## 📋 How It Works

1. **MINTapp starts** and you connect to various MCP servers (filesystem, web-search, etc.)
2. **HTTP Gateway auto-starts** at `http://localhost:3001` exposing all connected tools
3. **Claude Desktop launches** this bridge package via npx
4. **Bridge connects** to MINTapp's HTTP gateway and translates between HTTP and stdio
5. **Claude sees all tools** from your MINTapp gateway as if they were local MCP servers

```
Claude Desktop ←→ stdio ←→ MINTapp Bridge ←→ HTTP ←→ MINTapp Gateway ←→ Your MCP Servers
```

## 🛠 Typical Workflow

### 1. Start MINTapp
```bash
# Your MINTapp starts up
npm start
```

### 2. Connect MCP Servers in MINTapp
- Add filesystem server: `/path/to/your/files`
- Add web search server: `@modelcontextprotocol/server-web-search`
- Add any other MCP servers you need

### 3. Claude Desktop Configuration
```json
{
  "mcpServers": {
    "mintapp": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge"]
    }
  }
}
```

### 4. Use in Claude Desktop
All your MINTapp tools are now available in Claude Desktop! You can:
- Search the web
- Read and write files
- Use any other tools from your connected servers

## 🔍 Troubleshooting

### "Connection refused" Error

**Problem**: Bridge can't connect to MINTapp's HTTP gateway

**Solutions**:
1. Make sure MINTapp is running and has at least one MCP server connected
2. Check that the HTTP gateway started on port 3001 (check MINTapp logs)
3. Try with debug logging: `--debug` flag
4. Verify port with custom port: `--port <your-port>`

### "No tools available" in Claude Desktop

**Problem**: Bridge connects but Claude sees no tools

**Solutions**:
1. Ensure you have MCP servers connected in MINTapp
2. Check MINTapp's gateway status - should show running servers and tools
3. Try refreshing tools in MINTapp UI
4. Check debug logs for JSON-RPC communication issues

### Connection Timeout

**Solutions**:
1. Increase timeout: `--timeout 60000`
2. Check MINTapp is responding (open `http://localhost:3001` in browser)
3. Restart MINTapp to refresh the gateway

### Debug Logging

Enable detailed logging to see what's happening:
```json
{
  "mcpServers": {
    "mintapp": {
      "command": "npx",
      "args": ["-y", "@neomint-pst/mintapp-mcp-bridge", "--debug"]
    }
  }
}
```

## 🔐 Security

- Bridge only connects to localhost by default
- All communication happens locally between your processes
- No external network access required
- Security depends on your MINTapp configuration

## 📄 License

MIT License - see LICENSE file for details

## 🤝 Support

- **GitHub Issues**: https://github.com/neomint/mintapp-mcp-bridge/issues
- **Email**: support@neomint.com
- **MINTapp Documentation**: [Link to MINTapp docs when available]

## 🏷 Changelog

### v1.0.0
- Initial release for MINTapp integration
- stdio to HTTP bridge functionality
- Claude Desktop compatibility
- Debug logging support
- Error handling and timeout configuration