# Siemens Graph Studio MCP Server

[![PyPI version](https://badge.fury.io/py/siemens-graph-studio-mcp-server.svg)](https://badge.fury.io/py/siemens-graph-studio-mcp-server)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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](docs/INSTALLATION_GUIDE.md) 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](CHANGELOG.md) for full details.

## VS Code Quick Start (5 Steps)

**1. Install the package:**
```bash
pipx install siemens-graph-studio-mcp-server
# Verify: siemens-graph-studio-mcp --verify
```

**2. Auto-generate VS Code config (recommended):**
```bash
cd your-project
siemens-graph-studio-mcp --setup-vscode
# Edit .vscode/mcp.json to add your credentials
```

Or create `.vscode/mcp.json` manually:
```json
{
  "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](docs/INSTALLATION_GUIDE.md) for troubleshooting.

## Documentation

- [Installation Guide](docs/INSTALLATION_GUIDE.md) - Detailed setup, troubleshooting, and PATH configuration
- [Agent System Prompt](docs/AGENT_SYSTEM_PROMPT.md) - Recommended workflow and tool usage for AI agents
- [SPARQL Reference](docs/SPARQL_REFERENCE.md) - Query patterns, naming conventions, and troubleshooting
- [Architecture Guide](AGS_Architecture_Guide.md) - Technical architecture overview
- [Skills Documentation](skills/) - Best practices for ontology and linking patterns

## Installation

### Recommended: pipx or uv (Isolated Environment)

```bash
# 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

```bash
pip install siemens-graph-studio-mcp-server
```

### Verify Installation

```bash
siemens-graph-studio-mcp --verify
```

> **Command not found?** See [Installation Guide](docs/INSTALLATION_GUIDE.md#command-not-found-after-installation) for PATH troubleshooting.

## Quick Start

### 1. Configure Environment Variables

```bash
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

```bash
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:

```json
{
  "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"

<details>
<summary><b>⚠️ Troubleshooting VS Code + Copilot</b></summary>

**Command not found in VS Code:**
```jsonc
// 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](docs/INSTALLATION_GUIDE.md)

</details>

### 4. Use with Claude Desktop

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

```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:

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

See [examples/config.example.jsonc](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:
```bash
siemens-graph-studio-mcp
```

### SSE (Server-Sent Events)
For web clients:
```bash
siemens-graph-studio-mcp --transport sse --port 8000
```

### HTTP Streaming
```bash
siemens-graph-studio-mcp --transport streamable-http --port 8000
```

## Programmatic Usage

```python
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
```bash
git clone https://github.com/siemens/graph-studio-mcp-server.git
cd graph-studio-mcp-server
pip install -e ".[dev]"
```

### Running Tests
```bash
pytest
```

### Building for Distribution
```bash
pip install build twine
python -m build
```

### Publishing to PyPI
```bash
# 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](LICENSE) for details.

## Related

- [Model Context Protocol](https://modelcontextprotocol.io/) - The MCP specification
- [Siemens Graph Studio](https://www.siemens.com/) - Knowledge graph platform
- [FastMCP](https://github.com/jlowin/fastmcp) - Python MCP framework

## Support

For issues and feature requests, please use the [GitHub Issues](https://github.com/siemens/graph-studio-mcp-server/issues) page.
