fix: Add debounced Undo/Redo system to avoid character-by-character history
- Add debounced state updates for title and content (500ms delay) - Immediate UI updates with delayed history saving - Prevent one-letter-per-undo issue - Add cleanup for debounce timers on unmount
This commit is contained in:
348
mcp-server/README-SSE.md
Normal file
348
mcp-server/README-SSE.md
Normal file
@@ -0,0 +1,348 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user