data-modeling - add namespacing (#181)

* added namespacing to mcp tools in data modeling server, added tests as well

* linting fixes

* updating changelog, docs, and fixing namespacing inconsistency

* updating tests to pass

* move feature to next section of changelog

* update readme, namespace utils fn, unit tests

---------

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

Author: rfrneo4j

servers/mcp-neo4j-data-modeling/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.5.0
 

servers/mcp-neo4j-data-modeling/README.md

@@ -193,6 +193,27 @@ Add the server to your `claude_desktop_config.json` with the transport method sp
 }
 ```
 
+### 🏷️ Namespacing Tools
+
+The server supports namespacing the server tools:
+
+```json
+"mcpServers": {
+  "neo4j-data-modeling-app1": {
+    "command": "uvx",
+    "args": [ "[email protected]", "--transport", "stdio", "--namespace", "app1" ]
+  },
+  "neo4j-data-modeling-app2": {
+    "command": "uvx", 
+    "args": [ "[email protected]", "--transport", "stdio", "--namespace", "app2" ]
+  }
+}
+```
+
+With namespacing enabled:
+- Tools get prefixed: `app1-validate_node`, `app2-validate_node` 
+- Each namespace operates independently
+
 ### 🌐 HTTP Transport Mode
 
 The server supports HTTP transport for web-based deployments and microservices:
@@ -203,6 +224,9 @@ mcp-neo4j-data-modeling --transport http
 
 # Custom HTTP configuration
 mcp-neo4j-data-modeling --transport http --host 127.0.0.1 --port 8080 --path /api/mcp/
+
+# With namespace for multi-tenant deployment
+mcp-neo4j-data-modeling --transport http --namespace myapp
 ```
 
 Environment variables for HTTP configuration:
@@ -212,6 +236,7 @@ export MCP_TRANSPORT=http
 export NEO4J_MCP_SERVER_HOST=127.0.0.1
 export NEO4J_MCP_SERVER_PORT=8080
 export NEO4J_MCP_SERVER_PATH=/api/mcp/
+export NEO4J_NAMESPACE=myapp
 mcp-neo4j-data-modeling
 ```
 
@@ -245,6 +270,7 @@ Here we use the Docker Hub hosted Data Modeling MCP server image with stdio tran
         "-p",
         "8000:8000",
         "-e", "NEO4J_TRANSPORT=stdio",
+        "-e", "NEO4J_NAMESPACE=myapp",
         "mcp/neo4j-data-modeling:latest"
       ]
     }
@@ -289,6 +315,7 @@ docker run --rm -p 8000:8000 \
 | `NEO4J_MCP_SERVER_HOST`            | `127.0.0.1` (local)                     | Host to bind to                                    |
 | `NEO4J_MCP_SERVER_PORT`            | `8000`                                  | Port for HTTP/SSE transport                        |
 | `NEO4J_MCP_SERVER_PATH`            | `/mcp/`                                 | Path for accessing MCP server                      |
+| `NEO4J_NAMESPACE`                  | _(empty - no prefix)_                   | Namespace prefix for tool names (e.g., `myapp-validate_node`) |
 | `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) |
 

servers/mcp-neo4j-data-modeling/src/mcp_neo4j_data_modeling/__init__.py

@@ -30,6 +30,7 @@ def main():
         default=None,
         help="Allowed hosts for DNS rebinding protection on remote servers (comma-separated list)",
     )
+    parser.add_argument("--namespace", default=None, help="Tool namespace prefix")
 
     args = parser.parse_args()
 

servers/mcp-neo4j-data-modeling/src/mcp_neo4j_data_modeling/server.py

@@ -7,6 +7,7 @@
 from starlette.middleware import Middleware
 from starlette.middleware.cors import CORSMiddleware
 from starlette.middleware.trustedhost import TrustedHostMiddleware
+from .utils import format_namespace
 
 from .data_model import (
     DataModel,
@@ -29,13 +30,15 @@
 logger = logging.getLogger("mcp_neo4j_data_modeling")
 
 
-def create_mcp_server() -> FastMCP:
+def create_mcp_server(namespace: str = "") -> FastMCP:
     """Create an MCP server instance for data modeling."""
 
     mcp: FastMCP = FastMCP(
         "mcp-neo4j-data-modeling", dependencies=["pydantic"], stateless_http=True
     )
 
+    namespace_prefix = format_namespace(namespace)
+
     @mcp.resource("resource://schema/node")
     def node_schema() -> dict[str, Any]:
         """Get the schema for a node."""
@@ -108,7 +111,7 @@ def example_health_insurance_fraud_model() -> str:
         logger.info("Getting the Health Insurance Fraud Detection data model.")
         return json.dumps(HEALTH_INSURANCE_FRAUD_MODEL, indent=2)
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "validate_node")
     def validate_node(
         node: Node, return_validated: bool = False
     ) -> bool | dict[str, Any]:
@@ -125,7 +128,7 @@ def validate_node(
             logger.error(f"Validation error: {e}")
             raise ValueError(f"Validation error: {e}")
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "validate_relationship")
     def validate_relationship(
         relationship: Relationship, return_validated: bool = False
     ) -> bool | dict[str, Any]:
@@ -144,7 +147,7 @@ def validate_relationship(
             logger.error(f"Validation error: {e}")
             raise ValueError(f"Validation error: {e}")
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "validate_data_model")
     def validate_data_model(
         data_model: DataModel, return_validated: bool = False
     ) -> bool | dict[str, Any]:
