@knowall-ai/reverie 0.4.0

package/build/hygiene.js

@@ -0,0 +1,43 @@
+import { EMBEDDING_FIELDS } from './embeddings.js';
+/** Above this many real properties a node is "bloated": facts are being piled on instead of modelled. */
+export const DEFAULT_MAX_PROPERTIES = 30;
+export const MAX_PROPERTIES_CAP = 500;
+const HOUSEKEEPING = new Set([...EMBEDDING_FIELDS, 'created_at', 'updated_at', 'status', 'archived_at']);
+const DATE_SUFFIX_RE = /(_|-)\d{4}(_|-)\d{2}(_|-)\d{2}$/;
+const LONG_TEXT = 120;
+/** REVERIE_MAX_PROPERTIES must be a whole number in 1..MAX_PROPERTIES_CAP; anything else falls back to the default. */
+export function maxProperties(env = process.env) {
+    const raw = (env.REVERIE_MAX_PROPERTIES ?? '').trim();
+    if (!/^\d+$/.test(raw)) {
+        return DEFAULT_MAX_PROPERTIES;
+    }
+    const value = Number(raw);
+    return value >= 1 && value <= MAX_PROPERTIES_CAP ? value : DEFAULT_MAX_PROPERTIES;
+}
+/** User-visible properties only: no `_id`-style metadata, timestamps, status or embedding fields. */
+export function contentKeys(props) {
+    return Object.keys(props).filter((key) => !key.startsWith('_') && !HOUSEKEEPING.has(key));
+}
+/** Keys that look like facts or episodes rather than attributes: dated names, or long prose values. */
+export function factLikeKeys(props) {
+    return contentKeys(props).filter((key) => {
+        const value = props[key];
+        return DATE_SUFFIX_RE.test(key) || (typeof value === 'string' && value.length > LONG_TEXT);
+    });
+}
+export const DEFAULT_LAZY_EMBED_BATCH = 100;
+export const MAX_LAZY_EMBED_BATCH = 1000;
+/** REVERIE_LAZY_EMBED_BATCH: stale candidates embedded per search; whole number 1..1000, else the default. */
+export function lazyEmbedBatch(env = process.env) {
+    const raw = (env.REVERIE_LAZY_EMBED_BATCH ?? '').trim();
+    if (!/^\d+$/.test(raw)) {
+        return DEFAULT_LAZY_EMBED_BATCH;
+    }
+    const value = Number(raw);
+    return value >= 1 && value <= MAX_LAZY_EMBED_BATCH ? value : DEFAULT_LAZY_EMBED_BATCH;
+}
+export function bloatHint(name, count, limit) {
+    return `"${name}" now has ${count} properties (limit ${limit}). The graph maps entities and relationships; ` +
+        'keep only durable attributes here. Fold dated facts and episodes into a short attribute, a relationship, ' +
+        'or your notes. See get_guidance("best-practices").';
+}

package/build/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+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_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);
+    process.exit(1);
+});
+// 終了時のクリーンアップ
+process.on('SIGINT', async () => {
+    try {
+        await server.close();
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Error during shutdown:', error);
+        process.exit(1);
+    }
+});
+process.on('SIGTERM', async () => {
+    try {
+        await server.close();
+        process.exit(0);
+    }
+    catch (error) {
+        console.error('Error during shutdown:', error);
+        process.exit(1);
+    }
+});

package/build/neo4j-client.js

