AGS SPARQL Agent MCP Server v2.1

LLM-Driven SPARQL Generation with Streamable HTTP Transport 🚀

An intelligent MCP server that provides SPARQL query generation and execution capabilities for AGS (Anzo Graph Server) instances. This version uses the latest MCP SDK with Streamable HTTP transport (recommended for production) and eliminates the need for external API keys.

🚀 Quick Start

Prerequisites

• Python 3.10+
• Access to an AGS instance with graphmart data

Installation

cd Altair_Graph_MCP_HTTP
pip install -r requirements.txt

Configuration

Create a .env file with your AGS credentials:

ANZO_SERVER=your-ags-server
ANZO_PORT=443
ANZO_USERNAME=your-username
ANZO_PASSWORD=your-password
GRAPHMART_URI=http://your-graphmart-uri

Run the Server

python src/ags_sparql_agent_server.py

Expected output:

🚀 Starting AGS SPARQL Agent MCP Server (Streamable HTTP Transport)
🔧 Configuration: HOST=0.0.0.0, PORT=8000
🔧 Mode: Stateless (recommended)
✅ FastMCP server created for Streamable HTTP transport
✅ 42 tools registered successfully
✅ 3 prompts registered successfully
📡 Starting MCP server with Streamable HTTP transport...
🌐 MCP endpoint: http://0.0.0.0:8000/mcp

Connect to the Server

The MCP endpoint is available at http://localhost:8000/mcp. Use POST requests to send MCP protocol messages.

Example with Claude Code:

claude mcp add --transport http my-ags-server http://localhost:8000/mcp

✨ Features

MCP Tools (43 Total)

New SPARQL Generation Tools

• get_sparql_generation_context - Get LLM-optimized ontology context
• validate_sparql_syntax - Validate queries before execution
• get_sparql_examples - Get working query examples

Tool Categories

• System & Monitoring (2 tools)
• SPARQL Query Execution (3 tools)
• Knowledge Discovery (5 tools)
• Ontology Management (10 tools)
• Graphmart Construction (10 tools)
• Graphmart Management (2 tools)
• Graphmart Diagnostics (2 tools)

MCP Prompts (3 Total)

• generate_sparql_query - Step-by-step SPARQL generation guide
• improve_sparql_query - Fix failed queries based on errors
• sparql_best_practices - AGS-specific best practices reference

🎯 Usage Examples

Example Query Flow

User: "How many products are in the knowledge graph?"

Claude Response:

I'll help you query the knowledge graph:

1. Getting ontology context...
   [Calls: get_sparql_generation_context]
   Found: c:0 = Product (1,234 instances)

2. Generating SPARQL query:
   SELECT (COUNT(?product) as ?count)
   WHERE { ?product a c:0 }

3. Validating...
   [Calls: validate_sparql_syntax]
   ✅ Valid query

4. Executing...
   [Calls: execute_sparql_query]
   Result: 1,234 products

Answer: There are 1,234 products in the knowledge graph.

🎓 Query Examples

Simple Count Query

User: "How many customers do we have?"
→ Generated SPARQL: SELECT (COUNT(?customer) as ?count) WHERE { ?customer a c:5 }
→ Result: 2,567 customers

Filtered Search Query

User: "Find products with 'bike' in the name"
→ Generated SPARQL: 
   SELECT ?product ?name WHERE { 
     ?product a c:0 ; p:0 ?name .
     FILTER(CONTAINS(LCASE(?name), "bike"))
   } LIMIT 20
→ Result: List of bike products

Iterative Query Improvement

User: "Show me orders and their products"
→ First attempt fails (no results)
→ System uses improve_sparql_query prompt
→ Makes relationships OPTIONAL
→ Second attempt succeeds
→ Result: Orders with and without products

🧪 Testing

Quick Validation

Start the server and verify the output:

python src/ags_sparql_agent_server.py

Look for these success indicators:

• ✅ FastMCP server created for Streamable HTTP transport
• ✅ 42 tools registered
• ✅ 3 prompts registered
• 🌐 MCP endpoint available at /mcp

Test Queries

Try these sample questions:

1. "How many entities are in the graph?"
2. "Find products containing 'bike'"
3. "Which customers have placed orders?"
4. "Show the average order value per customer"

Expected Query Flow

Each query should follow this pattern:

• ✅ Get ontology context
• ✅ Generate SPARQL internally
• ✅ Validate before executing
• ✅ Execute successfully
• ✅ Return natural language response

🚂 Railway Deployment

This server is optimized for Railway deployment. The server automatically:

• Binds to 0.0.0.0 for cloud accessibility
• Uses the PORT environment variable provided by Railway
• Runs in stateless mode for optimal scalability

Deploy with:

railway up

The MCP endpoint will be available at: https://your-app.railway.app/mcp