security

.gitignore

@@ -54,6 +54,12 @@ reproduce_auth_500.py
 debug_list_notes.py
 DEPLOY_TO_HF.md
 
+# Debug and inspection scripts
+debug_*.py
+inspect_*.py
+test_remote_mcp.py
+generate_jwt_token.py
+
 # Documentation
 docs/fastmcp/
 
@@ -62,3 +68,4 @@ docs/fastmcp/
 *.jpg
 *.jpeg
 *.gif
+AUDIT_REPORT.md

CLAUDE.md

@@ -31,7 +31,7 @@ uv pip install -e .
 uv pip install -e ".[dev]"
 
 # Run FastAPI HTTP server (for UI)
-uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000
+uv run uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000
 
 # Run MCP STDIO server (for Claude Desktop/Code)
 uv run python src/mcp/server.py
@@ -76,7 +76,7 @@ npm run preview               # Serve dist/ (after npm run build)
 # Manual reset (WARNING: destroys all data)
 cd backend
 rm -f ../data/index.db
-uv run python -c "from src.services.database import DatabaseService; DatabaseService().init_schema()"
+uv run python -c "from src.services.database import DatabaseService; DatabaseService().initialize()"
 ```
 
 ## Architecture Deep Dive
@@ -107,7 +107,7 @@ uv run python -c "from src.services.database import DatabaseService; DatabaseSer
    - `database.py`: SQLite connection manager + schema DDL
 
 3. **API/MCP** (`backend/src/api/` and `backend/src/mcp/`):
-   - `api/routes/`: FastAPI endpoints (11 routes: auth, notes CRUD, search, backlinks, tags, index health/rebuild)
+   - `api/routes/`: FastAPI endpoints (17 routes: auth, notes CRUD, search, backlinks, tags, index health/rebuild)
    - `api/middleware/auth_middleware.py`: JWT Bearer token validation
    - `mcp/server.py`: FastMCP tools (7 tools: list, read, write, delete, search, backlinks, tags)
 

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Document-MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

README.md

@@ -98,7 +98,7 @@ Want persistent storage and full control? Deploy your own instance:
 3. Configure environment variables
 4. Deploy to HF Spaces or any Docker host
 
-See [DEPLOYMENT.md](https://github.com/YOUR_REPO/Document-MCP/blob/main/DEPLOYMENT.md) for detailed instructions.
+See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed instructions.
 
 ## 🔒 Privacy & Data
 

ai-notes/documentation-audit-2025-11-27.md

@@ -0,0 +1,492 @@
+# Documentation Audit Report - Document-MCP
+**Date**: 2025-11-27
+**Purpose**: Pre-release audit for accuracy, completeness, and professionalism
+
+## Executive Summary
+
+The Document-MCP project documentation is **generally accurate and comprehensive**, but requires several critical fixes before public release:
+
+### Critical Issues (MUST FIX)
+1. ❌ **Personal information exposed** in DEPLOY_TO_HF.md (username: YOUR_USERNAME)
+2. ❌ **Placeholder URLs** not replaced (YOUR_REPO, YOUR_USERNAME)
+3. ❌ **Missing LICENSE file** (mentioned in README but doesn't exist)
+4. ❌ **Inaccurate route count** in CLAUDE.md (claims 11 routes, actual is 18)
+5. ❌ **Incomplete .env.example** (missing several required variables)
+
+### Minor Issues (SHOULD FIX)
+1. ⚠️ **Outdated frontend README** (generic Vite template)
+2. ⚠️ **Empty backend README** (only 1 line)
+3. ⚠️ **GEMINI.md is auto-generated** and out of sync
+4. ⚠️ **Inconsistent command format** in CLAUDE.md (uses `main:app` but file is at `src.api.main:app`)
+
+---
+
+## Detailed Findings
+
+### 1. README.md (Root)
+**Location**: `$PROJECT_ROOT/README.md`
+
+**Status**: ✅ Mostly Good
+
+**Strengths**:
+- Clear project description
+- Good feature list
+- Well-structured sections
+- Includes demo mode warning
+
+**Issues**:
+1. **Line 101**: `https://github.com/YOUR_REPO/Document-MCP/blob/main/DEPLOYMENT.md` - placeholder URL not replaced
+2. **Line 112**: References LICENSE file that doesn't exist
+3. Missing repository URL in frontmatter (lines 1-9)
+
+**Recommendations**:
+- Replace `YOUR_REPO` with actual GitHub username/org
+- Create LICENSE file (MIT as stated)
+- Add actual repository URL to YAML frontmatter
+
+---
+
+### 2. CLAUDE.md
+**Location**: `$PROJECT_ROOT/CLAUDE.md`
+
+**Status**: ⚠️ Needs Updates
+
+**Strengths**:
+- Comprehensive technical documentation
+- Excellent architecture descriptions
+- Detailed command examples
+- Good MCP configuration examples
+
+**Inaccuracies Found**:
+
+#### Line 34: Incorrect uvicorn command
+```bash
+# CLAUDE.md says:
+uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000
+
+# Should be (verified against backend/main.py):
+uv run uvicorn src.api.main:app --reload --host 0.0.0.0 --port 8000
+# OR simply:
+cd backend && uv run python main.py
+```
+
+#### Line 110: Incorrect route count
+```
+# Claims:
+11 routes: auth, notes CRUD, search, backlinks, tags, index health/rebuild
+
+# Actual count: 18 routes across 7 files
+- auth.py: 4 routes
+- notes.py: 5 routes
+- search.py: 3 routes
+- index.py: 2 routes
+- graph.py: 1 route
+- demo.py: 1 route
+- system.py: 2 routes
+```
+
+#### Lines 88-93: Missing models
+**Claims these models exist**:
+- `note.py` ✅ EXISTS
+- `user.py` ✅ EXISTS
+- `search.py` ✅ EXISTS
+- `index.py` ✅ EXISTS
+- `auth.py` ✅ EXISTS
+- `graph.py` ✅ EXISTS (not mentioned but exists)
+
+**Recommendation**: Add `graph.py` to the list.
+
+#### Line 112: Missing route files
+**Claims**: "7 tools: list, read, write, delete, search, backlinks, tags"
+
+**Actual MCP tools**: Should verify this count against actual MCP server implementation.
+
+#### Line 79: Database init command inaccuracy
+```bash
+# Claims:
+uv run python -c "from src.services.database import DatabaseService; DatabaseService().init_schema()"
+
+# Actual method is:
+DatabaseService().initialize()
+# NOT init_schema()
+```
+
+**Verified from `$PROJECT_ROOT/backend/src/services/database.py`**:
+- Line 92: Method is `def initialize(self, statements: Iterable[str] | None = None)`
+- No `init_schema()` method exists
+
+---
+
+### 3. DEPLOYMENT.md
+**Location**: `$PROJECT_ROOT/DEPLOYMENT.md`
+
+**Status**: ✅ Good, Minor Placeholders
+
+**Issues**:
+1. Multiple instances of `YOUR_USERNAME` placeholder (appropriate for public doc)
+2. All technical instructions verified as accurate
+
+**Recommendations**:
+- Keep `YOUR_USERNAME` as placeholder (this is correct for public docs)
+- Maybe add a note at the top: "Replace YOUR_USERNAME with your HuggingFace username"
+
+---
+
+### 4. DEPLOY_TO_HF.md ⚠️ CRITICAL
+**Location**: `$PROJECT_ROOT/DEPLOY_TO_HF.md`
+
+**Status**: ❌ Contains Personal Information
+
+**CRITICAL ISSUES**:
+1. **Line 6**: `hf-space` → `https://huggingface.co/spaces/YOUR_USERNAME/Document-MCP`
+2. **Line 12**: `git config credential.helper '!f() { echo "username=YOUR_USERNAME"; ...`
+3. **Line 32**: `huggingface-cli upload YOUR_USERNAME/Document-MCP`
+4. **Line 40**: `git clone https://huggingface.co/spaces/YOUR_USERNAME/Document-MCP`
+
+**Recommendation**:
+- **DELETE this file** before public release (it's personal deployment notes)
+- OR replace all instances of `YOUR_USERNAME` with `YOUR_USERNAME`
+
+---
+
+### 5. .env.example
+**Location**: `$PROJECT_ROOT/.env.example`
+
+**Status**: ❌ Incomplete
+
+**Current Contents** (only 4 variables):
+```env
+JWT_SECRET_KEY=change-me
+HF_OAUTH_CLIENT_ID=your-hf-client-id
+HF_OAUTH_CLIENT_SECRET=your-hf-client-secret
+VAULT_BASE_PATH=./data/vaults
+```
+
+**Missing Variables** (referenced in CLAUDE.md and code):
+- `MODE` (local or space)
+- `DB_PATH` (SQLite database location)
+- `LOCAL_USER_ID` (default user for local mode)
+- `HF_SPACE_HOST` (for HF Space deployments)
+
+**Recommendation**: Add comprehensive .env.example with all variables documented.
+
+---
+
+### 6. backend/README.md
+**Location**: `$PROJECT_ROOT/backend/README.md`
+
+**Status**: ❌ Nearly Empty (1 line)
+
+**Current State**: File exists but has no meaningful content.
+
+**Recommendation**: Add backend-specific documentation:
+- Installation instructions
+- Development setup
+- Testing guide
+- Service architecture overview
+
+---
+
+### 7. frontend/README.md
+**Location**: `$PROJECT_ROOT/frontend/README.md`
+
+**Status**: ⚠️ Generic Vite Template
+
+**Current State**: Still contains the default Vite + React template README.
+
+**Recommendation**: Replace with project-specific frontend documentation:
+- Component architecture
+- Development workflow
+- Build instructions
+- UI/UX guidelines
+
+---
+
+### 8. GEMINI.md
+**Location**: `$PROJECT_ROOT/GEMINI.md`
+
+**Status**: ⚠️ Auto-generated, Out of Sync
+
+**Issues**:
+- Clearly auto-generated from SpecKit
+- Contains malformed commands (e.g., "cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]")
+- Last updated 2025-11-25 (2 days old)
+- Doesn't match actual project structure
+
+**Recommendation**:
+- **DELETE** or move to `.specify/` internal folder
+- Not useful for public documentation
+
+---
+
+### 9. LICENSE File
+**Status**: ❌ MISSING
+
+**Referenced in**:
+- README.md line 112: "MIT License - See LICENSE file for details"
+- README.md line 8: `license: mit`
+
+**Recommendation**: Create LICENSE file with MIT license text.
+
+---
+
+### 10. Package Metadata
+
+#### backend/pyproject.toml
+**Location**: `$PROJECT_ROOT/backend/pyproject.toml`
+
+**Status**: ⚠️ Incomplete Metadata
+
+**Issues**:
+- Line 1: `name = "Documentation-MCP"` (inconsistent with project name "Document-MCP")
+- Line 4: `description = "Add your description here"` (placeholder)
+- Line 5: `readme = "README.md"` (points to empty README)
+
+**Recommendations**:
+- Fix name to `"document-mcp"`
+- Add proper description
+- Add author, repository URL, keywords
+
+#### frontend/package.json
+**Location**: `$PROJECT_ROOT/frontend/package.json`
+
+**Status**: ⚠️ Generic Template
+
+**Issues**:
+- Line 2: `"name": "frontend"` (too generic)
+- Line 3: `"private": true` (correct for non-published packages)
+- Line 5: `"version": "0.0.0"` (should match backend version)
+- Missing description, author, repository fields
+
+**Recommendations**:
+- Change name to `"document-mcp-frontend"`
+- Add proper metadata matching backend
+
+---
+
+## File Structure Verification
+
+### Backend Structure ✅
+Verified actual structure matches CLAUDE.md claims:
+
+```
+backend/src/
+├── models/          ✅ (7 files: auth, graph, index, note, search, user, __init__)
+├── services/        ✅ (7 files: auth, config, database, indexer, seed, vault, __init__)
+├── api/
+│   ├── routes/      ✅ (8 files: auth, demo, graph, index, notes, search, system, __init__)
+│   └── middleware/  ✅
+└── mcp/
+    └── server.py    ✅
+```
+
+### Frontend Structure ✅
+```
+frontend/src/
+├── components/      ✅ (GraphView, NoteViewer, NoteEditor, DirectoryTree, etc.)
+├── lib/            ✅
+├── services/       ✅
+└── types/          ✅
+```
+
+---
+
+## Command Verification
+
+### Backend Commands (from CLAUDE.md)
+
+| Command | Line | Status | Notes |
+|---------|------|--------|-------|
+| `uv venv` | 26 | ✅ Works | Verified |
+| `uv pip install -e .` | 28 | ✅ Works | Verified |
+| `uv run uvicorn main:app` | 34 | ❌ Wrong | Should be `src.api.main:app` |
+| `uv run python src/mcp/server.py` | 37 | ✅ Works | Verified |
+| `uv run pytest` | 43 | ✅ Works | Requires dev deps |
+
+### Frontend Commands
+
+| Command | Line | Status |
+|---------|------|--------|
+| `npm install` | 57 | ✅ Works |
+| `npm run dev` | 60 | ✅ Works |
+| `npm run build` | 63 | ✅ Works |
+| `npm run lint` | 66 | ✅ Works |
+
+---
+
+## Architecture Verification
+
+### SQLite Schema ✅
+Verified against `$PROJECT_ROOT/backend/src/services/database.py`:
+
+**CLAUDE.md claims 5 tables**:
+1. `note_metadata` ✅ (lines 15-26)
+2. `note_fts` ✅ (lines 33-41)
+3. `note_tags` ✅ (lines 43-49)
+4. `note_links` ✅ (lines 53-61)
+5. `index_health` ✅ (lines 66-72)
+
+**All verified as accurate!**
+
+### API Routes Count ❌
+**CLAUDE.md Line 110 claims**: "11 routes: auth, notes CRUD, search, backlinks, tags, index health/rebuild"
+
+**Actual count**: 18 routes across 7 router files
+- Not technically wrong (may be counting logical endpoints vs. HTTP routes)
+- But confusing and should be clarified
+
+---
+
+## Links Audit
+
+### Internal Links
+All internal file references in CLAUDE.md verified:
+- ✅ `backend/src/models/`
+- ✅ `backend/src/services/`
+- ✅ `backend/src/api/routes/`
+- ✅ `.env.example`
+
+### External Links
+No broken external links found in:
+- README.md
+- DEPLOYMENT.md
+- CLAUDE.md
+
+### Placeholder Links ❌
+- `https://github.com/YOUR_REPO/Document-MCP` (README.md)
+- Multiple `YOUR_USERNAME` placeholders (appropriate for templates)
+
+---
+
+## Recommendations by Priority
+
+### 🔴 CRITICAL (Must fix before public release)
+
+1. **Create LICENSE file** (MIT as stated)
+   ```bash
+   # Add MIT license text to LICENSE file
+   ```
+
+2. **Remove/anonymize DEPLOY_TO_HF.md**
+   - Delete entirely OR
+   - Replace `YOUR_USERNAME` with `YOUR_USERNAME`
+
+3. **Fix placeholder URLs in README.md**
+   - Replace `YOUR_REPO` with actual GitHub username/org
+
+4. **Fix .env.example**
+   - Add all missing environment variables
+   - Add comments explaining each variable
+
+5. **Fix CLAUDE.md inaccuracies**:
+   - Line 34: Correct uvicorn command
+   - Line 79: Fix `init_schema()` → `initialize()`
+   - Line 110: Clarify route count or update to 18
+
+### 🟡 IMPORTANT (Should fix)
+
+6. **Update backend/pyproject.toml**
+   - Fix name: `Documentation-MCP` → `document-mcp`
+   - Add proper description
+   - Add author, repository, keywords
+
+7. **Replace frontend/README.md**
+   - Remove Vite template content
+   - Add project-specific frontend docs
+
+8. **Create backend/README.md**
+   - Installation guide
+   - Testing instructions
+   - Architecture overview
+
+9. **Delete or hide GEMINI.md**
+   - Auto-generated, not useful publicly
+   - Move to `.specify/` if needed internally
+
+### 🟢 NICE TO HAVE (Optional improvements)
+
+10. **Add CONTRIBUTING.md**
+    - Contribution guidelines
+    - Code style requirements
+    - PR process
+
+11. **Add CHANGELOG.md**
+    - Version history
+    - Breaking changes
+    - Migration guides
+
+12. **Expand docs/ folder**
+    - Architecture diagrams
+    - API reference
+    - Deployment guides per platform
+
+---
+
+## Code Quality Cross-Check
+
+### Python Code ✅
+- All imports in CLAUDE.md verified working
+- Service layer structure matches documentation
+- Database schema matches DDL statements
+
+### TypeScript/React Code ✅
+- Component hierarchy matches CLAUDE.md
+- Dependencies in package.json match documentation
+
+### MCP Integration ✅
+- Server file exists at documented location
+- Transport modes (STDIO/HTTP) documented correctly
+- Configuration examples are accurate
+
+---
+
+## Security & Privacy Check
+
+### Exposed Information ❌
+- **DEPLOY_TO_HF.md**: Contains username `YOUR_USERNAME`
+- No API keys or secrets exposed ✅
+- No real JWT tokens in examples ✅
+
+### Placeholder Patterns ✅
+- Appropriate use of `YOUR_USERNAME` in public docs
+- Example tokens are clearly fake
+- Environment variables use placeholder values
+
+---
+
+## Conclusion
+
+The Document-MCP documentation is **well-written and comprehensive** but needs **critical fixes before public release**:
+
+### Must-Fix Checklist
+- [ ] Create LICENSE file
+- [ ] Remove/anonymize DEPLOY_TO_HF.md
+- [ ] Replace `YOUR_REPO` placeholder in README.md
+- [ ] Expand .env.example with all variables
+- [ ] Fix CLAUDE.md command inaccuracies
+- [ ] Update backend/pyproject.toml metadata
+- [ ] Replace generic frontend/README.md
+- [ ] Delete or move GEMINI.md
+
+### Quality Score: 7.5/10
+**Breakdown**:
+- Technical accuracy: 8/10 (few minor inaccuracies)
+- Completeness: 7/10 (missing LICENSE, sparse READMEs)
+- Professionalism: 6/10 (personal info, placeholders)
+- Usability: 9/10 (clear, well-organized)
+
+**Estimated time to fix**: 2-3 hours
+
+---
+
+## Confidence Assessment
+
+**Confidence Level**: 9/10
+
+**Reasoning**:
+- Manually verified file structure against documentation
+- Tested import paths and commands
+- Cross-referenced schema definitions
+- Counted actual routes in codebase
+- Found both critical and minor issues
+- Some uncertainty remains on MCP tool count (need to verify against actual MCP server implementation)

ai-notes/hf-deployment-complete.md

@@ -75,14 +75,14 @@ You'll need to add these secrets in HF Space settings:
 JWT_SECRET_KEY=<generate with: openssl rand -hex 32>
 HF_OAUTH_CLIENT_ID=<from your OAuth app>
 HF_OAUTH_CLIENT_SECRET=<from your OAuth app>
-HF_SPACE_URL=https://huggingface.co/spaces/bigwolfe/Document-MCP
+HF_SPACE_URL=https://huggingface.co/spaces/YOUR_USERNAME/Document-MCP
 ```
 
 ### 2. Push to HF Space
 
 ```bash
 # Clone your HF Space repo
-git clone https://huggingface.co/spaces/bigwolfe/Document-MCP
+git clone https://huggingface.co/spaces/YOUR_USERNAME/Document-MCP
 cd Document-MCP
 
 # Copy project files
@@ -100,7 +100,7 @@ git push
 ### 3. Test the Deployment
 
 1. Wait for HF Spaces to build (5-10 minutes)
-2. Visit: `https://bigwolfe-document-mcp.hf.space` (or your actual URL)
+2. Visit: `https://YOUR_USERNAME-document-mcp.hf.space` (or your actual URL)
 3. Click "Sign in with Hugging Face"
 4. Browse the demo notes
 5. Go to Settings to get your API token
@@ -111,7 +111,7 @@ git push
 After deployment, test MCP access:
 
 ```bash
-curl -X POST "https://bigwolfe-document-mcp.hf.space/mcp/list_notes" \
+curl -X POST "https://YOUR_USERNAME-document-mcp.hf.space/mcp/list_notes" \
   -H "Authorization: Bearer YOUR_JWT_TOKEN" \
   -H "Content-Type: application/json"
 ```

ai-notes/ui-fix-required.md

@@ -9,7 +9,7 @@ PostCSS is still loading cached Tailwind CSS v4 modules even though we've downgr
 ```bash
 # Stop the current dev server (Ctrl+C)
 # Then restart:
-cd /home/wolfe/Projects/Document-MCP/frontend
+cd $PROJECT_ROOT/frontend
 npm run dev
 ```
 

backend/pyproject.toml

@@ -1,9 +1,11 @@
 [project]
-name = "Documentation-MCP"
+name = "document-mcp"
 version = "0.1.0"
-description = "Add your description here"
+description = "Multi-tenant Obsidian-like documentation viewer with AI-first workflow via MCP"
 readme = "README.md"
 requires-python = ">=3.11"
+license = {text = "MIT"}
+keywords = ["mcp", "documentation", "obsidian", "ai-agents", "fastapi", "fastmcp"]
 dependencies = [
     "fastapi>=0.121.2",
     "fastmcp>=2.13.1",

backend/src/services/seed.py

@@ -270,7 +270,7 @@ For **HTTP mode** (HF Space), use:
 {
   "mcpServers": {
     "obsidian-docs": {
-      "url": "https://huggingface.co/spaces/bigwolfe/Document-MCP/mcp",
+      "url": "https://huggingface.co/spaces/YOUR_USERNAME/Document-MCP/mcp",
       "headers": {
         "Authorization": "Bearer YOUR_JWT_TOKEN"
       }

frontend/package.json

@@ -1,8 +1,10 @@
 {
-  "name": "frontend",
+  "name": "document-mcp-frontend",
   "private": true,
-  "version": "0.0.0",
+  "version": "0.1.0",
   "type": "module",
+  "description": "React frontend for Document-MCP - Multi-tenant documentation viewer with AI integration",
+  "license": "MIT",
   "scripts": {
     "dev": "vite",
     "build": "tsc -b && vite build",

scripts/test_mcp_tools.py

@@ -19,7 +19,7 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description="Test MCP HTTP tools end-to-end")
     parser.add_argument(
         "--url",
-        default=os.environ.get("MCP_URL", "https://bigwolfe-document-mcp.hf.space/mcp"),
+        default=os.environ.get("MCP_URL", "https://YOUR_USERNAME-document-mcp.hf.space/mcp"),
         help="Hosted MCP endpoint base URL",
     )
     parser.add_argument(