Keep/mcp-server/README-SSE.md

# Memento MCP SSE Server

Server-Sent Events (SSE) version of the Memento MCP Server for remote N8N access.

## 🎯 Purpose

This SSE server allows N8N (or other MCP clients) running on **remote machines** to connect to Memento via HTTP/SSE instead of stdio.

### stdio vs SSE

| Feature | stdio (`index.js`) | SSE (`index-sse.js`) |
|---------|-------------------|---------------------|
| **Connection** | Local process | Network HTTP |
| **Remote access** | ❌ No | ✅ Yes |
| **Use case** | Claude Desktop, local tools | N8N on remote machine |
| **Port** | N/A | 3001 |

## 🚀 Quick Start

### 1. Install Dependencies
```bash
cd mcp-server
npm install
```

### 2. Start the Server

**Option A: PowerShell Script (Recommended)**
```powershell
.\start-sse.ps1
```

**Option B: Direct Node**
```bash
npm run start:sse
# or
node index-sse.js
```

### 3. Verify Server is Running

Open browser to: `http://localhost:3001`

You should see:
```json
{
  "name": "Memento MCP SSE Server",
  "version": "1.0.0",
  "status": "running",
  "endpoints": {
    "sse": "/sse",
    "message": "/message"
  }
}
```

## 🌐 Get Your IP Address

### Windows
```powershell
ipconfig
```
Look for "IPv4 Address" (usually 192.168.x.x)

### Mac/Linux
```bash
ifconfig
# or
ip addr show
```

## 🔌 N8N Configuration

### Method 1: MCP Client Community Node

If your N8N has the MCP Client node installed:

1. Open N8N Settings → MCP Access
2. Add new server:
   ```json
   {
     "name": "memento",
     "transport": "sse",
     "url": "http://YOUR_IP:3001/sse"
   }
   ```
   Replace `YOUR_IP` with your machine's IP (e.g., `192.168.1.100`)

3. Enable "Available in MCP" for your workflow
4. Use MCP Client node to call tools

### Method 2: HTTP Request Nodes (Fallback)

Use N8N's standard HTTP Request nodes with the REST API:
- POST `http://YOUR_IP:3000/api/notes` (Memento REST API)

## 🛠️ Available Tools (9)

All tools from the stdio version are available:

1. **create_note** - Create new note
   ```json
   {
     "name": "create_note",
     "arguments": {
       "content": "My note",
       "title": "Optional title",
       "color": "blue",
       "images": ["data:image/png;base64,..."]
     }
   }
   ```

2. **get_notes** - Get all notes
   ```json
   {
     "name": "get_notes",
     "arguments": {
       "includeArchived": false,
       "search": "optional search query"
     }
   }
   ```

3. **get_note** - Get specific note by ID
4. **update_note** - Update existing note
5. **delete_note** - Delete note
6. **search_notes** - Search notes
7. **get_labels** - Get all unique labels
8. **toggle_pin** - Pin/unpin note
9. **toggle_archive** - Archive/unarchive note

## 🧪 Testing the SSE Server

### Test 1: Health Check
```bash
curl http://localhost:3001/
```

### Test 2: SSE Connection
```bash
curl -N http://localhost:3001/sse
```

### Test 3: Call a Tool (get_notes)
```bash
curl -X POST http://localhost:3001/message \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get_notes",
      "arguments": {}
    },
    "id": 1
  }'
```

### Test 4: Create Note via MCP
```powershell
$body = @{
    jsonrpc = "2.0"
    method = "tools/call"
    params = @{
        name = "create_note"
        arguments = @{
            content = "Test from MCP SSE"
            title = "SSE Test"
            color = "green"
        }
    }
    id = 1
} | ConvertTo-Json -Depth 5

Invoke-RestMethod -Method POST -Uri "http://localhost:3001/message" `
  -Body $body -ContentType "application/json"
