Doc-MCP Application

.dockerignore

@@ -0,0 +1,64 @@
+# Python
+**/__pycache__
+**/*.pyc
+**/*.pyo
+**/*.pyd
+**/.Python
+**/env
+**/venv
+**/.venv
+**/ENV
+**/env.bak/
+**/venv.bak/
+**/*.egg-info/
+**/.pytest_cache/
+**/.mypy_cache/
+**/.ruff_cache/
+
+# Node.js
+**/node_modules
+**/npm-debug.log*
+**/yarn-debug.log*
+**/yarn-error.log*
+**/pnpm-debug.log*
+**/lerna-debug.log*
+frontend/dist
+frontend/.vite
+
+# Git
+.git
+.gitignore
+.gitattributes
+
+# IDE
+**/.vscode
+**/.idea
+**/*.swp
+**/*.swo
+**/*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.log
+.backend.pid
+.frontend.pid
+backend.log
+frontend.log
+data/index.db
+data/vaults/*
+!data/vaults/.gitkeep
+
+# Documentation (not needed in container)
+*.md
+!backend/README.md
+specs/
+ai-notes/
+
+# Scripts
+start-dev.sh
+stop-dev.sh
+status-dev.sh
+

Dockerfile

@@ -0,0 +1,39 @@
+# Dockerfile for Hugging Face Space deployment
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install Node.js for frontend build
+RUN apt-get update && \
+    apt-get install -y nodejs npm curl && \
+    rm -rf /var/lib/apt/lists/*
+
+# Copy and install frontend dependencies
+COPY frontend/package*.json frontend/
+RUN cd frontend && npm ci
+
+# Copy frontend source and build
+COPY frontend/ frontend/
+RUN cd frontend && npm run build
+
+# Install Python dependencies
+COPY backend/pyproject.toml backend/README.md backend/
+RUN pip install --no-cache-dir -e backend/
+
+# Copy backend source
+COPY backend/ backend/
+
+# Create data directory for vaults and database
+RUN mkdir -p /app/data/vaults
+
+# Expose port 7860 (required by Hugging Face Spaces)
+EXPOSE 7860
+
+# Set environment variables for production
+ENV PYTHONUNBUFFERED=1 \
+    VAULT_BASE_PATH=/app/data/vaults \
+    DATABASE_PATH=/app/data/index.db
+
+# Start the FastAPI server
+CMD ["uvicorn", "backend.src.api.main:app", "--host", "0.0.0.0", "--port", "7860", "--log-level", "info"]
+

backend/.env

@@ -0,0 +1,13 @@
+JWT_SECRET_KEY=61012f17c920190990c90bfc9c810e24bbed86382df3cc573e78fd82e8809661
+# JWT_SECRET_KEY="local-dev-secret-key-123"
+HF_OAUTH_CLIENT_ID=9a79980a-74ce-4e06-9fce-ed787b2242c8
+HF_OAUTH_CLIENT_SECRET=05a8a57e-6940-4bd4-a7f8-7f0a6db1460
+HF_SPACE_URL=https://huggingface.co/spaces/Wothmag07/Document-MCP
+MCP_HOST=0.0.0.0
+MCP_PORT=8001
+
+ENABLE_LOCAL_MODE=False
+LOCAL_DEV_TOKEN=local-dev-token
+MCP_TRANSPORT = "http"
+
+VAULT_BASE_PATH=../data/vaults

backend/.python-version

@@ -0,0 +1 @@
+3.11

backend/main.py

@@ -0,0 +1,11 @@
+"""Entry point for running the FastAPI application."""
+
+import uvicorn
+
+if __name__ == "__main__":
+    uvicorn.run(
+        "src.api.main:app",
+        host="0.0.0.0",
+        port=8000,
+        reload=True,
+    )

backend/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "Documentation-MCP"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.121.2",
+    "fastmcp>=2.13.1",
+    "huggingface-hub>=1.1.4",
+    "mcp>=1.21.0",
+    "pyjwt>=2.10.1",
+    "python-dotenv>=1.0.0",
+    "python-frontmatter>=1.1.0",
+    "uvicorn[standard]>=0.38.0",
+]
+
+[dependency-groups]
+dev = [
+    "httpx>=0.28.1",
+    "pytest>=9.0.1",
+    "pytest-asyncio>=1.3.0",
+]

backend/requirements.txt

@@ -0,0 +1,12 @@
+fastapi
+fastmcp
+python-frontmatter
+pyjwt
+huggingface_hub
+uvicorn
+httpx
+pytest
+pytest-asyncio
+python-dotenv
+requests
+sqlite

backend/src/api/__init__.py

@@ -0,0 +1 @@
+"""FastAPI application and routing."""

backend/src/api/main.py

@@ -0,0 +1,196 @@
+"""FastAPI application main entry point."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from dotenv import load_dotenv
+from fastapi import Depends, FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastmcp.server.http import StreamableHTTPSessionManager
+from starlette.responses import FileResponse, Response
+
+from .middleware import AuthContext, get_auth_context
+from .routes import auth, index, notes, search
+from ..mcp.server import mcp
+from ..services.seed import init_and_seed
+
+load_dotenv(dotenv_path="backend/.env")
+
+logger = logging.getLogger(__name__)
+
+
+session_manager = StreamableHTTPSessionManager(
+    app=mcp._mcp_server,
+    event_store=None,
+    json_response=False,
+    stateless=False,
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Start and stop the Streamable HTTP session manager."""
+    async with session_manager.run():
+        yield
+
+
+app = FastAPI(
+    title="Document Viewer API",
+    description="Multi-tenant Obsidian-like documentation system",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "http://localhost:5173",
+        "http://localhost:3000",
+        "https://huggingface.co",
+    ],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Startup event: Initialize database and seed demo data
+@app.on_event("startup")
+async def startup_event():
+    """Initialize database schema and seed demo vault on startup."""
+    logger.info("Running startup: initializing database and seeding demo vault...")
+    try:
+        init_and_seed(user_id="demo-user")
+        logger.info("Startup complete: database and demo vault ready")
+    except Exception as e:
+        logger.exception(f"Startup failed: {e}")
+        # Don't crash the app, but log the error
+        logger.error("App starting without demo data due to initialization error")
+
+
+# Error handlers
+@app.exception_handler(404)
+async def not_found_handler(request: Request, exc: Exception):
+    """Handle 404 errors."""
+    return JSONResponse(
+        status_code=404,
+        content={"error": "Not found", "detail": str(exc)},
+    )
+
+
+@app.exception_handler(409)
+async def conflict_handler(request: Request, exc: Exception):
+    """Handle 409 Conflict errors."""
+    return JSONResponse(
+        status_code=409,
+        content={"error": "Conflict", "detail": str(exc)},
+    )
+
+
+@app.exception_handler(500)
+async def internal_error_handler(request: Request, exc: Exception):
+    """Handle 500 errors."""
+    return JSONResponse(
+        status_code=500,
+        content={"error": "Internal server error", "detail": str(exc)},
+    )
+
+
+# Mount routers (auth must come first for /auth/login and /auth/callback)
+app.include_router(auth.router, tags=["auth"])
+app.include_router(notes.router, tags=["notes"])
+app.include_router(search.router, tags=["search"])
+app.include_router(index.router, tags=["index"])
+
+
+@app.api_route("/mcp", methods=["GET", "POST", "DELETE"])
+async def mcp_http_bridge(
+    request: Request, auth: AuthContext = Depends(get_auth_context)
+) -> Response:
+    """Forward HTTP requests to the FastMCP streamable HTTP session manager."""
+
+    send_queue: asyncio.Queue = asyncio.Queue()
+
+    async def send(message):
+        await send_queue.put(message)
+
+    await session_manager.handle_request(request.scope, request.receive, send)
+    await send_queue.put(None)
+
+    result_body = b""
+    headers = {}
+    status = 200
+
+    while True:
+        message = await send_queue.get()
+        if message is None:
+            break
+        msg_type = message["type"]
+        if msg_type == "http.response.start":
+            status = message.get("status", 200)
+            raw_headers = message.get("headers", [])
+            headers = {key.decode(): value.decode() for key, value in raw_headers}
+        elif msg_type == "http.response.body":
+            result_body += message.get("body", b"")
+            if not message.get("more_body"):
+                break
+
+    return Response(content=result_body, status_code=status, headers=headers)
+
+
+logger.info("MCP HTTP endpoint mounted at /mcp via StreamableHTTPSessionManager")
+
+
+@app.get("/health")
+async def health():
+    """Health check endpoint for HF Spaces."""
+    return {"status": "healthy"}
+
+
+frontend_dist = Path(__file__).resolve().parents[3] / "frontend" / "dist"
+if frontend_dist.exists():
+    # Mount static assets
+    app.mount(
+        "/assets", StaticFiles(directory=str(frontend_dist / "assets")), name="assets"
+    )
+
+    # Catch-all route for SPA - serve index.html for all non-API routes
+    @app.get("/{full_path:path}")
+    async def serve_spa(full_path: str):
+        """Serve the SPA for all non-API routes."""
+        # Don't intercept API or auth routes
+        if (
+            full_path.startswith(("api/", "auth/"))
+            or full_path == "health"
+            or full_path.startswith("mcp/")
+            or full_path == "mcp"
+        ):
+            # Let FastAPI's 404 handler take over
+            raise HTTPException(status_code=404, detail="Not found")
+
+        # If the path looks like a file (has extension), try to serve it
+        file_path = frontend_dist / full_path
+        if file_path.is_file():
+            return FileResponse(file_path)
+        # Otherwise serve index.html for SPA routing
+        return FileResponse(frontend_dist / "index.html")
+
+    logger.info(f"Serving frontend SPA from: {frontend_dist}")
+else:
+    logger.warning(f"Frontend dist not found at: {frontend_dist}")
+
+    # Fallback health endpoint if no frontend
+    @app.get("/")
+    async def root():
+        """API health check endpoint."""
+        return {"status": "ok", "service": "Document Viewer API"}
+
+
+__all__ = ["app"]

backend/src/api/middleware/__init__.py

@@ -0,0 +1,19 @@
+"""FastAPI middleware for authentication and error handling."""
+
+from .auth_middleware import AuthContext, extract_user_id_from_jwt, get_auth_context
+from .error_handlers import (
+    http_exception_handler,
+    internal_exception_handler,
+    register_error_handlers,
+    validation_exception_handler,
+)
+
+__all__ = [
+    "AuthContext",
+    "extract_user_id_from_jwt",
+    "get_auth_context",
+    "register_error_handlers",
+    "validation_exception_handler",
+    "http_exception_handler",
+    "internal_exception_handler",
+]

backend/src/api/middleware/auth_middleware.py

@@ -0,0 +1,65 @@
+"""Authentication dependency helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Annotated, Optional
+
+from fastapi import Header, HTTPException, status
+
+from ...models.auth import JWTPayload
+from ...services.auth import AuthError, AuthService
+
+auth_service = AuthService()
+
+
+def _unauthorized(message: str, error: str = "unauthorized") -> HTTPException:
+    return HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail={"error": error, "message": message},
+    )
+
+
+@dataclass
+class AuthContext:
+    """Context extracted from a bearer token."""
+
+    user_id: str
+    token: str
+    payload: JWTPayload
+
+
+def get_auth_context(
+    authorization: Annotated[Optional[str], Header(alias="Authorization")] = None,
+) -> AuthContext:
+    """
+    Extract and validate the user_id from a Bearer token.
+
+    Raises HTTPException if the header is missing/invalid.
+    """
+    if not authorization:
+        raise _unauthorized("Authorization header required")
+
+    scheme, _, token = authorization.partition(" ")
+    if scheme.lower() != "bearer" or not token:
+        raise _unauthorized("Authorization header must be in format: Bearer <token>")
+
+    try:
+        payload = auth_service.validate_jwt(token)
+    except AuthError as exc:
+        raise HTTPException(
+            status_code=exc.status_code,
+            detail={"error": exc.error, "message": exc.message, "detail": exc.detail},
+        ) from exc
+
+    return AuthContext(user_id=payload.sub, token=token, payload=payload)
+
+
+def extract_user_id_from_jwt(
+    authorization: Annotated[Optional[str], Header(alias="Authorization")] = None,
+) -> str:
+    """Compatibility helper that returns only the user_id."""
+    return get_auth_context(authorization).user_id
+
+
+__all__ = ["AuthContext", "extract_user_id_from_jwt", "get_auth_context"]

backend/src/api/middleware/error_handlers.py

@@ -0,0 +1,113 @@
+"""FastAPI exception handlers aligned with HTTP API contract."""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional, Tuple
+
+from fastapi import FastAPI, Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_ERRORS: Dict[int, Tuple[str, str]] = {
+    status.HTTP_400_BAD_REQUEST: ("validation_error", "Invalid request payload"),
+    status.HTTP_401_UNAUTHORIZED: ("unauthorized", "Authorization required"),
+    status.HTTP_403_FORBIDDEN: ("forbidden", "Forbidden"),
+    status.HTTP_404_NOT_FOUND: ("not_found", "Resource not found"),
+    status.HTTP_409_CONFLICT: ("version_conflict", "Resource version conflict"),
+    status.HTTP_413_REQUEST_ENTITY_TOO_LARGE: (
+        "payload_too_large",
+        "Payload exceeds allowed size",
+    ),
+    status.HTTP_500_INTERNAL_SERVER_ERROR: ("internal_error", "Internal server error"),
+}
+
+
+def _normalize_error(
+    status_code: int, detail: Any
+) -> Tuple[str, str, Optional[Dict[str, Any]]]:
+    default_error, default_message = DEFAULT_ERRORS.get(
+        status_code, DEFAULT_ERRORS[status.HTTP_500_INTERNAL_SERVER_ERROR]
+    )
+    if isinstance(detail, dict):
+        error = detail.get("error", default_error)
+        message = detail.get("message", default_message)
+        detail_payload = detail.get("detail")
+        if detail_payload is None:
+            remainder = {
+                k: v for k, v in detail.items() if k not in {"error", "message", "detail"}
+            }
+            detail_payload = remainder or None
+        return error, message, detail_payload
+    if isinstance(detail, str) and detail:
+        return default_error, detail, None
+    return default_error, default_message, None
+
+
+def _response(status_code: int, detail: Any) -> JSONResponse:
+    error, message, extra = _normalize_error(status_code, detail)
+    return JSONResponse(
+        status_code=status_code, content={"error": error, "message": message, "detail": extra}
+    )
+
+
+async def validation_exception_handler(
+    request: Request, exc: RequestValidationError
+) -> JSONResponse:
+    # Transform pydantic errors into more user-friendly format
+    errors = []
+    for error in exc.errors():
+        field = ".".join(str(loc) for loc in error["loc"] if loc != "body")
+        errors.append({
+            "field": field or "request",
+            "reason": error["msg"],
+            "type": error["type"]
+        })
+    
+    detail = {
+        "error": "validation_error",
+        "message": "Request validation failed",
+        "detail": {"fields": errors}
+    }
+    logger.warning(
+        "Validation error",
+        extra={"url": str(request.url), "errors": errors}
+    )
+    return _response(status.HTTP_400_BAD_REQUEST, detail)
+
+
+async def http_exception_handler(
+    request: Request, exc: StarletteHTTPException
+) -> JSONResponse:
+    logger.warning(
+        "HTTP exception",
+        extra={
+            "url": str(request.url),
+            "status_code": exc.status_code,
+            "detail": exc.detail
+        }
+    )
+    return _response(exc.status_code, exc.detail)
+
+
+async def internal_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    logger.exception("Unhandled exception: %s", exc)
+    return _response(status.HTTP_500_INTERNAL_SERVER_ERROR, exc.args[0] if exc.args else None)
+
+
+def register_error_handlers(app: FastAPI) -> None:
+    """Attach shared exception handlers to the FastAPI application."""
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+    app.add_exception_handler(StarletteHTTPException, http_exception_handler)
+    app.add_exception_handler(Exception, internal_exception_handler)
+
+
+__all__ = [
+    "register_error_handlers",
+    "validation_exception_handler",
+    "http_exception_handler",
+    "internal_exception_handler",
+]

backend/src/api/routes/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP API route handlers."""
+
+from . import auth, index, notes, search
+
+__all__ = ["auth", "notes", "search", "index"]

backend/src/api/routes/auth.py

@@ -0,0 +1,315 @@
+"""OAuth and authentication routes for Hugging Face integration."""
+
+from __future__ import annotations
+
+import logging
+import secrets
+import time
+from datetime import datetime, timezone
+from typing import Optional
+from urllib.parse import urlencode
+
+import httpx
+from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from fastapi.responses import RedirectResponse
+
+from ...models.auth import TokenResponse
+from ...models.user import HFProfile, User
+from ...services.auth import AuthError, AuthService
+from ...services.config import get_config
+from ...services.seed import ensure_welcome_note
+from ...services.vault import VaultService
+from ..middleware import AuthContext, get_auth_context
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+OAUTH_STATE_TTL_SECONDS = 300
+oauth_states: dict[str, float] = {}
+
+auth_service = AuthService()
+
+
+def _create_oauth_state() -> str:
+    """Generate a state token and store it with a timestamp."""
+    now = time.time()
+    # Garbage collect expired states
+    expired = [
+        state
+        for state, ts in oauth_states.items()
+        if now - ts > OAUTH_STATE_TTL_SECONDS
+    ]
+    for state in expired:
+        oauth_states.pop(state, None)
+
+    state = secrets.token_urlsafe(32)
+    oauth_states[state] = now
+    return state
+
+
+def _consume_oauth_state(state: str | None) -> None:
+    """Validate and remove the state token; raise if invalid."""
+    if not state or state not in oauth_states:
+        raise HTTPException(status_code=400, detail="Invalid or expired OAuth state.")
+    # Remove to prevent reuse
+    del oauth_states[state]
+
+
+def get_base_url(request: Request) -> str:
+    """
+    Get the base URL for OAuth redirects.
+
+    Uses the actual request URL scheme and hostname from FastAPI's request.url.
+    HF Spaces doesn't set X-Forwarded-Host, but the 'host' header is correct.
+    """
+    # Get scheme from X-Forwarded-Proto or request
+    forwarded_proto = request.headers.get("x-forwarded-proto")
+    scheme = forwarded_proto if forwarded_proto else str(request.url.scheme)
+
+    # Get hostname from request URL (this comes from the 'host' header)
+    hostname = str(request.url.hostname)
+
+    # Check for port (but HF Spaces uses standard 443 for HTTPS)
+    port = request.url.port
+    if port and port not in (80, 443):
+        base_url = f"{scheme}://{hostname}:{port}"
+    else:
+        base_url = f"{scheme}://{hostname}"
+
+    logger.info(
+        f"OAuth base URL detected: {base_url}",
+        extra={
+            "scheme": scheme,
+            "hostname": hostname,
+            "port": port,
+            "request_url": str(request.url),
+        },
+    )
+
+    return base_url
+
+
+@router.get("/auth/login")
+async def login(request: Request):
+    """Redirect to Hugging Face OAuth authorization page."""
+    config = get_config()
+
+    if not config.hf_oauth_client_id:
+        raise HTTPException(
+            status_code=501,
+            detail="OAuth not configured. Set HF_OAUTH_CLIENT_ID and HF_OAUTH_CLIENT_SECRET environment variables.",
+        )
+
+    # Get base URL from request (handles HF Spaces proxy)
+    base_url = get_base_url(request)
+    redirect_uri = f"{base_url}/auth/callback"
+
+    state = _create_oauth_state()
+
+    # Construct HF OAuth URL
+    oauth_base = "https://huggingface.co/oauth/authorize"
+    params = {
+        "client_id": config.hf_oauth_client_id,
+        "redirect_uri": redirect_uri,
+        "scope": "openid profile email",
+        "response_type": "code",
+        "state": state,
+    }
+
+    auth_url = f"{oauth_base}?{urlencode(params)}"
+    logger.info(
+        "Initiating OAuth flow",
+        extra={
+            "redirect_uri": redirect_uri,
+            "auth_url": auth_url,
+            "client_id": config.hf_oauth_client_id[:8] + "...",
+            "state": state,
+        },
+    )
+
+    return RedirectResponse(url=auth_url, status_code=302)
+
+
+@router.get("/auth/callback")
+async def callback(
+    request: Request,
+    code: str = Query(..., description="OAuth authorization code"),
+    state: Optional[str] = Query(
+        None, description="State parameter for CSRF protection"
+    ),
+):
+    """Handle OAuth callback from Hugging Face."""
+    config = get_config()
+
+    if not config.hf_oauth_client_id or not config.hf_oauth_client_secret:
+        raise HTTPException(status_code=501, detail="OAuth not configured")
+
+    # Get base URL from request (must match the one sent to HF)
+    base_url = get_base_url(request)
+    redirect_uri = f"{base_url}/auth/callback"
+
+    # Validate state token to prevent CSRF and replay attacks
+    _consume_oauth_state(state)
+
+    logger.info(
+        "OAuth callback received",
+        extra={
+            "redirect_uri": redirect_uri,
+            "state": state,
+            "code_length": len(code) if code else 0,
+        },
+    )
+
+    try:
+        # Exchange authorization code for access token
+        async with httpx.AsyncClient() as client:
+            token_response = await client.post(
+                "https://huggingface.co/oauth/token",
+                data={
+                    "grant_type": "authorization_code",
+                    "code": code,
+                    "redirect_uri": redirect_uri,
+                    "client_id": config.hf_oauth_client_id,
+                    "client_secret": config.hf_oauth_client_secret,
+                },
+            )
+
+            if token_response.status_code != 200:
+                logger.error(f"Token exchange failed: {token_response.text}")
+                raise HTTPException(
+                    status_code=400,
+                    detail="Failed to exchange authorization code for token",
+                )
+
+            token_data = token_response.json()
+            access_token = token_data.get("access_token")
+
+            if not access_token:
+                raise HTTPException(
+                    status_code=400, detail="No access token in response"
+                )
+
+            # Get user profile from HF
+            user_response = await client.get(
+                "https://huggingface.co/api/whoami-v2",
+                headers={"Authorization": f"Bearer {access_token}"},
+            )
+
+            if user_response.status_code != 200:
+                logger.error(f"User profile fetch failed: {user_response.text}")
+                raise HTTPException(
+                    status_code=400, detail="Failed to fetch user profile"
+                )
+
+            user_data = user_response.json()
+            username = user_data.get("name")
+            email = user_data.get("email")
+            hf_id = user_data.get("id") or user_data.get("uid")
+
+            if not username and not hf_id:
+                raise HTTPException(
+                    status_code=400, detail="No user identity in user profile"
+                )
+
+            # Prefer stable HF account id; fall back to username if missing
+            user_id = str(hf_id or username)
+
+            # Create JWT for our application
+            import jwt
+            from datetime import datetime, timedelta, timezone
+
+            # Ensure the user has an initialized vault with a welcome note
+            try:
+                created = ensure_welcome_note(user_id)
+                logger.info(
+                    "Ensured welcome note for user",
+                    extra={"user_id": user_id, "created": created},
+                )
+            except Exception as seed_exc:
+                logger.exception(
+                    "Failed to seed welcome note for user",
+                    extra={"user_id": user_id},
+                )
+
+            payload = {
+                "sub": user_id,
+                "username": username,
+                "email": email,
+                "exp": datetime.now(timezone.utc) + timedelta(days=7),
+                "iat": datetime.now(timezone.utc),
+            }
+
+            try:
+                jwt_secret = auth_service._require_secret()
+            except AuthError as exc:
+                raise HTTPException(status_code=exc.status_code, detail=exc.message)
+
+            jwt_token = jwt.encode(payload, jwt_secret, algorithm="HS256")
+
+            logger.info(
+                "OAuth successful",
+                extra={
+                    "username": username,
+                    "user_id": user_id,
+                    "email": email,
+                },
+            )
+
+            # Redirect to frontend with token in URL hash
+            frontend_url = base_url
+            redirect_url = f"{frontend_url}/#token={jwt_token}"
+            logger.info(f"Redirecting to frontend: {redirect_url}")
+            return RedirectResponse(url=redirect_url, status_code=302)
+
+    except httpx.HTTPError as e:
+        logger.exception(f"HTTP error during OAuth: {e}")
+        raise HTTPException(
+            status_code=500, detail="OAuth flow failed due to network error"
+        )
+    except Exception as e:
+        logger.exception(f"Unexpected error during OAuth: {e}")
+        raise HTTPException(status_code=500, detail="OAuth flow failed")
+
+
+@router.post("/api/tokens", response_model=TokenResponse)
+async def create_api_token(auth: AuthContext = Depends(get_auth_context)):
+    """Issue a new JWT for the authenticated user."""
+    token, expires_at = auth_service.issue_token_response(auth.user_id)
+    return TokenResponse(token=token, token_type="bearer", expires_at=expires_at)
+
+
+@router.get("/api/me", response_model=User)
+async def get_current_user(auth: AuthContext = Depends(get_auth_context)):
+    """Return profile metadata for the authenticated user."""
+    user_id = auth.user_id
+    vault_service = VaultService()
+    vault_path = vault_service.initialize_vault(user_id)
+
+    # Attempt to derive a stable "created" timestamp from the vault directory
+    try:
+        stat = vault_path.stat()
+        created_dt = datetime.fromtimestamp(stat.st_ctime, tz=timezone.utc)
+    except Exception:
+        created_dt = datetime.now(timezone.utc)
+
+    profile: Optional[HFProfile] = None
+    if user_id.startswith("hf-"):
+        username = user_id[len("hf-") :]
+        profile = HFProfile(
+            username=username,
+            name=username.replace("-", " ").title(),
+            avatar_url=f"https://api.dicebear.com/7.x/initials/svg?seed={username}",
+        )
+    elif user_id not in {"local-dev", "demo-user"}:
+        profile = HFProfile(username=user_id)
+
+    return User(
+        user_id=user_id,
+        hf_profile=profile,
+        vault_path=str(vault_path),
+        created=created_dt,
+    )
+
+
+__all__ = ["router"]

backend/src/api/routes/index.py

@@ -0,0 +1,135 @@
+"""HTTP API routes for index operations."""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+
+from ...models.index import IndexHealth
+from ...services.database import DatabaseService
+from ...services.indexer import IndexerService
+from ...services.vault import VaultService
+from ..middleware import AuthContext, get_auth_context
+
+router = APIRouter()
+
+
+class RebuildResponse(BaseModel):
+    """Response from index rebuild."""
+
+    status: str
+    notes_indexed: int
+
+
+@router.get("/api/index/health", response_model=IndexHealth)
+async def get_index_health(auth: AuthContext = Depends(get_auth_context)):
+    """Get index health statistics."""
+    user_id = auth.user_id
+    db_service = DatabaseService()
+    
+    try:
+        conn = db_service.connect()
+        try:
+            cursor = conn.execute(
+                """
+                SELECT note_count, last_full_rebuild, last_incremental_update
+                FROM index_health
+                WHERE user_id = ?
+                """,
+                (user_id,),
+            )
+            row = cursor.fetchone()
+            
+            if not row:
+                # Initialize if not exists
+                return IndexHealth(
+                    user_id=user_id,
+                    note_count=0,
+                    last_full_rebuild=None,
+                    last_incremental_update=None,
+                )
+            
+            last_full_rebuild = row["last_full_rebuild"]
+            last_incremental_update = row["last_incremental_update"]
+            
+            if last_full_rebuild and isinstance(last_full_rebuild, str):
+                last_full_rebuild = datetime.fromisoformat(last_full_rebuild.replace("Z", "+00:00"))
+            
+            if last_incremental_update and isinstance(last_incremental_update, str):
+                last_incremental_update = datetime.fromisoformat(last_incremental_update.replace("Z", "+00:00"))
+            
+            return IndexHealth(
+                user_id=user_id,
+                note_count=row["note_count"],
+                last_full_rebuild=last_full_rebuild,
+                last_incremental_update=last_incremental_update,
+            )
+        finally:
+            conn.close()
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to get index health: {str(e)}")
+
+
+@router.post("/api/index/rebuild", response_model=RebuildResponse)
+async def rebuild_index(auth: AuthContext = Depends(get_auth_context)):
+    """Rebuild the entire index from scratch."""
+    user_id = auth.user_id
+    vault_service = VaultService()
+    indexer_service = IndexerService()
+    
+    try:
+        # Get all notes
+        notes = vault_service.list_notes(user_id)
+        
+        # Clear existing index entries
+        db_service = DatabaseService()
+        conn = db_service.connect()
+        try:
+            with conn:
+                conn.execute("DELETE FROM note_metadata WHERE user_id = ?", (user_id,))
+                conn.execute("DELETE FROM note_fts WHERE user_id = ?", (user_id,))
+                conn.execute("DELETE FROM note_tags WHERE user_id = ?", (user_id,))
+                conn.execute("DELETE FROM note_links WHERE user_id = ?", (user_id,))
+        finally:
+            conn.close()
+        
+        # Re-index all notes
+        indexed_count = 0
+        for note in notes:
+            try:
+                note_data = vault_service.read_note(user_id, note["path"])
+                indexer_service.index_note(user_id, note_data)
+                indexed_count += 1
+            except Exception as e:
+                print(f"Failed to index {note['path']}: {e}")
+        
+        # Update index health
+        conn = db_service.connect()
+        try:
+            with conn:
+                conn.execute(
+                    """
+                    INSERT INTO index_health (user_id, note_count, last_full_rebuild, last_incremental_update)
+                    VALUES (?, ?, datetime('now'), datetime('now'))
+                    ON CONFLICT(user_id) DO UPDATE SET
+                        note_count = excluded.note_count,
+                        last_full_rebuild = excluded.last_full_rebuild,
+                        last_incremental_update = excluded.last_incremental_update
+                    """,
+                    (user_id, indexed_count),
+                )
+        finally:
+            conn.close()
+        
+        return RebuildResponse(
+            status="completed",
+            notes_indexed=indexed_count,
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to rebuild index: {str(e)}")
+
+
+__all__ = ["router", "RebuildResponse"]
+

backend/src/api/routes/notes.py

@@ -0,0 +1,288 @@
+"""HTTP API routes for note operations."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+from urllib.parse import unquote
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+
+from ...models.note import Note, NoteSummary, NoteUpdate, NoteCreate
+from ...services.database import DatabaseService
+from ...services.indexer import IndexerService
+from ...services.vault import VaultService
+from ..middleware import AuthContext, get_auth_context
+
+router = APIRouter()
+
+
+class ConflictError(Exception):
+    """Raised when optimistic concurrency check fails."""
+
+    def __init__(self, message: str = "Version conflict detected"):
+        self.message = message
+        super().__init__(self.message)
+
+
+@router.get("/api/notes", response_model=list[NoteSummary])
+async def list_notes(
+    folder: Optional[str] = Query(None, description="Optional folder filter"),
+    auth: AuthContext = Depends(get_auth_context),
+):
+    """List all notes in the vault."""
+    user_id = auth.user_id
+    vault_service = VaultService()
+    
+    try:
+        notes = vault_service.list_notes(user_id, folder=folder)
+        
+        summaries = []
+        for note in notes:
+            # list_notes returns {path, title, last_modified}
+            updated = note.get("last_modified")
+            if not isinstance(updated, datetime):
+                updated = datetime.now()
+            
+            summaries.append(
+                NoteSummary(
+                    note_path=note["path"],
+                    title=note["title"],
+                    updated=updated,
+                )
+            )
+        return summaries
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to list notes: {str(e)}")
+
+
+@router.post("/api/notes", response_model=Note, status_code=201)
+async def create_note(create: NoteCreate, auth: AuthContext = Depends(get_auth_context)):
+    """Create a new note."""
+    user_id = auth.user_id
+    vault_service = VaultService()
+    indexer_service = IndexerService()
+    db_service = DatabaseService()
+    
+    try:
+        note_path = create.note_path
+        
+        # Check if note already exists
+        try:
+            vault_service.read_note(user_id, note_path)
+            raise HTTPException(status_code=409, detail=f"Note already exists: {note_path}")
+        except FileNotFoundError:
+            pass  # Good, note doesn't exist
+        
+        # Prepare metadata
+        metadata = create.metadata.model_dump() if create.metadata else {}
+        if create.title:
+            metadata["title"] = create.title
+        
+        # Write note to vault
+        written_note = vault_service.write_note(
+            user_id,
+            note_path,
+            body=create.body,
+            metadata=metadata,
+            title=create.title
+        )
+        
+        # Index the note
+        new_version = indexer_service.index_note(user_id, written_note)
+        
+        # Update index health
+        conn = db_service.connect()
+        try:
+            with conn:
+                indexer_service.update_index_health(conn, user_id)
+        finally:
+            conn.close()
+        
+        # Return created note
+        created = written_note["metadata"].get("created")
+        updated_ts = written_note["metadata"].get("updated")
+        
+        if isinstance(created, str):
+            created = datetime.fromisoformat(created.replace("Z", "+00:00"))
+        elif not isinstance(created, datetime):
+            created = datetime.now()
+            
+        if isinstance(updated_ts, str):
+            updated_ts = datetime.fromisoformat(updated_ts.replace("Z", "+00:00"))
+        elif not isinstance(updated_ts, datetime):
+            updated_ts = created
+        
+        return Note(
+            user_id=user_id,
+            note_path=note_path,
+            version=new_version,
+            title=written_note["title"],
+            metadata=written_note["metadata"],
+            body=written_note["body"],
+            created=created,
+            updated=updated_ts,
+            size_bytes=written_note.get("size_bytes", len(written_note["body"].encode("utf-8"))),
+        )
+    except HTTPException:
+        raise
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to create note: {str(e)}")
+
+
+@router.get("/api/notes/{path:path}", response_model=Note)
+async def get_note(path: str, auth: AuthContext = Depends(get_auth_context)):
+    """Get a specific note by path."""
+    user_id = auth.user_id
+    vault_service = VaultService()
+    db_service = DatabaseService()
+    
+    try:
+        # URL decode the path
+        note_path = unquote(path)
+        
+        # Read note from vault
+        note_data = vault_service.read_note(user_id, note_path)
+        
+        # Get version from index
+        conn = db_service.connect()
+        try:
+            cursor = conn.execute(
+                "SELECT version FROM note_metadata WHERE user_id = ? AND note_path = ?",
+                (user_id, note_path),
+            )
+            row = cursor.fetchone()
+            version = row["version"] if row else 1
+        finally:
+            conn.close()
+        
+        # Parse metadata
+        metadata = note_data.get("metadata", {})
+        created = metadata.get("created")
+        updated = metadata.get("updated")
+        
+        if isinstance(created, str):
+            created = datetime.fromisoformat(created.replace("Z", "+00:00"))
+        elif not isinstance(created, datetime):
+            created = datetime.now()
+            
+        if isinstance(updated, str):
+            updated = datetime.fromisoformat(updated.replace("Z", "+00:00"))
+        elif not isinstance(updated, datetime):
+            updated = created
+        
+        return Note(
+            user_id=user_id,
+            note_path=note_path,
+            version=version,
+            title=note_data["title"],
+            metadata=metadata,
+            body=note_data["body"],
+            created=created,
+            updated=updated,
+            size_bytes=note_data.get("size_bytes", len(note_data["body"].encode("utf-8"))),
+        )
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Note not found: {path}")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to read note: {str(e)}")
+
+
+@router.put("/api/notes/{path:path}", response_model=Note)
+async def update_note(
+    path: str,
+    update: NoteUpdate,
+    auth: AuthContext = Depends(get_auth_context),
+):
+    """Update a note with optimistic concurrency control."""
+    user_id = auth.user_id
+    vault_service = VaultService()
+    indexer_service = IndexerService()
+    db_service = DatabaseService()
+    
+    try:
+        # URL decode the path
+        note_path = unquote(path)
+        
+        # Check version if provided
+        if update.if_version is not None:
+            conn = db_service.connect()
+            try:
+                cursor = conn.execute(
+                    "SELECT version FROM note_metadata WHERE user_id = ? AND note_path = ?",
+                    (user_id, note_path),
+                )
+                row = cursor.fetchone()
+                current_version = row["version"] if row else 0
+                
+                if current_version != update.if_version:
+                    raise ConflictError(
+                        f"Version conflict: expected {update.if_version}, got {current_version}"
+                    )
+            finally:
+                conn.close()
+        
+        # Prepare metadata
+        metadata = update.metadata.model_dump() if update.metadata else {}
+        if update.title:
+            metadata["title"] = update.title
+        
+        # Write note to vault
+        written_note = vault_service.write_note(
+            user_id, 
+            note_path, 
+            body=update.body, 
+            metadata=metadata,
+            title=update.title
+        )
+        
+        # Index the note
+        new_version = indexer_service.index_note(user_id, written_note)
+        
+        # Update index health
+        conn = db_service.connect()
+        try:
+            with conn:
+                indexer_service.update_index_health(conn, user_id)
+        finally:
+            conn.close()
+        
+        # Return updated note
+        created = written_note["metadata"].get("created")
+        updated_ts = written_note["metadata"].get("updated")
+        
+        if isinstance(created, str):
+            created = datetime.fromisoformat(created.replace("Z", "+00:00"))
+        elif not isinstance(created, datetime):
+            created = datetime.now()
+            
+        if isinstance(updated_ts, str):
+            updated_ts = datetime.fromisoformat(updated_ts.replace("Z", "+00:00"))
+        elif not isinstance(updated_ts, datetime):
+            updated_ts = created
+        
+        return Note(
+            user_id=user_id,
+            note_path=note_path,
+            version=new_version,
+            title=written_note["title"],
+            metadata=written_note["metadata"],
+            body=written_note["body"],
+            created=created,
+            updated=updated_ts,
+            size_bytes=written_note.get("size_bytes", len(written_note["body"].encode("utf-8"))),
+        )
+    except ConflictError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    except FileNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Note not found: {path}")
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to update note: {str(e)}")
+
+
+__all__ = ["router", "ConflictError"]
+

backend/src/api/routes/search.py

@@ -0,0 +1,107 @@
+"""HTTP API routes for search operations."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+from urllib.parse import unquote
+
+from fastapi import APIRouter, Depends, HTTPException, Query
+from pydantic import BaseModel
+
+from ...models.index import Tag
+from ...models.search import SearchResult
+from ...services.database import DatabaseService
+from ...services.indexer import IndexerService
+from ..middleware import AuthContext, get_auth_context
+
+router = APIRouter()
+
+
+class BacklinkResult(BaseModel):
+    """Result from backlinks query."""
+
+    note_path: str
+    title: str
+
+
+@router.get("/api/search", response_model=list[SearchResult])
+async def search_notes(
+    q: str = Query(..., min_length=1, max_length=256),
+    auth: AuthContext = Depends(get_auth_context),
+):
+    """Full-text search across all notes."""
+    user_id = auth.user_id
+    indexer_service = IndexerService()
+    
+    try:
+        results = indexer_service.search_notes(user_id, q, limit=50)
+        
+        search_results = []
+        for result in results:
+            # Use snippet from search results
+            snippet = result.get("snippet", "")
+            
+            updated = result.get("updated")
+            if isinstance(updated, str):
+                updated = datetime.fromisoformat(updated.replace("Z", "+00:00"))
+            elif not isinstance(updated, datetime):
+                updated = datetime.now()
+            
+            search_results.append(
+                SearchResult(
+                    note_path=result["path"],
+                    title=result["title"],
+                    snippet=snippet,
+                    score=result.get("score", 0.0),
+                    updated=updated,
+                )
+            )
+        
+        return search_results
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Search failed: {str(e)}")
+
+
+@router.get("/api/backlinks/{path:path}", response_model=list[BacklinkResult])
+async def get_backlinks(path: str, auth: AuthContext = Depends(get_auth_context)):
+    """Get all notes that link to this note."""
+    user_id = auth.user_id
+    indexer_service = IndexerService()
+    
+    try:
+        # URL decode the path
+        note_path = unquote(path)
+        
+        backlinks = indexer_service.get_backlinks(user_id, note_path)
+        
+        return [
+            BacklinkResult(
+                note_path=backlink["path"],
+                title=backlink["title"],
+            )
+            for backlink in backlinks
+        ]
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to get backlinks: {str(e)}")
+
+
+@router.get("/api/tags", response_model=list[Tag])
+async def get_tags(auth: AuthContext = Depends(get_auth_context)):
+    """Get all tags with usage counts."""
+    user_id = auth.user_id
+    indexer_service = IndexerService()
+    
+    try:
+        tags = indexer_service.get_tags(user_id)
+        
+        return [
+            Tag(tag_name=tag["tag"], count=tag["count"])
+            for tag in tags
+        ]
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"Failed to get tags: {str(e)}")
+
+
+__all__ = ["router", "BacklinkResult"]
+

backend/src/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP (Model Context Protocol) server implementation."""
+
+from .server import mcp
+
+__all__ = ["mcp"]

backend/src/mcp/server.py

@@ -0,0 +1,284 @@
+"""FastMCP server exposing vault and indexing tools."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any, Dict, List, Optional
+from pathlib import Path
+
+from dotenv import load_dotenv
+from fastmcp import FastMCP
+from pydantic import Field
+
+# Load environment variables from the backend/.env file regardless of CWD
+ENV_PATH = Path(__file__).resolve().parents[2] / ".env"
+load_dotenv(dotenv_path=ENV_PATH)
+
+from ..services import IndexerService, VaultNote, VaultService
+from ..services.auth import AuthError, AuthService
+
+try:
+    from fastmcp.server.http import _current_http_request  # type: ignore
+except ImportError:  # pragma: no cover
+    _current_http_request = None
+
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP(
+    "obsidian-docs-viewer",
+    instructions=(
+        "Multi-tenant vault tools. STDIO uses user_id 'local-dev'; HTTP mode must validate each "
+        "request with JWT.sub. Note paths must be relative '.md' ≤256 chars without '..' or '\\'. "
+        "Frontmatter is YAML: tags are string arrays and 'version' is reserved. Notes must be ≤1 MiB; "
+        "writes refresh created/updated timestamps and synchronously update the search index; deletes "
+        "clear index rows and backlinks. Wikilinks use [[...]] slug matching (prefer same folder, else "
+        "lexicographic). Search ranking = bm25(title*3, body*1) + recency bonus (+1 ≤7d, +0.5 ≤30d)."
+    ),
+)
+
+vault_service = VaultService()
+indexer_service = IndexerService()
+auth_service = AuthService()
+
+
+def _current_user_id() -> str:
+    """Resolve the acting user ID (local mode defaults to local-dev)."""
+    # HTTP transport (hosted) uses Authorization headers
+    if _current_http_request is not None:
+        try:
+            request = _current_http_request.get()  # type: ignore[call-arg]
+        except LookupError:
+            request = None
+        if request is not None:
+            header = request.headers.get("Authorization")
+            if not header:
+                raise PermissionError("Authorization header required")
+            scheme, _, token = header.partition(" ")
+            if scheme.lower() != "bearer" or not token:
+                raise PermissionError("Authorization header must be 'Bearer <token>'")
+            try:
+                payload = auth_service.validate_jwt(token)
+            except AuthError as exc:
+                raise PermissionError(exc.message) from exc
+            os.environ.setdefault("LOCAL_USER_ID", payload.sub)
+            return payload.sub
+
+    # STDIO / local fall back
+    return os.getenv("LOCAL_USER_ID", "local-dev")
+
+
+def _note_to_response(note: VaultNote) -> Dict[str, Any]:
+    return {
+        "path": note["path"],
+        "title": note["title"],
+        "metadata": dict(note.get("metadata") or {}),
+        "body": note.get("body", ""),
+    }
+
+
+@mcp.tool(
+    name="list_notes",
+    description="List notes in the vault (optionally scoped to a folder).",
+)
+def list_notes(
+    folder: Optional[str] = Field(
+        default=None,
+        description="Optional relative folder (trim '/' ; no '..' or '\\').",
+    ),
+) -> List[Dict[str, Any]]:
+    start_time = time.time()
+    user_id = _current_user_id()
+
+    notes = vault_service.list_notes(user_id, folder=folder)
+
+    duration_ms = (time.time() - start_time) * 1000
+    logger.info(
+        "MCP tool called",
+        extra={
+            "tool_name": "list_notes",
+            "user_id": user_id,
+            "folder": folder or "(root)",
+            "result_count": len(notes),
+            "duration_ms": f"{duration_ms:.2f}",
+        },
+    )
+
+    return [
+        {
+            "path": entry["path"],
+            "title": entry["title"],
+            "last_modified": entry["last_modified"].isoformat(),
+        }
+        for entry in notes
+    ]
+
+
+@mcp.tool(name="read_note", description="Read a Markdown note with metadata and body.")
+def read_note(
+    path: str = Field(
+        ..., description="Relative '.md' path ≤256 chars (no '..' or '\\')."
+    ),
+) -> Dict[str, Any]:
+    start_time = time.time()
+    user_id = _current_user_id()
+
+    note = vault_service.read_note(user_id, path)
+
+    duration_ms = (time.time() - start_time) * 1000
+    logger.info(
+        "MCP tool called",
+        extra={
+            "tool_name": "read_note",
+            "user_id": user_id,
+            "note_path": path,
+            "duration_ms": f"{duration_ms:.2f}",
+        },
+    )
+
+    return _note_to_response(note)
+
+
+@mcp.tool(
+    name="write_note",
+    description="Create or update a note. Automatically updates frontmatter timestamps and search index.",
+)
+def write_note(
+    path: str = Field(
+        ..., description="Relative '.md' path ≤256 chars (no '..' or '\\')."
+    ),
+    body: str = Field(..., description="Markdown body ≤1 MiB."),
+    title: Optional[str] = Field(
+        default=None,
+        description="Optional title override; otherwise frontmatter/H1/filename is used.",
+    ),
+    metadata: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Optional frontmatter dict (tags arrays of strings; 'version' reserved).",
+    ),
+) -> Dict[str, Any]:
+    start_time = time.time()
+    user_id = _current_user_id()
+
+    note = vault_service.write_note(
+        user_id,
+        path,
+        title=title,
+        metadata=metadata,
+        body=body,
+    )
+    indexer_service.index_note(user_id, note)
+
+    duration_ms = (time.time() - start_time) * 1000
+    logger.info(
+        "MCP tool called",
+        extra={
+            "tool_name": "write_note",
+            "user_id": user_id,
+            "note_path": path,
+            "duration_ms": f"{duration_ms:.2f}",
+        },
+    )
+
+    return {"status": "ok", "path": path}
+
+
+@mcp.tool(name="delete_note", description="Delete a note and remove it from the index.")
+def delete_note(
+    path: str = Field(
+        ..., description="Relative '.md' path ≤256 chars (no '..' or '\\')."
+    ),
+) -> Dict[str, str]:
+    start_time = time.time()
+    user_id = _current_user_id()
+
+    vault_service.delete_note(user_id, path)
+    indexer_service.delete_note_index(user_id, path)
+
+    duration_ms = (time.time() - start_time) * 1000
+    logger.info(
+        "MCP tool called",
+        extra={
+            "tool_name": "delete_note",
+            "user_id": user_id,
+            "note_path": path,
+            "duration_ms": f"{duration_ms:.2f}",
+        },
+    )
+
+    return {"status": "ok"}
+
+
+@mcp.tool(
+    name="search_notes",
+    description="Full-text search with snippets and recency-aware scoring.",
+)
+def search_notes(
+    query: str = Field(..., description="Non-empty search query (bm25 + recency)."),
+    limit: int = Field(50, ge=1, le=100, description="Result cap between 1 and 100."),
+) -> List[Dict[str, Any]]:
+    start_time = time.time()
+    user_id = _current_user_id()
+
+    results = indexer_service.search_notes(user_id, query, limit=limit)
+
+    duration_ms = (time.time() - start_time) * 1000
+    logger.info(
+        "MCP tool called",
+        extra={
+            "tool_name": "search_notes",
+            "user_id": user_id,
+            "query": query,
+            "limit": limit,
+            "result_count": len(results),
+            "duration_ms": f"{duration_ms:.2f}",
+        },
+    )
+
+    return [
+        {
+            "path": row["path"],
+            "title": row["title"],
+            "snippet": row["snippet"],
+        }
+        for row in results
+    ]
+
+
+@mcp.tool(
+    name="get_backlinks", description="List notes that reference the target note."
+)
+def get_backlinks(
+    path: str = Field(
+        ..., description="Relative '.md' path ≤256 chars (no '..' or '\\')."
+    ),
+) -> List[Dict[str, Any]]:
+    user_id = _current_user_id()
+    backlinks = indexer_service.get_backlinks(user_id, path)
+    return backlinks
+
+
+@mcp.tool(name="get_tags", description="List tags and associated note counts.")
+def get_tags() -> List[Dict[str, Any]]:
+    user_id = _current_user_id()
+    return indexer_service.get_tags(user_id)
+
+
+if __name__ == "__main__":
+    transport = os.getenv("MCP_TRANSPORT", "stdio").strip().lower()
+
+    # Configure HTTP transport with custom port if specified
+    if transport == "http":
+        # Prefer MCP_PORT, then platform-provided PORT, with a sane default.
+        port = int(os.getenv("MCP_PORT"))
+        # Bind to all interfaces by default for hosted environments (HF Spaces).
+        host = os.getenv("MCP_HOST", "0.0.0.0")
+        logger.info(
+            "Starting MCP server",
+            extra={"transport": transport, "host": host, "port": port},
+        )
+        mcp.run(transport=transport, host=host, port=port)
+    else:
+        logger.info("Starting MCP server", extra={"transport": transport})
+        mcp.run(transport=transport)

backend/src/models/__init__.py

@@ -0,0 +1,25 @@
+"""Pydantic models for data validation and serialization."""
+
+from .auth import JWTPayload, TokenResponse
+from .index import IndexHealth, Tag, Wikilink
+from .note import Note, NoteCreate, NoteMetadata, NoteSummary, NoteUpdate
+from .search import SearchRequest, SearchResult
+from .user import HFProfile, User
+
+__all__ = [
+    "User",
+    "HFProfile",
+    "Note",
+    "NoteMetadata",
+    "NoteCreate",
+    "NoteUpdate",
+    "NoteSummary",
+    "Wikilink",
+    "Tag",
+    "IndexHealth",
+    "SearchResult",
+    "SearchRequest",
+    "TokenResponse",
+    "JWTPayload",
+]
+