# RMGS MCP Server

An MCP (Model Context Protocol) server for **Altair Graph Studio (AGS)** that provides intelligent SPARQL query capabilities, ontology management, and graphmart construction tools — all accessible from AI coding assistants like GitHub Copilot, Claude Code, and other MCP-compatible clients.

## Features

- **SPARQL Query Execution** — Run SPARQL queries against AGS graphmarts
- **Knowledge Discovery** — Explore ontologies, classes, and properties
- **Ontology Management** — Create, modify, and delete ontologies
- **Graphmart Construction** — Build and manage transformation layers and steps
- **Agent Memory** — Persistent and ephemeral memory for context retention
- **Dual Modes** — `explore` (read-only, 13 tools) and `create` (all 51 tools)
- **Multiple Transports** — stdio, SSE, and streamable-http

## Installation

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

### Default setup (recommended)

Use this as the baseline setup when installing from PyPI.

1. Create a Python virtual environment:

```bash
python -m venv graph_mcp_env
```

2. Activate the environment:

```bash
source /.../howtomcp/graph_mcp_env/bin/activate
```

3. Install from PyPI:

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

4. Start MCP as two separate servers (recommended):

```bash
siemens-graph-studio-mcp-server --config ags-config.json --mode explore --transport sse --port 8000
siemens-graph-studio-mcp-server --config ags-config.json --mode create --transport sse --port 8001
```

> **Note:** This also installs `rdflib`, which adds `rdfpipe` and `rdfgraphisomorphism` executables to your environment. These are standard rdflib CLI utilities and can be safely ignored.

### From Source

```bash
git clone <repository-url>
cd rmgs-mcp-server
pip install -e .
```

---

## Quick Start

### 1. Create a config file

Save this as `ags-config.json` (e.g., in your home directory or project):

```json
{
  "servers": {
    "my-server": {
      "host": "your-ags-server.example.com",
      "port": 443,
      "username": "your-username",
      "password": "${AGS_PASSWORD}",
      "graphmart_uri": "http://cambridgesemantics.com/Graphmart/your-graphmart-id",
      "default": true
    }
  }
}
```

> **Security:** Use `${ENV_VAR}` references for passwords — they are resolved from environment variables at startup. **Never commit real passwords** to config files.

### 2. Connect your MCP client

Choose your client below.

---

## VS Code — GitHub Copilot (Agent Mode)

### Setup

1. Create `.vscode/mcp.json` in your workspace:

```json
{
  "servers": {
    "ags-sparql-agent": {
      "type": "stdio",
      "command": "siemens-graph-studio-mcp-server",
      "args": ["--config", "/absolute/path/to/ags-config.json"],
      "env": {
        "AGS_PASSWORD": "your-password-here"
      }
    }
  }
}
```

2. Reload VS Code (`Cmd+Shift+P` → "Developer: Reload Window").
3. Open **Copilot Chat** and switch to **Agent mode** (click the mode selector at the top of the chat panel).
4. The AGS tools will appear in the tool list (click the 🔧 icon to verify).

### Usage

Type natural language prompts in Copilot Chat (Agent mode):

```
What ontologies are available in this graphmart?
Show me all classes in the equipment ontology
Run a SPARQL query to count all products
Create a new transformation layer for data linking
```

Copilot will automatically select and call the appropriate MCP tools.

### Running from source (without pip install)

If you prefer to run directly from the cloned repo:

```json
{
  "servers": {
    "ags-sparql-agent": {
      "type": "stdio",
      "command": "python",
      "args": [
        "/absolute/path/to/rmgs_mcp_server/ags_sparql_agent.py",
        "--config", "/absolute/path/to/ags-config.json"
      ],
      "env": {
        "AGS_PASSWORD": "your-password-here"
      }
    }
  }
}
```

---

## Claude Code

### Setup

Add to your project's `.mcp.json` (or `~/.claude.json` for global config):

```json
{
  "mcpServers": {
    "ags-sparql-agent": {
      "command": "siemens-graph-studio-mcp-server",
      "args": ["--config", "/absolute/path/to/ags-config.json"],
      "env": {
        "AGS_PASSWORD": "your-password-here"
      }
    }
  }
}
```

### Usage

In Claude Code, the MCP tools are automatically available. Use natural language:

```
What data is in this knowledge graph?
Show me all properties of the Customer class
Create a linking ontology between orders and products
```

Claude Code will call the appropriate MCP tools to interact with your AGS graphmart.

---

## Advanced Configuration

### Multiple servers

```json
{
  "servers": {
    "production": {
      "host": "prod-ags.example.com",
      "port": 443,
      "username": "your-username",
      "password": "${PROD_PASSWORD}",
      "graphmart_uri": "http://cambridgesemantics.com/Graphmart/prod-id",
      "default": true
    },
    "staging": {
      "host": "staging-ags.example.com",
      "port": 8443,
      "username": "your-username",
      "password": "${STAGING_PASSWORD}"
    }
  }
}
```

The server marked `"default": true` is automatically selected at startup. Switch at runtime using `select_server` and `select_graphmart` tools.

### Agent configuration

```json
{
  "servers": { "...": "..." },
  "agent_config": {
    "max_iterations": 3,
    "query_timeout": 30,
    "cache_ontologies": true,
    "ontology_cache_ttl": 86400
  }
}
```

### Transport options

```bash
# SSE (default)
siemens-graph-studio-mcp-server --config ags-config.json --transport sse --port 8000

# stdio (used by VS Code and Claude Code)
siemens-graph-studio-mcp-server --config ags-config.json

# Streamable HTTP
siemens-graph-studio-mcp-server --config ags-config.json --transport streamable-http --port 8000
```

