A newer version of the Gradio SDK is available:
6.1.0
metadata
title: Getting Started with KGraph-MCP
description: Quick setup guide to get KGraph-MCP running in minutes
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.
!!! info "Prerequisites" - Python 3.11.8 or higher - Git for version control - 4GB+ RAM for development - Internet connection for package downloads
🚀 Quick Start Journey
User Journey Overview
journey
title Getting Started with KGraph-MCP
section Setup
Clone Repository : 5: Developer
Run Automated Setup : 5: Developer
Verify Installation : 4: Developer
section First Steps
Explore Web Interface : 5: Developer
Check API Documentation : 4: Developer
View Available Tasks : 5: Developer
section Development
Get First Task : 5: Developer
Start Development : 5: Developer
Run Quality Checks : 4: Developer
section Exploration
Try MCP Integration : 3: Developer
Explore Knowledge Graph : 3: Developer
Test AI Agents : 3: Developer
Setup Process Flow
flowchart TD
Start([👋 Welcome to KGraph-MCP]) --> Check{Prerequisites Met?}
Check -->|✅ Yes| Clone[📥 Clone Repository]
Check -->|❌ No| Install[🔧 Install Prerequisites]
Install --> Pyenv[Install Python 3.11.8]
Pyenv --> Git[Install Git]
Git --> Clone
Clone --> Setup{Choose Setup Method}
Setup -->|🚀 Automated| AutoSetup[just setup]
Setup -->|🔧 Manual| ManualSetup[Manual Steps]
AutoSetup --> Python[🐍 Install Python 3.11.8]
Python --> VEnv[📦 Create Virtual Environment]
VEnv --> Deps[⬇️ Install Dependencies]
Deps --> TaskInit[📋 Initialize Tasks]
TaskInit --> Success[✅ Setup Complete]
ManualSetup --> UVInstall[uv python install 3.11.8]
UVInstall --> VEnvManual[uv venv .venv]
VEnvManual --> Activate[source .venv/bin/activate]
Activate --> SyncDeps[uv pip sync requirements.lock]
SyncDeps --> Success
Success --> Verify[🔍 Verify Installation]
Verify --> Health{Health Checks Pass?}
Health -->|✅ Pass| Ready[🎉 Ready to Develop!]
Health -->|❌ Fail| Debug[🐛 Debug Issues]
Debug --> Verify
Ready --> FirstSteps[🏁 First Steps]
style Start fill:#e3f2fd
style AutoSetup fill:#e8f5e8
style Success fill:#c8e6c9
style Ready fill:#c8e6c9
style Debug fill:#ffebee
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
Automated Setup Process
sequenceDiagram
participant User
participant Just as Just Command
participant UV as UV Package Manager
participant Python as Python 3.11.8
participant VEnv as Virtual Environment
participant Deps as Dependencies
participant Tasks as Task System
User->>Just: just setup
Just->>UV: Check UV installation
UV-->>Just: UV ready
Just->>Python: Install Python 3.11.8
Python-->>Just: Python installed
Just->>VEnv: Create .venv environment
VEnv-->>Just: Environment created
Just->>Deps: Install dependencies
Note over Deps: 69+ packages installed
Deps-->>Just: Dependencies ready
Just->>Tasks: Initialize task system
Tasks-->>Just: Tasks initialized
Just-->>User: ✅ Setup complete!
Note over User,Tasks: Environment ready for development
!!! success "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
Application Startup Flow
flowchart LR
Activate[Activate Virtual Environment] --> DevCommand[just dev]
DevCommand --> Parallel{Start Services}
Parallel --> Gradio[🎨 Gradio Interface<br/>localhost:7860]
Parallel --> API[🔌 FastAPI Server<br/>localhost:8000]
Parallel --> Docs[📚 Documentation<br/>localhost:8001]
Gradio --> Ready[🎉 All Services Ready]
API --> Ready
Docs --> Ready
Ready --> Explore[🔍 Start Exploring]
style Activate fill:#e3f2fd
style Parallel fill:#e8f5e8
style Ready fill:#c8e6c9
style Explore fill:#fff3e0
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:
Manual Setup Process
graph TD
subgraph "🐍 Python Environment"
UVPython[uv python install 3.11.8]
CreateVEnv[uv venv .venv --python 3.11.8]
ActivateVEnv[source .venv/bin/activate]
end
subgraph "📦 Dependencies"
LockFile[just lock]
InstallDeps[just install]
SyncDeps[uv pip sync requirements.lock]
end
subgraph "✅ Verification"
LintCheck[just lint-check]
FormatCheck[just format-check]
TypeCheck[just type-check]
TestCheck[just test]
end
UVPython --> CreateVEnv
CreateVEnv --> ActivateVEnv
ActivateVEnv --> LockFile
LockFile --> InstallDeps
InstallDeps --> SyncDeps
SyncDeps --> LintCheck
LintCheck --> FormatCheck
FormatCheck --> TypeCheck
TypeCheck --> TestCheck
TestCheck --> ManualComplete[✅ Manual Setup Complete]
style UVPython fill:#e3f2fd
style SyncDeps fill:#e8f5e8
style TestCheck fill:#f3e5f5
style ManualComplete fill:#c8e6c9
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 Overview
mindmap
root((Just Commands))
Core Development
just dev
just run-app
just run-api
Code Quality
just check
just format
just lint
just type-check
just test
Task Management
just tasks
just task-next
just task-start
just task-done
Environment
just setup
just update
just clean
Essential Commands
KGraph-MCP includes 30+ automation commands via justfile:
=== "Core Development"
```bash
# 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
```
=== "Task Management"
```bash
# 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
```
=== "Quality & Maintenance"
```bash
# 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)
```
Development Command Flow
flowchart TD
Developer[👨💻 Developer] --> TaskCheck[just task-next]
TaskCheck --> StartTask[just task-start <id>]
StartTask --> DevLoop{Development Loop}
DevLoop --> Code[💻 Write Code]
Code --> Test[just test]
Test --> Quality[just check]
Quality --> Pass{Quality Pass?}
Pass -->|✅ Yes| Commit[git commit]
Pass -->|❌ No| Fix[🔧 Fix Issues]
Fix --> Code
Commit --> Push[git push]
Push --> PR[Create Pull Request]
PR --> DoneTask[just task-done <id>]
DoneTask --> TaskCheck
style Developer fill:#e3f2fd
style Quality fill:#e8f5e8
style Pass fill:#f3e5f5
style Commit fill:#c8e6c9
style Fix fill:#ffebee
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
Project Structure Visualization
graph TB
subgraph "🏗️ Core Application"
App[app.py<br/>Main Entry Point]
Config[Configuration<br/>Environment Setup]
end
subgraph "🔌 API Layer"
API[api/<br/>FastAPI Backend]
Routes[routes/<br/>HTTP Endpoints]
Models[models/<br/>Data Schemas]
Services[services/<br/>Business Logic]
end
subgraph "🤖 Intelligence Layer"
Agents[agents/<br/>AI Agents]
KG[kg_services/<br/>Knowledge Graph]
Planning[Planning Engine]
Execution[Execution Engine]
end
subgraph "🔧 Development Tools"
Just[justfile<br/>Automation]
Tests[tests/<br/>Test Suite]
Docs[docs/<br/>Documentation]
Scripts[scripts/<br/>Utilities]
end
App --> API
API --> Routes
API --> Models
API --> Services
Services --> Agents
Agents --> KG
Agents --> Planning
Agents --> Execution
Just --> Tests
Just --> Docs
Just --> Scripts
style App fill:#e3f2fd
style API fill:#e8f5e8
style Agents fill:#f3e5f5
style Just fill:#fff3e0
Exploring the Platform
User Exploration Journey
journey
title Exploring KGraph-MCP Platform
section Web Interface
Open Gradio Interface : 5: User
Explore Task Management : 4: User
View System Status : 3: User
section API Exploration
Open API Documentation : 4: User
Test Health Endpoint : 5: User
Explore Available APIs : 3: User
section Task System
View Current Tasks : 5: User
Understand Task Flow : 4: User
Try Task Commands : 3: User
section Development
Read Documentation : 4: User
Run First Tests : 5: User
Start First Task : 5: User
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)
Web Interface Architecture
graph TB
subgraph "🎨 Gradio Interface (localhost:7860)"
TaskTab[📋 Task Management Tab]
KGTab[🧠 Knowledge Graph Tab]
AgentTab[🤖 Agent Interaction Tab]
StatusTab[📊 System Status Tab]
end
subgraph "🔌 FastAPI Backend (localhost:8000)"
TaskAPI[/api/tasks]
KGAPI[/api/kg]
AgentAPI[/api/agents]
HealthAPI[/health]
end
subgraph "📚 Documentation (localhost:8001)"
UserGuide[User Guide]
APIRef[API Reference]
Architecture[Architecture Docs]
Examples[Examples & Tutorials]
end
TaskTab --> TaskAPI
KGTab --> KGAPI
AgentTab --> AgentAPI
StatusTab --> HealthAPI
TaskAPI --> UserGuide
KGAPI --> APIRef
AgentAPI --> Architecture
HealthAPI --> Examples
style TaskTab fill:#e3f2fd
style TaskAPI fill:#e8f5e8
style UserGuide fill:#f3e5f5
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)
API Exploration Flow
sequenceDiagram
participant User
participant Browser as Web Browser
participant API as FastAPI Server
participant Docs as API Documentation
participant Backend as Backend Services
User->>Browser: Open http://localhost:8000/docs
Browser->>API: Request API documentation
API->>Docs: Generate interactive docs
Docs-->>Browser: Display Swagger UI
Browser-->>User: Show API interface
User->>Docs: Try API endpoint
Docs->>API: Send test request
API->>Backend: Process request
Backend-->>API: Return response
API-->>Docs: Response data
Docs-->>User: Display results
Note over User,Backend: Interactive API exploration
3. Task Management System
KGraph-MCP includes a sophisticated task management system:
# View current development tasks
just tasks
# Example output:
# 📋 Current tasks:
Task Management Flow
stateDiagram-v2
[*] --> ViewTasks : just tasks
ViewTasks --> SelectTask : Choose task
SelectTask --> StartTask : just task-start <id>
StartTask --> Development : Write code
Development --> Testing : Run tests
Testing --> QualityCheck : Quality gates
QualityCheck --> Commit : All checks pass
QualityCheck --> FixIssues : Issues found
FixIssues --> Development
Commit --> Review : Create PR
Review --> CompleteTask : just task-done <id>
CompleteTask --> ViewTasks : Get next task
state Development {
[*] --> Coding
Coding --> LocalTesting
LocalTesting --> Debugging
Debugging --> Coding
LocalTesting --> [*]
}
state QualityCheck {
[*] --> Linting
Linting --> Formatting
Formatting --> TypeCheck
TypeCheck --> TestRun
TestRun --> [*]
}
🎯 Next Steps & Learning Path
Learning Journey
journey
title KGraph-MCP Learning Path
section Foundation
Complete Setup : 5: Learner
Explore Interface : 4: Learner
Read Core Documentation : 3: Learner
section Practice
Complete First Task : 5: Learner
Understand Workflow : 4: Learner
Try Quality Tools : 4: Learner
section Advanced
Explore Architecture : 3: Learner
Understand Agents : 2: Learner
Contribute Features : 4: Learner
section Mastery
Lead Development : 4: Expert
Mentor Others : 5: Expert
System Architecture : 3: Expert
Recommended Learning Path
flowchart TD
Start([🎯 Start Learning]) --> Setup[✅ Complete Setup]
Setup --> Basic[📚 Basic Understanding]
Basic --> Practice[💻 Hands-on Practice]
Practice --> Advanced[🚀 Advanced Topics]
Advanced --> Contribute[🤝 Contribute Back]
subgraph "📚 Basic Understanding"
ReadDocs[Read Documentation]
ExploreUI[Explore User Interface]
UnderstandTasks[Understand Task System]
end
subgraph "💻 Hands-on Practice"
FirstTask[Complete First Task]
QualityTools[Use Quality Tools]
TestFramework[Write Tests]
end
subgraph "🚀 Advanced Topics"
Architecture[Study Architecture]
AIAgents[Understand AI Agents]
KnowledgeGraph[Knowledge Graph Concepts]
end
subgraph "🤝 Contribute Back"
FeatureDev[Develop Features]
Documentation[Improve Docs]
Community[Help Community]
end
Setup --> ReadDocs
ReadDocs --> ExploreUI
ExploreUI --> UnderstandTasks
UnderstandTasks --> FirstTask
FirstTask --> QualityTools
QualityTools --> TestFramework
TestFramework --> Architecture
Architecture --> AIAgents
AIAgents --> KnowledgeGraph
KnowledgeGraph --> FeatureDev
FeatureDev --> Documentation
Documentation --> Community
style Start fill:#e3f2fd
style Setup fill:#e8f5e8
style Practice fill:#f3e5f5
style Contribute fill:#c8e6c9
Immediate Next Steps
- Complete Setup: Follow the setup guide and verify your environment
- Explore Interface: Open the web interface and familiarize yourself with the tabs
- Read Documentation: Browse through the documentation to understand the system
- Try Commands: Experiment with the
justcommands to understand the workflow - Get First Task: Use
just task-nextto get your first development task
Learning Resources
- User Guide - Comprehensive user documentation
- Developer Guide - Development processes and patterns
- API Reference - Complete API documentation
- Architecture Docs - System design and patterns
Resource Navigation Map
mindmap
root((KGraph-MCP Docs))
User Guide
Quick Start
Task Management
Configuration
Troubleshooting
Developer Guide
Development Workflow
Code Standards
Testing Patterns
Deployment
Architecture
System Overview
Agent Framework
Knowledge Graph
Data Flow
API Reference
FastAPI Docs
Agent APIs
Knowledge Graph APIs
Integration APIs
🆘 Getting Help
If you encounter issues:
- Check Documentation: Browse the comprehensive docs for answers
- View Issues: Check GitHub issues for known problems
- Ask Questions: Create a new issue with detailed information
- Join Discussions: Participate in GitHub discussions
Support Flow
flowchart TD
Issue[❓ Have a Question/Issue?] --> Search[🔍 Search Documentation]
Search --> Found{Answer Found?}
Found -->|✅ Yes| Resolved[✅ Issue Resolved]
Found -->|❌ No| CheckGitHub[🐙 Check GitHub Issues]
CheckGitHub --> Exists{Issue Exists?}
Exists -->|✅ Yes| Follow[👀 Follow Existing Issue]
Exists -->|❌ No| Create[📝 Create New Issue]
Create --> Provide[📋 Provide Details]
Provide --> Submit[📤 Submit Issue]
Submit --> Community[👥 Community Support]
Follow --> Community
Community --> Resolved
style Issue fill:#e3f2fd
style Found fill:#e8f5e8
style Resolved fill:#c8e6c9
style Create fill:#fff3e0
Welcome to the KGraph-MCP community! Happy coding! 🚀