aura-manager - add namespacing (#182)

* implemented tool namespacing support, updated docs and changelog, updated tests

* update utils, tests

test in claude desktop

---------

Co-authored-by: runfourestrun <[email protected]>
Co-authored-by: alex <[email protected]>

Author: rfrneo4j

servers/mcp-neo4j-cloud-aura-api/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Changed
 
 ### Added
+* Add namespacing support for multi-tenant deployments with `--namespace` CLI argument and `NEO4J_NAMESPACE` environment variable
 
 ## v0.4.2
 

servers/mcp-neo4j-cloud-aura-api/README.md

@@ -164,6 +164,57 @@ Alternatively, you can set environment variables:
 }
 ```
 
+### 🏷️ Namespacing for Multi-tenant Deployments
+
+The server supports namespacing to prefix tool names for multi-tenant deployments:
+
+```json
+"mcpServers": {
+  "neo4j-aura-app1": {
+    "command": "uvx",
+    "args": [
+      "[email protected]",
+      "--client-id", "<your-client-id>",
+      "--client-secret", "<your-client-secret>",
+      "--namespace", "app1"
+    ]
+  },
+  "neo4j-aura-app2": {
+    "command": "uvx", 
+    "args": [
+      "[email protected]",
+      "--client-id", "<your-client-id>",
+      "--client-secret", "<your-client-secret>",
+      "--namespace", "app2"
+    ]
+  }
+}
+```
+
+#### CLI Usage
+```bash
+# With namespace
+mcp-neo4j-aura-manager --client-id <id> --client-secret <secret> --namespace myapp
+
+# Tools become: myapp-list_instances, myapp-create_instance, etc.
+```
+
+#### Environment Variables
+```bash
+export NEO4J_AURA_CLIENT_ID=your_client_id
+export NEO4J_AURA_CLIENT_SECRET=your_client_secret  
+export NEO4J_NAMESPACE=myapp
+mcp-neo4j-aura-manager
+```
+
+#### Docker with Namespacing
+```bash
+docker run -e NEO4J_AURA_CLIENT_ID=<id> \
+           -e NEO4J_AURA_CLIENT_SECRET=<secret> \
+           -e NEO4J_NAMESPACE=myapp \
+           mcp-neo4j-aura-manager
+```
+
 ### 🌐 HTTP Transport Mode
 
 The server supports HTTP transport for web-based deployments and microservices:
@@ -185,6 +236,7 @@ export NEO4J_MCP_SERVER_PORT=8080
 export NEO4J_MCP_SERVER_PATH=/api/mcp/
 export NEO4J_MCP_SERVER_ALLOWED_HOSTS="localhost,127.0.0.1"
 export NEO4J_MCP_SERVER_ALLOW_ORIGINS="http://localhost:3000"
+export NEO4J_NAMESPACE=myapp
 mcp-neo4j-aura-manager
 ```
 
@@ -330,6 +382,7 @@ docker run --rm -p 8000:8000 \
 | `NEO4J_MCP_SERVER_PATH`            | `/mcp/`                                 | Path for accessing MCP server                      |
 | `NEO4J_MCP_SERVER_ALLOW_ORIGINS`   | _(empty - secure by default)_           | Comma-separated list of allowed CORS origins       |
 | `NEO4J_MCP_SERVER_ALLOWED_HOSTS`   | `localhost,127.0.0.1`                   | Comma-separated list of allowed hosts (DNS rebinding protection) |
+| `NEO4J_NAMESPACE`                  | _(empty - no prefix)_                   | Namespace prefix for tool names (e.g., `myapp-list_instances`) |
 
 ### 🌐 SSE Transport for Legacy Web Access
 

servers/mcp-neo4j-cloud-aura-api/src/mcp_neo4j_aura_manager/__init__.py

@@ -20,6 +20,7 @@ def main():
     parser.add_argument("--client-secret", help="Neo4j Aura API Client Secret", 
                         default=os.environ.get("NEO4J_AURA_CLIENT_SECRET"))
     parser.add_argument("--transport", default=None, help="Transport type")
+    parser.add_argument("--namespace", default=None, help="Tool namespace prefix")
     parser.add_argument("--server-host", default=None, help="Server host")
     parser.add_argument("--server-port", default=None, help="Server port")
     parser.add_argument("--server-path", default=None, help="Server path")
@@ -33,6 +34,7 @@ def main():
         default=None,
         help="Allowed hosts for DNS rebinding protection on remote servers(comma-separated list)",
     )
+  
 
     args = parser.parse_args()
 

servers/mcp-neo4j-cloud-aura-api/src/mcp_neo4j_aura_manager/server.py