### Modes

```bash
# Explore mode — read-only tools only (safe for browsing)
siemens-graph-studio-mcp-server --config ags-config.json --mode explore

# Create mode — all tools including write operations (default)
siemens-graph-studio-mcp-server --config ags-config.json --mode create
```

**Explore mode tools (13):**
`list_servers`, `select_server`, `list_graphmarts`, `select_graphmart`, `execute_sparql_query`, `discover_knowledge_overview`, `discover_available_ontologies`, `discover_ontology_classes`, `discover_class_data_properties`, `discover_class_object_properties`, `list_ontology_imports`, `initialize_agent_memory`, `read_agent_memory`

**Create mode** includes all 51 tools (explore + write operations).

> **Legacy:** Direct `ANZO_*` environment variables (without a config file) are still supported but deprecated.

---

## Tool Categories

### System & Monitoring
| Tool | Description |
|---|---|
| `test_system_connection` | Test MCP server and AGS agent status |
| `get_session_logs` | Get session logs and interaction history |
| `list_servers` | List all configured AGS servers |
| `select_server` | Switch to a different AGS server at runtime |
| `list_graphmarts` | List all graphmarts on the active server |
| `select_graphmart` | Switch to a different graphmart at runtime |

### SPARQL Query Execution
| Tool | Description |
|---|---|
| `execute_sparql_query` | Execute SPARQL directly against graphmart |
| `query_ags_configuration` | Query graphmart metadata (local volume) |
| `update_ags_configuration` | Update graphmart metadata with SPARQL |

### Knowledge Discovery
| Tool | Description |
|---|---|
| `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
| Tool | Description |
|---|---|
| `create_ontology` | Create a new ontology |
| `delete_ontology` | Delete an ontology |
| `register_ontology` | Register ontology with graphmart |
| `load_ontology_from_file` | Load TTL files into named graphs |
| `add_ontology_class` | Add a class to an ontology |
| `remove_ontology_class` | Remove a class from an ontology |
| `add_ontology_property` | Add a property to an ontology |
| `remove_ontology_property` | Remove a property from an ontology |
| `add_ontology_import` | Add an import to an ontology |
| `remove_ontology_import` | Remove an import from an ontology |
| `list_ontology_imports` | List imports of an ontology |
| `list_ontology_structure_classes` | List classes in ontology structure |
| `list_ontology_structure_properties` | List properties in ontology structure |
| `get_ontology_cache_status` | Get ontology cache status |
| `clear_ontology_cache` | Clear ontology caches |
| `refresh_ontology_cache` | Force cache refresh |

### Graphmart Construction & Management
| Tool | Description |
|---|---|
| `create_transformation_layer` | Create transformation layers |
| `update_transformation_layer` | Update layer properties |
| `delete_transformation_layer` | Delete transformation layers |
| `list_transformation_layers` | List all transformation layers |
| `add_transformation_step` | Add transformation steps to layers |
| `update_transformation_step` | Update transformation step properties |
| `delete_transformation_step` | Delete transformation steps |
| `list_transformation_steps` | List steps within a layer |
| `add_direct_load_step` | Add direct data loading steps |
| `update_direct_load_step` | Update direct load step properties |
| `add_bookmark_query` | Add a SPARQL query bookmark to graphmart |
| `delete_bookmark_query` | Delete a single bookmark from a graphmart |
| `delete_all_bookmark_queries` | Delete all bookmarks from a graphmart |
| `refresh_graphmart` | Lightweight refresh of changed layers |
| `reload_graphmart` | Complete reprocessing of all layers |
| `get_layer_status` | Comprehensive layer and step error info |
| `get_step_status` | Specific step debugging |

### Agent Memory
| Tool | Description |
|---|---|
| `initialize_agent_memory` | Initialize memory for the agent |
| `write_permanent_memory` | Write to persistent memory |
| `write_ephemeral_memory` | Write to session-scoped memory |
| `promote_ephemeral_memory` | Promote ephemeral to permanent memory |
| `clear_agent_memory` | Clear agent memory |
| `read_agent_memory` | Read from agent memory |

---

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Build package
python -m build
```

### Bump Version

Update the version in both:
- `pyproject.toml` → `version = "x.y.z"`
- `rmgs_mcp_server/__init__.py` → `__version__ = "x.y.z"`

### Publish to PyPI

```bash
pip install build twine
python -m build
twine upload dist/*
```

## Project Structure

```
rmgs-mcp-server/
├── rmgs_mcp_server/           # Main package
│   ├── __init__.py            # Package init with version
│   ├── ags_sparql_agent.py    # MCP server entry point
│   ├── models.py              # Data models
│   ├── server_registry.py     # Multi-server configuration manager
│   ├── sparql_agent_core.py   # Core SPARQL agent logic
│   ├── sparql_query_engine.py # SPARQL query engine
│   ├── ontology_cache.py      # Ontology caching
│   ├── ontology_discovery.py  # Ontology discovery
│   ├── interaction_logger.py  # Logging utilities
│   ├── tools/                 # MCP tool implementations
│   │   ├── base_tool.py       # Base tool class
│   │   ├── system/            # System, server & graphmart tools
│   │   ├── query/             # SPARQL query tools
│   │   ├── discovery/         # Knowledge discovery tools
│   │   ├── ontology/          # Ontology management tools
│   │   ├── graphmart/         # Graphmart construction tools
│   │   └── memory/            # Agent memory tools
│   └── utils/                 # Shared utilities
├── prompts/                   # Agent prompt templates
├── skills/                    # Best practices guides
├── pyproject.toml             # Package metadata & build config
├── LICENSE                    # MIT License
└── README.md                  # This file
```

## License

MIT