pagedex 0.0.0-stage → 0.1.0

package/src/server/mcp.js

@@ -0,0 +1,364 @@
+import { randomUUID } 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';
+
+const sseSessions = new Map();
+const encoder = new TextEncoder();
+
+class WebStandardSSEServerTransport {
+  constructor(endpoint = '/mcp') {
+    this.endpoint = endpoint;
+    this.sessionId = randomUUID();
+    this._controller = null;
+    this.onmessage = undefined;
+    this.onclose = undefined;
+    this.onerror = undefined;
+  }
+
+  async start() {
+    // Stream is initialized in createResponse()
+  }
+
+  createResponse(signal) {
+    const stream = new ReadableStream({
+      start: (controller) => {
+        this._controller = controller;
+        const endpointUri = `${this.endpoint}?sessionId=${this.sessionId}`;
+        controller.enqueue(encoder.encode(`event: endpoint\ndata: ${endpointUri}\n\n`));
+      },
+      cancel: () => {
+        this.close();
+      }
+    });
+
+    signal?.addEventListener('abort', () => this.close(), { once: true });
+
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache, no-transform',
+        Connection: 'keep-alive',
+        'X-Accel-Buffering': 'no'
+      }
+    });
+  }
+
+  async send(message) {
+    if (!this._controller) return;
+    try {
+      this._controller.enqueue(encoder.encode(`event: message\ndata: ${JSON.stringify(message)}\n\n`));
+    } catch (err) {
+      this.onerror?.(err);
+    }
+  }
+
+  async handlePostMessage(req) {
+    let body;
+    try {
+      body = await req.json();
+    } catch (err) {
+      this.onerror?.(err);
+      return new Response('Invalid JSON', { status: 400 });
+    }
+    try {
+      const parsed = parseJSONRPCMessage(body);
+      this.onmessage?.(parsed);
+    } catch (err) {
+      this.onerror?.(err);
+      return new Response('Invalid JSON-RPC message', { status: 400 });
+    }
+    return new Response('Accepted', { status: 202 });
+  }
+
+  async close() {
+    if (!this._controller) return;
+    const ctrl = this._controller;
+    this._controller = null;
+    sseSessions.delete(this.sessionId);
+    try {
+      ctrl.close();
+    } catch {
+      // already closed
+    }
+    this.onclose?.();
+  }
+}
+
+function createVaultMcpServer() {
+  const server = new McpServer({
+    name: 'vault-mcp',
+    version: '0.1.0'
+  });
+
+  server.registerTool(
+    'list_vault',
+    {
+      title: 'List Vault Directory',
+      description:
+        'List immediate folders and files in a vault directory (like ls). Leave folder empty for root "/", or pass a folder path (e.g. "core", "backups/2026") to drill down.',
+      inputSchema: z.object({
+        folder: z.string().optional()
+      }),
+      outputSchema: z.object({
+        folder: z.string(),
+        folders: z.array(z.string()),
+        files: z.array(z.string())
+      })
+    },
+    async ({ folder }) => {
+      const { tree } = getCachedVault();
+      const cleanFolder = (folder || '').trim().replace(/^\/+|\/+$/g, '');
+
+      let nodes = tree;
+      if (cleanFolder) {
+        for (const segment of cleanFolder.split('/')) {
+          const dirNode = nodes.find((n) => n.type === 'dir' && n.name === segment);
+          if (!dirNode) {
+            return {
+              isError: true,
+              content: [{ type: 'text', text: `Folder not found: ${cleanFolder}` }]
+            };
+          }
+          nodes = dirNode.children || [];
+        }
+      }
+
+      const folders = nodes.filter((n) => n.type === 'dir').map((n) => `${n.path}/`);
+      const files = nodes.filter((n) => n.type === 'file').map((n) => n.path);
+      const lines = [
+        ...folders.map((d) => `[DIR]  ${d}`),
+        ...files.map((f) => `[FILE] ${f}`)
+      ];
+
+      return {
+        structuredContent: {
+          folder: cleanFolder || '/',
+          folders,
+          files
+        },
+        content: [
+          {
+            type: 'text',
+            text: lines.length ? lines.join('\n') : '(empty directory)'
+          }
+        ]
+      };
+    }
+  );
+
+  server.registerTool(
+    'read_note',
+    {
+      title: 'Read Note',
+      description: 'Read a file or note from the vault by relative path, including incoming backlinks.',
+      inputSchema: z.object({
+        path: z.string()
+      }),
+      outputSchema: z.object({
+        path: z.string(),
+        backlinks: z.array(z.string()),
+        content: z.string()
+      })
+    },
+    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}` }] };
+      }
+      const content = fs.readFileSync(full, 'utf8');
+      const { backlinks } = getCachedVault();
+      const bl = backlinks[relPath] || [];
+      return {
+        structuredContent: {
+          path: relPath,
+          backlinks: bl,
+          content
+        },
+        content: [
+          {
+            type: 'text',
+            text: `# ${relPath}\nBacklinks: ${bl.length ? bl.join(', ') : 'none'}\n\n${content}`
+          }
+        ]
+      };
+    }
+  );
+
+  server.registerTool(
+    'search_vault',
+    {
+      title: 'Search Vault',
+      description: 'Search across vault filenames and note contents.',
+      inputSchema: z.object({
+        query: z.string(),
+        limit: z.number().int().min(1).max(50).optional()
+      }),
+      outputSchema: z.object({
+        query: z.string(),
+        count: z.number(),
+        results: z.array(
+          z.object({
+            path: z.string(),
+            mtimeMs: z.number(),
+            snippet: z.string()
+          })
+        )
+      })
+    },
+    async ({ query, limit }) => {
+      const hits = searchFts(query, limit ?? 20).map((h) => ({
+        path: h.path,
+        mtimeMs: h.mtimeMs,
+        snippet: (h.snippet || '').replace(/\s+/g, ' ').trim()
+      }));
+      const lines = hits.map((h) => (h.snippet ? `${h.path} — ${h.snippet}` : h.path));
+      return {
+        structuredContent: {
+          query,
+          count: hits.length,
+          results: hits
+        },
+        content: [
+          {
+            type: 'text',
+            text: lines.length ? lines.join('\n') : `No matches found for: ${query}`
+          }
+        ]
+      };
+    }
+  );
+
+  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(
+    '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}` }]
+      };
+    }
+  );
+
+  return server;
+}
+
+const mcpHandler = createMcpHandler(createVaultMcpServer);
+
+export async function handleMcpRequest(req) {
+  const url = new URL(req.url, 'http://localhost');
+  const sessionId = url.searchParams.get('sessionId');
+  const isStreamableHttpGet =
+    req.headers.has('mcp-protocol-version') || req.headers.has('mcp-session-id');
+
+  // 1. Legacy HTTP+SSE (2024-11-05): GET /mcp (without Streamable HTTP headers) establishes SSE stream
+  if (req.method === 'GET' && !sessionId && !isStreamableHttpGet) {
+    const transport = new WebStandardSSEServerTransport(url.pathname);
+    sseSessions.set(transport.sessionId, transport);
+    const server = createVaultMcpServer();
+    await server.connect(transport);
+    return transport.createResponse(req.signal);
+  }
+
+  // 2. Legacy HTTP+SSE: POST /mcp?sessionId=<uuid> delivers JSON-RPC message to active SSE session
+  if (req.method === 'POST' && sessionId) {
+    const transport = sseSessions.get(sessionId);
+    if (!transport) {
+      return new Response('Session not found', { status: 404 });
+    }
+    return transport.handlePostMessage(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);
+}

package/src/server/paths.js

@@ -0,0 +1,53 @@
+import path from 'node:path';
+
+export const VAULT_ROOT = path.resolve(
+  process.env.PAGEDEX_ROOT || process.env.VAULT_ROOT || process.cwd()
+);
+
+export const IGNORED = new Set([
+  '.git',
+  '.gitignore',
+  'node_modules',
+  'package.json',
+  'pnpm-lock.yaml',
+  'pnpm-workspace.yaml',
+  '.venv',
+  '__pycache__',
+  '.obsidian',
+  '.DS_Store',
+  'dist',
+  '.vault-index.db',
+  '.vault-index.db-wal',
+  '.vault-index.db-shm',
+  '.pagedex-index.db',
+  '.pagedex-index.db-wal',
+  '.pagedex-index.db-shm'
+]);
+
+export const IMAGE_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon'
+};
+
+export function isImagePath(p) {
+  return /\.(png|jpe?g|gif|webp|svg|ico)$/i.test(p);
+}
+
+export function resolveSafe(relPath) {
+  const cleaned = String(relPath || '').replace(/^\/+/, '');
+  const resolved = path.resolve(VAULT_ROOT, cleaned);
+  if (resolved !== VAULT_ROOT && !resolved.startsWith(VAULT_ROOT + path.sep)) {
+    return null;
+  }
+  return resolved;
+}
+
+export function isProtectedPath(relPath) {
+  const parts = String(relPath || '').replace(/^\/+/, '').split('/');
+  return parts.some((p) => p === '.git' || p === 'node_modules' || p === 'dist');
+}

