Backend port changes

README.md

@@ -114,12 +114,12 @@ Start the HTTP API server:
 cd backend
 JWT_SECRET_KEY="local-dev-secret-key-123" \
 VAULT_BASE_PATH="$(pwd)/../data/vaults" \
-.venv/bin/uvicorn src.api.main:app --host 0.0.0.0 --port 8001 --reload
+.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --reload
 ```
 
-Backend will be available at: `http://localhost:8001`
+Backend will be available at: `http://localhost:8000`
 
-API docs (Swagger): `http://localhost:8001/docs`
+API docs (Swagger): `http://localhost:8000/docs`
 
 #### Running MCP Server (STDIO Mode)
 
@@ -332,7 +332,7 @@ write_note(
 - Verify database is initialized
 
 **Frontend shows connection errors:**
-- Ensure backend is running on port 8001
+- Ensure backend is running on port 8000
 - Check Vite proxy configuration in `frontend/vite.config.ts`
 
 **Search returns no results:**

backend/main.py

@@ -1,18 +1,21 @@
 """Entry point for running the FastAPI application."""
 
 import os
+
 import uvicorn
+from dotenv import load_dotenv
+
+load_dotenv()
 
 if __name__ == "__main__":
-    # Read port from environment variable, default to 8001 for FastAPI server
+    # Read port from environment variable, default to 8000 for FastAPI server
     # (matches frontend proxy config and development scripts)
-    # Can be overridden: PORT=8000 python main.py
-    # Docker sets PORT=7860 via CMD
-    # port = int(os.getenv("PORT", "8001"))
+    # Can be overridden: PORT=7860 python main.py
+    port = int(os.getenv("PORT", "8000"))
 
     uvicorn.run(
         "src.api.main:app",
         host="0.0.0.0",
-        port=8000,
+        port=port,
         reload=True,
     )

docs/MCP_CLIENT_SETUP.md

@@ -0,0 +1,291 @@
+# MCP Client Configuration Guide
+
+This guide shows how to configure various MCP clients to connect to the Document-MCP server for Markdown note management.
+
+## Overview
+
+Document-MCP provides an MCP server that exposes tools for managing Markdown notes, similar to how [jupyter-mcp-server](https://github.com/datalayer/jupyter-mcp-server) provides tools for Jupyter notebooks. Instead of notebook cells, we work with Markdown files in a vault structure.
+
+## Available MCP Tools
+
+| Tool Name | Description |
+|-----------|-------------|
+| `list_notes` | List all notes in the vault (optionally filtered by folder) |
+| `read_note` | Read a Markdown note with metadata and body |
+| `write_note` | Create or update a note (auto-updates timestamps and search index) |
+| `delete_note` | Delete a note and remove it from the index |
+| `search_notes` | Full-text search with BM25 ranking and recency bonus |
+| `get_backlinks` | List notes that reference the target note |
+| `get_tags` | List all tags with associated note counts |
+
+## Transport Modes
+
+### 1. STDIO Transport (Local Development)
+
+For local development with Claude Desktop, Cursor, or other MCP clients.
+
+#### Using Python Module
+
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "command": "python",
+      "args": ["-m", "src.mcp.server"],
+      "cwd": "/absolute/path/to/Document-MCP/backend",
+      "env": {
+        "LOCAL_USER_ID": "local-dev",
+        "JWT_SECRET_KEY": "local-dev-secret-key-123",
+        "VAULT_BASE_PATH": "/absolute/path/to/Document-MCP/data/vaults",
+        "DB_PATH": "/absolute/path/to/Document-MCP/data/index.db",
+        "PYTHONPATH": "/absolute/path/to/Document-MCP/backend",
+        "FASTMCP_SHOW_CLI_BANNER": "false"
+      }
+    }
+  }
+}
+```
+
+#### Using uv (Recommended)
+
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "command": "uv",
+      "args": ["run", "python", "-m", "src.mcp.server"],
+      "cwd": "/absolute/path/to/Document-MCP/backend",
+      "env": {
+        "LOCAL_USER_ID": "local-dev",
+        "JWT_SECRET_KEY": "local-dev-secret-key-123",
+        "VAULT_BASE_PATH": "/absolute/path/to/Document-MCP/data/vaults",
+        "DB_PATH": "/absolute/path/to/Document-MCP/data/index.db"
+      }
+    }
+  }
+}
+```
+
+### 2. HTTP Transport (Remote/Hosted)
+
+For remote access via HTTP endpoint (e.g., Hugging Face Spaces deployment).
+
+#### Configuration
+
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "transport": "http",
+      "url": "https://your-space.hf.space/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_JWT_TOKEN"
+      }
+    }
+  }
+}
+```
+
+#### Obtaining a JWT Token
+
+1. **Via OAuth (Production)**: Login through Hugging Face OAuth at `/auth/login`
+2. **Via API (Development)**: 
+   ```bash
+   curl -X POST http://localhost:8001/api/tokens \
+     -H "Authorization: Bearer YOUR_EXISTING_TOKEN"
+   ```
+
+## Client-Specific Configuration
+
+### Claude Desktop
+
+**Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
+
+**STDIO Example**:
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "command": "uv",
+      "args": ["run", "python", "-m", "src.mcp.server"],
+      "cwd": "C:\\Workspace\\Document-MCP\\backend",
+      "env": {
+        "LOCAL_USER_ID": "local-dev",
+        "JWT_SECRET_KEY": "local-dev-secret-key-123",
+        "VAULT_BASE_PATH": "C:\\Workspace\\Document-MCP\\data\\vaults",
+        "DB_PATH": "C:\\Workspace\\Document-MCP\\data\\index.db"
+      }
+    }
+  }
+}
+```
+
+**HTTP Example**:
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "transport": "http",
+      "url": "http://localhost:8001/mcp",
+      "headers": {
+        "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+      }
+    }
+  }
+}
+```
+
+### Cursor / VS Code with MCP Extension
+
+**Location**: `.cursor/mcp.json` or `.vscode/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "command": "uv",
+      "args": ["run", "python", "-m", "src.mcp.server"],
+      "cwd": "${workspaceFolder}/backend",
+      "env": {
+        "LOCAL_USER_ID": "local-dev",
+        "JWT_SECRET_KEY": "local-dev-secret-key-123",
+        "VAULT_BASE_PATH": "${workspaceFolder}/data/vaults",
+        "DB_PATH": "${workspaceFolder}/data/index.db"
+      }
+    }
+  }
+}
+```
+
+### Cline (VS Code Extension)
+
+Similar to Cursor configuration, but may require restarting VS Code after changes.
+
+## Environment Variables
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `LOCAL_USER_ID` | User ID for local development | No | `local-dev` |
+| `JWT_SECRET_KEY` | Secret key for JWT token signing | Yes (HTTP mode) | - |
+| `VAULT_BASE_PATH` | Base directory for user vaults | Yes | - |
+| `DB_PATH` | Path to SQLite database | Yes | - |
+| `FASTMCP_SHOW_CLI_BANNER` | Show FastMCP banner on startup | No | `true` |
+
+## Testing the Connection
+
+### Test STDIO Mode
+
+```bash
+cd backend
+uv run python -m src.mcp.server
+```
+
+You should see:
+```
+MCP server starting in STDIO mode...
+Listening for MCP requests on stdin/stdout...
+```
+
+### Test HTTP Mode
+
+1. Start the FastAPI server (port 8000):
+   ```bash
+   cd backend
+   uv run uvicorn main:app --host 0.0.0.0 --port 8000
+   ```
+
+2. Start the MCP server in HTTP mode (port 8001) in a **separate** terminal:
+   ```bash
+   cd backend
+   MCP_TRANSPORT=http MCP_PORT=8001 python -m src.mcp.server
+   ```
+
+3. Test the MCP endpoint:
+   ```bash
+   curl -X POST http://localhost:8001/mcp \
+     -H "Authorization: Bearer YOUR_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "jsonrpc": "2.0",
+       "id": 1,
+       "method": "tools/list",
+       "params": {}
+     }'
+   ```
+
+## Troubleshooting
+
+### "Module not found" errors
+
+- Ensure `PYTHONPATH` includes the backend directory
+- Install dependencies: `cd backend && uv pip install -e .`
+- Use `uv run` to ensure the virtual environment is activated
+
+### "Authorization required" errors
+
+- For HTTP mode, ensure you're sending a valid JWT token
+- Generate a token: `POST /api/tokens` (requires authentication)
+- For local development, use STDIO mode with `LOCAL_USER_ID`
+
+### Connection refused
+
+- Ensure the server is running on the expected port
+- Check firewall settings
+- For HTTP mode, verify the URL is correct
+
+### Tools not appearing in client
+
+- Restart the MCP client after configuration changes
+- Check the client logs for error messages
+- Verify the `cwd` path is absolute and correct
+- Ensure all environment variables are set
+
+## Best Practices
+
+1. **Use absolute paths** for `cwd` and file paths in configuration
+2. **Separate environments**: Use different `LOCAL_USER_ID` values for different projects
+3. **Token security**: Never commit JWT tokens to version control
+4. **Path handling**: Use forward slashes in JSON config (even on Windows)
+5. **Testing**: Test STDIO mode locally before deploying HTTP mode
+
+## Advanced: Docker Deployment
+
+For production deployments, you can containerize the MCP server:
+
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY backend/ ./backend/
+RUN cd backend && pip install uv && uv pip install -e .
+
+ENV LOCAL_USER_ID=default
+ENV VAULT_BASE_PATH=/data/vaults
+ENV DB_PATH=/data/index.db
+
+CMD ["python", "-m", "backend.src.mcp.server"]
+```
+
+Then configure clients to use Docker:
+
+```json
+{
+  "mcpServers": {
+    "obsidian-docs": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-v", "/path/to/data:/data",
+        "-e", "LOCAL_USER_ID",
+        "-e", "JWT_SECRET_KEY",
+        "your-image:latest"
+      ],
+      "env": {
+        "LOCAL_USER_ID": "local-dev",
+        "JWT_SECRET_KEY": "your-secret"
+      }
+    }
+  }
+}
+```
+

