vAirpower/Stardog-MCP-Server

Stardog MCP Server & AWS Strands Integration

🤖 Claude 3.7 Sonnet + AWS Strands Agent + Stardog Knowledge Graphs = Intelligent GEOINT Analysis

🏗️ Architecture Overview

This repository contains two interconnected components that work together to provide an intelligent, conversational interface to Stardog knowledge graphs:

┌─────────────────┐    HTTP/MCP     ┌─────────────────┐    SPARQL/GraphQL    ┌─────────────────┐
│  Streamlit App  │ ────────────── │   MCP Server    │ ──────────────────── │   Stardog DB    │
│                 │                │                 │                      │                 │
│ • Claude 3.7    │                │ • SPARQL Tools  │                      │ • Knowledge     │
│ • AWS Strands   │                │ • GraphQL API   │                      │   Graph         │
│ • Chat UI       │                │ • Schema Tools  │                      │ • GEOINT Data   │
│ • Port 8501     │                │ • Port 8000     │                      │ • Semantic Web  │
└─────────────────┘                └─────────────────┘                      └─────────────────┘

🔧 MCP Server (mcp-server/)

• Purpose: Custom Model Context Protocol server for Stardog knowledge graphs
• Capabilities:
  • SPARQL query execution and optimization
  • GraphQL API for modern applications
  • Schema discovery and ontology exploration
  • Natural language to SPARQL conversion
• Deployment: Local development, Docker, or AWS ECS
• Port: 8000
• Technology: Python, FastAPI, MCP Protocol

🖥️ Streamlit App (streamlit-app/)

• Purpose: Interactive chatbot with autonomous reasoning capabilities
• AI Model: Claude 3.7 Sonnet via AWS Bedrock Converse API
• Agent Framework: AWS Strands for intelligent tool orchestration
• Features:
  • Natural language GEOINT queries
  • Real-time knowledge graph exploration
  • Multi-turn conversations with context
  • Visual query suggestions and examples
• Port: 8501
• Technology: Streamlit, AWS Bedrock, Strands Agent

🚀 Quick Start

Option 1: Docker Compose (Recommended)

# Clone the repository
git clone https://github.com/vAirpower/Stardog-MCP-Server.git
cd Stardog-MCP-Server

# Copy and configure environment files
cp mcp-server/.env.example .env
cp streamlit-app/.env.example .env.local

# Edit .env files with your Stardog and AWS configuration
nano .env      # Configure Stardog connection
nano .env.local # Configure AWS Bedrock and Claude

# Start both services
docker-compose up --build

Access the application:

• 🖥️ Streamlit App: http://localhost:8501
• 🔧 MCP Server: http://localhost:8000
• 📊 Health Check: http://localhost:8000/health

Option 2: Manual Setup

# Terminal 1: Start MCP Server
cd mcp-server
pip install -r requirements.txt
python -m stardog_mcp_server.server

# Terminal 2: Start Streamlit App  
cd streamlit-app
pip install -r requirements.txt
streamlit run app.py

Option 3: Demo Mode (No Stardog Required)

For testing without a Stardog instance, use the built-in demo server with synthetic GEOINT data:

# Start demo with synthetic data
docker-compose --profile demo up

# Or manually
cd streamlit-app
python standalone_server.py &
streamlit run app.py

🔗 How Components Connect

1. MCP Server exposes Stardog capabilities through standardized MCP tools over HTTP
2. Streamlit App connects using the HTTP MCP Client for seamless integration
3. AWS Strands Agent orchestrates Claude 3.7 Sonnet + MCP tools for autonomous reasoning
4. Real-time queries enable conversational knowledge graph exploration

Example Interaction Flow:

User: "What military facilities are near Washington DC?"
  ↓
Strands Agent: Analyzes query → Calls MCP tools → Executes SPARQL
  ↓
MCP Server: Queries Stardog → Returns structured results
  ↓
Claude 3.7: Processes results → Generates natural language response
  ↓
User: Receives comprehensive answer with facility details

🛠️ Configuration

MCP Server Configuration

# mcp-server/.env
STARDOG_ENDPOINT=http://localhost:5820
STARDOG_USERNAME=admin
STARDOG_PASSWORD=admin
STARDOG_DATABASE=stardog
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=8000

Streamlit App Configuration

# streamlit-app/.env
AWS_REGION=us-east-1
BEDROCK_MODEL_ID=us.anthropic.claude-3-7-sonnet-20250219-v1:0
FUSEKI_MCP_SERVER_URL=http://localhost:8000
STREAMLIT_SERVER_PORT=8501

📚 Documentation

• - Setup, API reference, and deployment
• - Configuration, features, and usage
• - Technical deep-dive
• - AWS ECS and production setup
• - Getting started tutorial
• - Security best practices

🧪 Example Queries

Once running, try these sample queries in the Streamlit interface:

• "What facilities are in Virginia?" - Geographic filtering
• "Find all military bases with coordinates" - Type-based search
• "Show me the database schema" - Ontology exploration
• "What's connected to the Pentagon?" - Relationship queries
• "Convert this to SPARQL: Find airports" - Natural language processing

🏗️ Development

Project Structure

Stardog-MCP-Server/
├── mcp-server/                 # MCP Server component
│   ├── src/stardog_mcp_server/ # Core server implementation
│   ├── infrastructure/         # CDK deployment code
│   └── README.md               # Server-specific documentation
├── streamlit-app/              # Streamlit Application
│   ├── app.py                  # Main Streamlit application
│   ├── strands_agent.py        # AWS Strands integration
│   ├── mcp_http_client.py      # MCP client implementation
│   └── README.md               # App-specific documentation
├── deployment/                 # CloudFormation templates
├── docs/                       # Comprehensive documentation
└── docker-compose.yml          # Multi-service orchestration

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

🔧 Deployment

Local Development

• Use docker-compose for full stack development
• Individual components can be run separately for focused development

Production (AWS ECS)

• CloudFormation templates in deployment/
• CDK infrastructure code in mcp-server/infrastructure/
• See for detailed instructions

📊 Monitoring

• MCP Server Health: GET /health
• Metrics Endpoint: GET /metrics
• Streamlit Status: Built-in Streamlit monitoring
• AWS CloudWatch: Production monitoring and alerting

🤝 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See directory

📄 License

This project is licensed under the MIT License - see the file for details.

🌟 Acknowledgments

• Anthropic for Claude 3.7 Sonnet
• AWS for Bedrock and Strands Agent framework
• Stardog for the knowledge graph platform
• Model Context Protocol for standardized AI tool integration

Ready to explore your knowledge graphs with AI? 🚀

Get started with: docker-compose up --build