pagedex 0.1.5 → 0.1.6

package/README.md

@@ -18,7 +18,17 @@ By default, `pagedex` serves the current directory on `http://127.0.0.1:4321`:
 
 - `/` — React + Tiptap web UI (desktop & mobile with edge-swipe drawers + long-press tree actions)
 - `/api/v1/*` — REST API for reading, editing, searching, and Git diff/commit
-- `/mcp` — MCP endpoint supporting `2026-07-28` (`server/discover`), `2025-11-25` Streamable HTTP, and `2024-11-05` HTTP+SSE
+- `/mcp` — MCP endpoint supporting `2026-07-28` (`server/discover`), `2025-11-25` Streamable HTTP, and `2024-11-05` HTTP+SSE (see [MCP Server Guide](./docs/MCP.md))
+
+## Screenshots
+
+| Desktop Preview & Pinned Sidebar | WYSIWYG Editor (Tiptap) |
+|---|---|
+| ![Desktop Preview](./docs/images/desktop-preview.png) | ![Desktop Editor](./docs/images/desktop-edit.png) |
+
+| Quick Switcher (`Cmd/Ctrl+K`) | Mobile View & Bottom Bar |
+|---|---|
+| ![Quick Switcher](./docs/images/desktop-switcher.png) | ![Mobile Preview](./docs/images/mobile-preview.png) |
 
 ### CLI Options
 
@@ -27,14 +37,18 @@ Usage:
   pagedex [dir] [options]
 
 Arguments:
-  dir                 Directory to serve (defaults to current working directory)
+  dir                        Directory to serve (defaults to current working directory)
 
 Options:
-  -p, --port <port>   Port to listen on (default: 4321, or PORT env)
-  -H, --host <host>   Host to bind (default: 127.0.0.1, or HOST env; use 0.0.0.0 for LAN)
-  -o, --open          Open browser after starting
-  -v, --version       Show version
-  -h, --help          Show this help
+  -p, --port <port>          Port to listen on (default: 4321, or PORT env)
+  -H, --host <host>          Host to bind (default: 127.0.0.1, or HOST env; use 0.0.0.0 for LAN)
+  -o, --open                 Open browser after starting
+  --mcp <mode>               MCP mode: read, write, full (default), or off (or PAGEDEX_MCP_MODE)
+  --mcp-git                  Enable MCP git_commit and git_discard tools (or PAGEDEX_MCP_GIT=1)
+  --mcp-token-file <path>    File containing Bearer token for /mcp (or PAGEDEX_MCP_TOKEN_FILE)
+  --read-only                Disable all REST & MCP write/delete mutations (or PAGEDEX_READ_ONLY=1)
+  -v, --version              Show version
+  -h, --help                 Show this help
 ```
 
 ### Examples
@@ -43,8 +57,11 @@ Options:
 # Serve current folder on default port 4321
 npx pagedex
 
-# Serve a specific notes folder on LAN/Tailscale
-npx pagedex ~/vault --host 0.0.0.0 --port 4321
+# Serve a specific notes folder on LAN/Tailscale with read-only MCP and Bearer token file
+npx pagedex ~/vault --host 0.0.0.0 --mcp read --mcp-token-file ~/.config/pagedex/mcp-token
+
+# Allow MCP create/edit/move + local git commit/discard without delete_note
+npx pagedex ~/vault --mcp write --mcp-git
 ```
 
 ## Search Index Cache
@@ -58,5 +75,8 @@ pnpm install
 pnpm dev      # Hono API/MCP on :4321 + Vite HMR on :5173
 pnpm build    # Build production UI into dist/
 pnpm test     # Run unit tests
+pnpm test:playwright # Run Playwright E2E tests
 pnpm smoke    # Run REST + multi-era MCP smoke checks
 ```
+
+See [docs/README.md](./docs/README.md) for full documentation.

package/bin/pagedex.js

@@ -16,11 +16,15 @@ Arguments:
   dir                 Directory to serve (defaults to current working directory)
 
 Options:
-  -p, --port <port>   Port to listen on (default: 4321, or PORT env)
-  -H, --host <host>   Host to bind (default: 127.0.0.1, or HOST env; use 0.0.0.0 for LAN)
-  -o, --open          Open browser after starting
-  -v, --version       Show version
-  -h, --help          Show this help
+  -p, --port <port>          Port to listen on (default: 4321, or PORT env)
+  -H, --host <host>          Host to bind (default: 127.0.0.1, or HOST env; use 0.0.0.0 for LAN)
+  -o, --open                 Open browser after starting
+  --mcp <mode>               MCP mode: read, write, full (default), or off (or PAGEDEX_MCP_MODE)
+  --mcp-git                  Enable MCP git_commit and git_discard tools (or PAGEDEX_MCP_GIT=1)
+  --mcp-token-file <path>    File containing Bearer token for /mcp (or PAGEDEX_MCP_TOKEN_FILE)
+  --read-only                Disable all REST & MCP write/delete mutations (or PAGEDEX_READ_ONLY=1)
+  -v, --version              Show version
+  -h, --help                 Show this help
 `);
 }
 