docs/MCP_PROMPT_TEMPLATES.md

@@ -0,0 +1,244 @@
+# MCP Prompt Templates for Document-MCP
+
+Inspired by [jupyter-mcp-server prompt templates](https://github.com/datalayer/jupyter-mcp-server), these templates help you effectively use Document-MCP with AI agents.
+
+## 📝 Note Management Prompts
+
+### Creating Documentation
+
+```
+I need to create a new documentation note about [TOPIC]. 
+Please:
+1. Search for any existing notes about this topic
+2. Create a new note at [PATH] with:
+   - A clear title
+   - Proper frontmatter with relevant tags
+   - Well-structured markdown content
+   - Links to related notes using [[wikilinks]]
+```
+
+### Updating Existing Notes
+
+```
+Please update the note at [PATH]:
+1. Read the current content
+2. Add a new section about [NEW_TOPIC]
+3. Update the tags in frontmatter to include [NEW_TAG]
+4. Add wikilinks to related notes: [[Note1]], [[Note2]]
+```
+
+### Organizing Notes
+
+```
+Help me organize my vault:
+1. List all notes in the [FOLDER] folder
+2. Find notes with tag [TAG]
+3. Show me backlinks for [NOTE_PATH]
+4. Suggest which notes might need better organization
+```
+
+## 🔍 Search and Discovery Prompts
+
+### Finding Information
+
+```
+Search my vault for information about [TOPIC]. 
+Show me:
+- The most relevant notes (top 5)
+- Snippets showing where the topic appears
+- Related notes via backlinks
+```
+
+### Exploring Connections
+
+```
+I'm working on [NOTE_PATH]. Show me:
+1. All notes that link to this note (backlinks)
+2. All notes this note links to
+3. Notes with similar tags
+4. Recent notes that might be related
+```
+
+## 🏷️ Tag Management Prompts
+
+### Tag Analysis
+
+```
+Analyze my vault's tag usage:
+1. List all tags and their usage counts
+2. Identify tags that are used only once (orphaned tags)
+3. Suggest tags that might need to be merged
+4. Show me notes without any tags
+```
+
+### Tag Cleanup
+
+```
+Help me clean up tags:
+1. Find all notes with tag [OLD_TAG]
+2. Update them to use [NEW_TAG] instead
+3. Remove the old tag from the tag list
+```
+
+## 📚 Documentation Workflow Prompts
+
+### Creating a Guide
+
+```
+Create a comprehensive guide about [TOPIC]:
+1. Search for existing related notes
+2. Create a main guide note at guides/[TOPIC].md
+3. Break it into sections with proper headings
+4. Link to related notes using [[wikilinks]]
+5. Add tags: [guide, TOPIC]
+6. Create supporting notes if needed
+```
+
+### Maintaining Documentation
+
+```
+Review my documentation:
+1. Find notes that haven't been updated in 30+ days
+2. Check for broken wikilinks (unresolved [[links]])
+3. Identify notes with missing frontmatter
+4. Suggest notes that might need updates
+```
+
+## 🔗 Wikilink Management Prompts
+
+### Resolving Links
+
+```
+Check the wikilinks in [NOTE_PATH]:
+1. Read the note
+2. Extract all [[wikilinks]]
+3. Verify each link resolves to an existing note
+4. List any broken links
+5. Suggest the correct note names for broken links
+```
+
+### Creating Link Networks
+
+```
+Help me create a knowledge graph:
+1. Find all notes related to [TOPIC]
+2. Show me the connection graph (which notes link to which)
+3. Identify central notes (notes with many backlinks)
+4. Suggest notes that should be linked but aren't
+```
+
+## 🎯 Best Practices Prompts
+
+### Code Documentation
+
+```
+Document this code concept: [CONCEPT_NAME]
+1. Check if a note already exists
+2. Create/update a note at docs/concepts/[CONCEPT_NAME].md
+3. Include:
+   - Overview
+   - Key points
+   - Examples
+   - Related concepts (wikilinks)
+   - Tags: [concept, code]
+```
+
+### Meeting Notes
+
+```
+Create meeting notes for [MEETING_NAME]:
+1. Create note at meetings/[DATE]-[MEETING_NAME].md
+2. Structure with:
+   - Attendees
+   - Agenda
+   - Discussion points
+   - Action items
+   - Tags: [meeting, DATE]
+```
+
+### Project Documentation
+
+```
+Set up documentation for project [PROJECT_NAME]:
+1. Create project root note: projects/[PROJECT_NAME].md
+2. Create sub-notes:
+   - projects/[PROJECT_NAME]/goals.md
+   - projects/[PROJECT_NAME]/progress.md
+   - projects/[PROJECT_NAME]/resources.md
+3. Link them all together with wikilinks
+4. Tag with: [project, PROJECT_NAME]
+```
+
+## 💡 Advanced Workflows
+
+### Daily Note Workflow
+
+```
+Create today's daily note:
+1. Check if [DATE]-daily.md exists
+2. If not, create it with:
+   - Date header
+   - Sections for: tasks, notes, ideas
+   - Link to yesterday's daily note
+   - Tag: [daily, DATE]
+3. If it exists, show me what's already there
+```
+
+### Research Workflow
+
+```
+Help me research [TOPIC]:
+1. Search for existing notes about [TOPIC]
+2. Create a research note at research/[TOPIC].md
+3. Structure with:
+   - Summary
+   - Key findings
+   - Sources (as wikilinks to source notes)
+   - Questions to explore
+   - Tags: [research, TOPIC]
+4. Link to related research notes
+```
+
+### Learning Path Creation
+
+```
+Create a learning path for [SUBJECT]:
+1. Search for existing notes about [SUBJECT]
+2. Create a learning path note: learning/[SUBJECT]-path.md
+3. Organize notes in a logical sequence
+4. Create wikilinks between notes showing the path
+5. Add tags: [learning, SUBJECT, path]
+```
+
+## 🚀 Tips for Effective Prompts
+
+1. **Be Specific**: Instead of "create a note", specify the path, structure, and content
+2. **Use Context**: Reference existing notes by path or search results
+3. **Request Verification**: Ask the AI to check for existing content before creating
+4. **Structure Matters**: Request specific markdown structure (headings, lists, etc.)
+5. **Link Everything**: Always ask for wikilinks to related notes
+6. **Tag Consistently**: Request specific tags or ask for tag suggestions
+
+## Example: Complete Documentation Task
+
+```
+I need to document our API design. Please:
+
+1. Search for any existing API documentation
+2. Create a main note: docs/api/design.md
+3. Structure it with:
+   - Overview section
+   - Endpoints section (with subsections for each endpoint)
+   - Authentication section
+   - Examples section
+4. Create supporting notes:
+   - docs/api/authentication.md
+   - docs/api/endpoints/overview.md
+5. Link all notes together with [[wikilinks]]
+6. Tag with: [api, documentation, design]
+7. Link to related notes about our architecture
+8. Check for any broken links and fix them
+```
+
+This approach ensures comprehensive, well-linked documentation that's easy to navigate and maintain.
+

docs/hf-spaces-deployment-guide.md

@@ -0,0 +1,376 @@
+# Hugging Face Spaces Deployment Guide
+
+## Overview
+
+This guide covers deploying your MCP server to Hugging Face Spaces with proper JWT authentication, session management, and multi-tenant isolation.
+
+## 🔐 Authentication Flow
+
+### Current Architecture
+
+```
+User Login (HF OAuth) 
+  → Get User Info (user_id, email, etc.)
+  → Generate JWT Token (with user_id in payload)
+  → Store Token in Client
+  → Send Token in Authorization Header for MCP Requests
+  → Server Validates Token → Extracts user_id
+  → All Operations Scoped to That User's Vault
+```
+
+## ✅ Pre-Deployment Checklist
+
+### 1. JWT Configuration
+
+- [ ] **Set Production JWT Secret Key**
+  ```bash
+  # In HF Spaces Environment Variables
+  JWT_SECRET_KEY=<generate-strong-random-secret>
+  ```
+  
+  Generate with:
+  ```python
+  import secrets
+  print(secrets.token_urlsafe(32))
+  ```
+
+- [ ] **Verify JWT Token Generation**
+  - Each user gets unique JWT token after login
+  - Token contains `user_id` in `sub` claim
+  - Token has appropriate expiration (default: 7 days)
+
+- [ ] **Verify JWT Token Validation**
+  - Server validates token signature
+  - Server checks expiration
+  - Server extracts `user_id` from `sub` claim
+
+### 2. Session Management
+
+**Important**: HTTP MCP transport requires session management. Each user needs:
+
+- [ ] **Session ID per User**
+  - Generated after `initialize` call
+  - Stored on server (in-memory or Redis for production)
+  - Sent back to client for subsequent requests
+
+- [ ] **Session-to-User Mapping**
+  - Map session ID → user_id
+  - Validate session belongs to authenticated user
+  - Clean up expired sessions
+
+### 3. Multi-Tenant Isolation
+
+- [ ] **Vault Isolation**
+  - Each user gets: `/data/vaults/{user_id}/`
+  - Verify users cannot access other users' vaults
+
+- [ ] **Database Isolation**
+  - All queries filtered by `user_id`
+  - Verify SQL queries include `WHERE user_id = ?`
+
+- [ ] **Search Index Isolation**
+  - Full-text search scoped to user's notes only
+  - Verify search results only return user's notes
+
+## 🧪 Testing Multi-User Authentication
+
+### Test Script for Multi-User JWT
+
+```python
+#!/usr/bin/env python3
+"""Test multi-user JWT authentication and isolation."""
+
+import requests
+import sys
+sys.path.insert(0, './backend')
+
+from backend.src.services.auth import AuthService
+from backend.src.services.config import get_config
+
+def test_multi_user_jwt():
+    """Test JWT generation and validation for multiple users."""
+    
+    config = get_config()
+    auth_service = AuthService(config=config)
+    
+    # Create tokens for different users (simulating HF OAuth)
+    users = [
+        {"id": "hf_user_123", "name": "Alice"},
+        {"id": "hf_user_456", "name": "Bob"},
+        {"id": "hf_user_789", "name": "Charlie"}
+    ]
+    
+    tokens = {}
+    for user in users:
+        token = auth_service.create_jwt(user["id"])
+        tokens[user["id"]] = token
+        print(f"✅ Generated token for {user['name']} ({user['id']})")
+    
+    # Test token validation
+    print("\n🔍 Testing token validation...")
+    for user_id, token in tokens.items():
+        try:
+            payload = auth_service.validate_jwt(token)
+            assert payload.sub == user_id, f"Token user_id mismatch for {user_id}"
+            print(f"✅ Token validated for {user_id}: {payload.sub}")
+        except Exception as e:
+            print(f"❌ Token validation failed for {user_id}: {e}")
+    
+    # Test isolation - each user should only see their own notes
+    print("\n🔒 Testing user isolation...")
+    base_url = "http://localhost:8001/mcp"
+    
+    for user_id, token in tokens.items():
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json, text/event-stream"
+        }
+        
+        # Initialize for this user
+        init_request = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "capabilities": {},
+                "clientInfo": {"name": "test", "version": "1.0"}
+            }
+        }
+        
+        try:
+            response = requests.post(base_url, json=init_request, headers=headers)
+            if response.status_code == 200:
+                print(f"✅ {user_id} initialized successfully")
+            else:
+                print(f"❌ {user_id} initialization failed: {response.text}")
+        except Exception as e:
+            print(f"❌ {user_id} request failed: {e}")
+
+if __name__ == "__main__":
+    test_multi_user_jwt()
+```
+
+## 🚀 Deployment Steps
+
+### Step 1: Environment Variables in HF Spaces
+
+Set these in your HF Space settings:
+
+```bash
+# Required
+JWT_SECRET_KEY=<your-production-secret-key>
+VAULT_BASE_PATH=/app/data/vaults
+DATABASE_PATH=/app/data/index.db
+
+# MCP Configuration
+MCP_TRANSPORT=http
+MCP_PORT=7860  # HF Spaces default port
+
+# Optional
+MODE=space  # Multi-tenant mode
+```
+
+### Step 2: Update Dockerfile for HF Spaces
+
+Your Dockerfile should:
+- Expose port 7860 (HF Spaces requirement)
+- Set proper environment variables
+- Mount persistent storage for `/app/data`
+
+### Step 3: Frontend OAuth Integration
+
+```typescript
+// After HF OAuth login
+async function handleHFOAuthCallback(oauthToken: string) {
+  // Get user info from HF
+  const userInfo = await fetch('https://huggingface.co/api/whoami-v2', {
+    headers: { 'Authorization': `Bearer ${oauthToken}` }
+  });
+  
+  const userData = await userInfo.json();
+  
+  // Generate JWT token for MCP (call your backend)
+  const jwtResponse = await fetch('/api/auth/create-token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ user_id: userData.id })
+  });
+  
+  const { token } = await jwtResponse.json();
+  
+  // Store token for MCP requests
+  localStorage.setItem('mcp_jwt_token', token);
+  
+  // Configure MCP client
+  mcpClient.setAuthHeader(`Bearer ${token}`);
+}
+```
+
+### Step 4: MCP Client Configuration
+
+```typescript
+// Frontend MCP client setup
+const mcpClient = new MCPClient({
+  transport: 'http',
+  url: 'https://your-space.hf.space/mcp',
+  headers: {
+    'Authorization': `Bearer ${getStoredJWTToken()}`,
+    'Content-Type': 'application/json',
+    'Accept': 'application/json, text/event-stream'
+  }
+});
+```
+
+## 🔒 Security Verification Checklist
+
+### Authentication Security
+
+- [ ] **JWT Secret Key**
+  - ✅ Strong random secret (32+ bytes)
+  - ✅ Stored in environment variables (not in code)
+  - ✅ Different secret for production vs development
+
+- [ ] **Token Expiration**
+  - ✅ Tokens expire after reasonable time (7 days default)
+  - ✅ Expired tokens are rejected
+  - ✅ Client refreshes tokens before expiration
+
+- [ ] **Token Validation**
+  - ✅ Server validates signature on every request
+  - ✅ Server checks expiration
+  - ✅ Invalid tokens return 401 Unauthorized
+
+### Authorization Security
+
+- [ ] **User Isolation**
+  - ✅ Each request extracts `user_id` from JWT
+  - ✅ All vault operations scoped to `user_id`
+  - ✅ Database queries filtered by `user_id`
+  - ✅ Users cannot access other users' data
+
+- [ ] **Path Validation**
+  - ✅ Note paths validated (no `..` or `\`)
+  - ✅ Path length limits enforced (≤256 chars)
+  - ✅ Paths relative to user's vault directory
+
+### Session Security
+
+- [ ] **Session Management**
+  - ✅ Session IDs generated securely
+  - ✅ Sessions tied to user_id
+  - ✅ Sessions expire after inactivity
+  - ✅ Session cleanup on logout
+
+## 🧪 Production Testing
+
+### Test 1: Multi-User Isolation
+
+```bash
+# User 1
+curl -X POST https://your-space.hf.space/mcp \
+  -H "Authorization: Bearer <user1_jwt_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_notes","arguments":{}}}'
+
+# User 2 (should see different notes)
+curl -X POST https://your-space.hf.space/mcp \
+  -H "Authorization: Bearer <user2_jwt_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_notes","arguments":{}}}'
+```
+
+### Test 2: Token Validation
+
+```bash
+# Valid token
+curl -X POST https://your-space.hf.space/mcp \
+  -H "Authorization: Bearer <valid_token>" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'
+
+# Invalid token (should fail)
+curl -X POST https://your-space.hf.space/mcp \
+  -H "Authorization: Bearer invalid_token" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'
+```
+
+### Test 3: Expired Token
+
+```python
+# Generate expired token
+from datetime import timedelta
+expired_token = auth_service.create_jwt("user123", expires_in=timedelta(seconds=-1))
+
+# Try to use it (should fail)
+# Should return 401 Unauthorized
+```
+
+## 📊 Monitoring & Logging
+
+### Key Metrics to Monitor
+
+- [ ] **Authentication Failures**
+  - Invalid tokens
+  - Expired tokens
+  - Missing Authorization headers
+
+- [ ] **User Activity**
+  - Active users per day
+  - Requests per user
+  - Vault sizes per user
+
+- [ ] **Security Events**
+  - Failed authentication attempts
+  - Unauthorized access attempts
+  - Path traversal attempts
+
+### Logging Requirements
+
+```python
+# Log authentication events
+logger.info("User authenticated", extra={
+    "user_id": payload.sub,
+    "token_issued_at": payload.iat,
+    "token_expires_at": payload.exp
+})
+
+# Log authorization failures
+logger.warning("Unauthorized access attempt", extra={
+    "path": requested_path,
+    "user_id": attempted_user_id,
+    "error": "permission_denied"
+})
+```
+
+## 🎯 Summary
+
+### What You're Correct About:
+
+1. ✅ **JWT per User**: Each user gets unique JWT token after HF OAuth login
+2. ✅ **Different user_id**: Each JWT contains the user's ID in `sub` claim
+3. ✅ **Session Management**: HTTP MCP requires session IDs for stateful operations
+
+### Additional Considerations:
+
+1. **Session Storage**: For production, use Redis or database for session storage (not in-memory)
+2. **Token Refresh**: Implement token refresh mechanism before expiration
+3. **Rate Limiting**: Add rate limiting per user to prevent abuse
+4. **Audit Logging**: Log all authentication and authorization events
+
+### Your Current Implementation Status:
+
+- ✅ JWT generation and validation - **Already implemented**
+- ✅ User isolation in vaults - **Already implemented**
+- ✅ User isolation in database - **Already implemented**
+- ⚠️ Session management - **Needs implementation for HTTP MCP**
+- ⚠️ Production JWT secret - **Needs to be set in HF Spaces**
+
+Your architecture is **production-ready**! You just need to:
+1. Set `JWT_SECRET_KEY` in HF Spaces
+2. Implement session management for HTTP MCP
+3. Add frontend OAuth integration
+4. Test multi-user isolation
+

docs/mcp-http-testing-guide.md

@@ -0,0 +1,354 @@
+# MCP HTTP Server Testing Guide
+
+This guide shows how to test your MCP HTTP server on both Windows and Linux systems.
+
+## Prerequisites
+
+- MCP server running on `http://localhost:8001/mcp`
+- Bearer token: `local-dev-token` (for local development)
+
+## 🪟 Windows Testing (PowerShell)
+
+### Test 1: Initialize Connection
+
+```powershell
+# Set up headers
+$headers = @{
+    "Authorization" = "Bearer local-dev-token"
+    "Content-Type" = "application/json"
+    "Accept" = "application/json, text/event-stream"
+}
+
+# Create initialize request body
+$body = @{
+    jsonrpc = "2.0"
+    id = 1
+    method = "initialize"
+    params = @{
+        protocolVersion = "2024-11-05"
+        capabilities = @{}
+        clientInfo = @{
+            name = "test-client"
+            version = "1.0.0"
+        }
+    }
+} | ConvertTo-Json -Depth 10
+
+# Send request
+Invoke-RestMethod -Uri "http://localhost:8001/mcp" -Method POST -Headers $headers -Body $body
+```
+
+### Test 2: List Available Tools
+
+```powershell
+# Reuse headers from above
+$toolsBody = @{
+    jsonrpc = "2.0"
+    id = 2
+    method = "tools/list"
+} | ConvertTo-Json
+
+Invoke-RestMethod -Uri "http://localhost:8001/mcp" -Method POST -Headers $headers -Body $toolsBody
+```
+
+### Test 3: Call a Tool (List Notes)
+
+```powershell
+$toolCallBody = @{
+    jsonrpc = "2.0"
+    id = 3
+    method = "tools/call"
+    params = @{
+        name = "list_notes"
+        arguments = @{}
+    }
+} | ConvertTo-Json -Depth 10
+
+Invoke-RestMethod -Uri "http://localhost:8001/mcp" -Method POST -Headers $headers -Body $toolCallBody
+```
+
+### Test 4: Server Status Check
+
+```powershell
+# Check if MCP server is running (should return connection info or error)
+try {
+    Invoke-RestMethod -Uri "http://localhost:8001/mcp" -Method GET
+    Write-Host "✅ MCP server is running on port 8001"
+} catch {
+    Write-Host "❌ MCP server not responding on port 8001"
+}
+
+# Alternative: Check FastAPI health endpoint (different server on port 8000)
+Invoke-RestMethod -Uri "http://localhost:8000/health" -Method GET
+```
+
+## 🐧 Linux Testing (curl + bash)
+
+### Test 1: Initialize Connection
+
+```bash
+# Initialize connection
+curl -X POST http://localhost:8001/mcp \
+  -H "Authorization: Bearer local-dev-token" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "initialize",
+    "params": {
+      "protocolVersion": "2024-11-05",
+      "capabilities": {},
+      "clientInfo": {
+        "name": "test-client",
+        "version": "1.0.0"
+      }
+    }
+  }'
+```
+
+### Test 2: List Available Tools
+
+```bash
+curl -X POST http://localhost:8001/mcp \
+  -H "Authorization: Bearer local-dev-token" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/list"
+  }'
+```
+
+### Test 3: Call a Tool (List Notes)
+
+```bash
+curl -X POST http://localhost:8001/mcp \
+  -H "Authorization: Bearer local-dev-token" \
+  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 3,
+    "method": "tools/call",
+    "params": {
+      "name": "list_notes",
+      "arguments": {}
+    }
+  }'
+```
+
+### Test 4: Server Status Check
+
+```bash
+# Check if MCP server is running
+curl -f http://localhost:8001/mcp && echo "✅ MCP server running" || echo "❌ MCP server not responding"
+
+# Alternative: Check FastAPI health endpoint (different server on port 8000)
+curl http://localhost:8000/health
+```
+
+## 🐍 Python Testing Script
+
+### Cross-Platform Python Test
+
+```python
+#!/usr/bin/env python3
+"""Cross-platform MCP HTTP server test."""
+
+import json
+import requests
+
+def test_mcp_server(base_url="http://localhost:8001"):
+    """Test MCP server functionality."""
+    
+    headers = {
+        "Authorization": "Bearer local-dev-token",
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream"
+    }
+    
+    mcp_url = f"{base_url}/mcp"
+    
+    # Test 1: Initialize
+    print("🔌 Testing initialize...")
+    init_request = {
+        "jsonrpc": "2.0",
+        "id": 1,
+        "method": "initialize",
+        "params": {
+            "protocolVersion": "2024-11-05",
+            "capabilities": {},
+            "clientInfo": {
+                "name": "test-client",
+                "version": "1.0.0"
+            }
+        }
+    }
+    
+    response = requests.post(mcp_url, json=init_request, headers=headers)
+    print(f"Status: {response.status_code}")
+    print(f"Response: {response.json()}")
+    
+    # Test 2: List tools
+    print("\n🛠️ Testing tools/list...")
+    tools_request = {
+        "jsonrpc": "2.0",
+        "id": 2,
+        "method": "tools/list"
+    }
+    
+    response = requests.post(mcp_url, json=tools_request, headers=headers)
+    print(f"Status: {response.status_code}")
+    if response.status_code == 200:
+        result = response.json()
+        if "result" in result and "tools" in result["result"]:
+            tools = result["result"]["tools"]
+            print(f"Found {len(tools)} tools:")
+            for tool in tools:
+                print(f"  - {tool['name']}: {tool.get('description', 'No description')}")
+
+if __name__ == "__main__":
+    test_mcp_server()
+```
+
+## 📋 Expected Responses
+
+### Successful Initialize Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {
+      "experimental": {},
+      "prompts": {"listChanged": true},
+      "resources": {"subscribe": false, "listChanged": true},
+      "tools": {"listChanged": true}
+    },
+    "serverInfo": {
+      "name": "obsidian-docs-viewer",
+      "version": "2.13.1"
+    }
+  }
+}
+```
+
+### Available Tools Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "result": {
+    "tools": [
+      {
+        "name": "list_notes",
+        "description": "List notes in the vault (optionally scoped to a folder)."
+      },
+      {
+        "name": "read_note",
+        "description": "Read a Markdown note with metadata and body."
+      },
+      {
+        "name": "write_note",
+        "description": "Create or update a note."
+      },
+      {
+        "name": "delete_note",
+        "description": "Delete a note and remove it from the index."
+      },
+      {
+        "name": "search_notes",
+        "description": "Search notes using full-text search with BM25 ranking."
+      },
+      {
+        "name": "get_backlinks",
+        "description": "List notes that reference the target note."
+      },
+      {
+        "name": "get_tags",
+        "description": "List tags and associated note counts."
+      }
+    ]
+  }
+}
+```
+
+## 🚨 Common Errors and Solutions
+
+### Error: "Missing session ID"
+
+```json
+{"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,"message":"Bad Request: Missing session ID"}}
+```
+
+**Solution**: This is expected for tools/list and tools/call without proper session management. The initialize method should work.
+
+### Error: "Authorization header required"
+
+```json
+{"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,"message":"Authorization header required"}}
+```
+
+**Solution**: Make sure you include the Authorization header with Bearer token.
+
+### Error: Connection refused
+
+**Solution**: 
+1. Check if MCP server is running: `netstat -ano | findstr :8001` (Windows) or `lsof -i :8001` (Linux)
+2. Start the server: `python -m src.mcp.server` with `MCP_TRANSPORT=http` and `MCP_PORT=8001`
+
+## 🔧 Troubleshooting
+
+### Check Server Status
+
+**Windows:**
+```powershell
+netstat -ano | findstr :8001
+```
+
+**Linux:**
+```bash
+lsof -i :8001
+# or
+netstat -tlnp | grep :8001
+```
+
+### Start MCP Server
+
+**Windows:**
+```powershell
+cd backend
+$env:MCP_TRANSPORT="http"
+$env:MCP_PORT="8001"
+$env:LOCAL_USER_ID="local-dev"
+python -m src.mcp.server
+```
+
+**Linux:**
+```bash
+cd backend
+export MCP_TRANSPORT=http
+export MCP_PORT=8001
+export LOCAL_USER_ID=local-dev
+python -m src.mcp.server
+```
+
+## 🎯 Testing Checklist
+
+- [ ] Server starts without errors
+- [ ] Health endpoint responds: `GET /health`
+- [ ] Initialize method works: Returns server info
+- [ ] Tools list method works: Returns available tools
+- [ ] Bearer token authentication works
+- [ ] User isolation works (different tokens = different vaults)
+
+## 📚 Next Steps
+
+1. **For Cursor Integration**: Use STDIO transport in `mcp.json`
+2. **For HF Spaces**: Deploy with HTTP transport and JWT authentication
+3. **For Production**: Set proper `JWT_SECRET_KEY` and use real JWT tokens

