@knowall-ai/reverie 0.4.0 → 0.5.0

package/build/http-server.js

@@ -0,0 +1,418 @@
+/**
+ * `reverie serve`: the same MCP server over Streamable HTTP at /mcp, plus the read-only Brain API
+ * (/brain/graph, /brain/state, /brain/events as Server-Sent Events) the Agents Portal's Brain tab
+ * uses. One bearer token (REVERIE_SERVE_TOKEN) protects everything except the health check.
+ * Plain node:http: nothing here needs a framework.
+ */
+import http from 'node:http';
+import { timingSafeEqual } from 'node:crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { diffSnapshot, isEmptyDiff, parseLimit, snapshot, snapshotAsDiff, state } from './brain.js';
+import { neo4jConfigError, neo4jConfigFromEnv } from './config.js';
+import { START_CURSOR, eventsPath, readSince } from './events.js';
+import { Neo4jClient } from './neo4j-client.js';
+import { createMcpServer, safeCreateEmbedder } from './server.js';
+export class ConfigError extends Error {
+}
+const MAX_BODY_BYTES = 1024 * 1024;
+const PING_SECONDS = 15;
+const SHUTDOWN_GRACE_MS = 10_000;
+const HEALTH_CACHE_MS = 5_000;
+const HEALTH_TIMEOUT_MS = 5_000;
+const BACKPRESSURE_GRACE_MS = 30_000;
+const PENDING_ACTIVATIONS_MAX = 1000;
+function settingsFromEnv(env) {
+    const token = env.REVERIE_SERVE_TOKEN?.trim();
+    if (!token) {
+        throw new ConfigError('REVERIE_SERVE_TOKEN is required for reverie serve');
+    }
+    const rawPort = env.REVERIE_HTTP_PORT?.trim() || '8643';
+    const port = /^\d{1,5}$/.test(rawPort) ? Number.parseInt(rawPort, 10) : Number.NaN;
+    if (!Number.isInteger(port) || port > 65535) {
+        throw new ConfigError(`REVERIE_HTTP_PORT must be a port number, got ${env.REVERIE_HTTP_PORT}`);
+    }
+    const seconds = (variable, fallback) => {
+        const parsed = Number.parseFloat(env[variable]?.trim() || '');
+        return Number.isFinite(parsed) && parsed > 0 ? parsed * 1000 : fallback * 1000;
+    };
+    return {
+        token,
+        // Streamable HTTP requires Origin validation. Non-browser clients send no Origin; a browser
+        // origin is accepted only when listed in REVERIE_ALLOWED_ORIGINS (comma-separated).
+        allowedOrigins: new Set((env.REVERIE_ALLOWED_ORIGINS ?? '').split(',').map((o) => o.trim().toLowerCase()).filter(Boolean)),
+        host: env.REVERIE_HTTP_HOST?.trim() || '127.0.0.1',
+        port,
+        graphPollMs: seconds('REVERIE_GRAPH_POLL_SECONDS', 5),
+        statePollMs: seconds('REVERIE_STATE_SECONDS', 5),
+        eventPollMs: seconds('REVERIE_EVENT_POLL_SECONDS', 1)
+    };
+}
+/** Constant-time bearer check; a wrong length is a plain mismatch, never a timing tell. */
+export function isAuthorized(header, token) {
+    if (!header || !token) {
+        return false;
+    }
+    const match = /^Bearer\s+(\S+)$/i.exec(header.trim());
+    if (!match) {
+        return false;
+    }
+    const given = Buffer.from(match[1], 'utf8');
+    const expected = Buffer.from(token, 'utf8');
+    return given.length === expected.length && timingSafeEqual(given, expected);
+}
+function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+        'Cache-Control': 'no-store'
+    });
+    res.end(payload);
+}
+class BodyTooLarge extends Error {
+}
+function readJsonBody(req) {
+    return new Promise((resolve, reject) => {
+        let chunks = [];
+        let size = 0;
+        let tooLarge = false;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (tooLarge) {
+                return;
+            }
+            if (size > MAX_BODY_BYTES) {
+                // Keep draining so the client receives the 413 instead of a connection reset.
+                tooLarge = true;
+                chunks = [];
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            if (tooLarge) {
+                reject(new BodyTooLarge('request body exceeds 1 MiB'));
+                return;
+            }
+            const text = Buffer.concat(chunks).toString('utf8');
+            if (!text.trim()) {
+                resolve(undefined);
+                return;
+            }
+            try {
+                resolve(JSON.parse(text));
+            }
+            catch (error) {
+                reject(new SyntaxError(`invalid JSON body: ${error instanceof Error ? error.message : error}`));
+            }
+        });
+        req.on('error', reject);
+        // A client abort can close the request without 'end' or 'error'; do not leave the handler pending.
+        req.on('close', () => {
+            if (!req.readableEnded) {
+                reject(new Error('request closed before the body was received'));
+            }
+        });
+    });
+}
+function errorMessage(error) {
+    return (error instanceof Error ? error.message : String(error)).slice(0, 200);
+}
+export async function startHttpServer(env = process.env) {
+    const settings = settingsFromEnv(env);
+    const configError = neo4jConfigError(env);
+    if (configError) {
+        throw new ConfigError(configError);
+    }
+    const config = neo4jConfigFromEnv(env);
+    const neo4j = config ? new Neo4jClient(config.uri, config.username, config.password, config.database) : null;
+    const embedder = config ? safeCreateEmbedder() : null;
+    const run = neo4j ? (cypher, params) => neo4j.executeQuery(cypher, params ?? {}) : null;
+    // The health probe is unauthenticated, so it is cached and coalesced: one Neo4j query in flight
+    // at a time, tracked until it really settles (a timed-out answer does not release it), and its
+    // result cached for HEALTH_CACHE_MS. Callers wait at most HEALTH_TIMEOUT_MS and get false meanwhile.
+    let healthCache = null;
+    let healthQuery = null;
+    function neo4jHealthy() {
+        if (!neo4j) {
+            return Promise.resolve(false);
+        }
+        if (healthCache && Date.now() - healthCache.at < HEALTH_CACHE_MS) {
+            return Promise.resolve(healthCache.ok);
+        }
+        if (!healthQuery) {
+            healthQuery = neo4j
+                .executeQuery('RETURN 1 AS ok')
+                .then(() => true, () => false)
+                .then((ok) => {
+                healthCache = { at: Date.now(), ok };
+                healthQuery = null;
+                return ok;
+            });
+        }
+        let timer;
+        const timeout = new Promise((resolve) => {
+            timer = setTimeout(() => resolve(false), HEALTH_TIMEOUT_MS);
+            timer.unref();
+        });
+        return Promise.race([healthQuery, timeout]).finally(() => clearTimeout(timer));
+    }
+    async function handleMcp(req, res) {
+        let body;
+        if (req.method === 'POST') {
+            try {
+                body = await readJsonBody(req);
+            }
+            catch (error) {
+                if (error instanceof BodyTooLarge) {
+                    sendJson(res, 413, { error: error.message });
+                }
+                else {
+                    sendJson(res, 400, { error: errorMessage(error) });
+                }
+                return;
+            }
+        }
+        // Stateless: a fresh protocol server and transport per request, sharing the Neo4j client and embedder.
+        const server = createMcpServer(neo4j, embedder);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        res.on('close', () => {
+            transport.close().catch(() => undefined);
+            server.close().catch(() => undefined);
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    }
+    function streamEvents(req, res, limit) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream; charset=utf-8',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+            'X-Accel-Buffering': 'no'
+        });
+        // Backpressure: when the client stops reading, stop producing. Activations wait in a bounded
+        // queue and the graph baseline only advances once its frame was handed to the socket, so
+        // nothing is silently lost; a connection that has not drained in BACKPRESSURE_GRACE_MS is dropped.
+        let blocked = false;
+        let blockedSince = 0;
+        const pending = [];
+        const write = (chunk) => {
+            if (blocked || res.writableEnded) {
+                return false;
+            }
+            if (!res.write(chunk)) {
+                blocked = true;
+                blockedSince = Date.now();
+                res.once('drain', () => {
+                    blocked = false;
+                    flushPending();
+                });
+            }
+            return true;
+        };
+        const send = (event, data) => write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+        const flushPending = () => {
+            while (pending.length > 0 && !blocked && !res.writableEnded) {
+                send('activation', pending.shift());
+            }
+        };
+        const queueActivations = (events) => {
+            pending.push(...events);
+            flushPending(); // deliver what the socket will take before any cap applies
+            if (pending.length > PENDING_ACTIVATIONS_MAX) {
+                // A client that has not read for this long loses the oldest queued activations; say so.
+                const dropped = pending.splice(0, pending.length - PENDING_ACTIVATIONS_MAX).length;
+                pending.unshift({ ts: Date.now() / 1000, kind: 'gap', dropped });
+            }
+        };
+        const file = eventsPath(env);
+        let cursor = START_CURSOR;
+        if (file) {
+            // One read gives both the recent history to replay and the cursor to continue from, so no
+            // event can fall between the two.
+            const initial = readSince(file, START_CURSOR);
+            cursor = initial.cursor;
+            queueActivations(initial.events.slice(-30));
+        }
+        let prev = null;
+        let polling = false;
+        const pollGraph = async () => {
+            if (polling || blocked || !run) {
+                return;
+            }
+            polling = true;
+            try {
+                const curr = await snapshot(run, limit);
+                // The first frame is the full snapshot, so the stream never depends on what the client
+                // fetched from /brain/graph moments earlier.
+                const diff = prev ? diffSnapshot(prev, curr) : snapshotAsDiff(curr);
+                if (isEmptyDiff(diff) || send('graph', { ...diff, stats: curr.stats })) {
+                    prev = curr;
+                }
+            }
+            catch (error) {
+                send('error', { message: errorMessage(error) });
+            }
+            finally {
+                polling = false;
+            }
+        };
+        const timers = [];
+        const stop = () => {
+            for (const timer of timers) {
+                clearInterval(timer);
+            }
+            if (!res.writableEnded) {
+                res.end();
+            }
+        };
+        req.on('close', stop);
+        res.on('error', stop);
+        pollGraph().then(() => send('state', state(undefined, undefined, env)));
+        timers.push(setInterval(() => {
+            if (!file) {
+                return;
+            }
+            const next = readSince(file, cursor);
+            cursor = next.cursor;
+            queueActivations(next.events);
+        }, settings.eventPollMs), setInterval(() => void pollGraph(), settings.graphPollMs), setInterval(() => send('state', state(undefined, undefined, env)), settings.statePollMs), setInterval(() => {
+            if (blocked && Date.now() - blockedSince > BACKPRESSURE_GRACE_MS) {
+                stop();
+                res.destroy();
+                return;
+            }
+            write(': ping\n\n');
+        }, PING_SECONDS * 1000));
+    }
+    async function route(req, res) {
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        const path = url.pathname.replace(/\/+$/, '') || '/';
+        const method = req.method ?? 'GET';
+        // Browser callers: an Origin is accepted only when allowlisted, and then gets real CORS
+        // answers (preflight before auth, since browsers send preflights without credentials).
+        const origin = req.headers.origin?.trim();
+        const originAllowed = origin !== undefined && settings.allowedOrigins.has(origin.toLowerCase());
+        if (origin !== undefined && !originAllowed) {
+            sendJson(res, 403, { error: 'Origin not allowed' });
+            return;
+        }
+        if (originAllowed) {
+            res.setHeader('Access-Control-Allow-Origin', origin);
+            res.setHeader('Vary', 'Origin');
+            if (method === 'OPTIONS') {
+                res.writeHead(204, {
+                    'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+                    'Access-Control-Allow-Headers': 'Authorization, Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version',
+                    'Access-Control-Max-Age': '600'
+                });
+                res.end();
+                return;
+            }
+        }
+        if ((path === '/health' || path === '/brain/health') && method === 'GET') {
+            sendJson(res, 200, { ok: true, neo4j: await neo4jHealthy(), ts: Date.now() / 1000 });
+            return;
+        }
+        if (!isAuthorized(req.headers.authorization, settings.token)) {
+            sendJson(res, 401, { error: 'Unauthorized' });
+            return;
+        }
+        if (path === '/mcp') {
+            if (method !== 'POST' && method !== 'GET' && method !== 'DELETE') {
+                sendJson(res, 405, { error: 'Method not allowed' });
+                return;
+            }
+            await handleMcp(req, res);
+            return;
+        }
+        if (path.startsWith('/brain/')) {
+            if (method !== 'GET') {
+                sendJson(res, 405, { error: 'Method not allowed' });
+                return;
+            }
+            const limit = parseLimit(url.searchParams.get('limit'));
+            if (limit === null) {
+                sendJson(res, 400, { error: 'limit must be an integer between 1 and 1500' });
+                return;
+            }
+            if (!run) {
+                sendJson(res, 503, { error: 'Neo4j not configured' });
+                return;
+            }
+            if (path === '/brain/graph') {
+                try {
+                    const snap = await snapshot(run, limit);
+                    sendJson(res, 200, { ...snap, state: state(undefined, undefined, env) });
+                }
+                catch (error) {
+                    sendJson(res, 502, { error: errorMessage(error) });
+                }
+                return;
+            }
+            if (path === '/brain/state') {
+                sendJson(res, 200, state(undefined, undefined, env));
+                return;
+            }
+            if (path === '/brain/events') {
+                streamEvents(req, res, limit);
+                return;
+            }
+        }
+        sendJson(res, 404, { error: 'Not found' });
+    }
+    const server = http.createServer((req, res) => {
+        const started = Date.now();
+        res.on('finish', () => console.error(`${req.method} ${req.url} ${res.statusCode} ${Date.now() - started}ms`));
+        route(req, res).catch((error) => {
+            console.error('Request failed:', error);
+            if (!res.headersSent) {
+                sendJson(res, 500, { jsonrpc: '2.0', error: { code: -32603, message: errorMessage(error) }, id: null });
+            }
+            else if (!res.writableEnded) {
+                res.end();
+            }
+        });
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(settings.port, settings.host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    const address = server.address();
+    const port = typeof address === 'object' && address ? address.port : settings.port;
+    console.error(`Reverie HTTP server listening on http://${settings.host}:${port}`);
+    let closing = null;
+    const close = () => {
+        if (!closing) {
+            closing = new Promise((resolve) => {
+                server.close(() => resolve());
+                server.closeAllConnections?.();
+            }).then(() => neo4j?.close());
+        }
+        return closing;
+    };
+    return { server, host: settings.host, port, close };
+}
+/** Wire SIGINT/SIGTERM to a bounded shutdown; used by the `reverie serve` entry point. */
+export function installShutdown(handle) {
+    const shutdown = () => {
+        console.error('Shutting down Reverie HTTP server…');
+        const force = setTimeout(() => {
+            console.error('Forced shutdown');
+            process.exit(1);
+        }, SHUTDOWN_GRACE_MS);
+        force.unref();
+        handle
+            .close()
+            .then(() => process.exit(0))
+            .catch((error) => {
+            console.error('Error during shutdown:', error);
+            process.exit(1);
+        });
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+}

package/build/index.js

@@ -1,65 +1,63 @@
 #!/usr/bin/env node
+import { neo4jConfigError, neo4jConfigFromEnv } from './config.js';
 import { Neo4jServer } from './server.js';
 // Debug environment for Smithery
 if (process.env.DEBUG_SMITHERY) {
     console.error('Environment variables:', {
         NEO4J_URI: process.env.NEO4J_URI,
         NEO4J_USERNAME: process.env.NEO4J_USERNAME,
-        NEO4J_PASSWORD: process.env.NEO4J_PASSWORD,
+        NEO4J_PASSWORD: process.env.NEO4J_PASSWORD ? '(set)' : undefined,
         NEO4J_DATABASE: process.env.NEO4J_DATABASE
     });
 }
-// Check if we have database configuration (ignore empty strings)
-const uri = process.env.NEO4J_URI?.trim();
-const username = process.env.NEO4J_USERNAME?.trim();
-const password = process.env.NEO4J_PASSWORD?.trim();
-const hasDbConfig = uri && username && password;
-// Only validate environment variables if at least one non-empty value is provided
-if ((uri || username || password) && !hasDbConfig) {
-    // If any Neo4j env var is set, all required ones must be set
-    if (!password) {
-        console.error('Error: NEO4J_PASSWORD environment variable is required');
-        process.exit(1);
-    }
-    if (!uri) {
-        console.error('Error: NEO4J_URI environment variable is required');
-        process.exit(1);
-    }
-    if (!username) {
-        console.error('Error: NEO4J_USERNAME environment variable is required');
-        process.exit(1);
-    }
-}
-const config = hasDbConfig ? {
-    uri: uri,
-    username: username,
-    password: password,
-    database: process.env.NEO4J_DATABASE?.trim() || undefined, // Optional for Neo4j Community Edition
-} : undefined;
-// サーバーの起動
-const server = new Neo4jServer(config);
-server.run().catch((error) => {
-    console.error('Failed to start Neo4j MCP server:', error);
+const configError = neo4jConfigError();
+if (configError) {
+    console.error(configError);
     process.exit(1);
-});
-// 終了時のクリーンアップ
-process.on('SIGINT', async () => {
+}
+const config = neo4jConfigFromEnv();
+if (process.argv[2] === 'serve') {
+    const { ConfigError, installShutdown, startHttpServer } = await import('./http-server.js');
     try {
-        await server.close();
-        process.exit(0);
+        installShutdown(await startHttpServer());
     }
     catch (error) {
-        console.error('Error during shutdown:', error);
+        console.error(error instanceof ConfigError ? `Error: ${error.message}` : `Failed to start Reverie HTTP server: ${error instanceof Error ? error.message : error}`);
         process.exit(1);
     }
-});
-process.on('SIGTERM', async () => {
-    try {
-        await server.close();
-        process.exit(0);
-    }
-    catch (error) {
-        console.error('Error during shutdown:', error);
+}
+else if (process.argv.length > 2) {
+    console.error('Usage: reverie [serve]');
+    process.exit(2);
+}
+else {
+    startStdio();
+}
+function startStdio() {
+    const server = new Neo4jServer(config);
+    server.run().catch((error) => {
+        console.error('Failed to start Neo4j MCP server:', error);
         process.exit(1);
-    }
-});
+    });
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown) {
+            return;
+        }
+        shuttingDown = true;
+        process.off('SIGINT', shutdown);
+        process.off('SIGTERM', shutdown);
+        const force = setTimeout(() => process.exit(1), 10_000);
+        force.unref();
+        try {
+            await server.close();
+            process.exit(0);
+        }
+        catch (error) {
+            console.error('Error during shutdown:', error);
+            process.exit(1);
+        }
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}

package/build/server.js

@@ -6,7 +6,7 @@ import { handleToolCall } from './handlers/index.js';
 import { Neo4jClient } from './neo4j-client.js';
 import { tools } from './tools/definitions.js';
 /** A misconfigured provider (missing key, http endpoint…) must not stop the server; search degrades to keyword. */
-function safeCreateEmbedder() {
+export function safeCreateEmbedder() {
     try {
         return createEmbedder();
     }
@@ -15,47 +15,35 @@ function safeCreateEmbedder() {
         return null;
     }
 }
+export const VERSION = '0.5.0';
+/** The MCP protocol server with Reverie's tools, bound to a (possibly absent) Neo4j client and embedder. */
+export function createMcpServer(neo4j, embedder) {
+    const server = new Server({ name: 'reverie', version: VERSION }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (!neo4j) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: 'Neo4j connection not configured. Please set NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD environment variables.',
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const { name, arguments: args } = request.params;
+        return handleToolCall(name, args, neo4j, embedder);
+    });
+    server.onerror = (error) => console.error('[MCP Error]', error);
+    return server;
+}
 export class Neo4jServer {
     server;
     neo4j;
-    embedder;
     constructor(config) {
-        this.server = new Server({
-            name: 'reverie',
-            version: '0.4.0',
-        }, {
-            capabilities: {
-                tools: {},
-            },
-        });
         this.neo4j = config ? new Neo4jClient(config.uri, config.username, config.password, config.database) : null;
-        this.embedder = config ? safeCreateEmbedder() : null;
-        this.setupToolHandlers();
-        this.server.onerror = (error) => console.error('[MCP Error]', error);
-        process.on('SIGINT', async () => {
-            await this.close();
-            process.exit(0);
-        });
-    }
-    setupToolHandlers() {
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-            tools,
-        }));
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
-            if (!this.neo4j) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: 'Neo4j connection not configured. Please set NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD environment variables.',
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-            const { name, arguments: args } = request.params;
-            return handleToolCall(name, args, this.neo4j, this.embedder);
-        });
+        this.server = createMcpServer(this.neo4j, config ? safeCreateEmbedder() : null);
     }
     async run() {
         const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowall-ai/reverie",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Reverie — graph memory that dreams. Graph-based memory system for AI agents. Store people, places, organizations as nodes. Build semantic relationships (KNOWS, WORKS_AT, CREATED). Hybrid keyword + semantic search finds partial matches and close variants. Filter by date, traverse relationships, maintain temporal context. Simple tools, LLM handles complexity. 12 tools for complete memory management.",
   "type": "module",
   "module": "./src/index.ts",
@@ -16,6 +16,7 @@
     "prepare": "npm run build",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",
+    "start:http": "node build/index.js serve",
     "test": "node --test tests/unit.test.mjs tests/startup.test.mjs tests/integration.test.mjs",
     "test:unit": "node --test tests/unit.test.mjs tests/startup.test.mjs",
     "test:integration": "node --test tests/integration.test.mjs",
@@ -23,10 +24,11 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^3.8.1",
-    "@modelcontextprotocol/sdk": "0.6.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "dotenv": "^17.2.0",
     "neo4j-driver": "^5.27.0",
-    "uuid": "^11.0.4"
+    "uuid": "^11.0.4",
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@types/node": "^20.11.24",