Frequently Asked Questions¶

Common questions and detailed answers about the KGraph-MCP project.

🔧 General Questions¶

What is KGraph-MCP?¶

KGraph-MCP is a knowledge graph-powered Model Context Protocol implementation that enables intelligent tool management and orchestration. It combines semantic knowledge representation with MCP server capabilities to provide context-aware tool recommendations and execution.

What are the system requirements?¶

Python: 3.11.8 or higher
Node.js: 16.0 or higher (for certain tooling)
Git: 2.0 or higher
Operating System: Linux, macOS, or Windows (with WSL2)
Memory: 4GB RAM minimum, 8GB recommended
Storage: 2GB free space

How do I get started quickly?¶

# Clone and setup in one go
git clone https://github.com/BasalGanglia/kgraph-mcp-hackathon.git
cd kgraph-mcp-hackathon
just setup
just dev

📦 Installation & Setup¶

Why am I getting Python version errors?¶

KGraph-MCP requires Python 3.11.8+. The just setup command automatically installs the correct version using uv. If you're still having issues:

# Check your Python version
python --version

# Force reinstall with uv
uv python install 3.11.8
uv venv .venv --python 3.11.8

What if `just` command is not found?¶

Install Just using one of these methods:

# Using cargo (recommended)
cargo install just

# Using homebrew (macOS)
brew install just

# Using apt (Ubuntu/Debian)
sudo apt install just

How do I reset my development environment?¶

# Complete reset
just clean-all
just setup

# Partial reset (keep dependencies)
just clean
just install

🔨 Development¶

What's the recommended development workflow?¶

Start a task: just task-start <id>
Create feature branch: just branch-create <id> <name>
Develop with live reload: just dev
Run quality checks: just check
Submit changes: Standard git workflow

How do I run tests?¶

# All tests
just test

# With coverage
just test-cov

# Fast tests only
just test-fast

# Specific test file
just test-file tests/test_specific.py

What linting and formatting tools are used?¶

Linting: Ruff (replaces flake8, isort, and more)
Formatting: Black with line length 88
Type Checking: MyPy
Security: Bandit and Safety

# Run all quality checks
just check

# Individual tools
just lint        # Ruff with auto-fix
just format      # Black formatting
just type-check  # MyPy type checking
just security    # Security scans

🌐 Application & API¶

What ports does the application use?¶

FastAPI + Gradio: Port 7860 (default)
FastAPI only: Port 8000 (with just run-api)
Documentation: Port 8001 (with just docs-serve)

How do I access the different interfaces?¶

# Start full application (FastAPI + Gradio)
just run-app
# Access at: http://localhost:7860

# Start development mode with auto-reload
just dev
# Access at: http://localhost:7860

# Start API server only
just run-api  
# Access at: http://localhost:8000/docs

Can I change the default ports?¶

Yes, set environment variables:

export GRADIO_PORT=7861
export API_PORT=8001
just dev

📊 Knowledge Graph & Data¶

What knowledge graph technologies are used?¶

In-Memory Store: Custom Python implementation
Query Language: SPARQL-like interface
Embeddings: Hugging Face Transformers
Schema: JSON Schema with RDF-like semantics

How is tool metadata stored?¶

Tool metadata is stored in a knowledge graph structure with: - Nodes: Tools, parameters, categories - Edges: Relationships, dependencies, compatibility - Properties: Metadata, descriptions, constraints

Can I add custom tools?¶

Yes! Tools are defined in JSON schema format:

{
  "name": "my_custom_tool",
  "description": "Custom tool description",
  "parameters": {...},
  "category": "utility",
  "tags": ["custom", "utility"]
}

Add to the appropriate schema file and restart the application.

🤖 MCP Integration¶

What is the Model Context Protocol (MCP)?¶

MCP is an open protocol that enables AI models to securely access external tools and data sources. KGraph-MCP implements MCP to provide structured tool access with semantic understanding.

How do I connect to MCP clients?¶

KGraph-MCP runs as an MCP server. Connect from MCP-compatible clients:

# Server endpoint
ws://localhost:7860/mcp

# Or use the HTTP API
http://localhost:7860/api/v1/mcp

What MCP features are supported?¶

✅ Tool discovery and execution
✅ Resource access (files, data)
✅ Structured prompts
✅ Logging and observability
🔄 Streaming (in development)
🔄 Authentication (in development)

📚 Documentation¶

How do I build the documentation locally?¶

# Build documentation
just docs

# Serve locally with live reload
just docs-serve
# Access at: http://localhost:8001

# Watch for changes during development
just docs-watch

How do I deploy documentation to GitHub Pages?¶

# Deploy to GitHub Pages
just docs-deploy

# Or let GitHub Actions handle it
git push origin main  # Triggers automatic deployment

Where can I find API documentation?¶

Online: API Reference
Local: just docs-serve then visit /api/
Interactive: just run-api then visit /docs

🔧 Task Management¶

How does the task management system work?¶

KGraph-MCP includes a comprehensive task management system:

Local Database: SQLite-based task storage
GitHub Integration: Sync with GitHub Issues and Projects
Just Commands: CLI interface for task operations

How do I create and manage tasks?¶

# List all tasks
just tasks

# Create new task
just task-create "Task title" "Description"

# Start working on a task
just task-start <id>

# Complete a task
just task-done <id>

# View GitHub project status
just tasks-github

Can I sync tasks with GitHub?¶

Yes! The system provides bidirectional sync:

# Sync completed tasks to GitHub
just gh-sync-completed

# Create structured GitHub issues
just gh-create-structured-task <id>

# Full GitHub integration
just gh-sync-all

🐛 Troubleshooting¶

The application won't start. What should I check?¶

Python environment: source .venv/bin/activate
Dependencies: just install
Ports: Check if ports 7860/8000 are available
Environment variables: Create .env from .env.example
Logs: Check console output for specific errors

Tests are failing. How do I debug?¶

# Run tests with verbose output
just test -v

# Run specific failing test
just test-file tests/test_failing.py -v -s

# Check test coverage
just test-cov

Where can I get help?¶

Documentation: Troubleshooting Guide
GitHub Issues: Report problems
Developer Guide: Development setup

📈 Performance & Scaling¶

How do I monitor performance?¶

# System statistics
just stats

# Memory profiling
just profile-memory

# Process monitoring
just monitor

What are the performance characteristics?¶

Startup Time: ~2-5 seconds
Memory Usage: ~100-200MB base
Request Latency: <100ms for simple operations
Concurrent Users: 10-50 (depending on operations)

How can I improve performance?¶

Use SSD storage for better I/O
Increase available RAM
Enable response caching
Use production ASGI server (Gunicorn + Uvicorn)

🔗 Integration & Deployment¶

Can I deploy to production?¶

Yes! See the Deployment Guide for: - Docker deployment - Cloud platform setup - Environment configuration - Security considerations

What about CI/CD?¶

GitHub Actions workflows are included for: - Testing: Automated test runs - Quality: Linting and type checking
- Documentation: Automatic deployment to GitHub Pages - Releases: Automated versioning and releases

How do I integrate with other systems?¶

KGraph-MCP provides multiple integration points: - REST API: HTTP endpoints for all functionality - WebSocket: Real-time communication - MCP Protocol: Standard protocol for AI model integration - CLI Tools: Command-line automation

💡 Can't find your question?¶

Check the Troubleshooting Guide for technical issues
Browse the User Guide for usage instructions
Review the Developer Guide for development topics
Search GitHub Issues for similar questions
Create a new issue if you need help

Last updated: Documentation generated from KGraph-MCP project

This page is part of the Resources documentation section.