GitHub Projects V2 Integration Guide - v0.3.4

This guide covers the GitHub Projects V2 capabilities added in v0.3.4, including project management, templates, and RAG-enhanced smart field assignment.

🚀 Overview
📋 Prerequisites
🏗️ Architecture
🛠️ Configuration
📚 Usage Examples
🎯 Smart Field Assignment
📊 API Reference
🧪 Testing
🏆 Best Practices
❓ Troubleshooting

🚀 Overview

The GitHub Projects V2 integration transforms project management with intelligent automation:

Create projects with predefined templates (Roadmap, Bug Tracking, Feature Development)
Manage project items with automatic field assignment
Track project status and statistics
Analyze issues using RAG to determine appropriate field values
Automate tedious project management tasks

Key Features

Project Templates: Quick project setup with pre-configured fields
Smart Field Assignment: RAG-powered analysis automatically sets field values
GraphQL Integration: Full Projects V2 API support
Field Type Support: Single-select, text, number, date, and iteration fields
Error Handling: Comprehensive validation and user-friendly error messages

📋 Prerequisites

Required Scopes

Your GitHub Personal Access Token (PAT) must have:

project scope (for project operations)
repo scope (for repository access)

Important: Use a Classic PAT, not Fine-Grained, for full Projects V2 support.

Dependencies

The Projects V2 integration requires:

pip install "gql[aiohttp]"

This is already included in the standard installation.

🏗️ Architecture

Component Design

┌─────────────────────────────────────────────────────┐
│                   MCP Tools Layer                    │
│        (github_create_project, etc.)                 │
└─────────────────────┬───────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────┐
│           GitHubProjectsManager                      │
│         (GraphQL Adapter Pattern)                    │
│                                                      │
│  • Project CRUD operations                          │
│  • Field management                                 │
│  • Smart issue analysis                             │
│  • Template application                             │
└─────────────┬──────────────┬──────────────┬────────┘
              │              │              │
      GraphQL Client    RAG Analysis    GitHubClient
         (gql)       (Issue Analysis)   (REST API)

GraphQL vs REST

Projects V2 requires GraphQL API:

REST API: Issues, PRs, repositories (via PyGithub)
GraphQL API: Projects V2, fields, views (via gql)

🛠️ Configuration

Authentication Setup

# Set your GitHub token with project scope
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# Or in .env file
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Server Configuration

In config/server_config.json:

{
  "github": {
    "authentication": {
      "token": "${GITHUB_TOKEN}"
    },
    "projects": {
      "default_template": "bugs",
      "auto_assign_fields": true,
      "max_items_per_project": 1000
    }
  }
}

📚 Usage Examples

Listing Projects

# Via Claude Code (MCP)
"List my GitHub projects"
"Show all projects for organization myorg"
"List up to 50 projects for user ancoleman"

# Via HTTP API
# List projects for authenticated user
curl http://localhost:8081/github/projects

# List projects for specific owner
curl "http://localhost:8081/github/projects?owner=ancoleman"

# List with limit
curl "http://localhost:8081/github/projects?owner=myorg&limit=50"

Creating Projects

Basic Project Creation

# Via Claude Code (MCP)
"Create a GitHub project called 'Q1 Roadmap' for owner ancoleman"

# Via HTTP API
curl -X POST http://localhost:8081/github/projects \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "ancoleman",
    "title": "Q1 Roadmap"
  }'

Project with Template

# Via Claude Code
"Create a bug tracking project called 'Bug Tracker' using the bugs template"

# Via HTTP API
curl -X POST http://localhost:8081/github/projects \
  -H "Content-Type: application/json" \
  -d '{
    "owner": "ancoleman",
    "title": "Bug Tracker",
    "template": "bugs"
  }'

Available Templates

1. Bug Tracking Template (`bugs`)

