data modeling - feat: Add comprehensive example data models as MCP resources (#122)

* feat: Add comprehensive example data models as MCP resources

- Add DataModel.from_dict() class method for JSON to DataModel conversion
- Add 7 new example data models as MCP resources:
  * resource://examples/patient_journey_model (14 nodes, 21 relationships)
  * resource://examples/supply_chain_model (14 nodes, 23 relationships)
  * resource://examples/software_dependency_model (14 nodes, 17 relationships)
  * resource://examples/oil_gas_monitoring_model (12 nodes, 26 relationships)
  * resource://examples/customer_360_model (30 nodes, 35 relationships)
  * resource://examples/fraud_aml_model (15 nodes, 24 relationships)
  * resource://examples/health_insurance_fraud_model (14 nodes, 16 relationships)

- Add new MCP tools:
  * list_example_data_models: Lists all available examples with descriptions
  * load_example_data_model: Loads any example as DataModel object

- Remove CBRE_WORK_ORDER_MODEL (accidentally added)
- Remove Google references from Supply Chain model
- Fix server startup with asyncio.run(main())
- Add comprehensive test coverage for new tools and resources
- Ensure MCP resources return JSON strings, tools return DataModel objects

All 56 tests passing (43 unit + 13 integration)

* refactor: improve template and test organization

- Update DATA_MODELING_TEMPLATE to include example data in property descriptions
- Remove unnecessary template fields (Direction, Integration Needs, Compliance)
- Move server tools and MCP resources tests to dedicated test_server.py file
- Use pytest fixture for MCP server to avoid duplication
- All 43 tests passing with comprehensive coverage

* replace .to_dict with built in functions, update example unit tests and get_example model_tool to return viz config too

* update get_example_data_model tests

need to parse data model from response since we now include the viz config

* Added description field to static data models and removed data model prompt

* Fix duplicate relationship validation to allow multiple relationships with same pattern

* update readme and changelog

* Update CHANGELOG.md

---------

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

Author: rfrneo4j

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

@@ -7,6 +7,8 @@
 
 ### Added
 * Update PR workflow to iterate over Python 3.10 to 3.13
+* Add example data model resources 
+* Add tools to list and retrieve example data models and their Mermaid configurations
 
 ## v0.2.0
 

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

@@ -10,6 +10,8 @@ A Model Context Protocol (MCP) server implementation that provides tools for cre
 
 The server provides these resources:
 
+#### Schema 
+
 - `resource://schema/node`
    - Get the JSON schema for a Node object
    - Returns: JSON schema defining the structure of a Node
@@ -25,7 +27,40 @@ The server provides these resources:
 - `resource://schema/data_model`
    - Get the JSON schema for a DataModel object
    - Returns: JSON schema defining the structure of a DataModel
-  
+
+#### Example Data Models
+
+- `resource://examples/patient_journey_model`
+   - Get a real-world Patient Journey healthcare data model in JSON format
+   - Returns: JSON DataModel for tracking patient encounters, conditions, medications, and care plans
+
+- `resource://examples/supply_chain_model`
+   - Get a real-world Supply Chain data model in JSON format
+   - Returns: JSON DataModel for tracking products, orders, inventory, and locations
+
+- `resource://examples/software_dependency_model`
+   - Get a real-world Software Dependency Graph data model in JSON format
+   - Returns: JSON DataModel for software dependency tracking with security vulnerabilities, commits, and contributor analysis
+
+- `resource://examples/oil_gas_monitoring_model`
+   - Get a real-world Oil and Gas Equipment Monitoring data model in JSON format
+   - Returns: JSON DataModel for industrial monitoring of oil and gas equipment, sensors, alerts, and maintenance
+
+- `resource://examples/customer_360_model`
+   - Get a real-world Customer 360 data model in JSON format
+   - Returns: JSON DataModel for customer relationship management with accounts, contacts, orders, tickets, and surveys
+
+- `resource://examples/fraud_aml_model`
+   - Get a real-world Fraud & AML data model in JSON format
+   - Returns: JSON DataModel for financial fraud detection and anti-money laundering with customers, transactions, alerts, and compliance
+
+- `resource://examples/health_insurance_fraud_model`
+   - Get a real-world Health Insurance Fraud Detection data model in JSON format
+   - Returns: JSON DataModel for healthcare fraud detection tracking investigations, prescriptions, executions, and beneficiary relationships
+
+
+#### Ingest
+
 - `resource://neo4j_data_ingest_process`
    - Get a detailed explanation of the recommended process for ingesting data into Neo4j using the data model
    - Returns: Markdown document explaining the ingest process
@@ -77,6 +112,21 @@ These tools provide integration with **[Arrows](https://arrows.app/)** - a graph
      - `data_model` (DataModel): The data model to export
    - Returns: JSON string compatible with Arrows app
 
+#### 📚 Example Data Model Tools
+
+These tools provide access to pre-built example data models for common use cases and domains.
+
+- `list_example_data_models`
+   - List all available example data models with descriptions
+   - Input: None
+   - Returns: Dictionary with example names, descriptions, node/relationship counts, and usage instructions
+
+- `get_example_data_model`
+   - Get an example graph data model from the available templates
+   - Input:
+     - `example_name` (str): Name of the example to load ('patient_journey', 'supply_chain', 'software_dependency', 'oil_gas_monitoring', 'customer_360', 'fraud_aml', or 'health_insurance_fraud')
+   - Returns: ExampleDataModelResponse containing DataModel object and Mermaid visualization configuration
+
 #### 📝 Cypher Ingest Tools
 
 These tools may be used to create Cypher ingest queries based on the data model. These queries may then be used by other MCP servers or applications to load data into Neo4j.

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

@@ -414,14 +414,6 @@ def validate_relationships(
     ) -> list[Relationship]:
         "Validate the relationships."
 
-        # check for duplicate relationships
-        counts = Counter([r.pattern for r in relationships])
-        for pattern, count in counts.items():
-            if count > 1:
-                raise ValueError(
-                    f"Relationship with pattern {pattern} appears {count} times in data model"
-                )
-
         # ensure source and target nodes exist
         for relationship in relationships:
             if relationship.start_node_label not in [

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

@@ -0,0 +1,8 @@
+from pydantic import BaseModel, Field
+from .data_model import DataModel
+
+class ExampleDataModelResponse(BaseModel):
+    """Response model for the `get_example_data_model` tool."""
+
+    data_model: DataModel = Field(description="The example graph data model.")
+    mermaid_config: str = Field(description="The Mermaid visualization configuration for the example graph data model.")

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

@@ -1,3 +1,4 @@
+import json
 import logging
 from typing import Any, Literal
 
@@ -10,7 +11,17 @@
     Property,
     Relationship,
 )
-from .static import DATA_INGEST_PROCESS
+from .models import ExampleDataModelResponse
+from .static import (
+    DATA_INGEST_PROCESS,
+    PATIENT_JOURNEY_MODEL,
+    SUPPLY_CHAIN_MODEL,
+    SOFTWARE_DEPENDENCY_MODEL,
+    OIL_GAS_MONITORING_MODEL,
+    CUSTOMER_360_MODEL,
+    FRAUD_AML_MODEL,
+    HEALTH_INSURANCE_FRAUD_MODEL,
+)
 
 logger = logging.getLogger("mcp_neo4j_data_modeling")
 
@@ -52,6 +63,48 @@ def neo4j_data_ingest_process() -> str:
         logger.info("Getting the process for ingesting data into a Neo4j database.")
         return DATA_INGEST_PROCESS
 
+    @mcp.resource("resource://examples/patient_journey_model")
+    def example_patient_journey_model() -> str:
+        """Get a real-world Patient Journey healthcare data model in JSON format."""
+        logger.info("Getting the Patient Journey healthcare data model.")
+        return json.dumps(PATIENT_JOURNEY_MODEL, indent=2)
+
+    @mcp.resource("resource://examples/supply_chain_model")
+    def example_supply_chain_model() -> str:
+        """Get a real-world Supply Chain data model in JSON format."""
+        logger.info("Getting the Supply Chain data model.")
+        return json.dumps(SUPPLY_CHAIN_MODEL, indent=2)
+
+    @mcp.resource("resource://examples/software_dependency_model")
+    def example_software_dependency_model() -> str:
+        """Get a real-world Software Dependency Graph data model in JSON format."""
+        logger.info("Getting the Software Dependency Graph data model.")
+        return json.dumps(SOFTWARE_DEPENDENCY_MODEL, indent=2)
+
+    @mcp.resource("resource://examples/oil_gas_monitoring_model")
+    def example_oil_gas_monitoring_model() -> str:
+        """Get a real-world Oil and Gas Equipment Monitoring data model in JSON format."""
+        logger.info("Getting the Oil and Gas Equipment Monitoring data model.")
+        return json.dumps(OIL_GAS_MONITORING_MODEL, indent=2)
+
+    @mcp.resource("resource://examples/customer_360_model")
+    def example_customer_360_model() -> str:
+        """Get a real-world Customer 360 data model in JSON format."""
+        logger.info("Getting the Customer 360 data model.")
+        return json.dumps(CUSTOMER_360_MODEL, indent=2)
+
+    @mcp.resource("resource://examples/fraud_aml_model")
+    def example_fraud_aml_model() -> str:
+        """Get a real-world Fraud & AML data model in JSON format."""
+        logger.info("Getting the Fraud & AML data model.")
+        return json.dumps(FRAUD_AML_MODEL, indent=2)
+
+    @mcp.resource("resource://examples/health_insurance_fraud_model")
+    def example_health_insurance_fraud_model() -> str:
+        """Get a real-world Health Insurance Fraud Detection data model in JSON format."""
+        logger.info("Getting the Health Insurance Fraud Detection data model.")
+        return json.dumps(HEALTH_INSURANCE_FRAUD_MODEL, indent=2)
+
     @mcp.tool()
     def validate_node(
         node: Node, return_validated: bool = False
@@ -180,6 +233,96 @@ def get_constraints_cypher_queries(data_model: DataModel) -> list[str]:
         )
         return data_model.get_cypher_constraints_query()
 
+    @mcp.tool()
+    def get_example_data_model(
+        example_name: str = Field(
+            ...,
+            description="Name of the example to load: 'patient_journey', 'supply_chain', 'software_dependency', 'oil_gas_monitoring', 'customer_360', 'fraud_aml', or 'health_insurance_fraud'",
+        ),
+    ) -> ExampleDataModelResponse:
+        """Get an example graph data model from the available templates. Returns a DataModel object and the Mermaid visualization configuration for the example graph data model."""
+        logger.info(f"Getting example data model: {example_name}")
+
+        example_map = {
+            "patient_journey": PATIENT_JOURNEY_MODEL,
+            "supply_chain": SUPPLY_CHAIN_MODEL,
+            "software_dependency": SOFTWARE_DEPENDENCY_MODEL,
+            "oil_gas_monitoring": OIL_GAS_MONITORING_MODEL,
+            "customer_360": CUSTOMER_360_MODEL,
+            "fraud_aml": FRAUD_AML_MODEL,
+            "health_insurance_fraud": HEALTH_INSURANCE_FRAUD_MODEL,
+        }
+
+        if example_name not in example_map:
+            raise ValueError(
+                f"Unknown example: {example_name}. Available examples: {list(example_map.keys())}"
+            )
+
+        example_data = example_map[example_name]
+
+        validated_data_model = DataModel.model_validate(example_data)
+
+        return ExampleDataModelResponse(
+            data_model=validated_data_model,
+            mermaid_config=validated_data_model.get_mermaid_config_str(),
+        )
+
+    @mcp.tool()
+    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.")
+
+        examples = {
+            "patient_journey": {
+                "name": "Patient Journey",
+                "description": "Healthcare data model for tracking patient encounters, conditions, medications, and care plans",
+                "nodes": len(PATIENT_JOURNEY_MODEL["nodes"]),
+                "relationships": len(PATIENT_JOURNEY_MODEL["relationships"]),
+            },
+            "supply_chain": {
+                "name": "Supply Chain",
+                "description": "Supply chain management data model for tracking products, orders, inventory, and locations",
+                "nodes": len(SUPPLY_CHAIN_MODEL["nodes"]),
+                "relationships": len(SUPPLY_CHAIN_MODEL["relationships"]),
+            },
+            "software_dependency": {
+                "name": "Software Dependency Graph",
+                "description": "Software dependency tracking with security vulnerabilities, commits, and contributor analysis",
+                "nodes": len(SOFTWARE_DEPENDENCY_MODEL["nodes"]),
+                "relationships": len(SOFTWARE_DEPENDENCY_MODEL["relationships"]),
+            },
+            "oil_gas_monitoring": {
+                "name": "Oil & Gas Equipment Monitoring",
+                "description": "Industrial monitoring data model for oil and gas equipment, sensors, alerts, and maintenance",
+                "nodes": len(OIL_GAS_MONITORING_MODEL["nodes"]),
+                "relationships": len(OIL_GAS_MONITORING_MODEL["relationships"]),
+            },
+            "customer_360": {
+                "name": "Customer 360",
+                "description": "Customer relationship management data model for accounts, contacts, orders, tickets, and surveys",
+                "nodes": len(CUSTOMER_360_MODEL["nodes"]),
+                "relationships": len(CUSTOMER_360_MODEL["relationships"]),
+            },
+            "fraud_aml": {
+                "name": "Fraud & AML",
+                "description": "Financial fraud detection and anti-money laundering data model for customers, transactions, alerts, and compliance",
+                "nodes": len(FRAUD_AML_MODEL["nodes"]),
+                "relationships": len(FRAUD_AML_MODEL["relationships"]),
+            },
+            "health_insurance_fraud": {
+                "name": "Health Insurance Fraud Detection",
+                "description": "Healthcare fraud detection data model for tracking investigations, prescriptions, executions, and beneficiary relationships",
+                "nodes": len(HEALTH_INSURANCE_FRAUD_MODEL["nodes"]),
+                "relationships": len(HEALTH_INSURANCE_FRAUD_MODEL["relationships"]),
+            },
+        }
+
+        return {
+            "available_examples": examples,
+            "total_examples": len(examples),
+            "usage": "Use the get_example_data_model tool with any of the example names above to get a specific data model",
+        }
+
     return mcp