Spaces:

MCP-1st-Birthday
/

Vault.MCP

Running

App Files Files Community

Vault.MCP / specs /001-obsidian-docs-viewer /quickstart.md

bigwolfe

changes for MCP integration. Still not working.

58b4b49 27 days ago

preview code

raw

history blame contribute delete

34.9 kB

Quickstart Guide: Multi-Tenant Obsidian-Like Docs Viewer

Feature Branch: 001-obsidian-docs-viewer Created: 2025-11-15 Status: Draft

Prerequisites
Local Development Setup
Running the Backend
Running the Frontend
MCP Client Configuration
Testing Workflows
Development Workflows
Hugging Face Space Deployment
Troubleshooting

Prerequisites

Before starting, ensure you have the following installed:

Required Software

Python: 3.11 or higher
- Check version: python --version or python3 --version
- Download: https://www.python.org/downloads/
Node.js: 18 or higher
- Check version: node --version
- Download: https://nodejs.org/
Git: Any recent version
- Check version: git --version
- Download: https://git-scm.com/downloads/

Optional Tools

Poetry (recommended for Python dependency management): pip install poetry
Claude Desktop or Claude Code (for MCP STDIO integration)
Docker (for containerized deployment testing)

Local Development Setup

1. Clone the Repository

git clone <repository-url>
cd Document-MCP

2. Create Environment Configuration

Copy the example environment file and customize it:

cp .env.example .env

.env.example contents:

# Application Mode
# Options: "local" (single-user development) or "space" (multi-tenant HF Space)
MODE=local

# JWT Secret Key
# Required for HTTP/JWT auth (space mode). Remove this line entirely in local STDIO mode.
# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
# JWT_SECRET_KEY=your-secret-key-change-in-production

# Vault Storage
# Base directory for per-user vault storage
VAULT_BASE_DIR=./data/vaults

# SQLite Database
# Path to SQLite database file
DB_PATH=./data/index.db

# Local Mode Configuration
# Default user ID for local development (no authentication)
LOCAL_USER_ID=local-dev

# Optional: Static Bearer Token for Local Mode
# Leave empty to disable token requirement in local mode
# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
LOCAL_STATIC_TOKEN=

# Hugging Face Space Configuration (only needed for HF deployment)
# HF_OAUTH_CLIENT_ID=your-hf-client-id
# HF_OAUTH_CLIENT_SECRET=your-hf-client-secret
# HF_SPACE_HOST=https://your-space.hf.space

# Backend Server
BACKEND_HOST=0.0.0.0
BACKEND_PORT=8000

# Frontend Development
VITE_API_BASE_URL=http://localhost:8000

Generate secure secrets:

# Generate JWT secret
python -c "import secrets; print(secrets.token_urlsafe(32))"

# Generate optional local static token
python -c "import secrets; print(secrets.token_urlsafe(32))"

Update .env with generated values.

3. Backend Setup

Navigate to the backend directory:

cd backend

Option A: Using Poetry (Recommended)

# Install Poetry if not already installed
pip install poetry

# Install dependencies
poetry install

# Activate virtual environment
poetry shell

Option B: Using pip with venv

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

requirements.txt example:

fastapi==0.104.1
uvicorn[standard]==0.24.0
fastmcp==0.3.0
python-frontmatter==1.0.1
PyJWT==2.8.0
huggingface-hub==0.19.4
pydantic==2.5.0
python-multipart==0.0.6
aiosqlite==0.19.0

4. Initialize Database Schema

Run the database initialization script:

# From backend/ directory
python -m src.services.init_db

src/services/init_db.py (create this file):

"""
Database initialization script.
Creates SQLite schema and indexes.
"""
import sqlite3
import os
from pathlib import Path