@@ -0,0 +1,182 @@
+import { cypherIdentifier } from './types.js';
+import neo4j, { Integer, Node, Relationship } from 'neo4j-driver';
+const CLOSE_TIMEOUT_MS = 5_000;
+/** session.close() awaits connection release with no deadline; a stuck release must not hang a tool call. */
+async function closeBounded(session) {
+    let timer;
+    const deadline = new Promise((resolve) => { timer = setTimeout(resolve, CLOSE_TIMEOUT_MS); });
+    try {
+        await Promise.race([session.close().catch(() => undefined), deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class Neo4jClient {
+    driver;
+    database;
+    constructor(uri, username, password, database) {
+        this.driver = neo4j.driver(uri, neo4j.auth.basic(username, password));
+        this.database = database;
+    }
+    convertNestedIntegers(value) {
+        if (value instanceof Integer) {
+            return value.toNumber();
+        }
+        if (value instanceof Node) {
+            return {
+                ...this.convertNestedIntegers(value.properties),
+                _id: value.identity.toNumber(),
+                _labels: value.labels,
+            };
+        }
+        if (value instanceof Relationship) {
+            return {
+                ...this.convertNestedIntegers(value.properties),
+                _id: value.identity.toNumber(),
+                _type: value.type,
+                _start: value.start.toNumber(),
+                _end: value.end.toNumber(),
+            };
+        }
+        if (neo4j.isPath(value)) {
+            return {
+                start: this.convertNestedIntegers(value.start),
+                end: this.convertNestedIntegers(value.end),
+                segments: value.segments.map((segment) => ({
+                    start: this.convertNestedIntegers(segment.start),
+                    relationship: this.convertNestedIntegers(segment.relationship),
+                    end: this.convertNestedIntegers(segment.end),
+                })),
+            };
+        }
+        if (neo4j.isPoint(value)) {
+            return { srid: this.convertNestedIntegers(value.srid), x: value.x, y: value.y, z: value.z };
+        }
+        if (neo4j.isDate(value) || neo4j.isDateTime(value) || neo4j.isLocalDateTime(value) ||
+            neo4j.isTime(value) || neo4j.isLocalTime(value) || neo4j.isDuration(value)) {
+            return value.toString();
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) => this.convertNestedIntegers(item));
+        }
+        if (value && typeof value === 'object' && value.constructor === Object) {
+            const converted = {};
+            for (const [key, val] of Object.entries(value)) {
+                converted[key] = this.convertNestedIntegers(val);
+            }
+            return converted;
+        }
+        return value;
+    }
+    recordToObject(record) {
+        const obj = {};
+        for (const key of record.keys) {
+            obj[key] = this.convertNestedIntegers(record.get(key));
+        }
+        return obj;
+    }
+    async executeQuery(query, params = {}) {
+        const session = this.driver.session({
+            database: this.database
+        });
+        try {
+            const result = await session.run(query, params);
+            return result.records.map((record) => this.recordToObject(record));
+        }
+        finally {
+            await closeBounded(session);
+        }
+    }
+    /**
+     * Caller-supplied Cypher: runs in a READ transaction (the server rejects writes), stops
+     * consuming after `limit` records instead of materialising the whole result, and is
+     * bounded by a transaction timeout.
+     */
+    async executeReadQuery(query, params, options) {
+        if (!Number.isSafeInteger(options.limit) || options.limit < 0) {
+            throw new Error('Query limit must be a non-negative integer');
+        }
+        if (options.limit === 0) {
+            return [];
+        }
+        const session = this.driver.session({
+            database: this.database,
+            defaultAccessMode: neo4j.session.READ
+        });
+        try {
+            return await session.executeRead(async (tx) => {
+                const rows = [];
+                for await (const record of tx.run(query, params)) {
+                    rows.push(this.recordToObject(record));
+                    if (rows.length >= options.limit) {
+                        break;
+                    }
+                }
+                return rows;
+            }, { timeout: options.timeoutMs });
+        }
+        finally {
+            await closeBounded(session);
+        }
+    }
+    async getNodes(label) {
+        return this.executeQuery(`MATCH (n:${cypherIdentifier(label)}) RETURN n as memory`);
+    }
+    async createNode(label, properties) {
+        const result = await this.executeQuery(`CREATE (n:${cypherIdentifier(label)} $props) RETURN n as memory`, { props: properties });
+        return result[0];
+    }
+    async createRelationship(fromNodeId, toNodeId, relationType, properties = {}) {
+        const result = await this.executeQuery(`MATCH (a), (b)
+       WHERE id(a) = $fromId AND id(b) = $toId
+       CREATE (a)-[r:${cypherIdentifier(relationType)} $props]->(b)
+       RETURN r as relationship`, {
+            fromId: neo4j.int(fromNodeId),
+            toId: neo4j.int(toNodeId),
+            props: properties,
+        });
+        return result[0];
+    }
+    async updateNode(nodeId, properties) {
+        const result = await this.executeQuery(`MATCH (n) WHERE id(n) = $nodeId
+       SET n += $props
+       RETURN n as memory`, {
+            nodeId: neo4j.int(nodeId),
+            props: properties,
+        });
+        return result[0];
+    }
+    async updateRelationship(fromNodeId, toNodeId, relationType, properties) {
+        const result = await this.executeQuery(`MATCH (a)-[r:${cypherIdentifier(relationType)}]->(b)
+       WHERE id(a) = $fromId AND id(b) = $toId
+       SET r += $props
+       RETURN r as relationship`, {
+            fromId: neo4j.int(fromNodeId),
+            toId: neo4j.int(toNodeId),
+            props: properties,
+        });
+        return result[0];
+    }
+    async deleteNode(nodeId) {
+        const result = await this.executeQuery(`MATCH (n) WHERE id(n) = $nodeId
+       DETACH DELETE n
+       RETURN count(n) as deletedCount`, {
+            nodeId: neo4j.int(nodeId),
+        });
+        return result[0];
+    }
+    async deleteRelationship(fromNodeId, toNodeId, relationType) {
+        const result = await this.executeQuery(`MATCH (a)-[r:${cypherIdentifier(relationType)}]->(b)
+       WHERE id(a) = $fromId AND id(b) = $toId
+       DELETE r
+       RETURN count(r) as deletedCount`, {
+            fromId: neo4j.int(fromNodeId),
+            toId: neo4j.int(toNodeId),
+        });
+        return result[0];
+    }
+    async close() {
+        await this.driver.close();
+    }
+}

package/build/search.js

@@ -0,0 +1,92 @@
+import { cosine } from './embeddings.js';
+import { contentKeys } from './hygiene.js';
+/** Case-insensitive equality on name, aliases or email: the lookup to run before creating a memory. */
+export function exactMatches(query, props) {
+    const wanted = query.trim().toLowerCase();
+    if (!wanted)
+        return false;
+    const values = [props.name, props.email, ...(Array.isArray(props.aliases) ? props.aliases : [])];
+    return values.some((v) => typeof v === 'string' && v.trim().toLowerCase() === wanted);
+}
+export function keywordMatches(query, props) {
+    const trimmedQuery = query.trim().toLowerCase();
+    if (!trimmedQuery) {
+        return true;
+    }
+    const words = trimmedQuery.split(/\s+/);
+    // Only user content is searchable: timestamps, status and embedding fields never match.
+    for (const key of contentKeys(props)) {
+        const value = props[key];
+        if (value === null || value === undefined) {
+            continue;
+        }
+        const haystack = Array.isArray(value)
+            ? value.map((item) => item?.toString() || '').join(' ').toLowerCase()
+            : value.toString().toLowerCase();
+        if (words.some((word) => haystack.includes(word))) {
+            return true;
+        }
+    }
+    return false;
+}
+export function rank(candidates, opts) {
+    const trimmedQuery = opts.query.trim();
+    if (!trimmedQuery) {
+        return [...candidates]
+            .map((candidate) => ({ id: candidate.id, score: 0, match: 'keyword' }))
+            .sort(compareRankedBy(candidates));
+    }
+    const results = [];
+    const seen = new Set();
+    if (opts.mode === 'exact') {
+        for (const candidate of candidates) {
+            if (exactMatches(trimmedQuery, candidate.props)) {
+                results.push({ id: candidate.id, score: 1, match: 'exact' });
+            }
+        }
+        return results.sort(compareRankedBy(candidates));
+    }
+    if (opts.mode === 'hybrid' || opts.mode === 'keyword') {
+        for (const candidate of candidates) {
+            if (keywordMatches(trimmedQuery, candidate.props)) {
+                results.push({ id: candidate.id, score: 1, match: 'keyword' });
+                seen.add(candidate.id);
+            }
+        }
+    }
+    if ((opts.mode === 'hybrid' || opts.mode === 'semantic') && opts.queryEmbedding && opts.modelId) {
+        for (const candidate of candidates) {
+            if (seen.has(candidate.id)) {
+                continue;
+            }
+            if (candidate.props.embedding_model !== opts.modelId) {
+                continue;
+            }
+            const score = Math.max(similarity(opts.queryEmbedding, candidate.props.embedding), similarity(opts.queryEmbedding, candidate.props.name_embedding));
+            if (score >= opts.threshold) {
+                results.push({ id: candidate.id, score, match: 'semantic' });
+            }
+        }
+    }
+    return results.sort(compareRankedBy(candidates));
+}
+function similarity(query, vector) {
+    return Array.isArray(vector) ? cosine(query, vector.map((item) => Number(item))) : 0;
+}
+function compareRankedBy(candidates) {
+    const createdAt = new Map(candidates.map((candidate) => [
+        candidate.id,
+        typeof candidate.props.created_at === 'string' ? candidate.props.created_at : ''
+    ]));
+    return (left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        const leftCreatedAt = createdAt.get(left.id) ?? '';
+        const rightCreatedAt = createdAt.get(right.id) ?? '';
+        if (rightCreatedAt !== leftCreatedAt) {
+            return rightCreatedAt.localeCompare(leftCreatedAt);
+        }
+        return left.id - right.id;
+    };
+}

package/build/server.js

@@ -0,0 +1,71 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { createEmbedder } from './embeddings.js';
+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() {
+    try {
+        return createEmbedder();
+    }
+    catch (error) {
+        console.error('Embeddings disabled:', error instanceof Error ? error.message : error);
+        return null;
+    }
+}
+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);
+        });
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error('Neo4j MCP server running on stdio');
+    }
+    async close() {
+        if (this.neo4j) {
+            await this.neo4j.close();
+        }
+        await this.server.close();
+    }
+}