```

## 🔥 Troubleshooting

### Error: Prisma Client not initialized

**Solution**: Generate Prisma Client in the main app:
```bash
cd ..\keep-notes
npx prisma generate
```

### Error: Port 3001 already in use

**Solution**: Change port in `index-sse.js`:
```javascript
const PORT = process.env.PORT || 3002;
```

Or set environment variable:
```powershell
$env:PORT=3002; node index-sse.js
```

### Error: Cannot connect from N8N

**Checklist**:
1. ✅ Server is running (`http://localhost:3001` works locally)
2. ✅ Firewall allows port 3001
3. ✅ Using correct IP address (not `localhost`)
4. ✅ N8N can reach your network
5. ✅ Using `http://` not `https://`

**Test connectivity from N8N machine**:
```bash
curl http://YOUR_IP:3001/
```

### SSE Connection Keeps Dropping

This is normal! SSE maintains a persistent connection. If it drops:
- Client should automatically reconnect
- Check network stability
- Verify firewall/proxy settings

## 🔒 Security Notes

⚠️ **This server has NO AUTHENTICATION!**

For production use:
1. Add API key authentication
2. Use HTTPS with SSL certificates
3. Restrict CORS origins
4. Use environment variables for secrets
5. Deploy behind a reverse proxy (nginx, Caddy)

### Add Basic API Key (Example)

```javascript
// In index-sse.js, add middleware:
app.use((req, res, next) => {
  const apiKey = req.headers['x-api-key'];
  if (apiKey !== process.env.MCP_API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  next();
});
```

## 📊 Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/` | Health check |
| GET | `/sse` | SSE connection endpoint |
| POST | `/message` | MCP message handler |

## 🆚 Comparison with REST API

| Feature | MCP SSE | REST API |
|---------|---------|----------|
| **Protocol** | SSE (MCP) | HTTP JSON |
| **Port** | 3001 | 3000 (Next.js) |
| **Format** | MCP JSON-RPC | REST JSON |
| **Use case** | MCP clients | Standard HTTP clients |
| **Tools** | 9 MCP tools | 4 CRUD endpoints |

**Both work!** Use MCP SSE for proper MCP integration, or REST API for simpler HTTP requests.

## 🔄 Development Workflow

### Running Both Servers

**Terminal 1: Next.js + REST API**
```bash
cd keep-notes
npm run dev
# Runs on http://localhost:3000
```

**Terminal 2: MCP SSE Server**
```bash
cd mcp-server
npm run start:sse
# Runs on http://localhost:3001
```

**Terminal 3: MCP stdio (for Claude Desktop)**
```bash
cd mcp-server
npm start
# Runs as stdio process
```

## 📝 Configuration Examples

### N8N Workflow (MCP Client)

```json
{
  "nodes": [
    {
      "name": "Get Memento Notes",
      "type": "MCP Client",
      "typeVersion": 1,
      "position": [250, 300],
      "parameters": {
        "server": "memento",
        "tool": "get_notes",
        "arguments": {
          "includeArchived": false
        }
      }
    }
  ]
}
```

### Claude Desktop Config (stdio)

Use the original `index.js` with stdio:
```json
{
  "mcpServers": {
    "memento": {
      "command": "node",
      "args": ["D:/dev_new_pc/Keep/mcp-server/index.js"]
    }
  }
}
```

## 📚 Resources

- [MCP Protocol Documentation](https://modelcontextprotocol.io)
- [Server-Sent Events Spec](https://html.spec.whatwg.org/multipage/server-sent-events.html)
- [N8N MCP Integration Guide](https://community.n8n.io)
- [Express.js Documentation](https://expressjs.com)

## 🤝 Support

Issues? Check:
1. [MCP-SSE-ANALYSIS.md](../MCP-SSE-ANALYSIS.md) - Detailed SSE analysis
2. [README.md](../README.md) - Main project README
3. [COMPLETED-FEATURES.md](../COMPLETED-FEATURES.md) - Implementation details

---

**Version**: 1.0.0  
**Last Updated**: January 4, 2026  
**Status**: ✅ Production Ready