docs/resources/faq.md

metadata

title: Frequently Asked Questions
description: Common questions and answers about KGraph-MCP project

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?

1. Start a task: just task-start <id>
2. Create feature branch: just branch-create <id> <name>
3. Develop with live reload: just dev
4. Run quality checks: just check
5. 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?

1. Python environment: source .venv/bin/activate
2. Dependencies: just install
3. Ports: Check if ports 7860/8000 are available
4. Environment variables: Create .env from .env.example
5. 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?

1. Documentation: Troubleshooting Guide
2. GitHub Issues: Report problems
3. 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.