Tool Reference

The Blindata MCP server provides several specialized tools for different data exploration and analysis needs. Each tool is designed to work seamlessly with AI assistants supporting MCP, allowing you to access and analyze your Blindata data through natural language queries.

Available Tools

Universal Search Tool

The most versatile tool for finding resources across your Blindata instance.

Tool Name: universal_search

Parameters:

• search (string, optional): The search query text
• resourceTypes (array, optional): List of specific resource types to filter by
• searchMode (enum, optional): Search mode (NORMAL, FTS, SEMANTIC, HYBRID)

The search parameter accepts any text query that will be matched against resource names, descriptions, and metadata. The resourceTypes parameter allows you to filter results to specific resource types by providing an array of type names. The searchMode parameter controls the search algorithm, with options for normal exact matching, full-text search with typo tolerance, semantic search for conceptual matching, or hybrid search that combines multiple approaches.

Usage Examples:

# Find customer-related data products
universal_search(
    search="customer data products",
    resourceTypes=["DATA_PRODUCT"],
    searchMode="SEMANTIC"
)

# Results:
{
    "resources": [
        {
            "id": "dp_customer_analytics_001",
            "name": "Customer Analytics Dataset",
            "type": "DATA_PRODUCT",
            ...
        },
        ...
    ],
}

Fetch resource details tool

Retrieve detailed metadata and contextual information for a specific resource using its unique identifier.

Tool Name: fetch_resource_details

Parameters:

Description:

The fetch_resource_details tool allows you to retrieve in-depth information about a specific resource within Blindata.

The resourceIdentifier parameter must be the unique identifier (UUID) of the resource. This is usually acquired from other operations like the Universal Search Tool.

The resourceType ensures the system fetches and formats the data correctly based on the resource’s schema and context. The tool returns structured information including metadata, relationships, lineage, governance attributes, and operational details depending on the resource type.

Supported Resource Types:

The following resource types are supported by fetch_resource_details:

• DATA_PRODUCT
• QUALITY_CHECK
• SYSTEM
• PHYSICAL_ENTITY
• DATA_CATEGORY
• LOGICAL_FIELD
• PHYSICAL_FIELD
• QUALITY_SUITE
• PROCESSING
• TASK
• DATA_ACTOR
• DATA_PRODUCT_DOMAIN
• LOGICAL_NAMESPACE
• LOGICAL_PREDICATE
• GOVERNANCE_POLICY
• GOVERNANCE_POLICY_SUITE
• GOVERNANCE_POLICY_SUITE

Usage Example:

# Retrieve details of a specific data product
fetch_resource_details(
    resourceIdentifier="dc17a8a6-b8df-44b9-b906-b155a8df674c",
    resourceType="DATA_PRODUCT"
)

# Example Response:
{
    "data": {
        "uuid": "dc17a8a6-b8df-44b9-b906-b155a8df674c",
        "name": "customerAnalytics",
        "displayName": "Customer Analytics Dataset",
        "identifier": "urn:dpds:blindata:dataproducts:customerAnalytics:1",
        "description": "Comprehensive customer behavior analytics for business intelligence",
        "ports": [],
        ...
    }
}

Get Relationships Tool

This tool enables you to navigate between related entities within Blindata, uncovering how data elements are connected through metadata relationships. It supports graph-based exploration, helping you analyze dependencies, trace linkages, and gain a deeper understanding of your data ecosystem.

Tool Name: get_relationships

Parameters:

• filter_resource_id (string, required): The unique identifier of the filter resource
• filter_resource_type (enum, required): The type of the filter resource
• result_resource_type (enum, required): The type of result resources to find

The filter_resource_id parameter specifies the unique identifier of the resource you want to filter by. The filter_resource_type parameter defines the type of the filter resource to ensure proper relationship mapping. The result_resource_type parameter indicates what type of result resources you want to discover, allowing you to explore specific types of connections within your data ecosystem.

Usage Examples:

# Find all data categories related to customer data product
get_relationships(
    "filter_resource_id": "11223344-5566-7788-99aa-bbccddeeff00",
    "filter_resource_type": "LOGICAL_NAMESPACE",
    "result_resource_type": "DATA_CATEGORY"
)

# Results:
{
    "related_objects":
    [
        {
            "createdAt": "2025-04-10T08:15:30.123Z",
            "updatedAt": "2025-04-15T14:22:45.456Z",
            "teamCode": null,
            "uuid": "83d8c6f1-1f9d-4b20-bb65-9c4a12345678",
            "name": "ItemBrand",
            "displayName": "Item Brand",
            "description": "The brand associated with the item",
            "clearance": null,
            "dataClass": "Inventory Metadata"
        },
        {
            "createdAt": "2025-04-11T10:42:10.789Z",
            "updatedAt": "2025-04-17T09:38:15.321Z",
            "teamCode": null,
            "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "name": "ItemType",
            "displayName": "Item Type",
            "description": "Specifies the type or category of item",
            "clearance": null,
            "dataClass": "Inventory Metadata"
        },
        ...
    ],
    "count": 8,
    "via":"explicit_filter:namespaceUuid"
}

Get JSON Schema Tool

Retrieve the JSON schema definition for a specific Blindata resource type to understand its structure and validation rules.