def init_database(db_path: str):
    """Initialize SQLite database with schema."""
    # Ensure directory exists
    db_file = Path(db_path)
    db_file.parent.mkdir(parents=True, exist_ok=True)

    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()

    # Begin transaction
    cursor.execute("BEGIN TRANSACTION")

    # Core metadata table
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS note_metadata (
            user_id TEXT NOT NULL,
            note_path TEXT NOT NULL,
            version INTEGER NOT NULL DEFAULT 1,
            title TEXT NOT NULL,
            created TEXT NOT NULL,
            updated TEXT NOT NULL,
            size_bytes INTEGER NOT NULL DEFAULT 0,
            normalized_title_slug TEXT,
            normalized_path_slug TEXT,
            PRIMARY KEY (user_id, note_path)
        )
    """)

    cursor.execute("CREATE INDEX IF NOT EXISTS idx_metadata_user ON note_metadata(user_id)")
    cursor.execute("CREATE INDEX IF NOT EXISTS idx_metadata_updated ON note_metadata(user_id, updated DESC)")
    cursor.execute("CREATE INDEX IF NOT EXISTS idx_metadata_title_slug ON note_metadata(user_id, normalized_title_slug)")
    cursor.execute("CREATE INDEX IF NOT EXISTS idx_metadata_path_slug ON note_metadata(user_id, normalized_path_slug)")

    # Full-text search index
    cursor.execute("""
        CREATE VIRTUAL TABLE IF NOT EXISTS note_fts USING fts5(
            user_id UNINDEXED,
            note_path UNINDEXED,
            title,
            body,
            content='',
            tokenize='porter unicode61',
            prefix='2 3'
        )
    """)

    # Tag index
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS note_tags (
            user_id TEXT NOT NULL,
            note_path TEXT NOT NULL,
            tag TEXT NOT NULL,
            PRIMARY KEY (user_id, note_path, tag)
        )
    """)

    cursor.execute("CREATE INDEX IF NOT EXISTS idx_tags_user_tag ON note_tags(user_id, tag)")
    cursor.execute("CREATE INDEX IF NOT EXISTS idx_tags_user_path ON note_tags(user_id, note_path)")

    # Link graph
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS note_links (
            user_id TEXT NOT NULL,
            source_path TEXT NOT NULL,
            target_path TEXT,
            link_text TEXT NOT NULL,
            is_resolved INTEGER NOT NULL DEFAULT 0,
            PRIMARY KEY (user_id, source_path, link_text)
        )
    """)

    cursor.execute("CREATE INDEX IF NOT EXISTS idx_links_user_source ON note_links(user_id, source_path)")
    cursor.execute("CREATE INDEX IF NOT EXISTS idx_links_user_target ON note_links(user_id, target_path)")
    cursor.execute("CREATE INDEX IF NOT EXISTS idx_links_unresolved ON note_links(user_id, is_resolved)")

    # Index health tracking
    cursor.execute("""
        CREATE TABLE IF NOT EXISTS index_health (
            user_id TEXT PRIMARY KEY,
            note_count INTEGER NOT NULL DEFAULT 0,
            last_full_rebuild TEXT,
            last_incremental_update TEXT
        )
    """)

    # Commit transaction
    cursor.execute("COMMIT")

    conn.close()
    print(f"Database initialized at: {db_path}")

if __name__ == "__main__":
    # Load DB path from environment or use default
    db_path = os.getenv("DB_PATH", "./data/index.db")
    init_database(db_path)

Run initialization:

python -m src.services.init_db

Expected output:

Database initialized at: ./data/index.db

5. Create Vault Directory Structure

# From project root
mkdir -p data/vaults/local-dev

# Create a test note
cat > data/vaults/local-dev/README.md << 'EOF'
---
title: Welcome to Your Vault
tags: [getting-started]
created: 2025-01-15T10:00:00Z
updated: 2025-01-15T10:00:00Z
---

# Welcome to Your Vault

This is your personal documentation vault.

## Features

- **AI-powered writing**: Use MCP tools to create and update notes
- **Full-text search**: Search across all notes instantly
- **Wikilinks**: Link notes together with `[[Note Name]]` syntax
- **Tags**: Organize notes with frontmatter tags

## Getting Started

Try creating your first note:
- Via MCP: Use the `write_note` tool
- Via UI: Click "New Note" in the sidebar

Check out [[Quick Start Guide]] for more details.
EOF

6. Frontend Setup

Open a new terminal and navigate to the frontend directory:

cd frontend

Install dependencies:

npm install

package.json example:

{
  "name": "obsidian-docs-viewer-frontend",
  "version": "0.1.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview",
    "test": "vitest",
    "test:e2e": "playwright test",
    "lint": "eslint src --ext ts,tsx"
  },
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.20.0",
    "react-markdown": "^9.0.0",
    "remark-gfm": "^4.0.0",
    "remark-frontmatter": "^5.0.0",
    "@radix-ui/react-dialog": "^1.0.5",
    "@radix-ui/react-dropdown-menu": "^2.0.6",
    "@radix-ui/react-scroll-area": "^1.0.5",
    "@radix-ui/react-separator": "^1.0.3",
    "class-variance-authority": "^0.7.0",
    "clsx": "^2.0.0",
    "tailwind-merge": "^2.1.0",
    "lucide-react": "^0.295.0"
  },
  "devDependencies": {
    "@types/react": "^18.2.43",
    "@types/react-dom": "^18.2.17",
    "@typescript-eslint/eslint-plugin": "^6.14.0",
    "@typescript-eslint/parser": "^6.14.0",
    "@vitejs/plugin-react": "^4.2.1",
    "autoprefixer": "^10.4.16",
    "eslint": "^8.55.0",
    "postcss": "^8.4.32",
    "tailwindcss": "^3.3.6",
    "typescript": "^5.2.2",
    "vite": "^5.0.8",
    "vitest": "^1.0.4",
    "@playwright/test": "^1.40.0"
  }
}

Configure API base URL (if not already in .env):

# frontend/.env
VITE_API_BASE_URL=http://localhost:8000

Running the Backend

The backend can be run in multiple modes depending on your use case.

Mode 1: FastAPI HTTP Server (for UI access)

Start the FastAPI development server:

# From backend/ directory (with venv activated)
uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000

Expected output:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Test the API:

# Health check
curl http://localhost:8000/api/health

# Expected response:
# {"status": "ok", "mode": "local"}

# Get user info (local mode)
curl http://localhost:8000/api/me

# Expected response:
# {"user_id": "local-dev", "vault_path": "./data/vaults/local-dev"}

Mode 2: MCP STDIO Server (for Claude Code/Desktop)

Start the MCP server in STDIO mode:

# From backend/ directory
python -m src.mcp.server

Expected output:

MCP server starting in STDIO mode...
Listening for MCP requests on stdin/stdout...

This server communicates via standard input/output and is designed to be invoked by MCP clients like Claude Desktop.

Mode 3: MCP HTTP Server (for remote MCP access)

Start the MCP server with HTTP transport:

# From backend/ directory
python -m src.mcp.server --http --port 8001

Expected output:

MCP server starting in HTTP mode...
Server running at: http://0.0.0.0:8001
Authentication: Bearer token required

Test MCP HTTP endpoint:

# Issue a token first (if using authentication)
curl -X POST http://localhost:8000/api/tokens

# Use token to call MCP tool
curl -X POST http://localhost:8001/mcp/call \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_notes",
    "arguments": {}
  }'

Run All Backend Services (Production Mode)

For production, run both servers together:

# Terminal 1: FastAPI server
uvicorn src.api.main:app --host 0.0.0.0 --port 8000

# Terminal 2: MCP HTTP server
python -m src.mcp.server --http --port 8001

Or use a process manager like supervisord or pm2.

Running the Frontend

Start the Vite development server:

# From frontend/ directory
npm run dev

Expected output:

  VITE v5.0.8  ready in 523 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

Open your browser to http://localhost:5173

Local Mode UI Flow

Landing page: In local mode, you'll be automatically authenticated as local-dev
Directory pane (left sidebar):
- Shows vault folder structure
- Click on folders to expand/collapse
- Click on notes to view content
Search bar (top of left sidebar):
- Type to search notes
- Results appear in dropdown with snippets
Main pane (right side):
- View rendered Markdown
- Click "Edit" to enter edit mode
- Click wikilinks to navigate between notes
Footer (below main pane):
- View tags (clickable chips)
- See created/updated timestamps
- View backlinks (notes that reference current note)

Configure Static Token (Optional)

If you set LOCAL_STATIC_TOKEN in .env, configure the frontend:

In browser console (http://localhost:5173):

localStorage.setItem('auth_token', 'your-static-token-from-env');
location.reload();

Or update frontend/src/services/auth.ts to automatically use the token in local mode.

MCP Client Configuration

Claude Desktop (STDIO)

Configure Claude Desktop to use the MCP STDIO server.

Config file location:

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

claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian-docs": {
      "command": "python",
      "args": [
        "-m",
        "src.mcp.server"
      ],
      "cwd": "/absolute/path/to/Document-MCP/backend",
      "env": {
        "MODE": "local",
        "VAULT_BASE_DIR": "/absolute/path/to/Document-MCP/data/vaults",
        "DB_PATH": "/absolute/path/to/Document-MCP/data/index.db",
        "LOCAL_USER_ID": "local-dev"
      }
    }
  }
}

Important: Replace /absolute/path/to/Document-MCP with your actual project path.

Test in Claude Desktop:

Restart Claude Desktop
Open a conversation
Try: "List all notes in my vault"
Claude should call the list_notes MCP tool

Claude Code (STDIO)

Claude Code uses a similar configuration. Create or edit ~/.claude/mcp_config.json:

{
  "mcpServers": {
    "obsidian-docs": {
      "command": "python",
      "args": ["-m", "src.mcp.server"],
      "cwd": "/absolute/path/to/Document-MCP/backend",
      "env": {
        "MODE": "local",
        "VAULT_BASE_DIR": "/absolute/path/to/Document-MCP/data/vaults",
        "DB_PATH": "/absolute/path/to/Document-MCP/data/index.db"
      }
    }
  }
}

JWT_SECRET_KEY is optional for STDIO mode—omit it from the environment when running locally without HTTP authentication.

MCP HTTP Transport (Remote Access)

For remote access (e.g., from HF Space or external tools), use HTTP transport.

Setup:

Start MCP HTTP server:

python -m src.mcp.server --http --port 8001

Issue a JWT token:

curl -X POST http://localhost:8000/api/tokens

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_at": "2025-04-15T10:30:00Z"
}

Configure MCP client with HTTP endpoint:

Example HTTP MCP client configuration (pseudo-code):

{
  "mcp_endpoint": "http://localhost:8001/mcp",
  "auth": {
    "type": "bearer",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Manual HTTP MCP call:

curl -X POST http://localhost:8001/mcp/call \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "write_note",
    "arguments": {
      "path": "test/hello.md",
      "title": "Hello World",
      "body": "# Hello World\n\nThis is a test note created via MCP HTTP."
    }
  }'

Expected response:

{
  "status": "ok",
  "path": "test/hello.md"
}

Testing Workflows

Backend Unit Tests

Run pytest for unit tests:

# From backend/ directory
pytest tests/unit -v

Example test structure:

backend/tests/
├── unit/
│   ├── test_vault.py          # Vault service tests
│   ├── test_indexer.py        # Indexer service tests
│   ├── test_auth.py           # Auth service tests
│   └── test_wikilink.py       # Wikilink resolution tests
├── integration/
│   ├── test_api_notes.py      # API integration tests
│   ├── test_api_search.py     # Search API tests
│   └── test_mcp_tools.py      # MCP tool integration tests
└── contract/
    ├── test_http_api_contract.py   # OpenAPI contract validation
    └── test_mcp_contract.py        # MCP tool schema validation

Run specific test file:

pytest tests/unit/test_vault.py -v

Expected output:

tests/unit/test_vault.py::test_create_note PASSED
tests/unit/test_vault.py::test_read_note PASSED
tests/unit/test_vault.py::test_update_note PASSED
tests/unit/test_vault.py::test_delete_note PASSED
tests/unit/test_vault.py::test_path_validation PASSED
tests/unit/test_vault.py::test_path_traversal_blocked PASSED

====== 6 passed in 0.23s ======

Backend Integration Tests

Test full API workflows:

# From backend/ directory
pytest tests/integration -v

Expected output:

tests/integration/test_api_notes.py::test_create_and_read_note PASSED
tests/integration/test_api_notes.py::test_update_note_with_version PASSED
tests/integration/test_api_notes.py::test_version_conflict_409 PASSED
tests/integration/test_api_search.py::test_full_text_search PASSED
tests/integration/test_api_search.py::test_search_ranking PASSED
tests/integration/test_mcp_tools.py::test_write_note_tool PASSED
tests/integration/test_mcp_tools.py::test_search_notes_tool PASSED

====== 7 passed in 1.45s ======

Backend Contract Tests

Validate API contracts against OpenAPI spec:

pytest tests/contract -v

Expected output:

tests/contract/test_http_api_contract.py::test_openapi_spec_valid PASSED
tests/contract/test_http_api_contract.py::test_all_endpoints_match_spec PASSED
tests/contract/test_mcp_contract.py::test_mcp_tool_schemas_valid PASSED

====== 3 passed in 0.34s ======

Frontend Unit Tests

Run Vitest for component tests:

# From frontend/ directory
npm test

Example test structure:

frontend/tests/
├── unit/
│   ├── DirectoryTree.test.tsx
│   ├── NoteViewer.test.tsx
│   ├── NoteEditor.test.tsx
│   ├── SearchBar.test.tsx
│   └── wikilink.test.ts
└── e2e/
    ├── note-crud.spec.ts
    ├── search.spec.ts
    └── navigation.spec.ts

Run specific test:

npm test -- DirectoryTree.test.tsx

Expected output:

✓ tests/unit/DirectoryTree.test.tsx (5)
  ✓ renders folder tree structure
  ✓ expands/collapses folders on click
  ✓ selects note on click
  ✓ highlights selected note
  ✓ updates tree when notes change

Test Files  1 passed (1)
Tests  5 passed (5)

Frontend E2E Tests

Run Playwright for end-to-end tests:

# From frontend/ directory
npm run test:e2e

Setup Playwright (first time):

npx playwright install

Expected output:

Running 8 tests using 4 workers

  ✓ [chromium] › note-crud.spec.ts:3:1 › create new note (1.2s)
  ✓ [chromium] › note-crud.spec.ts:15:1 › edit existing note (0.9s)
  ✓ [chromium] › note-crud.spec.ts:28:1 › delete note (0.7s)
  ✓ [chromium] › search.spec.ts:3:1 › search notes by title (0.8s)
  ✓ [chromium] › search.spec.ts:12:1 › search notes by content (0.9s)
  ✓ [chromium] › navigation.spec.ts:3:1 › navigate via directory tree (0.6s)
  ✓ [chromium] › navigation.spec.ts:14:1 › navigate via wikilink click (1.1s)
  ✓ [chromium] › navigation.spec.ts:25:1 › view backlinks (0.8s)

  8 passed (6.0s)

Development Workflows

Workflow 1: AI Agent Writes a Note via MCP

Scenario: Use Claude Desktop to create a new design document.

Open Claude Desktop (with MCP configured)

Prompt Claude:

Create a new note at "design/api-authentication.md" with the following:

Title: API Authentication Design
Tags: backend, security, api

Content:
# API Authentication Design

## Overview
This document describes the authentication strategy for our API.

## JWT Token Flow
1. User authenticates via HF OAuth
2. Server issues JWT with 90-day expiration
3. Client includes token in Authorization header

## Token Validation
- Validate signature using HS256
- Check expiration timestamp
- Extract user_id from 'sub' claim

See [[Security Best Practices]] for more details.

Claude executes:
- Calls write_note MCP tool
- Creates file at data/vaults/local-dev/design/api-authentication.md
- Writes frontmatter with title, tags, timestamps
- Writes markdown body
- Updates index (full-text search, tag index, wikilink graph)
Verify in UI:
- Refresh browser at http://localhost:5173
- Expand "design" folder in directory tree
- Click "api-authentication.md"
- See rendered note with wikilink to "Security Best Practices"

Workflow 2: Human Edits a Note in UI

Scenario: Fix a typo in the note created above.

Navigate to note:
- Open http://localhost:5173
- Click on "design/api-authentication.md" in directory tree
Enter edit mode:
- Click "Edit" button in top-right
- UI switches to split view: markdown editor (left) and live preview (right)

Make changes:

Fix typo: "authenication" → "authentication"

Add a new section:

## Token Expiration
Tokens expire after 90 days. Users must re-authenticate.

Save changes:
- Click "Save" button
- UI sends PUT /api/notes/design/api-authentication.md with if_version: 1
- Backend increments version to 2, updates timestamp
- UI switches back to read mode with updated content
Verify version tracking:
- Check footer: "Updated: "
- Try editing again (version is now 2)

Workflow 3: Search for Notes

Scenario: Find all notes about "authentication".

Use search bar:
- Type "authentication" in search bar (top of left sidebar)
- Search debounces and calls GET /api/search?q=authentication
View results:
- Results dropdown shows:
  - "API Authentication Design" (title match, high score)
  - "Security Best Practices" (body match, lower score)
- Snippets highlight matching text: "...API authentication strategy..."
Navigate to result:
- Click on "API Authentication Design"
- Main pane renders the note

Workflow 4: Follow Wikilinks and View Backlinks

Scenario: Navigate from "API Authentication Design" to "Security Best Practices" via wikilink.

View note with wikilink:
- Open "design/api-authentication.md"
- See wikilink: [[Security Best Practices]] rendered as clickable link
Click wikilink:
- UI resolves slug: "security-best-practices"
- Navigates to "security-best-practices.md" (or prompts to create if not exists)
View backlinks:
- Footer shows "Referenced by:" section
- Lists "design/api-authentication.md" as a backlink
- Click backlink to navigate back

Workflow 5: Rebuild Index

Scenario: Manually added notes outside the app, need to rebuild index.

Add notes manually: ```bash # From terminal cat > data/vaults/local-dev/notes/meeting-2025-01-16.md << 'EOF'

title: Team Meeting Notes tags: [meetings]

Team Meeting - Jan 16, 2025

Attendees
- Alice, Bob, Charlie
Topics
- Reviewed [[API Authentication Design]]
- Discussed deployment strategy EOF

Rebuild index:

curl -X POST http://localhost:8000/api/index/rebuild

Response:

{
  "status": "ok",
  "note_count": 3,
  "rebuilt_at": "2025-01-16T14:30:00Z"
}

Verify in UI:
- Refresh browser
- See new note in directory tree
- Note is searchable
- Backlink from "API Authentication Design" now shows "Team Meeting Notes"

Hugging Face Space Deployment

Deploy the application to Hugging Face Spaces for multi-tenant access.

Prerequisites

HuggingFace account: https://huggingface.co/join
Create a Space:
- Go to https://huggingface.co/new-space
- Choose "Docker" as SDK
- Enable "OAuth" in Space settings

1. Configure OAuth

In your Space settings, enable OAuth and note:

Client ID: hf_oauth_client_id_xxxxx
Client Secret: hf_oauth_client_secret_xxxxx

2. Set Environment Variables

In Space settings → Variables, add:

Variable	Value	Visibility
`MODE`	`space`	Public
`JWT_SECRET_KEY`	(generate secure secret)	Secret
`VAULT_BASE_DIR`	`/data/vaults`	Public
`DB_PATH`	`/data/index.db`	Public
`HF_OAUTH_CLIENT_ID`	(from OAuth settings)	Secret
`HF_OAUTH_CLIENT_SECRET`	(from OAuth settings)	Secret
`HF_SPACE_HOST`	`https://your-space.hf.space`	Public

3. Create Dockerfile

Dockerfile:

FROM python:3.11-slim

WORKDIR /app

# Install Node.js for frontend build
RUN apt-get update && apt-get install -y \
    nodejs \
    npm \
    && rm -rf /var/lib/apt/lists/*

# Copy backend
COPY backend/ /app/backend/
WORKDIR /app/backend
RUN pip install --no-cache-dir -r requirements.txt

# Initialize database
RUN python -m src.services.init_db

# Copy frontend
COPY frontend/ /app/frontend/
WORKDIR /app/frontend

# Build frontend
RUN npm install && npm run build

# Copy built frontend to backend static directory
RUN mkdir -p /app/backend/static && \
    cp -r /app/frontend/dist/* /app/backend/static/

# Set working directory back to backend
WORKDIR /app/backend

# Create data directories
RUN mkdir -p /data/vaults

# Expose ports
EXPOSE 7860 8001

# Start backend (FastAPI + MCP HTTP)
CMD ["sh", "-c", "uvicorn src.api.main:app --host 0.0.0.0 --port 7860 & python -m src.mcp.server --http --port 8001 & wait"]

4. Configure Backend to Serve Frontend

backend/src/api/main.py (add static file serving):

from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
from fastapi.responses import FileResponse
import os

app = FastAPI(title="Obsidian Docs Viewer API")

# ... (existing API routes) ...

# Serve frontend static files
static_dir = os.path.join(os.path.dirname(__file__), "../../static")
if os.path.exists(static_dir):
    app.mount("/assets", StaticFiles(directory=f"{static_dir}/assets"), name="assets")

    @app.get("/{full_path:path}")
    async def serve_frontend(full_path: str):
        """Serve frontend SPA (fallback to index.html for client-side routing)."""
        if full_path.startswith("api/"):
            # API routes handled by existing endpoints
            return {"error": "Not found"}

        file_path = os.path.join(static_dir, full_path)
        if os.path.exists(file_path) and os.path.isfile(file_path):
            return FileResponse(file_path)

        # Fallback to index.html for SPA routing
        return FileResponse(f"{static_dir}/index.html")

5. Build Frontend with HF Space URL

Update frontend/.env.production:

VITE_API_BASE_URL=https://your-space.hf.space

Build:

cd frontend
npm run build

6. Push to HF Space

# From project root
git init
git add .
git commit -m "Initial commit"

# Add HF Space remote
git remote add space https://huggingface.co/spaces/your-username/your-space-name
git push space main

7. Verify Deployment

Visit https://your-space.hf.space
Click "Sign in with Hugging Face"
Authorize the app
You should see the main UI with your isolated vault

8. Configure MCP HTTP Client for HF Space

Sign in to the Space and navigate to Settings
Click "Issue API Token"
Copy the JWT token
Configure your local MCP client:

MCP HTTP client config:

{
  "mcp_endpoint": "https://your-space.hf.space:8001/mcp",
  "auth": {
    "type": "bearer",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Test from command line:

curl -X POST https://your-space.hf.space:8001/mcp/call \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_notes",
    "arguments": {}
  }'

Troubleshooting

Common Errors

Error: `401 Unauthorized - Invalid token`

Cause: JWT token is invalid, expired, or missing.

Solution:

Check token expiration:

# Decode JWT (requires `pyjwt` library)
python -c "import jwt; print(jwt.decode('your-token', options={'verify_signature': False}))"

Issue a new token:

curl -X POST http://localhost:8000/api/tokens

Update token in client configuration

Error: `400 Bad Request - Path traversal blocked`

Cause: Note path contains .. or absolute path components.

Example: write_note(path="../etc/passwd")

Solution: Use relative paths only, no .. allowed

# ✅ Correct
write_note(path="design/api.md")

# ❌ Incorrect
write_note(path="../design/api.md")
write_note(path="/design/api.md")

Error: `409 Conflict - Version mismatch`

Cause: Note was updated by another user/agent since you last read it.

Example:

You load note with version 5
Claude updates it via MCP (version → 6)
You click "Save" with if_version: 5
Server returns 409 Conflict

Solution:

Reload the note to get latest version
Re-apply your changes
Save with new version number

UI handling:

// In NoteEditor component
try {
  await updateNote(path, { body, if_version: currentVersion });
} catch (error) {
  if (error.status === 409) {
    alert("This note changed since you opened it. Please reload before saving.");
    // Optionally: reload note automatically
  }
}

Error: `413 Payload Too Large`

Cause: Note content exceeds 1 MiB (1,048,576 bytes).

Solution: Split large notes into smaller files

# Check note size
wc -c data/vaults/local-dev/large-note.md

# If > 1 MiB, split into multiple notes

Error: `403 Forbidden - Vault note limit exceeded`

Cause: Vault has reached 5,000 note limit.

Solution:

Delete unused notes
Archive old notes to external storage
Request limit increase (requires code change in FR-008)

Error: `SQLite database is locked`

Cause: Concurrent writes to SQLite database.

Solution:

Ensure only one backend process is running
Use connection pooling (in production)
Consider upgrading to PostgreSQL for high concurrency

Quick fix:

# Kill all backend processes
pkill -f uvicorn
pkill -f "python -m src.mcp.server"

# Restart backend
uvicorn src.api.main:app --reload

Error: `FTS5 extension not available`

Cause: SQLite was compiled without FTS5 support.

Solution:

Check if FTS5 is available:

import sqlite3
conn = sqlite3.connect(":memory:")
cursor = conn.cursor()
cursor.execute("PRAGMA compile_options")
print([row[0] for row in cursor.fetchall()])
# Look for 'ENABLE_FTS5' in output

If not available, reinstall SQLite with FTS5:

# macOS (Homebrew)
brew reinstall sqlite3

# Linux (Ubuntu/Debian)
sudo apt-get install --reinstall libsqlite3-0

# Python (rebuild pysqlite3 with FTS5)
pip install pysqlite3-binary

Debug Mode

Enable debug logging for troubleshooting:

Backend (.env):

LOG_LEVEL=DEBUG

Frontend (frontend/.env):

VITE_DEBUG=true

View logs:

# Backend logs (if using uvicorn)
tail -f backend.log

# Or run with verbose output
uvicorn src.api.main:app --reload --log-level debug

Frontend logs: Open browser DevTools → Console

Health Checks

Check API Health

curl http://localhost:8000/api/health

Expected response:

{
  "status": "ok",
  "mode": "local",
  "vault_base_dir": "./data/vaults",
  "db_path": "./data/index.db"
}

Check Index Health

curl http://localhost:8000/api/index/health

Expected response:

{
  "user_id": "local-dev",
  "note_count": 15,
  "last_full_rebuild": "2025-01-15T10:00:00Z",
  "last_incremental_update": "2025-01-16T14:30:00Z"
}

Verify MCP Server

# Test STDIO server (requires MCP client)
echo '{"tool": "list_notes", "arguments": {}}' | python -m src.mcp.server

# Test HTTP server
curl -X POST http://localhost:8001/mcp/call \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tool": "list_notes", "arguments": {}}'

Performance Profiling

Backend API Response Time

# Use curl with timing
curl -w "@curl-format.txt" -o /dev/null -s http://localhost:8000/api/notes

# curl-format.txt:
# time_namelookup:  %{time_namelookup}s\n
# time_connect:     %{time_connect}s\n
# time_appconnect:  %{time_appconnect}s\n
# time_total:       %{time_total}s\n

Expected: time_total < 2s for directory listing

Search Query Performance

time curl -s "http://localhost:8000/api/search?q=authentication" > /dev/null

Expected: < 1s for vaults with up to 5,000 notes

Index Rebuild Time

time curl -X POST http://localhost:8000/api/index/rebuild

Expected: < 30s for 1,000 notes

Next Steps

Read the full specification: See specs/001-obsidian-docs-viewer/spec.md
Review data model: See specs/001-obsidian-docs-viewer/data-model.md
Check API contracts: See specs/001-obsidian-docs-viewer/contracts/
Start implementation: Run /speckit.tasks to generate implementation tasks

Additional Resources

FastAPI Documentation: https://fastapi.tiangolo.com/
FastMCP Documentation: https://github.com/jlowin/fastmcp
React + shadcn/ui: https://ui.shadcn.com/
HuggingFace Spaces: https://huggingface.co/docs/hub/spaces
MCP Protocol: https://modelcontextprotocol.io/

Last Updated: 2025-11-15 Status: Ready for implementation

Quickstart Guide: Multi-Tenant Obsidian-Like Docs Viewer

Table of Contents

Prerequisites

Required Software

Optional Tools

Local Development Setup

1. Clone the Repository

2. Create Environment Configuration

3. Backend Setup

Option A: Using Poetry (Recommended)

Option B: Using pip with venv

4. Initialize Database Schema

5. Create Vault Directory Structure

6. Frontend Setup

Running the Backend

Mode 1: FastAPI HTTP Server (for UI access)

Mode 2: MCP STDIO Server (for Claude Code/Desktop)

Mode 3: MCP HTTP Server (for remote MCP access)

Run All Backend Services (Production Mode)

Running the Frontend

Local Mode UI Flow

Configure Static Token (Optional)

MCP Client Configuration

Claude Desktop (STDIO)

Claude Code (STDIO)

MCP HTTP Transport (Remote Access)

Testing Workflows

Backend Unit Tests

Backend Integration Tests

Backend Contract Tests

Frontend Unit Tests

Frontend E2E Tests

Development Workflows

Workflow 1: AI Agent Writes a Note via MCP

Workflow 2: Human Edits a Note in UI

Workflow 3: Search for Notes

Workflow 4: Follow Wikilinks and View Backlinks

Workflow 5: Rebuild Index

Add notes manually: ```bash # From terminal cat > data/vaults/local-dev/notes/meeting-2025-01-16.md << 'EOF'

title: Team Meeting Notes tags: [meetings]

Team Meeting - Jan 16, 2025

Attendees

Topics

Hugging Face Space Deployment

Prerequisites

1. Configure OAuth

2. Set Environment Variables

3. Create Dockerfile

4. Configure Backend to Serve Frontend

5. Build Frontend with HF Space URL

6. Push to HF Space

7. Verify Deployment

8. Configure MCP HTTP Client for HF Space

Troubleshooting

Common Errors

Error: 401 Unauthorized - Invalid token

Error: 400 Bad Request - Path traversal blocked

Error: 409 Conflict - Version mismatch

Error: 413 Payload Too Large

Error: 403 Forbidden - Vault note limit exceeded

Error: SQLite database is locked

Error: FTS5 extension not available

Debug Mode

Health Checks

Check API Health

Check Index Health

Verify MCP Server

Performance Profiling

Backend API Response Time

Search Query Performance

Index Rebuild Time

Next Steps

Additional Resources

Error: `401 Unauthorized - Invalid token`

Error: `400 Bad Request - Path traversal blocked`

Error: `409 Conflict - Version mismatch`

Error: `413 Payload Too Large`

Error: `403 Forbidden - Vault note limit exceeded`

Error: `SQLite database is locked`

Error: `FTS5 extension not available`