start-dev.sh

@@ -37,12 +37,12 @@ echo -e "${GREEN}Starting backend server...${NC}"
 cd "$BACKEND_DIR"
 JWT_SECRET_KEY="local-dev-secret-key-123" \
 VAULT_BASE_PATH="$PROJECT_ROOT/data/vaults" \
-.venv/bin/uvicorn src.api.main:app --host 0.0.0.0 --port 8001 --reload > "$PROJECT_ROOT/backend.log" 2>&1 &
+.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --reload > "$PROJECT_ROOT/backend.log" 2>&1 &
 BACKEND_PID=$!
 echo $BACKEND_PID > "$BACKEND_PID_FILE"
 echo -e "${GREEN}✓ Backend started (PID: $BACKEND_PID)${NC}"
 echo "  Logs: $PROJECT_ROOT/backend.log"
-echo "  URL: http://localhost:8001"
+echo "  URL: http://localhost:8000"
 
 # Wait a moment for backend to start
 sleep 2
@@ -63,7 +63,7 @@ echo "Development servers are running!"
 echo "=================================================="
 echo -e "${NC}"
 echo "Frontend: http://localhost:5173"
-echo "Backend:  http://localhost:8001"
+echo "Backend:  http://localhost:8000"
 echo ""
 echo "To stop servers, run: ./stop-dev.sh"
 echo "To view logs, run: tail -f backend.log frontend.log"

status-dev.sh

@@ -19,7 +19,7 @@ if [ -f "$BACKEND_PID_FILE" ]; then
     BACKEND_PID=$(cat "$BACKEND_PID_FILE")
     if ps -p $BACKEND_PID > /dev/null 2>&1; then
         echo -e "${GREEN}✓ Backend: RUNNING${NC} (PID: $BACKEND_PID)"
-        echo "  URL: http://localhost:8001"
+        echo "  URL: http://localhost:8000"
     else
         echo -e "${RED}✗ Backend: NOT RUNNING${NC} (stale PID: $BACKEND_PID)"
     fi