siemens-graph-studio-mcp-server 0.3.2

MCP (Model Context Protocol) server for Siemens Graph Studio - enables AI agents to interact with knowledge graphs via SPARQL

Siemens Graph Studio MCP Server

An MCP (Model Context Protocol) server that enables AI agents to interact with Siemens Graph Studio knowledge graphs via SPARQL queries.

Features

• 🔍 Execute SPARQL Queries - Run queries against GraphMarts with automatic result formatting
• 📊 Smart Knowledge Discovery - Intelligent property categorization (object vs data properties) for better query generation
• 🔄 Manage GraphMarts - Create and modify transformation layers and steps
• 🧠 AI-Powered Queries - Natural language to SPARQL translation (with OpenAI)
• 📦 Ontology Caching - Efficient schema discovery with persistent caching
• 🏗️ Modular Architecture - Well-organized tool categories for maintainability

What's New in 0.3.x

• 🎯 API_KEY Now Truly Optional: All basic operations (execute SPARQL, discovery, ontology management) work without OpenAI. Only natural language → SPARQL translation requires API_KEY.
• 🔧 Installation Diagnostics: New --verify flag checks Python version, dependencies, PATH, and configuration
• ⚡ Automated Setup: --setup-vscode generates .vscode/mcp.json with correct paths automatically
• 📖 Comprehensive Troubleshooting: New Installation Guide with solutions for common issues
• 🐛 Bug Fixes: Fixed critical import errors and query engine initialization issues

From 0.2.x:

• Property Type Detection: Distinguishes owl:ObjectProperty (relationships) from owl:DatatypeProperty (attributes)
• Smart Knowledge Discovery: Returns all object properties plus top data properties per class
• Enhanced Caching: Property type information persisted in ontology cache

See CHANGELOG.md for full details.

VS Code Quick Start (5 Steps)

1. Install the package:

pipx install siemens-graph-studio-mcp-server
# Verify: siemens-graph-studio-mcp --verify

2. Auto-generate VS Code config (recommended):

cd your-project
siemens-graph-studio-mcp --setup-vscode
# Edit .vscode/mcp.json to add your credentials

Or create .vscode/mcp.json manually:

{
  "servers": {
    "graph-studio": {
      "type": "stdio",
      "command": "siemens-graph-studio-mcp",
      "env": {
        "ANZO_SERVER": "your-server.example.com",
        "ANZO_PORT": "8443",
        "ANZO_USERNAME": "your-username",
        "ANZO_PASSWORD": "your-password",
        "GRAPHMART_URI": "http://example.com/Graphmart/your-id"
      }
    }
  }
}

💡 Tip: API_KEY is optional! Basic SPARQL queries work without it.

3. Enable MCP in VS Code: Settings (Cmd+,) → Search chat.mcp.enabled → Enable ✓

4. Reload VS Code: Cmd+Shift+P → "Developer: Reload Window"

5. Open Copilot Chat (Cmd+Shift+I) and ask:

• "What classes are in the GraphMart?"
• "Show properties of the Customer class"
• "Execute this SPARQL query: SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10"

Not working? See Installation Guide for troubleshooting.

Documentation

• Installation Guide - Detailed setup, troubleshooting, and PATH configuration
• Agent System Prompt - Recommended workflow and tool usage for AI agents
• SPARQL Reference - Query patterns, naming conventions, and troubleshooting
• Architecture Guide - Technical architecture overview
• Skills Documentation - Best practices for ontology and linking patterns

Installation

Recommended: pipx or uv (Isolated Environment)

# Using pipx (prevents dependency conflicts)
pipx install siemens-graph-studio-mcp-server

# Or using uv (faster)
uv tool install siemens-graph-studio-mcp-server

Alternative: pip

pip install siemens-graph-studio-mcp-server

Verify Installation

siemens-graph-studio-mcp --verify

Command not found? See Installation Guide for PATH troubleshooting.

Quick Start

1. Configure Environment Variables

export ANZO_SERVER="graph-studio.example.com"
export ANZO_PORT="8443"
export ANZO_USERNAME="your-username"
export ANZO_PASSWORD="your-password"
export GRAPHMART_URI="http://example.com/Graphmart/your-graphmart-id"

# Optional: Only for natural language to SPARQL translation
# Basic SPARQL, discovery, and ontology tools work without this
export API_KEY="sk-your-openai-api-key"

2. Run the Server

siemens-graph-studio-mcp

3. Use with VS Code + GitHub Copilot (Recommended)

VS Code with GitHub Copilot provides a powerful way to use the MCP server without requiring an OpenAI API key. Copilot's built-in AI handles natural language understanding.

Step 1: Create a .vscode/mcp.json in your project:

{
  "servers": {
    "graph-studio": {
      "command": "siemens-graph-studio-mcp",
      "env": {
        "ANZO_SERVER": "graph-studio.example.com",
        "ANZO_PORT": "8443",
        "ANZO_USERNAME": "your-username",
        "ANZO_PASSWORD": "your-password",
        "GRAPHMART_URI": "http://example.com/Graphmart/your-graphmart-id"
      }
    }
  }
}

Note: No API_KEY required - GitHub Copilot handles the AI layer.

Step 2: Enable MCP in VS Code settings (Settings → Extensions → GitHub Copilot Chat → Enable MCP).

Step 3: Open Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I) and ask questions like:

• "What classes are available in the GraphMart?"
• "Show me all properties of the Customer class"
• "Write a SPARQL query to find all active projects"

⚠️ Troubleshooting VS Code + Copilot

Command not found in VS Code:

// Use full path in .vscode/mcp.json if command not in PATH:
{
  "servers": {
    "graph-studio": {
      "command": "/full/path/to/siemens-graph-studio-mcp",
      // Find path with: siemens-graph-studio-mcp --verify
      ...
    }
  }
}

