Merge branch 'main' into add-data-modeling-mcp-server

Author: a-s-g93

servers/mcp-neo4j-cypher/CHANGELOG.md

@@ -5,6 +5,8 @@
 ### Changed
 
 ### Added
+* Namespace option via CLI or env variables. This allows many Cypher MCP servers to be used at once.
+* Allow transport to be specified via env variables
 
 
 ## v0.2.2 

servers/mcp-neo4j-cypher/README.md

@@ -31,19 +31,25 @@ The server offers these core tools:
    - No input required
    - Returns: JSON serialized list of node labels with two dictionaries: one for attributes and one for relationships
 
+### 🏷️ Namespacing
+
+The server supports namespacing to allow multiple Neo4j MCP servers to be used simultaneously. When a namespace is provided, all tool names are prefixed with the namespace followed by a hyphen (e.g., `mydb-read-neo4j-cypher`).
+
+This is useful when you need to connect to multiple Neo4j databases or instances from the same session.
+
 ## 🔧 Usage with Claude Desktop
 
 ### 💾 Released Package
 
 Can be found on PyPi https://pypi.org/project/mcp-neo4j-cypher/
 
-Add the server to your `claude_desktop_config.json` with the database connection configuration through environment variables. You may also specify the transport method with cli arguments.
+Add the server to your `claude_desktop_config.json` with the database connection configuration through environment variables. You may also specify the transport method and namespace with cli arguments or environment variables.
 
 ```json
 "mcpServers": {
   "neo4j-aura": {
     "command": "uvx",
-    "args": [ "[email protected].2", "--transport", "stdio"  ],
+    "args": [ "[email protected].3", "--transport", "stdio"  ],
     "env": {
       "NEO4J_URI": "bolt://localhost:7687",
       "NEO4J_USERNAME": "neo4j",
@@ -54,14 +60,50 @@ Add the server to your `claude_desktop_config.json` with the database connection
 }
 ```
 
+#### Multiple Database Example
+
+Here's an example of connecting to multiple Neo4j databases using namespaces:
+
+```json
+{
+  "mcpServers": {
+    "movies-neo4j": {
+      "command": "uvx",
+      "args": [ "[email protected]", "--namespace", "movies" ],
+      "env": {
+        "NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
+        "NEO4J_USERNAME": "recommendations",
+        "NEO4J_PASSWORD": "recommendations",
+        "NEO4J_DATABASE": "recommendations"
+      }
+    },
+    "local-neo4j": {
+      "command": "uvx",
+      "args": [ "[email protected]" ],
+      "env": {
+        "NEO4J_URI": "bolt://localhost:7687",
+        "NEO4J_USERNAME": "neo4j",
+        "NEO4J_PASSWORD": "password",
+        "NEO4J_DATABASE": "neo4j",
+        "NEO4J_NAMESPACE": "local"
+      }
+    }
+  }
+}
+```
+
+In this setup:
+- The movies database tools will be prefixed with `movies-` (e.g., `movies-read-neo4j-cypher`)
+- The local database tools will be prefixed with `local-` (e.g., `local-get-neo4j-schema`)
+
 Here is an example connection for the movie database with Movie, Person (Actor, Director), Genre, User and ratings:
 
 ```json
 {
   "mcpServers": {
     "movies-neo4j": {
       "command": "uvx",
-      "args": [ "[email protected].2" ],
+      "args": [ "[email protected].3" ],
       "env": {
         "NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
         "NEO4J_USERNAME": "recommendations",
@@ -83,13 +125,15 @@ Syntax with `--db-url`, `--username` and `--password` command line arguments is
   "neo4j": {
     "command": "uvx",
     "args": [
-      "[email protected].2",
+      "[email protected].3",
       "--db-url",
       "bolt://localhost",
       "--username",
       "neo4j",
       "--password",
-      "<your-password>"
+      "<your-password>",
+      "--namespace",
+      "mydb"
     ]
   }
 }
@@ -102,7 +146,7 @@ Here is an example connection for the movie database with Movie, Person (Actor,
   "mcpServers": {
     "movies-neo4j": {
       "command": "uvx",
-      "args": ["[email protected].2", 
+      "args": ["[email protected].3", 
       "--db-url", "neo4j+s://demo.neo4jlabs.com", 
       "--user", "recommendations", 
       "--password", "recommendations",
@@ -125,6 +169,7 @@ Here is an example connection for the movie database with Movie, Person (Actor,
       "-e", "NEO4J_URI=bolt://host.docker.internal:7687",
       "-e", "NEO4J_USERNAME=neo4j",
       "-e", "NEO4J_PASSWORD=<your-password>",
+      "-e", "NEO4J_NAMESPACE=mydb",
       "mcp/neo4j-cypher:latest"
     ]
   }
@@ -177,7 +222,7 @@ uv pip install -e ".[dev]"
     "command": "uv",
     "args": [
       "--directory", "parent_of_servers_repo/servers/mcp-neo4j-cypher/src",
-      "run", "mcp-neo4j-cypher", "--transport", "stdio"],
+      "run", "mcp-neo4j-cypher", "--transport", "stdio", "--namespace", "dev"],
     "env": {
       "NEO4J_URI": "bolt://localhost",
       "NEO4J_USERNAME": "neo4j",
@@ -200,6 +245,7 @@ docker build -t mcp/neo4j-cypher:latest .
 docker run -e NEO4J_URI="bolt://host.docker.internal:7687" \
           -e NEO4J_USERNAME="neo4j" \
           -e NEO4J_PASSWORD="your-password" \
+          -e NEO4J_NAMESPACE="mydb" \
           mcp/neo4j-cypher:latest
 ```
 