Bug Status: 🆕 New, 🔍 Triaged, 🔧 In Progress, 👀 In Review, ✅ Fixed, ❌ Won't Fix
Severity: 💥 Critical, 🔴 High, 🟡 Medium, 🟢 Low
Component: 🎯 Core, 🔍 Search, 📚 Indexing, 🌐 API, 🧩 Integration, 📖 Documentation
Reproduction Steps: Text field
Fix Version: Text field

2. Implementation Roadmap Template (`roadmap`)

Progress: 📋 Planned, 🚧 In Progress, ✅ Completed, ❌ Cancelled, ⏸️ On Hold
Priority: 🔥 Critical, ⭐ High, 📌 Medium, 📎 Low
Epic: 🏗️ Foundation, 🚀 Enhancement, 🔌 Integration, ⚡ Optimization, 📚 Documentation
Complexity: 1️⃣ Trivial to 5️⃣ Very Complex
Target Version: Text field
Due Date: Date field

3. Feature Development Template (`features`)

Stage: 💡 Ideation, 📋 Planning, 🛠️ Development, 🧪 Testing, 🚀 Deployment, 📊 Monitoring
Effort: XS (<1 day) to XL (>2 weeks)
Impact: 🌟 High, ➕ Medium, ➖ Low
Dependencies: Text field
Target Release: Text field

Managing Project Items

Adding Issues to Projects

# Basic add
"Add issue #123 to project PVT_kwHOAdYevc4A7ABC"

# With smart field assignment
"Smart add issue #123 to project PVT_kwHOAdYevc4A7ABC"

# HTTP API
curl -X POST http://localhost:8081/github/projects/items/smart \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PVT_kwHOAdYevc4A7ABC",
    "issue_number": 123
  }'

Updating Field Values

# Via Claude Code
"Update project item PVTI_xxxx field Status to 'In Progress'"

# HTTP API
curl -X POST http://localhost:8081/github/projects/items/update \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PVT_xxxx",
    "item_id": "PVTI_xxxx",
    "field_updates": {
      "Status": "47fc9ee4",
      "Priority": "high"
    }
  }'

Project Status and Analytics

# Via Claude Code
"Get status for project #5 owned by ancoleman"

# HTTP API
curl http://localhost:8081/github/projects/ancoleman/5/status

# Response includes:
{
  "project": {
    "id": "PVT_xxxx",
    "title": "Bug Tracker",
    "url": "https://github.com/users/ancoleman/projects/5"
  },
  "statistics": {
    "total_items": 42,
    "issues": {
      "open": 30,
      "closed": 12
    },
    "completion_rate": 28.6
  },
  "fields": [...]
}

🎯 Smart Field Assignment

The most powerful feature is RAG-enhanced field assignment that analyzes issue content to automatically set appropriate field values.

How It Works

Issue Analysis: Examines title, body, and labels
Field Detection: Identifies relevant project fields
Value Matching: Uses RAG and keyword analysis to determine values
Automatic Assignment: Sets fields based on confidence levels

Analysis Examples

Bug Priority Detection

Issue: "Critical: Application crashes on startup"
Labels: ["bug", "critical", "blocking"]

Analysis Result:
- Severity: 💥 Critical (high confidence)
- Bug Status: 🆕 New
- Component: 🎯 Core

Component Identification

Issue: "Search results are inconsistent"
Body: "The search functionality returns different results..."

Analysis Result:
- Component: 🔍 Search (high confidence)
- Severity: 🟡 Medium

Feature Classification

Issue: "Add dark mode support"
Labels: ["enhancement", "ui"]

Analysis Result:
- Type: ✨ Enhancement
- Impact: 🌟 High
- Stage: 💡 Ideation

Field Type Support

Single Select: Automatically matches option based on keywords
Text: Extracts relevant content (e.g., reproduction steps)
Number: Parses numeric values from content
Date: Extracts dates in various formats

📊 API Reference

MCP Tools

`github_list_projects`

List GitHub Projects V2 for a user or organization.

Parameters:

owner (optional): Username or organization (defaults to current repo owner or authenticated user)
limit (optional): Maximum number of projects (default: 20, max: 100)