@@ -161,19 +164,19 @@ def validate_data_model(
             logger.error(f"Validation error: {e}")
             raise ValueError(f"Validation error: {e}")
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "load_from_arrows_json")
     def load_from_arrows_json(arrows_data_model_dict: dict[str, Any]) -> DataModel:
         "Load a data model from the Arrows web application format. Returns a data model as a JSON string."
         logger.info("Loading a data model from the Arrows web application format.")
         return DataModel.from_arrows(arrows_data_model_dict)
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "export_to_arrows_json")
     def export_to_arrows_json(data_model: DataModel) -> str:
         "Export the data model to the Arrows web application format. Returns a JSON string. This should be presented to the user as an artifact if possible."
         logger.info("Exporting the data model to the Arrows web application format.")
         return data_model.to_arrows_json_str()
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "get_mermaid_config_str")
     def get_mermaid_config_str(data_model: DataModel) -> str:
         "Get the Mermaid configuration string for the data model. This may be visualized in Claude Desktop and other applications with Mermaid support."
         logger.info("Getting the Mermaid configuration string for the data model.")
@@ -184,7 +187,7 @@ def get_mermaid_config_str(data_model: DataModel) -> str:
             raise ValueError(f"Validation error: {e}")
         return dm_validated.get_mermaid_config_str()
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "get_node_cypher_ingest_query")
     def get_node_cypher_ingest_query(
         node: Node = Field(description="The node to get the Cypher query for."),
     ) -> str:
@@ -198,7 +201,7 @@ def get_node_cypher_ingest_query(
         )
         return node.get_cypher_ingest_query_for_many_records()
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "get_relationship_cypher_ingest_query")
     def get_relationship_cypher_ingest_query(
         data_model: DataModel = Field(
             description="The data model snippet that contains the relationship, start node and end node."
@@ -228,15 +231,15 @@ def get_relationship_cypher_ingest_query(
             relationship_end_node_label,
         )
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "get_constraints_cypher_queries")
     def get_constraints_cypher_queries(data_model: DataModel) -> list[str]:
         "Get the Cypher queries to create constraints on the data model. This creates range indexes on the key properties of the nodes and relationships and enforces uniqueness and existence of the key properties."
         logger.info(
             "Getting the Cypher queries to create constraints on the data model."
         )
         return data_model.get_cypher_constraints_query()
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "get_example_data_model")
     def get_example_data_model(
         example_name: str = Field(
             ...,
@@ -270,7 +273,7 @@ def get_example_data_model(
             mermaid_config=validated_data_model.get_mermaid_config_str(),
         )
 
-    @mcp.tool()
+    @mcp.tool(name=namespace_prefix + "list_example_data_models")
     def list_example_data_models() -> dict[str, Any]:
         """List all available example data models with descriptions. Returns a dictionary with example names and their descriptions."""
         logger.info("Listing available example data models.")
@@ -401,6 +404,7 @@ def create_new_data_model(
 
 async def main(
     transport: Literal["stdio", "sse", "http"] = "stdio",
+    namespace: str = "",
     host: str = "127.0.0.1",
     port: int = 8000,
     path: str = "/mcp/",
@@ -419,7 +423,7 @@ async def main(
         Middleware(TrustedHostMiddleware, allowed_hosts=allowed_hosts),
     ]
 
-    mcp = create_mcp_server()
+    mcp = create_mcp_server(namespace=namespace)
 
     match transport:
         case "http":

servers/mcp-neo4j-data-modeling/src/mcp_neo4j_data_modeling/utils.py

@@ -7,7 +7,28 @@
 
 ALLOWED_TRANSPORTS = ["stdio", "http", "sse"]
 
+def format_namespace(namespace: str) -> str:
+    """
+    Format the namespace to ensure it ends with a hyphen.
+
+    Parameters
+    ----------
+    namespace : str
+        The namespace to format.
 
+    Returns
+    -------
+    formatted_namespace : str
+        The namespace in format: namespace-toolname
+    """
+    if namespace:
+        if namespace.endswith("-"):
+            return namespace
+        else:
+            return namespace + "-"
+    else:
+        return ""
+    
 def parse_transport(args: argparse.Namespace) -> Literal["stdio", "http", "sse"]:
     """
     Parse the transport from the command line arguments or environment variables.
@@ -265,6 +286,21 @@ 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]]:
     """
@@ -291,8 +327,13 @@ def process_config(args: argparse.Namespace) -> dict[str, Union[str, int, None]]
     config["port"] = parse_server_port(args, config["transport"])
     config["path"] = parse_server_path(args, config["transport"])
 
+    # namespace configuration
+    config["namespace"] = parse_namespace(args)
+
     # middleware configuration
     config["allow_origins"] = parse_allow_origins(args)
     config["allowed_hosts"] = parse_allowed_hosts(args)
 
+
+
     return config

servers/mcp-neo4j-data-modeling/tests/unit/conftest.py

@@ -20,6 +20,7 @@ def clean_env():
         "NEO4J_MCP_SERVER_PATH",
         "NEO4J_MCP_SERVER_ALLOW_ORIGINS",
         "NEO4J_MCP_SERVER_ALLOWED_HOSTS",
+        "NEO4J_NAMESPACE",
     ]
     # Store original values
     original_values = {}
@@ -47,6 +48,7 @@ def _create_args(**kwargs):
             "server_path": None,
             "allow_origins": None,
             "allowed_hosts": None,
+            "namespace": None,
         }
         defaults.update(kwargs)
         return argparse.Namespace(**defaults)