@@ -40,6 +44,12 @@ let targetDir = null;
 let port = process.env.PORT || '4321';
 let host = process.env.HOST || '127.0.0.1';
 let shouldOpen = false;
+let mcpMode = process.env.PAGEDEX_MCP_MODE || 'full';
+let mcpGit = process.env.PAGEDEX_MCP_GIT === '1' || process.env.PAGEDEX_MCP_GIT === 'true';
+let mcpTokenFile = process.env.PAGEDEX_MCP_TOKEN_FILE || '';
+let readOnly = process.env.PAGEDEX_READ_ONLY === '1' || process.env.PAGEDEX_READ_ONLY === 'true';
+
+const VALID_MCP_MODES = new Set(['read', 'write', 'full', 'off']);
 
 for (let i = 0; i < args.length; i++) {
   const arg = args[i];
@@ -55,6 +65,46 @@ for (let i = 0; i < args.length; i++) {
     shouldOpen = true;
     continue;
   }
+  if (arg === '--read-only') {
+    readOnly = true;
+    continue;
+  }
+  if (arg === '--mcp-git') {
+    mcpGit = true;
+    continue;
+  }
+  if (arg === '--mcp') {
+    mcpMode = (args[++i] || '').toLowerCase();
+    if (!VALID_MCP_MODES.has(mcpMode)) {
+      console.error(`Invalid --mcp mode: ${mcpMode || '(missing)'}. Expected: read, write, full, or off`);
+      process.exit(1);
+    }
+    continue;
+  }
+  if (arg.startsWith('--mcp=')) {
+    mcpMode = arg.slice('--mcp='.length).toLowerCase();
+    if (!VALID_MCP_MODES.has(mcpMode)) {
+      console.error(`Invalid --mcp mode: ${mcpMode || '(missing)'}. Expected: read, write, full, or off`);
+      process.exit(1);
+    }
+    continue;
+  }
+  if (arg === '--mcp-token-file') {
+    mcpTokenFile = args[++i];
+    if (!mcpTokenFile) {
+      console.error('Missing value for --mcp-token-file');
+      process.exit(1);
+    }
+    continue;
+  }
+  if (arg.startsWith('--mcp-token-file=')) {
+    mcpTokenFile = arg.slice('--mcp-token-file='.length);
+    if (!mcpTokenFile) {
+      console.error('Missing value for --mcp-token-file');
+      process.exit(1);
+    }
+    continue;
+  }
   if (arg === '-p' || arg === '--port') {
     port = args[++i];
     if (!port) {
@@ -95,10 +145,28 @@ if (!fs.existsSync(resolvedRoot) || !fs.statSync(resolvedRoot).isDirectory()) {
   process.exit(1);
 }
 
+if (!VALID_MCP_MODES.has(mcpMode.toLowerCase())) {
+  console.error(`Invalid PAGEDEX_MCP_MODE: ${mcpMode}. Expected: read, write, full, or off`);
+  process.exit(1);
+}
+
+if (mcpTokenFile) {
+  const resolvedTokenFile = path.resolve(mcpTokenFile);
+  if (!fs.existsSync(resolvedTokenFile) || !fs.statSync(resolvedTokenFile).isFile()) {
+    console.error(`MCP token file not found: ${resolvedTokenFile}`);
+    process.exit(1);
+  }
+  mcpTokenFile = resolvedTokenFile;
+}
+
 process.env.PAGEDEX_ROOT = resolvedRoot;
 process.env.VAULT_ROOT = resolvedRoot;
 process.env.PORT = String(port);
 process.env.HOST = String(host);
+process.env.PAGEDEX_MCP_MODE = mcpMode.toLowerCase();
+if (mcpGit) process.env.PAGEDEX_MCP_GIT = '1';
+if (mcpTokenFile) process.env.PAGEDEX_MCP_TOKEN_FILE = mcpTokenFile;
+if (readOnly) process.env.PAGEDEX_READ_ONLY = '1';
 
 await import('../src/server/index.js');
 

package/docs/MCP.md

@@ -0,0 +1,107 @@
+# MCP Server Guide (`docs/MCP.md`)
+
+`pagedex` includes a built-in **Model Context Protocol (MCP)** server at `/mcp` supporting three protocol eras simultaneously:
+- **`2026-07-28`** (`server/discover` + Streamable HTTP)
+- **`2025-11-25`** (legacy Streamable HTTP `initialize`)
+- **`2024-11-05`** (legacy HTTP+SSE)
+
+## Access Control & CLI Flags
+
+| Flag | Env Var | Default | Behavior |
+|---|---|---|---|
+| `--mcp <mode>` | `PAGEDEX_MCP_MODE` | `full` | Controls which MCP tools are exposed (`read`, `write`, `full`, or `off`) |
+| `--mcp-git` | `PAGEDEX_MCP_GIT` | `false` | Opt-in flag to expose `git_commit` and `git_discard` (requires `write` or `full`) |
+| `--mcp-token-file <path>` | `PAGEDEX_MCP_TOKEN_FILE` | — | File containing Bearer token required in `Authorization: Bearer <token>` on `/mcp` |
+| — | `PAGEDEX_MCP_TOKEN` | — | Optional env fallback if `--mcp-token-file` is not set |
+| `--read-only` | `PAGEDEX_READ_ONLY` | `false` | Blocks all REST mutations (`403`) and forces MCP to `read` mode (unless `off`) |
+
+### MCP Modes
+
+| Mode | Read Tools | Write / Move Tools | `delete_note` | `git_commit` / `git_discard` |
+|---|---|---|---|---|
+| `read` | Yes | No | No | No |
+| `write` | Yes | Yes | No | Only with `--mcp-git` |
+| `full` *(default)* | Yes | Yes | Yes | Only with `--mcp-git` |
+| `off` | Disabled (`404` on `/mcp`) | No | No | No |
+
+### Examples
+
+```bash
+# Safe read-only MCP for browsing/searching notes
+pagedex ~/vault --mcp read
+
+# Allow AI agents to create/edit/move notes, but forbid deletions
+pagedex ~/vault --mcp write
+
+# Expose on LAN with Bearer token stored in a 0600 file (not in ps/shell history)
+pagedex ~/vault --host 0.0.0.0 --mcp write --mcp-token-file ~/.config/pagedex/mcp-token
+
+# Allow local git commit/discard via MCP (never pushes)
+pagedex ~/vault --mcp write --mcp-git
+
+# Lock down both Web UI/REST and MCP completely
+pagedex ~/vault --read-only
+```
+
+## Client Configuration
+
+Without token auth:
+
+```json
+{
+  "mcpServers": {
+    "pagedex": {
+      "url": "http://127.0.0.1:4321/mcp"
+    }
+  }
+}
+```
+
+With `--mcp-token-file`:
+
+```json
+{
+  "mcpServers": {
+    "pagedex": {
+      "url": "http://127.0.0.1:4321/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_TOKEN_HERE"
+      }
+    }
+  }
+}
+```
+
+## Exposed Tools
+
+### Read Tools (`read`, `write`, `full`)
+
+| Tool | Inputs | Purpose |
+|---|---|---|
+| `list_vault` | `{ folder? }` | List immediate subfolders and files in `/` or a subfolder |
+| `read_note` | `{ path }` | Read a file's contents and incoming backlinks |
+| `search_vault` | `{ query, limit? }` | Run SQLite FTS5 trigram full-text search across filenames & contents |
+| `get_vault_info` | `{ recentLimit? }` | Get total file count and most recently modified files |
+| `get_note_links` | `{ path }` | Get outgoing `[[wikilinks]]`, incoming backlinks, and Markdown headings |
+| `git_status` | `{}` | List uncommitted modified, added, or untracked files |
+| `git_diff` | `{ path }` | Get unified git diff for a specific file |
+
+### Write Tools (`write`, `full`)
+
+| Tool | Inputs | Purpose |
+|---|---|---|
+| `write_note` | `{ path, content?, append?, target?, replacement?, replaceAll? }` | Create, overwrite, append, or patch (`target` → `replacement`) a file |
+| `move_path` | `{ oldPath, newPath, type? }` | Rename or move a file or directory (`type`: `auto` \| `file` \| `dir`) |
+
+### Destructive Tool (`full` only)
+
+| Tool | Inputs | Purpose |
+|---|---|---|
+| `delete_note` | `{ path }` | Delete a file from disk and remove it from the search index |
+
+### Git Mutation Tools (`--mcp-git` with `write` or `full`)
+
+| Tool | Inputs | Purpose |
+|---|---|---|
+| `git_commit` | `{ message, files? }` | Stage and commit changes locally (never pushes) |
+| `git_discard` | `{ path }` | Discard uncommitted changes to a file (or delete an untracked file) |

package/docs/README.md

@@ -4,6 +4,7 @@ User, integration, and developer guides for **pagedex**.
 
 - [Getting Started](./getting-started.md) — CLI flags, environment variables, UI features, wikilinks, Git sync, and mobile gestures.
 - [Supported File Types](./supported-files.md) — Markdown/MDX, sandboxed HTML + sibling assets, PDF, audio/video, CSV/TSV, SVG, code, and binaries.
-- [MCP & REST API](./mcp-and-api.md) — Connecting AI clients to `/mcp`, the 5 vault tools, REST endpoints, `/raw/*`, and SSE live reload.
+- [MCP Server Guide](./MCP.md) — MCP modes (`read`, `write`, `full`, `off`), `--mcp-token-file`, `--mcp-git`, and all 12 vault tools.
+- [MCP & REST API](./mcp-and-api.md) — Quick reference for `/mcp`, REST endpoints, `/raw/*`, and SSE live reload.
 - [Security Model](./security.md) — Sandboxed HTML iframes, CSP/CORS behavior, `Origin: null` guard, and path protection.
 - [Development & Release](./development.md) — Running `pnpm dev`, unit & smoke tests, and npm packaging.

package/docs/getting-started.md

@@ -27,6 +27,10 @@ npx pagedex ~/vault --host 0.0.0.0 --port 4321
 | `-p, --port <port>` | `PORT` | `4321` | HTTP port |
 | `-H, --host <host>` | `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` for LAN/Tailscale) |
 | `-o, --open` | — | `false` | Open browser on startup |
+| `--mcp <mode>` | `PAGEDEX_MCP_MODE` | `full` | MCP mode: `read`, `write`, `full`, or `off` |
+| `--mcp-git` | `PAGEDEX_MCP_GIT` | `false` | Enable `git_commit` and `git_discard` MCP tools |
+| `--mcp-token-file <path>` | `PAGEDEX_MCP_TOKEN_FILE` | — | File containing Bearer token for `/mcp` |
+| `--read-only` | `PAGEDEX_READ_ONLY` | `false` | Disable all REST & MCP write/delete mutations |
 | `-v, --version` | — | — | Print version |
 | `-h, --help` | — | — | Print CLI help |
 
@@ -40,6 +44,8 @@ Override the cache location with:
 
 ## Web UI Highlights
 
+![Desktop Preview](./images/desktop-preview.png)
+
 - **View Modes (top-right `⋮` menu):**
   - **Download** — downloads any open file via `/api/v1/file?path=...&download=1`
   - **Preview** — rendered Markdown, sandboxed HTML, PDF, audio/video, CSV/TSV tables, or images

package/docs/mcp-and-api.md

@@ -25,13 +25,14 @@ Point any HTTP-capable MCP client (Claude Code, Cursor, VS Code, etc.) at:
 
 ### Exposed MCP Tools
 
-| Tool | Purpose |
+See the full **[MCP Server Guide](./MCP.md)** for CLI access control (`--mcp`, `--mcp-git`, `--mcp-token-file`, `--read-only`) and detailed schemas.
+
+| Tier | Tools |
 |---|---|
-| `list_vault` | List files/folders and metadata in the served root |
-| `read_note` | Read file contents and backlinks |
-| `search_vault` | Run SQLite FTS5 trigram full-text search |
-| `write_note` | Create, overwrite, append, or patch (`target` → `replacement`) files |
-| `delete_note` | Delete a file from disk and update the search index |
+| Read (`read`, `write`, `full`) | `list_vault`, `read_note`, `search_vault`, `get_vault_info`, `get_note_links`, `git_status`, `git_diff` |
+| Write (`write`, `full`) | `write_note`, `move_path` |
+| Full (`full` default) | `delete_note` |
+| Git mutations (`--mcp-git`) | `git_commit`, `git_discard` |
 
 ## REST API (`/api/v1/*`)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagedex",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Local-first Markdown knowledge viewer, editor, Git bridge, and MCP v2 server for any directory.",
   "license": "MIT",
   "repository": {

package/src/server/index.js

@@ -12,6 +12,7 @@ import { registerEventRoutes, startVaultWatcher } from './routes/events.js';
 
 const HOST = process.env.HOST || '127.0.0.1';
 const PORT = Number(process.env.PORT || 4321);
+const READ_ONLY = process.env.PAGEDEX_READ_ONLY === '1' || process.env.PAGEDEX_READ_ONLY === 'true';
 
 try {
   syncIndex();
@@ -27,6 +28,9 @@ const app = new Hono();
 app.use('/api/v1/*', async (c, next) => {
   const method = c.req.method.toUpperCase();
   if (method !== 'GET' && method !== 'HEAD' && method !== 'OPTIONS') {
+    if (READ_ONLY) {
+      return c.json({ error: 'Server is running in read-only mode' }, 403);
+    }
     if (c.req.header('origin') === 'null') {
       return c.json({ error: 'Forbidden origin' }, 403);
     }

package/src/server/mcp.js

@@ -1,9 +1,57 @@
-import { randomUUID } from 'node:crypto';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
 import fs from 'node:fs';
 import { McpServer, createMcpHandler, parseJSONRPCMessage } from '@modelcontextprotocol/server';
 import { z } from 'zod';
-import { deleteNote, editNote, getCachedVault, resolveSafe, writeNote } from './vault.js';
-import { removeFileFromIndex, searchFts, upsertFileInIndex } from './search-index.js';
+import {
+  deleteNote,
+  discardGitChange,
+  editNote,
+  getCachedVault,
+  getGitChanges,
+  getGitDiff,
+  gitCommitAndPush,
+  renameDir,
+  renameNote,
+  resolveSafe,
+  writeNote
+} from './vault.js';
+import { removeFileFromIndex, searchFts, syncIndex, upsertFileInIndex } from './search-index.js';
+
+const VALID_MCP_MODES = new Set(['read', 'write', 'full', 'off']);
+
+export function getMcpConfig() {
+  const readOnly = process.env.PAGEDEX_READ_ONLY === '1' || process.env.PAGEDEX_READ_ONLY === 'true';
+  const rawMode = (process.env.PAGEDEX_MCP_MODE || 'full').toLowerCase();
+  const normalized = VALID_MCP_MODES.has(rawMode) ? rawMode : 'full';
+  const mode = normalized === 'off' ? 'off' : readOnly ? 'read' : normalized;
+  const allowWrite = mode === 'write' || mode === 'full';
+  const allowDelete = mode === 'full';
+  const allowGit =
+    !readOnly &&
+    (process.env.PAGEDEX_MCP_GIT === '1' || process.env.PAGEDEX_MCP_GIT === 'true') &&
+    allowWrite;
+  return { mode, readOnly, allowWrite, allowDelete, allowGit };
+}
+
+function readMcpToken() {
+  const tokenFile = process.env.PAGEDEX_MCP_TOKEN_FILE;
+  if (tokenFile) {
+    return fs.readFileSync(tokenFile, 'utf8').trim();
+  }
+  return (process.env.PAGEDEX_MCP_TOKEN || '').trim();
+}
+
+function isAuthorizedMcpRequest(req) {
+  const expected = readMcpToken();
+  if (!expected) return true;
+  const auth = req.headers.get('authorization') || '';
+  const match = auth.match(/^Bearer\s+(.+)$/i);
+  if (!match) return false;
+  const provided = match[1].trim();
+  const a = Buffer.from(provided, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  return a.length === b.length && timingSafeEqual(a, b);
+}
 
 const sseSessions = new Map();
 const encoder = new TextEncoder();
@@ -88,7 +136,7 @@ class WebStandardSSEServerTransport {
   }
 }
 
-function createVaultMcpServer() {
+function createVaultMcpServer(config = getMcpConfig()) {
   const server = new McpServer({
     name: 'vault-mcp',
     version: '0.1.0'
@@ -233,68 +281,142 @@ function createVaultMcpServer() {
   );
 
   server.registerTool(
-    'write_note',
+    'get_vault_info',
     {
-      title: 'Write or Edit Note',
-      description:
-        'Create/overwrite/append a note (with content), or partially edit an existing note (with target + replacement).',
+      title: 'Get Vault Info',
+      description: 'Return vault summary: total indexed files and the most recently modified files.',
       inputSchema: z.object({
-        path: z.string(),
-        content: z.string().optional(),
-        append: z.boolean().optional(),
-        target: z.string().optional(),
-        replacement: z.string().optional(),
-        replaceAll: z.boolean().optional()
+        recentLimit: z.number().int().min(1).max(50).optional()
+      }),
+      outputSchema: z.object({
+        totalFiles: z.number(),
+        recentFiles: z.array(
+          z.object({
+            path: z.string(),
+            mtimeMs: z.number()
+          })
+        )
+      })
+    },
+    async ({ recentLimit }) => {
+      const { flatFiles, fileStats } = getCachedVault();
+      const limit = recentLimit ?? 15;
+      const recentFiles = [...(fileStats || [])]
+        .sort((a, b) => (b.mtimeMs || 0) - (a.mtimeMs || 0))
+        .slice(0, limit)
+        .map((f) => ({ path: f.path, mtimeMs: f.mtimeMs || 0 }));
+      const lines = recentFiles.map((f) => f.path);
+      return {
+        structuredContent: {
+          totalFiles: flatFiles.length,
+          recentFiles
+        },
+        content: [
+          {
+            type: 'text',
+            text: `Total files: ${flatFiles.length}\nRecent files:\n${lines.length ? lines.join('\n') : '(none)'}`
+          }
+        ]
+      };
+    }
+  );
+
+  server.registerTool(
+    'get_note_links',
+    {
+      title: 'Get Note Links and Outline',
+      description: 'Return outgoing [[wikilinks]], incoming backlinks, and Markdown headings for a note.',
+      inputSchema: z.object({
+        path: z.string()
       }),
       outputSchema: z.object({
-        ok: z.boolean(),
         path: z.string(),
-        mode: z.enum(['write', 'append', 'edit']),
-        bytes: z.number().optional(),
-        replacements: z.number().optional()
+        outgoingLinks: z.array(z.string()),
+        backlinks: z.array(z.string()),
+        headings: z.array(
+          z.object({
+            level: z.number(),
+            text: z.string()
+          })
+        )
       })
     },
-    async ({ path: relPath, content, append, target, replacement, replaceAll }) => {
-      if (typeof target === 'string' && typeof replacement === 'string') {
-        const result = editNote(relPath, target, replacement, { replaceAll: Boolean(replaceAll) });
-        if (result.error) {
-          return { isError: true, content: [{ type: 'text', text: result.error }] };
-        }
-        upsertFileInIndex(result.path);
-        return {
-          structuredContent: {
-            ok: true,
-            path: result.path,
-            mode: 'edit',
-            replacements: result.replacements
-          },
-          content: [
-            {
-              type: 'text',
-              text: `Edited ${result.path} (${result.replacements} replacement${result.replacements === 1 ? '' : 's'})`
-            }
-          ]
-        };
+    async ({ path: relPath }) => {
+      const full = resolveSafe(relPath);
+      if (!full || !fs.existsSync(full) || !fs.statSync(full).isFile()) {
+        return { isError: true, content: [{ type: 'text', text: `Not found: ${relPath}` }] };
       }
-      if (typeof content !== 'string') {
-        return { isError: true, content: [{ type: 'text', text: 'Provide either content or target + replacement' }] };
+      const raw = fs.readFileSync(full, 'utf8');
+      const outgoingSet = new Set();
+      for (const m of raw.matchAll(/\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]/g)) {
+        const target = m[1].trim();
+        if (target) outgoingSet.add(target);
       }
-      const result = writeNote(relPath, content, { append: Boolean(append) });
-      if (!result) {
-        return { isError: true, content: [{ type: 'text', text: `Invalid or protected path: ${relPath}` }] };
+      const headings = [];
+      for (const line of raw.split('\n')) {
+        const hm = line.match(/^(#{1,6})\s+(.+?)\s*#*$/);
+        if (hm) headings.push({ level: hm[1].length, text: hm[2].trim() });
       }
-      upsertFileInIndex(result.path);
+      const { backlinks } = getCachedVault();
+      const outgoingLinks = [...outgoingSet];
+      const incoming = backlinks[relPath] || [];
+      return {
+        structuredContent: {
+          path: relPath,
+          outgoingLinks,
+          backlinks: incoming,
+          headings
+        },
+        content: [
+          {
+            type: 'text',
+            text: [
+              `# ${relPath}`,
+              `Outgoing: ${outgoingLinks.length ? outgoingLinks.join(', ') : 'none'}`,
+              `Backlinks: ${incoming.length ? incoming.join(', ') : 'none'}`,
+              `Headings: ${headings.length ? headings.map((h) => `${'#'.repeat(h.level)} ${h.text}`).join(' | ') : 'none'}`
+            ].join('\n')
+          }
+        ]
+      };
+    }
+  );
+
+  server.registerTool(
+    'git_status',
+    {
+      title: 'Git Status',
+      description: 'List uncommitted modified, added, or untracked files in the vault.',
+      inputSchema: z.object({}),
+      outputSchema: z.object({
+        isGit: z.boolean(),
+        count: z.number(),
+        changes: z.array(
+          z.object({
+            status: z.string(),
+            path: z.string(),
+            mtimeMs: z.number()
+          })
+        )
+      })
+    },
+    async () => {
+      const { isGit, changes } = getGitChanges();
+      const lines = changes.map((c) => `[${c.status}] ${c.path}`);
       return {
         structuredContent: {
-          ok: true,
-          path: result.path,
-          mode: append ? 'append' : 'write',
-          bytes: result.bytes
+          isGit,
+          count: changes.length,
+          changes
         },
         content: [
           {
             type: 'text',
-            text: `${append ? 'Appended' : 'Wrote'} ${result.path} (${result.bytes} bytes)`
+            text: !isGit
+              ? 'Not a git repository'
+              : lines.length
+                ? lines.join('\n')
+                : 'Working tree clean'
           }
         ]
       };
@@ -302,40 +424,276 @@ function createVaultMcpServer() {
   );
 
   server.registerTool(
-    'delete_note',
+    'git_diff',
     {
-      title: 'Delete Note',
-      description: 'Delete a note/file from the vault by relative path.',
+      title: 'Git Diff',
+      description: 'Get the unified git diff for a specific file in the vault.',
       inputSchema: z.object({
         path: z.string()
       }),
       outputSchema: z.object({
-        ok: z.boolean(),
-        path: z.string()
+        path: z.string(),
+        untracked: z.boolean(),
+        raw: z.string()
       })
     },
     async ({ path: relPath }) => {
-      const result = deleteNote(relPath);
-      if (!result) {
-        return { isError: true, content: [{ type: 'text', text: `Not found or protected path: ${relPath}` }] };
+      const diff = getGitDiff(relPath);
+      if (diff.error) {
+        return { isError: true, content: [{ type: 'text', text: diff.error }] };
       }
-      removeFileFromIndex(result.path);
       return {
         structuredContent: {
-          ok: true,
-          path: result.path
+          path: diff.path,
+          untracked: Boolean(diff.untracked),
+          raw: diff.raw || ''
         },
-        content: [{ type: 'text', text: `Deleted ${result.path}` }]
+        content: [
+          {
+            type: 'text',
+            text: diff.raw ? diff.raw : `No changes in ${diff.path}`
+          }
+        ]
       };
     }
   );
 
+  if (config.allowWrite) {
+    server.registerTool(
+      'write_note',
+      {
+        title: 'Write or Edit Note',
+        description:
+          'Create/overwrite/append a note (with content), or partially edit an existing note (with target + replacement).',
+        inputSchema: z.object({
+          path: z.string(),
+          content: z.string().optional(),
+          append: z.boolean().optional(),
+          target: z.string().optional(),
+          replacement: z.string().optional(),
+          replaceAll: z.boolean().optional()
+        }),
+        outputSchema: z.object({
+          ok: z.boolean(),
+          path: z.string(),
+          mode: z.enum(['write', 'append', 'edit']),
+          bytes: z.number().optional(),
+          replacements: z.number().optional()
+        })
+      },
+      async ({ path: relPath, content, append, target, replacement, replaceAll }) => {
+        if (typeof target === 'string' && typeof replacement === 'string') {
+          const result = editNote(relPath, target, replacement, { replaceAll: Boolean(replaceAll) });
+          if (result.error) {
+            return { isError: true, content: [{ type: 'text', text: result.error }] };
+          }
+          upsertFileInIndex(result.path);
+          return {
+            structuredContent: {
+              ok: true,
+              path: result.path,
+              mode: 'edit',
+              replacements: result.replacements
+            },
+            content: [
+              {
+                type: 'text',
+                text: `Edited ${result.path} (${result.replacements} replacement${result.replacements === 1 ? '' : 's'})`
+              }
+            ]
+          };
+        }
+        if (typeof content !== 'string') {
+          return { isError: true, content: [{ type: 'text', text: 'Provide either content or target + replacement' }] };
+        }
+        const result = writeNote(relPath, content, { append: Boolean(append) });
+        if (!result) {
+          return { isError: true, content: [{ type: 'text', text: `Invalid or protected path: ${relPath}` }] };
+        }
+        upsertFileInIndex(result.path);
+        return {
+          structuredContent: {
+            ok: true,
+            path: result.path,
+            mode: append ? 'append' : 'write',
+            bytes: result.bytes
+          },
+          content: [
+            {
+              type: 'text',
+              text: `${append ? 'Appended' : 'Wrote'} ${result.path} (${result.bytes} bytes)`
+            }
+          ]
+        };
+      }
+    );
+
+    server.registerTool(
+      'move_path',
+      {
+        title: 'Move or Rename File/Folder',
+        description: 'Rename or move a file or folder within the vault.',
+        inputSchema: z.object({
+          oldPath: z.string(),
+          newPath: z.string(),
+          type: z.enum(['auto', 'file', 'dir']).optional()
+        }),
+        outputSchema: z.object({
+          ok: z.boolean(),
+          type: z.enum(['file', 'dir']),
+          oldPath: z.string(),
+          newPath: z.string()
+        })
+      },
+      async ({ oldPath, newPath, type = 'auto' }) => {
+        const full = resolveSafe(oldPath);
+        if (!full || !fs.existsSync(full)) {
+          return { isError: true, content: [{ type: 'text', text: `Source not found: ${oldPath}` }] };
+        }
+        const isDir = type === 'dir' || (type === 'auto' && fs.statSync(full).isDirectory());
+        const result = isDir ? renameDir(oldPath, newPath) : renameNote(oldPath, newPath);
+        if (result.error) {
+          return { isError: true, content: [{ type: 'text', text: result.error }] };
+        }
+        if (isDir) {
+          syncIndex();
+        } else {
+          removeFileFromIndex(result.oldPath);
+          upsertFileInIndex(result.newPath);
+        }
+        return {
+          structuredContent: {
+            ok: true,
+            type: isDir ? 'dir' : 'file',
+            oldPath: result.oldPath,
+            newPath: result.newPath
+          },
+          content: [{ type: 'text', text: `Moved ${result.oldPath} -> ${result.newPath}` }]
+        };
+      }
+    );
+  }
+
+  if (config.allowDelete) {
+    server.registerTool(
+      'delete_note',
+      {
+        title: 'Delete Note',
+        description: 'Delete a note/file from the vault by relative path.',
+        inputSchema: z.object({
+          path: z.string()
+        }),
+        outputSchema: z.object({
+          ok: z.boolean(),
+          path: z.string()
+        })
+      },
+      async ({ path: relPath }) => {
+        const result = deleteNote(relPath);
+        if (!result) {
+          return { isError: true, content: [{ type: 'text', text: `Not found or protected path: ${relPath}` }] };
+        }
+        removeFileFromIndex(result.path);
+        return {
+          structuredContent: {
+            ok: true,
+            path: result.path
+          },
+          content: [{ type: 'text', text: `Deleted ${result.path}` }]
+        };
+      }
+    );
+  }
+
+  if (config.allowGit) {
+    server.registerTool(
+      'git_commit',
+      {
+        title: 'Git Commit',
+        description: 'Stage and commit vault changes locally (never pushes).',
+        inputSchema: z.object({
+          message: z.string(),
+          files: z.array(z.string()).optional()
+        }),
+        outputSchema: z.object({
+          ok: z.boolean(),
+          output: z.string()
+        })
+      },
+      async ({ message, files }) => {
+        const result = gitCommitAndPush({ message, files, push: false });
+        if (result.error) {
+          return { isError: true, content: [{ type: 'text', text: result.error }] };
+        }
+        return {
+          structuredContent: {
+            ok: true,
+            output: result.output || ''
+          },
+          content: [{ type: 'text', text: result.output || 'Committed' }]
+        };
+      }
+    );
+
+    server.registerTool(
+      'git_discard',
+      {
+        title: 'Git Discard File Changes',
+        description: 'Discard all uncommitted changes to a file (or remove an untracked file).',
+        inputSchema: z.object({
+          path: z.string()
+        }),
+        outputSchema: z.object({
+          ok: z.boolean(),
+          path: z.string(),
+          discarded: z.string()
+        })
+      },
+      async ({ path: relPath }) => {
+        const result = discardGitChange({ path: relPath });
+        if (result.error) {
+          return { isError: true, content: [{ type: 'text', text: result.error }] };
+        }
+        syncIndex();
+        return {
+          structuredContent: {
+            ok: true,
+            path: result.path,
+            discarded: result.discarded || 'file'
+          },
+          content: [{ type: 'text', text: `Discarded changes in ${result.path} (${result.discarded})` }]
+        };
+      }
+    );
+  }
+
   return server;
 }
 
-const mcpHandler = createMcpHandler(createVaultMcpServer);
+const mcpHandlers = new Map();
+
+function getMcpHandler(config) {
+  const key = `${config.mode}:${config.allowGit}`;
+  let handler = mcpHandlers.get(key);
+  if (!handler) {
+    handler = createMcpHandler(() => createVaultMcpServer(config));
+    mcpHandlers.set(key, handler);
+  }
+  return handler;
+}
 
 export async function handleMcpRequest(req) {
+  const config = getMcpConfig();
+  if (config.mode === 'off') {
+    return Response.json({ error: 'MCP endpoint is disabled' }, { status: 404 });
+  }
+  if (!isAuthorizedMcpRequest(req)) {
+    return Response.json(
+      { error: 'Unauthorized' },
+      { status: 401, headers: { 'WWW-Authenticate': 'Bearer' } }
+    );
+  }
+
   const url = new URL(req.url, 'http://localhost');
   const sessionId = url.searchParams.get('sessionId');
   const isStreamableHttpGet =
@@ -345,7 +703,7 @@ export async function handleMcpRequest(req) {
   if (req.method === 'GET' && !sessionId && !isStreamableHttpGet) {
     const transport = new WebStandardSSEServerTransport(url.pathname);
     sseSessions.set(transport.sessionId, transport);
-    const server = createVaultMcpServer();
+    const server = createVaultMcpServer(config);
     await server.connect(transport);
     return transport.createResponse(req.signal);
   }
@@ -360,5 +718,5 @@ export async function handleMcpRequest(req) {
   }
 
   // 3. Official MCP v2 handler: supports BOTH Modern (2026-07-28 server/discover) and Legacy Streamable HTTP (2025-11-25 initialize)
-  return mcpHandler.fetch(req);
+  return getMcpHandler(config).fetch(req);
 }