Metadata-Version: 2.4
Name: siemens-graph-studio-mcp-server
Version: 0.4.4
Summary: MCP (Model Context Protocol) server for Siemens Graph Studio - enables AI agents to interact with knowledge graphs via SPARQL
Project-URL: Homepage, https://github.com/siemens/graph-studio-mcp-server
Project-URL: Documentation, https://github.com/siemens/graph-studio-mcp-server#readme
Project-URL: Repository, https://github.com/siemens/graph-studio-mcp-server
Project-URL: Issues, https://github.com/siemens/graph-studio-mcp-server/issues
Project-URL: Changelog, https://github.com/siemens/graph-studio-mcp-server/blob/main/CHANGELOG.md
Author-email: Boris Shalumov <boris.shalumov@siemens.com>
Maintainer-email: Boris Shalumov <boris.shalumov@siemens.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,graph-studio,knowledge-graph,llm,mcp,model-context-protocol,ontology,rdf,siemens,sparql
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: asyncio-throttle>=1.0.0
Requires-Dist: instructor>=1.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pyanzo>=3.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rdflib>=7.0.0
Requires-Dist: starlette>=0.35.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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.4.x

- **✅ 0.4.4**: `explanation` parameter is now optional in all graphmart layer/step tools — no longer a required field
- **🔌 0.4.3**: Fixed REST API HTTP 400 errors by adding missing `Accept: */*` header
- **📦 0.4.2**: Removed external `anzo-api-wrapper` dependency — replaced with a self-contained `AnzoRestClient` using Python stdlib only (no more `requests==2.31.0` conflicts)
- **🔄 0.4.0**: All 11 graphmart tools migrated from SPARQL journal writes to the REST API

See [CHANGELOG.md](CHANGELOG.md) for full details.

## VS Code Setup (Recommended)

> **No API_KEY needed!** GitHub Copilot handles natural language — the MCP server only needs credentials to connect to your Graph Studio instance.

### Step 1 — Install the package

```bash
pipx install siemens-graph-studio-mcp-server
# Verify it works:
siemens-graph-studio-mcp --verify
```

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

### Step 2 — Gather your Graph Studio credentials

You need four connection values from your Graph Studio administrator or the Graph Studio UI:

| Variable | Where to find it | Example |
|---|---|---|
| `ANZO_SERVER` | Hostname of your Graph Studio server | `graphstudio.mycompany.com` |
| `ANZO_PORT` | HTTP/HTTPS port (check with your admin) | `8443` |
| `ANZO_USERNAME` | Your Graph Studio login username | `jsmith` |
| `ANZO_PASSWORD` | Your Graph Studio login password | `••••••••` |
| `GRAPHMART_URI` | URI of the target GraphMart (see below) | `http://…/Graphmart/abc123` |

**How to find your GRAPHMART_URI:**
1. Open Graph Studio in a browser and log in
2. Navigate to the GraphMart you want to use
3. Click the GraphMart name to open its detail view
4. Copy the URI from the browser address bar — it looks like:
   ```
   http://graphstudio.mycompany.com:8443/graphmart/view?datasource=http%3A%2F%2F...%2FGraphmart%2Fabc123
   ```
5. Decode the `datasource=` parameter value — that decoded URL is your `GRAPHMART_URI`:
   ```
   http://cambridgesemantics.com/Graphmart/abc123
   ```
   Alternatively, in Graph Studio go to **Settings → GraphMart Info** — the URI is shown there directly.

### Step 3 — Create `.vscode/mcp.json`

In your project root, create the file `.vscode/mcp.json`:

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

> **Tip:** Auto-generate a template with the correct command path:
> ```bash
> cd your-project
> siemens-graph-studio-mcp --setup-vscode
> # Then edit .vscode/mcp.json to fill in your real values
> ```

> **Command not in PATH?** Use the full absolute path:
> ```json
> "command": "/Users/yourname/.local/bin/siemens-graph-studio-mcp"
> ```
> Find it with: `which siemens-graph-studio-mcp`

### Step 4 — Enable MCP in VS Code

1. Open Settings (`Cmd+,` / `Ctrl+,`)
2. Search for **`chat.mcp.enabled`**
3. Enable the checkbox ✓

### Step 5 — Reload and verify

1. `Cmd+Shift+P` → **"Developer: Reload Window"**
2. Open Copilot Chat (`Cmd+Shift+I`)
3. Click the **tools icon** (wrench) — you should see Graph Studio tools listed
4. Try asking:
   - *"What ontologies are available in the GraphMart?"*
   - *"Show me classes in the default ontology"*
   - *"Execute: SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 5"*

> **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 server-side natural language to SPARQL translation
# NOT needed when using VS Code Copilot (Copilot generates SPARQL for you)
# 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"
      }
    }
  }
}
```
the **server** to do natural language to SPARQL translation internally. With Claude Desktop, this enables asking questions like "show me all customers" and having the server convert them to SPARQL automatically
> **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 |server-side NL→SPARQL**. Not needed with VS Code Copilot (Copilot does the NL understanding). All basic SPARQL
| `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.
