docs/resources/faq.md

---
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?**
```bash
# 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:

```bash
# 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:

```bash
# 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?**
```bash
# 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?**
```bash
# 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

```bash
# 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?**
```bash
# 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:
```bash
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:

```json
{
  "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:

```bash
# 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?**
```bash
# 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?**
```bash
# 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](../api/index.md)
- **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?**
```bash
# 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:

```bash
# 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?**
```bash
# 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](troubleshooting.md)
2. **GitHub Issues**: [Report problems](https://github.com/BasalGanglia/kgraph-mcp-hackathon/issues)
3. **Developer Guide**: [Development setup](../developer-guide/index.md)

## 📈 **Performance & Scaling**

### **How do I monitor performance?**
```bash
# 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](../user-guide/deployment.md) 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](troubleshooting.md) for technical issues
- Browse the [User Guide](../user-guide/index.md) for usage instructions  
- Review the [Developer Guide](../developer-guide/index.md) for development topics
- Search [GitHub Issues](https://github.com/BasalGanglia/kgraph-mcp-hackathon/issues) for similar questions
- [Create a new issue](https://github.com/BasalGanglia/kgraph-mcp-hackathon/issues/new) if you need help

---

*Last updated: Documentation generated from KGraph-MCP project*

---

*This page is part of the [Resources](index.md) documentation section.*