MCP tools not appearing:

1. Run "Developer: Reload Window" (Ctrl+Shift+P → Reload)
2. Check Output panel → "MCP" for errors
3. Verify the command works in terminal: siemens-graph-studio-mcp --verify

See full troubleshooting guide: docs/INSTALLATION_GUIDE.md

4. Use with Claude Desktop

Add to your ~/.config/claude-desktop/claude_desktop_config.json:

{
  "mcpServers": {
    "graph-studio": {
      "command": "siemens-graph-studio-mcp",
      "env": {
        "ANZO_SERVER": "graph-studio.example.com",
        "ANZO_PORT": "8443",
        "ANZO_USERNAME": "your-username",
        "ANZO_PASSWORD": "your-password",
        "GRAPHMART_URI": "http://example.com/Graphmart/your-graphmart-id",
        "API_KEY": "sk-your-openai-api-key"
      }
    }
  }
}

Note: API_KEY is optional. Include it only if you want natural language to SPARQL translation. Basic SPARQL execution, knowledge discovery, and GraphMart management work without it.

Configuration

Environment Variables

Variable	Required	Description
ANZO_SERVER	Yes	Graph Studio server hostname
ANZO_PORT	Yes	Server port (typically 8443)
ANZO_USERNAME	Yes	Authentication username
ANZO_PASSWORD	Yes	Authentication password
GRAPHMART_URI	Yes	Target GraphMart URI
API_KEY	No	OpenAI API key - only needed for NL→SPARQL. All basic operations work without it.
ENABLE_AGENT_DEBUG	No	Enable debug output
ENABLE_LOGGING_DEBUG	No	Enable detailed logging

Config File

Alternatively, use a config file:

siemens-graph-studio-mcp --config my-config.json

See examples/config.example.jsonc for a template.

Architecture

The server is organized into focused, maintainable modules:

siemens_graph_studio_mcp/
├── server.py              # MCP server entry point
├── sparql_agent_core.py   # Core agent logic
├── ontology_discovery.py  # Schema extraction
├── ontology_cache.py      # Persistent caching
├── models.py              # Pydantic data models
├── tools/
│   ├── discovery/         # Knowledge exploration tools
│   ├── query/             # SPARQL execution tools
│   ├── ontology/          # Ontology management tools
│   ├── graphmart/         # GraphMart construction tools
│   └── system/            # System monitoring tools
└── utils/                 # Shared utilities

Key Components

• SPARQLAgent: The intelligent agent that converts natural language to SPARQL queries
• OntologyDiscovery: Extracts and analyzes ontology schemas from GraphMarts
• OntologyCache: Provides persistent caching for schema information
• Property Detection: Distinguishes between owl:ObjectProperty (relationships) and owl:DatatypeProperty (attributes) for smarter query generation

Available Tools

System & Monitoring

• test_system_connection - Test MCP server and Graph Studio agent status
• get_session_logs - Get session logs and interaction history

SPARQL Query Execution

• execute_sparql_query - Execute SPARQL directly against GraphMart
• query_ags_configuration - Query Graph Studio configuration
• update_ags_configuration - Update Graph Studio configuration

Knowledge Discovery

• discover_knowledge_overview - Get overview of available knowledge
• discover_available_ontologies - List all available ontologies
• discover_ontology_classes - List classes in a specific ontology
• discover_class_data_properties - List data properties for a class
• discover_class_object_properties - List object properties for a class

Ontology Management

• create_ontology - Create new ontologies
• delete_ontology - Delete ontologies
• load_ontology_from_file - Load TTL files into named graphs
• register_ontology - Register ontologies
• add_ontology_class / remove_ontology_class - Manage classes
• add_ontology_property / remove_ontology_property - Manage properties
• get_ontology_cache_status / clear_ontology_cache / refresh_ontology_cache - Cache management

GraphMart Construction

• create_transformation_layer - Create transformation layers
• add_transformation_step - Add transformation steps
• add_direct_load_step - Add direct data loading steps
• update_transformation_layer / delete_transformation_layer - Layer management
• list_transformation_layers / list_transformation_steps - List components
• refresh_graphmart / reload_graphmart - GraphMart operations

Transport Modes

stdio (default)

For use with Claude Desktop and other MCP clients:

siemens-graph-studio-mcp

SSE (Server-Sent Events)

For web clients:

siemens-graph-studio-mcp --transport sse --port 8000

HTTP Streaming

siemens-graph-studio-mcp --transport streamable-http --port 8000

Programmatic Usage

import asyncio
from siemens_graph_studio_mcp import GraphmartConfig, SPARQLAgent

async def main():
    config = GraphmartConfig(
        ags_server="graph-studio.example.com",
        ags_port=8443,
        graphmart_uri="http://example.com/Graphmart/demo",
        username="admin",
        password="secret"
    )
    
    agent = SPARQLAgent(config)
    await agent.initialize()
    
    # Now use the agent...

asyncio.run(main())

Development

Setup

git clone https://github.com/siemens/graph-studio-mcp-server.git
cd graph-studio-mcp-server
pip install -e ".[dev]"

Running Tests

pytest

Building for Distribution

pip install build twine
python -m build

Publishing to PyPI

# Test PyPI
twine upload --repository testpypi dist/*

# Production PyPI
twine upload dist/*

Requirements

• Python 3.10+
• Access to a Siemens Graph Studio instance
• Valid user credentials with GraphMart access

License

Apache License 2.0 - See LICENSE for details.

Related

• Model Context Protocol - The MCP specification
• Siemens Graph Studio - Knowledge graph platform
• FastMCP - Python MCP framework

Support

For issues and feature requests, please use the GitHub Issues page.