package/src/server/routes/events.js

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { streamSSE } from 'hono/streaming';
+import { IGNORED, VAULT_ROOT, invalidateVaultCache, updateVaultCacheFile } from '../vault.js';
+import { upsertFileInIndex } from '../search-index.js';
+
+const subscribers = new Set();
+let watchTimer = null;
+let lastChanged = '';
+
+export function startVaultWatcher() {
+  try {
+    fs.watch(VAULT_ROOT, { recursive: true }, (_event, filename) => {
+      if (filename) {
+        const parts = filename.split(path.sep);
+        if (parts.some((p) => IGNORED.has(p))) return;
+        lastChanged = parts.join('/');
+        updateVaultCacheFile(lastChanged);
+        try {
+          upsertFileInIndex(lastChanged);
+        } catch {
+          // Ignore transient watch update error
+        }
+      } else {
+        invalidateVaultCache();
+      }
+      clearTimeout(watchTimer);
+      watchTimer = setTimeout(() => {
+        for (const send of subscribers) send(lastChanged);
+      }, 100);
+    });
+  } catch (err) {
+    console.warn('fs.watch warning:', err.message);
+  }
+}
+
+export function registerEventRoutes(app) {
+  app.get('/api/v1/events', (c) => {
+    return streamSSE(c, async (stream) => {
+      await stream.writeSSE({ data: JSON.stringify({ type: 'connected' }) });
+      const notify = (changedPath) => {
+        stream.writeSSE({ data: JSON.stringify({ type: 'reload', path: changedPath }) }).catch(() => {});
+      };
+      subscribers.add(notify);
+      const keepAlive = setInterval(() => {
+        stream.writeSSE({ data: JSON.stringify({ type: 'ping' }) }).catch(() => {});
+      }, 25000);
+      await new Promise((resolve) => {
+        c.req.raw.signal.addEventListener('abort', resolve, { once: true });
+      });
+      clearInterval(keepAlive);
+      subscribers.delete(notify);
+    });
+  });
+}

