Getting Started with KGraph-MCP¶

Welcome to KGraph-MCP! This guide will help you set up the development environment and start exploring our intelligent MCP orchestration platform.

Prerequisites

Python 3.11.8 or higher
Git for version control
4GB+ RAM for development
Internet connection for package downloads

Quick Setup (Recommended)¶

The fastest way to get started is using our automated setup system:

1. Clone the Repository¶

git clone https://github.com/BasalGanglia/kgraph-mcp-hackathon.git
cd kgraph-mcp-hackathon

2. Run Automated Setup¶

# This installs Python 3.11.8, creates venv, installs dependencies, and initializes tasks
just setup

One-Command Setup

The just setup command handles everything automatically:

✅ Installs Python 3.11.8 with uv
✅ Creates virtual environment
✅ Installs all dependencies (69+ packages)
✅ Initializes task management system
✅ Sets up development tools

3. Activate Environment & Start Application¶

# Activate the virtual environment
source .venv/bin/activate

# Start the development server with hot reload
just dev

The application will be available at: - Main App: http://localhost:7860 (Gradio UI) - API Docs: http://localhost:8000/docs (FastAPI) - Health Check: http://localhost:8000/health

Manual Setup (Alternative)¶

If you prefer manual control or the automated setup doesn't work:

1. Python Environment¶

# Install Python 3.11.8 using uv
uv python install 3.11.8

# Create virtual environment
uv venv .venv --python 3.11.8

# Activate environment
source .venv/bin/activate

2. Dependencies¶

# Generate lock file and install dependencies
just lock
just install

# Or manually install
uv pip sync requirements.lock

3. Verify Installation¶

# Run comprehensive checks
just check

# Individual checks
just lint-check      # Code linting
just format-check    # Code formatting
just type-check      # Type checking
just test           # Run tests

Development Workflow¶

Essential Commands¶

KGraph-MCP includes 30+ automation commands via justfile:

Core DevelopmentTask ManagementQuality & Maintenance

# Start development server
just dev                    # Development mode with reload
just run-app               # Production mode
just run-api               # API server only

# Code quality
just check                 # Run all quality checks
just format                # Format code with Black + Ruff
just lint                  # Lint and auto-fix with Ruff
just type-check            # MyPy type checking
just test                  # Run pytest suite
just test-cov              # Test with coverage report

# View tasks
just tasks                 # List all tasks (GitHub + local)
just task-next             # Get next available task
just tasks-status Done     # Filter by status

# Work with tasks
just task-start 5          # Start task #5
just task-review 5         # Move to review
just task-done 5           # Complete task

# Pre-commit checks
just pre-commit            # Run before committing

# Environment maintenance
just update                # Update dependencies
just clean                 # Clean caches
just clean-all             # Deep clean (removes venv)

Project Structure Overview¶

kgraph-mcp-hackathon/
├── agents/                 # AI Agent Framework (planned)
├── api/                   # FastAPI backend
│   ├── core/             # Core API functionality
│   ├── models/           # Data models
│   ├── routes/           # API endpoints
│   └── services/         # Business logic
├── docs/                 # Comprehensive documentation
├── kg_services/          # Knowledge Graph services
├── scripts/              # Automation scripts
├── tests/                # Comprehensive test suite
├── app.py                # Main application entry
├── justfile              # Development automation
└── requirements*.txt     # Dependency management

Exploring the Platform¶

1. Web Interface¶

Once the development server is running, explore the Gradio interface:

Task Management Tab: View and manage development tasks
Knowledge Graph Tab: Visualize MCP primitives (coming soon)
Agent Interaction Tab: Chat with AI agents (planned)

2. API Exploration¶

The FastAPI backend provides comprehensive APIs:

# Open interactive API documentation
open http://localhost:8000/docs

# Key endpoints
curl http://localhost:8000/health          # Health check
curl http://localhost:8000/api/tasks       # Task management
curl http://localhost:8000/api/kg/tools    # Knowledge graph (planned)

3. Task Management System¶

KGraph-MCP includes a sophisticated task management system:

# View current development tasks
just tasks

# Example output:
# 📋 Current tasks:
# 🔗 GitHub Issues (BasalGanglia/kgraph-mcp-hackathon):
# 1: Implement Knowledge Graph Core [open]
# 2: Build Agent Framework [open]
# 
# 📄 Local Task Database:
# [1] Todo: Complete Sprint 0 setup
# [2] In Progress: Implement FastAPI Application Structure

Development Best Practices¶

Code Quality Standards¶

KGraph-MCP enforces enterprise-grade quality standards:

Type Safety: 100% MyPy strict mode compliance
Code Style: Black 25.1 formatting + Ruff linting (50+ rules)
Testing: 80%+ code coverage requirement
Security: Bandit security scanning + dependency checking

Git Workflow¶

# Create feature branch for task
just branch-create 5 knowledge_graph_core

# Pre-commit quality checks
just pre-commit

# Recommended commit message format
git commit -m "feat(kg): implement knowledge graph core structure

- Add Neo4j integration for graph storage
- Implement MCP primitive models
- Add semantic query capabilities

Closes #5"

Testing¶

# Run all tests
just test

# Run with coverage
just test-cov

# Run specific test file
just test-file tests/test_knowledge_graph.py

# Run only fast tests (exclude slow integration tests)
just test-fast

Next Steps¶

Now that you have KGraph-MCP running, here are recommended next steps:

For Users¶

User Guide - Deep dive into features and usage
Architecture Overview - Understand the system design
Examples - See KGraph-MCP in action

For Developers¶

Developer Guide - Detailed development setup
Contributing - How to contribute to the project
API Reference - Complete API documentation
Active Tasks - Pick up development tasks

For Project Managers¶

Project Progress - Current development status
Sprint Reports - Sprint planning and execution
Development Workflow - Process and automation

Troubleshooting¶

Common Issues¶

Virtual Environment Issues

Problem: just setup fails with environment errors

Solution:

# Clean and retry
just clean-all
uv python install 3.11.8
just setup

Dependency Conflicts

Problem: Package installation fails

Solution:

# Regenerate lock file
just clean
just lock
just install

Port Already in Use

Problem: Cannot start development server

Solution:

# Find and kill process using port 7860
lsof -ti:7860 | xargs kill -9

# Or use different port
APP_PORT=7861 just dev

Getting Help¶

Documentation: Browse this comprehensive documentation site
Issues: Report bugs on GitHub Issues
Discussions: Join conversations in GitHub Discussions

Development Metrics

Use just stats to see project statistics:

Lines of Python code
Test coverage percentage
Number of tasks completed
Development velocity metrics

Ready to dive deeper? Explore our comprehensive documentation or jump into development tasks!