docs/getting-started.md

---
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**

```mermaid
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**

```mermaid
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

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

### 2. Run Automated Setup

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

### **Automated Setup Process**

```mermaid
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

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

# Start the development server with hot reload
just dev
```

### **Application Startup Flow**

```mermaid
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**

```mermaid
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

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

```bash
# Generate lock file and install dependencies
just lock
just install

# Or manually install
uv pip sync requirements.lock
```

### 3. Verify Installation

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

```mermaid
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**

```mermaid
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**

```mermaid
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**

```mermaid
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**

```mermaid
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:

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

```mermaid
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:

```bash
# View current development tasks
just tasks

# Example output:
# 📋 Current tasks:
```

### **Task Management Flow**

```mermaid
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**

```mermaid
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**

```mermaid
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

1. **Complete Setup**: Follow the setup guide and verify your environment
2. **Explore Interface**: Open the web interface and familiarize yourself with the tabs
3. **Read Documentation**: Browse through the documentation to understand the system
4. **Try Commands**: Experiment with the `just` commands to understand the workflow
5. **Get First Task**: Use `just task-next` to get your first development task

### Learning Resources

- **[User Guide](user-guide/index.md)** - Comprehensive user documentation
- **[Developer Guide](developer-guide/index.md)** - Development processes and patterns
- **[API Reference](api/index.md)** - Complete API documentation
- **[Architecture Docs](architecture/index.md)** - System design and patterns

### **Resource Navigation Map**

```mermaid
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:

1. **Check Documentation**: Browse the comprehensive docs for answers
2. **View Issues**: Check GitHub issues for known problems
3. **Ask Questions**: Create a new issue with detailed information
4. **Join Discussions**: Participate in GitHub discussions

### **Support Flow**

```mermaid
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! 🚀