Tool Name: get_json_schema

Parameters:

Description:

The get_json_schema tool returns the complete JSON schema definition for the specified Blindata resource type. This schema contains essential metadata including property definitions, validation rules, required fields, and version information that is necessary for creating or updating resources using the write_resource tool.

The returned schema includes:

• Property definitions and types
• Required fields and validation rules
• Field descriptions and metadata
• Resource type information
• Schema version information
• All other metadata required for validation

Supported Resource Types:

The following resource types have available JSON schemas:

• DATA_CATEGORY
• LOGICAL_FIELD
• LOGICAL_PREDICATE

Usage Example:

# Get the JSON schema for LOGICAL_FIELD resource type
# This schema is typically used with the write_resource tool
get_json_schema(
    resource_type="LOGICAL_FIELD"
)

# Example Response:
{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "LogicalField",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "description": "The logical field name"
        },
        "description": {
            "type": "string",
            "description": "The logical field description"
        },
        "dataType": {
            "type": "string",
            "description": "The data type of the field"
        },
        "dataCategory": {
            "type": "object",
            "properties": {
                "uuid": {"type": "string"}
            }
        }
    },
    "required": ["name"],
    "resourceType": "LOGICAL_FIELD",
    "version": "1.0.0"
}

Write Resource Tool

Write a resource in Blindata (create new or update existing) by validating a resource object against a JSON schema and making either a POST request (for creation) or PUT request (for updates) to the appropriate API endpoint.

Tool Name: write_resource

Parameters:

Description:

The write_resource tool validates a resource object against the provided JSON schema and then makes either a POST request (for creation) or PUT request (for updates) to the appropriate Blindata API endpoint.

The tool determines whether to create or update based on the presence of a uuid field in the resource object:

• If uuid is present: Updates the existing resource with that UUID
• If uuid is not present: Creates a new resource

This tool should typically be called after using the get_json_schema tool to retrieve the schema for the resource type you want to write (create or update).

Important Guidelines:

1. Schema Integrity: Ensure the schema obtained from get_json_schema is used in its entirety. Do not modify, delete, or filter any part of it, as it contains crucial metadata necessary for resource creation and updates.

2. Constructing the Resource Object:

   • Include only the fields specified in the resource’s schema.
   • Provide values for all fields marked as required in the schema.
   • You can omit optional fields if they are not needed, as they are not mandatory for resource creation or updates.
   • For updates: Include the uuid field with the resource’s UUID to specify which resource to update.

3. Handling Resource References:

   • For fields that allow references to other resources (e.g., namespace, dataCategory), only the UUID of the referenced resource is necessary. This ensures proper linkage without unnecessary data.

4. Create vs Update Behavior:

   • Creating new resources: Omit the uuid field in the resource_object
   • Updating existing resources: Include the uuid field with the existing resource’s UUID in the resource_object

Supported Resource Types:

The tool supports all resource types that have available JSON schemas, including:

• DATA_CATEGORY
• LOGICAL_FIELD
• LOGICAL_PREDICATE

Usage Examples:

Creating a New Resource:

# Step 1: Get the JSON schema for LOGICAL_FIELD
schema = get_json_schema(resource_type="LOGICAL_FIELD")

# Step 2: Create a logical field with data category association
write_resource(
    resource_object={
        "name": "Customer ID",
        "description": "Unique identifier for customers",
        "dataType": "VARCHAR",
        "dataCategory": {"uuid": "existing-category-uuid"}
    },
    json_schema=schema
)

# Example Response:
{
    "success": true,
    "status_code": 201,
    "data": {
        "uuid": "new-logical-field-uuid",
        "name": "Customer ID",
        "description": "Unique identifier for customers",
        "dataType": "VARCHAR",
        "dataCategory": {
            "uuid": "existing-category-uuid",
            "name": "Customer Data"
        },
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-15T10:30:00Z"
    },
    "message": "Resource created successfully"
}

Updating an Existing Resource:

# Step 1: Get the JSON schema for LOGICAL_FIELD
schema = get_json_schema(resource_type="LOGICAL_FIELD")

# Step 2: Update an existing logical field (include uuid field)
write_resource(
    resource_object={
        "uuid": "existing-logical-field-uuid",
        "name": "Updated Customer ID",
        "description": "Updated description for customer identifier",
        "dataType": "VARCHAR",
        "dataCategory": {"uuid": "existing-category-uuid"}
    },
    json_schema=schema
)

# Example Response:
{
    "success": true,
    "status_code": 200,
    "data": {
        "uuid": "existing-logical-field-uuid",
        "name": "Updated Customer ID",
        "description": "Updated description for customer identifier",
        "dataType": "VARCHAR",
        "dataCategory": {
            "uuid": "existing-category-uuid",
            "name": "Customer Data"
        },
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-15T11:45:00Z"
    },
    "message": "Resource updated successfully"
}

Error Handling:

The tool returns structured error responses for various scenarios:

• Missing Schema Metadata: Returns error if schema is missing required fields (resourceType, required, version)
• Validation Errors: Returns error if resource object doesn’t conform to schema
• Missing UUID for Updates: Returns error if attempting to update without providing a UUID
• API Errors: Returns error if the API request fails
• Invalid Resource Type: Returns error if the resource type in schema is not supported