From 60778b465ea28db6054b93331ceae8c9e2098d35 Mon Sep 17 00:00:00 2001 From: Katie Mulliken Date: Sun, 27 Jul 2025 23:14:09 -0400 Subject: [PATCH 1/2] chore: update version and enhance README with npm usage instructions - Bump package version to 1.0.1 in package.json. - Add instructions for running the server from npm in README.md. - Include a shebang in src/index.ts for direct execution. - Introduce a new graph reorganization prompt in src/mcp/prompts.ts for improved graph management. --- README.md | 24 +++++++++++ package.json | 2 +- src/index.ts | 2 + src/mcp/prompts.ts | 105 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 132 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dd41cce..fa3acfd 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,30 @@ This server implements the [Model Context Protocol (MCP)](https://modelcontextpr - FalkorDB instance (running locally or remotely) - Claude Desktop app (for AI integration) +### Running from npm + +Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): + +```json +{ + "mcpServers": { + "falkordb": { + "command": "npx", + "args": [ + "-y", + "falkordb-mcpserver@latest" + ], + "env": { + "FALKORDB_HOST": "localhost", + "FALKORDB_PORT": "6379", + "FALKORDB_USERNAME": "", + "FALKORDB_PASSWORD": "" + } + } + } +} +``` + ### Installation 1. **Clone and install:** diff --git a/package.json b/package.json index d6dc66e..19809e3 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "falkordb-mcpserver", - "version": "1.0.0", + "version": "1.0.1", "description": "Model Context Protocol server for FalkorDB graph databases - enables AI assistants to query and manage graph data using natural language", "main": "dist/index.js", "type": "module", diff --git a/src/index.ts b/src/index.ts index 1f41aed..641936b 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,3 +1,5 @@ +#!/usr/bin/env node + import { falkorDBService } from './services/falkordb.service.js'; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; diff --git a/src/mcp/prompts.ts b/src/mcp/prompts.ts index 6dfb2da..fb50d26 100644 --- a/src/mcp/prompts.ts +++ b/src/mcp/prompts.ts @@ -128,8 +128,113 @@ Please proceed with querying the memory graph for information about "${query}".` ) } +function registerGraphReorganizationPrompt(server: McpServer): void { + server.registerPrompt( + "graph_reorganization", + { + title: "Graph Reorganization", + description: "Analyze and reorganize the graph structure for optimal performance and usability" + }, + async () => { + const reorganizationMessage = `# Graph Reorganization Task + +You are working with a FalkorDB graph database to optimize its structure for better performance and usability. + +**Your task is to:** + +1. **Analyze Current Structure**: Examine the graph to identify structural issues: + - Find nodes with excessive connections (hubs with >50 relationships) + - Identify disconnected components or islands + - Locate duplicate or near-duplicate nodes + - Find outdated or stale connections + - Analyze relationship distribution and patterns + +2. **Performance Optimization**: Based on the analysis, implement improvements: + - **Merge duplicate nodes**: Combine nodes with similar properties or content + - **Create strategic hubs**: Add intermediate nodes to reduce direct connections + - **Remove dead connections**: Delete relationships to non-existent or irrelevant nodes + - **Add semantic clustering**: Group related nodes under topic or category nodes + - **Optimize relationship types**: Ensure relationship labels are descriptive and indexed + +3. **Usability Enhancement**: Improve graph navigation and querying: + - **Add metadata nodes**: Create nodes that summarize clusters or topics + - **Establish clear hierarchies**: Organize nodes in logical parent-child relationships + - **Create shortcut relationships**: Add direct paths for frequently accessed connections + - **Implement time-based organization**: Group nodes by temporal relevance + +4. **Validation and Testing**: After reorganization: + - Verify all critical paths remain intact + - Test common query patterns for performance + - Ensure no data loss occurred during restructuring + - Document changes made for future reference + +**Optimization Strategies by Goal:** + +**Performance Focus:** +- Minimize query traversal depth +- Balance node degree distribution +- Create efficient index structures +- Reduce redundant relationships + +**Usability Focus:** +- Improve semantic organization +- Add descriptive metadata +- Create intuitive navigation paths +- Enhance discoverability + +**Balanced Approach:** +- Apply moderate optimizations from both areas +- Prioritize changes with highest impact/effort ratio + +**Analysis Queries to Run:** +\`\`\`cypher +// Find high-degree nodes +MATCH (n)-[r]-() +WITH n, count(r) as degree +WHERE degree > 20 +RETURN n, degree ORDER BY degree DESC LIMIT 10 + +// Find disconnected components +MATCH (n) +WHERE NOT (n)--() +RETURN count(n) as isolated_nodes + +// Identify potential duplicates +MATCH (n1), (n2) +WHERE id(n1) < id(n2) +AND n1.name = n2.name +AND n1.type = n2.type +RETURN n1, n2 + +// Find stale nodes (older than 30 days with no recent connections) +MATCH (n) +WHERE n.created_at < datetime() - duration({days: 30}) +AND NOT (n)-[:UPDATED_AT|ACCESSED_AT]-() +RETURN n LIMIT 20 +\`\`\` + +**Reorganization Operations:** +Implement the most impactful optimizations. Prioritize operations that provide the best balance of performance improvement and structural clarity. + +Begin with analyzing the current graph structure and proceed with the reorganization plan.` + + return { + messages: [ + { + role: "user", + content: { + type: "text", + text: reorganizationMessage + } + } + ] + } + } + ) +} export default function registerAllPrompts(server: McpServer): void { registerUserSetupPrompt(server); registerMemoryQueryPrompt(server); + registerGraphReorganizationPrompt(server); } \ No newline at end of file From 9a3b4c256df01b0bae57dcc6485dbbc9113004a8 Mon Sep 17 00:00:00 2001 From: Katie Mulliken Date: Sun, 27 Jul 2025 23:16:11 -0400 Subject: [PATCH 2/2] Update src/mcp/prompts.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Katie Mulliken --- src/mcp/prompts.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mcp/prompts.ts b/src/mcp/prompts.ts index fb50d26..7c3e363 100644 --- a/src/mcp/prompts.ts +++ b/src/mcp/prompts.ts @@ -189,8 +189,8 @@ You are working with a FalkorDB graph database to optimize its structure for bet **Analysis Queries to Run:** \`\`\`cypher // Find high-degree nodes -MATCH (n)-[r]-() -WITH n, count(r) as degree +MATCH (n) +WITH n, size((n)--()) as degree WHERE degree > 20 RETURN n, degree ORDER BY degree DESC LIMIT 10