package/src/server/routes/files.js

@@ -0,0 +1,166 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  IMAGE_MIME,
+   VAULT_ROOT,
+  deleteNote,
+  editNote,
+  getCachedVault,
+  renameDir,
+  renameNote,
+  resolveSafe,
+  sortTree,
+  writeBinaryFile,
+  writeNote
+} from '../vault.js';
+import {
+  queryFiles,
+  removeFileFromIndex,
+  searchFts,
+  syncIndex,
+  upsertFileInIndex
+} from '../search-index.js';
+
+export function registerFileRoutes(app) {
+  app.get('/api/v1/health', (c) => c.json({ ok: true, root: VAULT_ROOT }));
+
+  app.get('/api/v1/tree', (c) => {
+    const rawLimit = Number(c.req.query('limit') || 10000);
+    const limit = Number.isFinite(rawLimit) && rawLimit > 0 ? Math.min(rawLimit, 10000) : 10000;
+    const sort = c.req.query('sort'); // 'mtime' | 'name' | undefined
+    const { tree, flatFiles, fileStats, sortedStats, backlinks } = getCachedVault();
+    const outTree = sort === 'mtime' ? sortTree(tree, 'mtime') : tree;
+    const outStats =
+      sort === 'name'
+        ? [...fileStats].sort((a, b) => a.path.localeCompare(b.path)).slice(0, limit)
+        : sortedStats.slice(0, limit);
+    return c.json({
+      tree: outTree,
+      flatFiles,
+      fileStats: outStats,
+      totalFiles: sortedStats.length,
+      truncated: sortedStats.length > limit,
+      backlinks
+    });
+  });
+
+  app.get('/api/v1/files', (c) => {
+    const sort = c.req.query('sort') === 'name' ? 'name' : 'mtime';
+    const offset = Number(c.req.query('offset') || 0);
+    const limit = Number(c.req.query('limit') || 100);
+    const q = c.req.query('q') || '';
+    return c.json(queryFiles({ sort, offset, limit, q }));
+  });
+
+  app.get('/api/v1/search', (c) => {
+    const q = c.req.query('q') || '';
+    const limit = Number(c.req.query('limit') || 50);
+    return c.json({ query: q, results: searchFts(q, limit) });
+  });
+
+  app.get('/api/v1/file', (c) => {
+    const rel = c.req.query('path') || '';
+    const full = resolveSafe(rel);
+    if (!full || !fs.existsSync(full) || !fs.statSync(full).isFile()) {
+      return c.text('Not found', 404);
+    }
+    const ext = path.extname(full).toLowerCase();
+    const isDownload = c.req.query('download') === '1';
+    const contentType = IMAGE_MIME[ext] || (isDownload ? 'application/octet-stream' : 'text/plain; charset=utf-8');
+    const buf = fs.readFileSync(full);
+    const headers = { 'Content-Type': contentType };
+    if (isDownload) {
+      const fileName = path.basename(full).replace(/"/g, '');
+      headers['Content-Disposition'] = `attachment; filename="${fileName}"`;
+    }
+    return new Response(buf, { status: 200, headers });
+  });
+
+  async function handleWriteOrEdit(c) {
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.path !== 'string') {
+      return c.json({ error: 'Expected JSON with path' }, 400);
+    }
+    if (typeof body.target === 'string' && typeof body.replacement === 'string') {
+      const result = editNote(body.path, body.target, body.replacement, {
+        replaceAll: Boolean(body.replaceAll)
+      });
+      if (result.error) return c.json(result, 400);
+      upsertFileInIndex(result.path);
+      return c.json(result);
+    }
+    if (typeof body.content === 'string') {
+      const result = writeNote(body.path, body.content, { append: Boolean(body.append) });
+      if (!result) return c.json({ error: 'Invalid or protected path' }, 400);
+      upsertFileInIndex(result.path);
+      return c.json(result);
+    }
+    return c.json({ error: 'Provide either { content } or { target, replacement }' }, 400);
+  }
+
+  app.put('/api/v1/file', handleWriteOrEdit);
+  app.post('/api/v1/file', handleWriteOrEdit);
+  app.patch('/api/v1/file', handleWriteOrEdit);
+
+  app.delete('/api/v1/file', (c) => {
+    const rel = c.req.query('path') || '';
+    const result = deleteNote(rel);
+    if (!result) return c.json({ error: 'Not found or protected path' }, 404);
+    removeFileFromIndex(result.path);
+    return c.json(result);
+  });
+
+  app.post('/api/v1/file/rename', async (c) => {
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.oldPath !== 'string' || typeof body.newPath !== 'string') {
+      return c.json({ error: 'Expected JSON { oldPath, newPath }' }, 400);
+    }
+    const result = renameNote(body.oldPath, body.newPath);
+    if (result.error) return c.json(result, 400);
+    removeFileFromIndex(result.oldPath);
+    upsertFileInIndex(result.newPath);
+    return c.json(result);
+  });
+
+  app.post('/api/v1/dir/rename', async (c) => {
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.oldPath !== 'string' || typeof body.newPath !== 'string') {
+      return c.json({ error: 'Expected JSON { oldPath, newPath }' }, 400);
+    }
+    const result = renameDir(body.oldPath, body.newPath);
+    if (result.error) return c.json(result, 400);
+    syncIndex();
+    return c.json(result);
+  });
+
+  app.post('/api/v1/file/upload', async (c) => {
+    const body = await c.req.parseBody({ all: true }).catch(() => null);
+    if (!body) {
+      return c.json({ error: 'Expected multipart/form-data' }, 400);
+    }
+    const dir = typeof body.dir === 'string' ? body.dir.trim().replace(/^\/+|\/+$/g, '') : '';
+    const rawFiles = body.files ?? body.file;
+    const list = (Array.isArray(rawFiles) ? rawFiles : rawFiles ? [rawFiles] : []).filter(
+      (item) => item && typeof item === 'object' && typeof item.arrayBuffer === 'function' && item.name
+    );
+    if (list.length === 0) {
+      return c.json({ error: 'No files provided' }, 400);
+    }
+    const uploaded = [];
+    for (const file of list) {
+      const safeName = path.basename(String(file.name));
+      if (!safeName || safeName === '.' || safeName === '..') {
+        return c.json({ error: 'Invalid filename' }, 400);
+      }
+      const relPath = dir ? `${dir}/${safeName}` : safeName;
+      const buf = Buffer.from(await file.arrayBuffer());
+      const result = writeBinaryFile(relPath, buf);
+      if (!result) {
+        return c.json({ error: `Invalid or protected path: ${relPath}` }, 400);
+      }
+      upsertFileInIndex(result.path);
+      uploaded.push(result);
+    }
+    return c.json({ ok: true, uploaded });
+  });
+}