Returns:

projects: List of projects with:
- id: Project node ID
- number: Project number
- title: Project name
- description: Project description
- url: Web URL
- item_count: Number of items in project
- created_at: Creation timestamp
- updated_at: Last update timestamp

`github_create_project`

Create a new GitHub Project V2.

Parameters:

owner (required): Username or organization
title (required): Project title
template (optional): Template name (bugs, roadmap, features)

Returns:

project: Created project with ID and URL
fields: List of fields (if template used)

`github_delete_project`

Delete a GitHub Project V2.

Parameters:

project_id (required): Project node ID (must start with PVT_)

Returns:

deleted: Boolean indicating success
title: Name of the deleted project
message: Confirmation message

Note: This action cannot be undone. All project data, including items and fields, will be permanently deleted.

`github_add_project_item`

Add an issue or PR to a project.

Parameters:

project_id (required): Project ID (PVT_xxxx format)
issue_number or pr_number (required): Item to add

Returns:

item: Added item with ID

`github_update_project_item`

Update field values for a project item.

Parameters:

project_id (required): Project ID
item_id (required): Item ID
field_updates (required): Dictionary of field:value pairs

`github_get_project_status`

Get project statistics and field information.

Parameters:

owner (required): Project owner
number (required): Project number

Returns:

project: Project information
statistics: Item counts and completion rate
fields: Available fields with options

`github_create_project_view`

Create a filtered view in a project.

Parameters:

project_id (required): Project ID
name (required): View name
filter (optional): Filter expression
sort (optional): Sort configuration

`github_smart_add_project_item`

Add item with intelligent field assignment.

Parameters:

project_id (required): Project ID
issue_number (required): Issue number

Returns:

item: Added item
applied_fields: Fields that were set
suggestions: All suggested values

HTTP Endpoints

Endpoint	Method	Purpose
`/github/projects`	GET	List projects
`/github/projects`	POST	Create project
`/github/projects/{owner}/{number}`	GET	Get project
`/github/projects/{project_id}`	DELETE	Delete project
`/github/projects/items`	POST	Add item
`/github/projects/items/update`	POST	Update item
`/github/projects/items/smart`	POST	Smart add
`/github/projects/{owner}/{number}/status`	GET	Get status
`/github/projects/views`	POST	Create view

🧪 Testing

Test Script

Use the provided test script:

# Run all project tests
./tests/integration/github/test_github_projects_http_api.sh

# Test smart add functionality
./tests/integration/github/test_github_projects_smart_add.sh

Manual Testing Flow

List existing projects:

# List all projects for current user
curl http://localhost:8081/github/projects

# List projects for specific owner
curl "http://localhost:8081/github/projects?owner=ancoleman&limit=10"

Create a test project:

curl -X POST http://localhost:8081/github/projects \
  -d '{"owner": "ancoleman", "title": "Test Project", "template": "bugs"}'

Create test issues:

curl -X POST http://localhost:8081/github/issues \
  -d '{"title": "Critical bug", "labels": ["bug", "critical"]}'

Smart add to project:

curl -X POST http://localhost:8081/github/projects/items/smart \
  -d '{"project_id": "PVT_xxxx", "issue_number": 1}'

Check results:

curl http://localhost:8081/github/projects/ancoleman/1/status

Delete test project (cleanup):

# First get the project ID
curl http://localhost:8081/github/projects/ancoleman/1 | jq '.project.id'

# Then delete the project
curl -X DELETE http://localhost:8081/github/projects/PVT_xxxx

🏆 Best Practices

Project Management

Deleting Projects

When cleaning up projects:

# Via Claude Code MCP
"Delete project PVT_kwDOBxxx"

# Via HTTP API
curl -X DELETE http://localhost:8081/github/projects/PVT_kwDOBxxx

Important considerations:

Deletion is permanent and cannot be undone
All project items, fields, and views are deleted
Consider archiving projects instead if you might need them later
Requires appropriate permissions (project admin)