@@ -8,17 +8,22 @@
 from starlette.middleware.trustedhost import TrustedHostMiddleware
 
 from .aura_manager import AuraManager
-from .utils import get_logger
+from .utils import get_logger, format_namespace
 
 logger = get_logger(__name__)
 
 
-def create_mcp_server(aura_manager: AuraManager) -> FastMCP:
+
+def create_mcp_server(aura_manager: AuraManager, namespace: str = "") -> FastMCP:
     """Create an MCP server instance for Aura management."""
 
+    namespace_prefix = format_namespace(namespace)
+    
     mcp: FastMCP = FastMCP("mcp-neo4j-aura-manager", dependencies=["requests", "pydantic", "starlette"])
 
-    @mcp.tool(annotations=ToolAnnotations(title="List Instances",
+    @mcp.tool(
+        name=namespace_prefix + "list_instances",
+        annotations=ToolAnnotations(title="List Instances",
                                           readOnlyHint=True,
                                           destructiveHint=False,
                                           idempotentHint=True,
@@ -30,19 +35,24 @@ async def list_instances() -> dict:
         result = await aura_manager.list_instances()
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Get Instance Details",
-                                          readOnlyHint=True,
-                                          destructiveHint=False,
-                                          idempotentHint=True,
-                                          openWorldHint=True
+    @mcp.tool(
+        name=namespace_prefix + "get_instance_details",
+        annotations=ToolAnnotations(
+            title="Get Instance Details",
+            readOnlyHint=True,
+            destructiveHint=False,
+            idempotentHint=True,
+            openWorldHint=True
         
     ))
     async def get_instance_details(instance_ids: List[str]) -> dict:
         """Get details for one or more Neo4j Aura instances by ID."""
         result = await aura_manager.get_instance_details(instance_ids)
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Get Instance by Name",
+    @mcp.tool(
+        name=namespace_prefix + "get_instance_by_name",
+        annotations=ToolAnnotations(title="Get Instance by Name",
                                           readOnlyHint=True,
                                           destructiveHint=False,
                                           idempotentHint=True,
@@ -54,7 +64,9 @@ async def get_instance_by_name(name: str) -> dict:
         result = await aura_manager.get_instance_by_name(name)
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Create Instance",
+    @mcp.tool(
+        name=namespace_prefix + "create_instance",
+        annotations=ToolAnnotations(title="Create Instance",
                                           readOnlyHint=False,
                                           destructiveHint=False,
                                           idempotentHint=True,
@@ -86,7 +98,9 @@ async def create_instance(
         )
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Update Instance Name",
+    @mcp.tool(
+        name=namespace_prefix + "update_instance_name",
+        annotations=ToolAnnotations(title="Update Instance Name",
                                           readOnlyHint=False,
                                           destructiveHint=True,
                                           idempotentHint=True,
@@ -98,7 +112,9 @@ async def update_instance_name(instance_id: str, name: str) -> dict:
         result = await aura_manager.update_instance_name(instance_id, name)
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Update Instance Memory",
+    @mcp.tool(
+        name=namespace_prefix + "update_instance_memory",
+        annotations=ToolAnnotations(title="Update Instance Memory",
                                           readOnlyHint=False,
                                           destructiveHint=True,
                                           idempotentHint=True,
@@ -110,7 +126,8 @@ async def update_instance_memory(instance_id: str, memory: int) -> dict:
         result = await aura_manager.update_instance_memory(instance_id, memory)
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Update Instance Vector Optimization",
+    @mcp.tool(name=namespace_prefix + "update_instance_vector_optimization",
+        annotations=ToolAnnotations(title="Update Instance Vector Optimization",
                                           readOnlyHint=False,
                                           destructiveHint=True,
                                           idempotentHint=True,
@@ -122,7 +139,9 @@ async def update_instance_vector_optimization(instance_id: str, vector_optimized
         result = await aura_manager.update_instance_vector_optimization(instance_id, vector_optimized)
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Pause Instance",
+    @mcp.tool(
+        name=namespace_prefix + "pause_instance",
+        annotations=ToolAnnotations(title="Pause Instance",
                                           readOnlyHint=False,
                                           destructiveHint=False,
                                           idempotentHint=True,
@@ -134,7 +153,9 @@ async def pause_instance(instance_id: str) -> dict:
         result = await aura_manager.pause_instance(instance_id)
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Resume Instance",
+    @mcp.tool(
+        name=namespace_prefix + "resume_instance",
+        annotations=ToolAnnotations(title="Resume Instance",
                                           readOnlyHint=False,
                                           destructiveHint=False,
                                           idempotentHint=True,
@@ -146,7 +167,10 @@ async def resume_instance(instance_id: str) -> dict:
         result = await aura_manager.resume_instance(instance_id)
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="List Tenants",
+
+    @mcp.tool(
+        name=namespace_prefix + "list_tenants",
+        annotations=ToolAnnotations(title="List Tenants",
                                           readOnlyHint=True,
                                           destructiveHint=False,
                                           idempotentHint=True,
@@ -158,7 +182,9 @@ async def list_tenants() -> dict:
         result = await aura_manager.list_tenants()
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Get Tenant Details",
+    @mcp.tool(
+        name=namespace_prefix + "get_tenant_details",
+        annotations=ToolAnnotations(title="Get Tenant Details",
                                           readOnlyHint=True,
                                           destructiveHint=False,
                                           idempotentHint=True,
@@ -170,7 +196,8 @@ async def get_tenant_details(tenant_id: str) -> dict:
         result = await aura_manager.get_tenant_details(tenant_id)
         return result
 
-    @mcp.tool(annotations=ToolAnnotations(title="Delete Instance",
+    @mcp.tool(name=namespace_prefix + "delete_instance",
+    annotations=ToolAnnotations(title="Delete Instance",
                                           readOnlyHint=False,
                                           destructiveHint=True,
                                           idempotentHint=True,
@@ -189,6 +216,7 @@ async def main(
     client_id: str,
     client_secret: str,
     transport: Literal["stdio", "sse", "http"] = "stdio",
+    namespace: str = "",
     host: str = "127.0.0.1",
     port: int = 8000,
     path: str = "/mcp/",
@@ -209,9 +237,9 @@ async def main(
         Middleware(TrustedHostMiddleware,
                    allowed_hosts=allowed_hosts)
     ]
-
+    
     # Create MCP server
-    mcp = create_mcp_server(aura_manager)
+    mcp = create_mcp_server(aura_manager, namespace)
 
     # Run the server with the specified transport
     match transport:

servers/mcp-neo4j-cloud-aura-api/src/mcp_neo4j_aura_manager/utils.py

@@ -13,6 +13,16 @@ def get_logger(name: str) -> logging.Logger:
 
 logger = get_logger(__name__)
 
+
+def format_namespace(namespace: str) -> str:
+    if namespace:
+        if namespace.endswith("-"):
+            return namespace
+        else:
+            return namespace + "-"
+    else:
+        return ""
+    
 def _validate_region(cloud_provider: str, region: str) -> None:
     """
     Validate the region exists for the given cloud provider.
@@ -298,6 +308,22 @@ def parse_allowed_hosts(args: argparse.Namespace) -> list[str]:
             )
             return ["localhost", "127.0.0.1"]
 
+def parse_namespace(args: argparse.Namespace) -> str:
+    """
+    Parse the namespace from the command line arguments or environment variables.
+    """
+        # namespace configuration
+    if args.namespace is not None:
+        logger.info(f"Info: Namespace provided for tools: {args.namespace}")
+        return args.namespace
+    else:
+        if os.getenv("NEO4J_NAMESPACE") is not None:
+            logger.info(f"Info: Namespace provided for tools: {os.getenv('NEO4J_NAMESPACE')}")
+            return os.getenv("NEO4J_NAMESPACE")
+        else:
+            logger.info("Info: No namespace provided for tools. No namespace will be used.")
+            return ""
+        
 def process_config(args: argparse.Namespace) -> dict[str, Union[str, int, None]]:
     """
     Process the command line arguments and environment variables to create a config dictionary. 
@@ -331,4 +357,7 @@ def process_config(args: argparse.Namespace) -> dict[str, Union[str, int, None]]
     config["allow_origins"] = parse_allow_origins(args)
     config["allowed_hosts"] = parse_allowed_hosts(args)
 
+    # namespace configuration
+    config["namespace"] = parse_namespace(args)
+
     return config

servers/mcp-neo4j-cloud-aura-api/tests/integration/conftest.py

@@ -95,7 +95,8 @@ def run_server():
                 port=8005,
                 path="/mcp/",
                 allow_origins=[],  # Empty by default for security testing
-                allowed_hosts=["localhost", "127.0.0.1"]
+                allowed_hosts=["localhost", "127.0.0.1"],
+                namespace=""  # Add namespace parameter
             ))
 
         server_thread = threading.Thread(target=run_server, daemon=True)
@@ -131,7 +132,8 @@ def run_server():
                 port=8006,
                 path="/mcp/",
                 allow_origins=["http://localhost:3000", "https://trusted-site.com"],
-                allowed_hosts=["localhost", "127.0.0.1"]
+                allowed_hosts=["localhost", "127.0.0.1"],
+                namespace=""  # Add namespace parameter
             ))
 
         server_thread = threading.Thread(target=run_server, daemon=True)