package/src/server/routes/git.js

@@ -0,0 +1,40 @@
+import { discardGitChange, getGitChanges, getGitDiff, gitCommitAndPush } from '../vault.js';
+import { upsertFileInIndex } from '../search-index.js';
+
+export function registerGitRoutes(app) {
+  app.get('/api/v1/changes', (c) => {
+    return c.json(getGitChanges());
+  });
+
+  app.get('/api/v1/git/diff', (c) => {
+    const rel = c.req.query('path') || '';
+    const result = getGitDiff(rel);
+    if (result.error) return c.json(result, 400);
+    return c.json(result);
+  });
+
+  app.post('/api/v1/git/discard', async (c) => {
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.path !== 'string') {
+      return c.json({ error: 'Expected JSON { path, hunkIndex?, lineIndex? }' }, 400);
+    }
+    const result = discardGitChange(body);
+    if (result.error) return c.json(result, 400);
+    upsertFileInIndex(body.path);
+    return c.json(result);
+  });
+
+  app.post('/api/v1/git/commit', async (c) => {
+    const body = await c.req.json().catch(() => null);
+    if (!body || typeof body.message !== 'string' || !body.message.trim()) {
+      return c.json({ error: 'Commit message is required' }, 400);
+    }
+    const result = gitCommitAndPush({
+      message: body.message,
+      files: body.files,
+      push: Boolean(body.push)
+    });
+    if (result.error) return c.json(result, 400);
+    return c.json(result);
+  });
+}