Project Organization

Use templates for consistent field structure
Name projects clearly with purpose and timeframe
Limit items per project to maintain performance
Archive completed projects to reduce clutter
Delete test projects to keep workspace clean

Field Design

Keep field names short but descriptive
Use emojis for visual distinction
Limit select options to 6-8 for usability
Include "Other" option for flexibility

Smart Assignment

Use descriptive issue titles for better analysis
Apply consistent labels for accurate classification
Include keywords in issue body for field detection
Review assignments before finalizing

Error Handling

Check for existing items before adding
Validate field IDs before updates
Handle GraphQL errors gracefully
Log operations for debugging

❓ Troubleshooting

Common Issues

"Personal access token cannot create projects"

Cause: Token missing project scope
Solution: Create Classic PAT with project scope

"Field name is reserved"

Cause: Using reserved names like "Status"
Solution: Use alternative names (e.g., "Task Status")

"Project not found"

Cause: Wrong owner or project number
Solution: Verify owner name and project exists

"Invalid content ID format"

Cause: Wrong issue/PR node ID format
Solution: Ensure IDs start with I_ or PR_

Debug Mode

Enable debug logging:

export QDRANT_LOG_LEVEL=DEBUG

Check logs for GraphQL queries:

./scripts/qdrant-logs | grep ">>>"

Rate Limiting

Projects V2 uses GraphQL rate limiting:

Limit: 5,000 points per hour
Project creation: ~50 points
Field updates: ~10 points
Queries: ~1-5 points

🔗 Related Documentation

GitHub Integration Guide - Issue management features
Complete Setup Guide - Installation and configuration
GitHub Workflow Examples - Real-world patterns
Advanced RAG Implementation Roadmap - Future features

📞 Support

For GitHub Projects integration issues:

Verify token has project scope
Check GraphQL query logs
Review error messages for field names
File issue with reproduction steps

🚀 Future Enhancements

Planned improvements:

Project templates marketplace
Bulk operations support
Cross-project item linking
Advanced automation rules
Project insights and analytics
AI-powered project planning

FilesExpand file tree

github-projects-guide.md

Latest commit

History

github-projects-guide.md

File metadata and controls

GitHub Projects V2 Integration Guide - v0.3.4

Table of Contents

🚀 Overview

Key Features

📋 Prerequisites

Required Scopes

Dependencies

🏗️ Architecture

Component Design

GraphQL vs REST

🛠️ Configuration

Authentication Setup

Server Configuration

📚 Usage Examples

Listing Projects

Creating Projects

Basic Project Creation

Project with Template

Available Templates

1. Bug Tracking Template (bugs)

2. Implementation Roadmap Template (roadmap)

3. Feature Development Template (features)

Managing Project Items

Adding Issues to Projects

Updating Field Values

Project Status and Analytics

🎯 Smart Field Assignment

How It Works

Analysis Examples

Bug Priority Detection

Component Identification

Feature Classification

Field Type Support

📊 API Reference

MCP Tools

github_list_projects

github_create_project

github_delete_project

github_add_project_item

github_update_project_item

github_get_project_status

github_create_project_view

github_smart_add_project_item

HTTP Endpoints

🧪 Testing

Test Script

Manual Testing Flow

🏆 Best Practices

Project Management

Deleting Projects

Project Organization

Field Design

Smart Assignment

Error Handling

❓ Troubleshooting

Common Issues

"Personal access token cannot create projects"

"Field name is reserved"

"Project not found"

"Invalid content ID format"

Debug Mode

Rate Limiting

🔗 Related Documentation

📞 Support

🚀 Future Enhancements

1. Bug Tracking Template (`bugs`)

2. Implementation Roadmap Template (`roadmap`)

3. Feature Development Template (`features`)

`github_list_projects`

`github_create_project`

`github_delete_project`

`github_add_project_item`

`github_update_project_item`

`github_get_project_status`

`github_create_project_view`

`github_smart_add_project_item`