Metadata-Version: 2.4
Name: siemens-graph-studio-mcp-server
Version: 0.2.0
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

## Documentation

- [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

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

## 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: For natural language queries
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"

**Troubleshooting VS Code + Copilot:**
- If MCP tools don't appear, run "Developer: Reload Window" (`Ctrl+Shift+P` → Reload)
- Check Output panel → "MCP" for connection errors
- Ensure the server is installed: `pip install siemens-graph-studio-mcp-server`
- Verify environment variables are correct (test with `siemens-graph-studio-mcp` in terminal first)

### 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 but enables advanced natural language to SPARQL translation.

## 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 for NL queries |
| `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.