servers/mcp-neo4j-cypher/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-neo4j-cypher"
-version = "0.2.2"
+version = "0.2.3"
 description = "A simple Neo4j MCP server"
 readme = "README.md"
 requires-python = ">=3.10"

servers/mcp-neo4j-cypher/src/mcp_neo4j_cypher/__init__.py

@@ -12,7 +12,8 @@ def main():
     parser.add_argument("--username", default=None, help="Neo4j username")
     parser.add_argument("--password", default=None, help="Neo4j password")
     parser.add_argument("--database", default=None, help="Neo4j database name")
-    parser.add_argument("--transport", default="stdio", help="Transport type")
+    parser.add_argument("--transport", default=None, help="Transport type")
+    parser.add_argument("--namespace", default=None, help="Tool namespace")
 
     args = parser.parse_args()
     asyncio.run(
@@ -21,7 +22,8 @@ def main():
             args.username or os.getenv("NEO4J_USERNAME", "neo4j"),
             args.password or os.getenv("NEO4J_PASSWORD", "password"),
             args.database or os.getenv("NEO4J_DATABASE", "neo4j"),
-            args.transport,
+            args.transport or os.getenv("NEO4J_TRANSPORT", "stdio"),
+            args.namespace or os.getenv("NEO4J_NAMESPACE", ""),
         )
     )
 

servers/mcp-neo4j-cypher/src/mcp_neo4j_cypher/server.py

@@ -19,6 +19,14 @@
 
 logger = logging.getLogger("mcp_neo4j_cypher")
 
+def _format_namespace(namespace: str) -> str:
+    if namespace:
+        if namespace.endswith("-"):
+            return namespace
+        else:
+            return namespace + "-"
+    else:
+        return ""
 
 async def _read(tx: AsyncTransaction, query: str, params: dict[str, Any]) -> str:
     raw_results = await tx.run(query, params)
@@ -41,7 +49,7 @@ def _is_write_query(query: str) -> bool:
     )
 
 
-def create_mcp_server(neo4j_driver: AsyncDriver, database: str = "neo4j") -> FastMCP:
+def create_mcp_server(neo4j_driver: AsyncDriver, database: str = "neo4j", namespace: str = "") -> FastMCP:
     mcp: FastMCP = FastMCP("mcp-neo4j-cypher", dependencies=["neo4j", "pydantic"])
 
     async def get_neo4j_schema() -> list[types.TextContent]:
@@ -126,9 +134,11 @@ async def write_neo4j_cypher(
                 types.TextContent(type="text", text=f"Error: {e}\n{query}\n{params}")
             ]
 
-    mcp.add_tool(get_neo4j_schema)
-    mcp.add_tool(read_neo4j_cypher)
-    mcp.add_tool(write_neo4j_cypher)
+    namespace_prefix = _format_namespace(namespace)
+    
+    mcp.add_tool(get_neo4j_schema, name=namespace_prefix+"get_neo4j_schema")
+    mcp.add_tool(read_neo4j_cypher, name=namespace_prefix+"read_neo4j_cypher")
+    mcp.add_tool(write_neo4j_cypher, name=namespace_prefix+"write_neo4j_cypher")
 
     return mcp
 
@@ -139,6 +149,7 @@ async def main(
     password: str,
     database: str,
     transport: Literal["stdio", "sse"] = "stdio",
+    namespace: str = "",
 ) -> None:
     logger.info("Starting MCP neo4j Server")
 
@@ -150,7 +161,7 @@ async def main(
         ),
     )
 
-    mcp = create_mcp_server(neo4j_driver, database)
+    mcp = create_mcp_server(neo4j_driver, database, namespace)
 
     match transport:
         case "stdio":