mcp-github-project-manager
by: kunwarVivek
a mcp server to manage github project's functionality
📌Overview
Purpose: To enable LLM clients to manage GitHub Projects programmatically through a Model Context Protocol (MCP) server.
Overview: This MCP server implementation provides a structured way to access GitHub Projects functionality. It leverages GitHub's GraphQL API to facilitate the management of projects, milestones, sprints, and other project-related metrics while adhering to MCP standards for state management and error handling.
Key Features:
-
Project Management
Allows users to create and manage GitHub Projects (v2), configure project settings, and control visibility and access. -
Project Resources
Supports management of issues and milestones, sprint planning and tracking, custom fields and views, as well as resource versioning and locking. -
MCP Implementation
Ensures full compliance with the MCP specifications, offering standardized tool definitions, efficient resource state management, and robust error handling. -
GitHub Integration
Features seamless integration with GitHub's GraphQL API, including effective rate limit handling and optimistic concurrency, with future plans for webhook support.
GitHub Project Manager MCP Server
A Model Context Protocol (MCP) server implementation that provides GitHub Projects functionality through standardized tools and resources. This server enables LLM clients to manage GitHub Projects programmatically through the MCP interface.
Overview
This server implements the Model Context Protocol to expose GitHub Projects functionality to LLM clients. It provides tools for managing projects, milestones, sprints, and metrics through GitHub's GraphQL API while maintaining state and handling errors according to MCP specifications.
Key Features
-
Project Management
- Create and manage GitHub Projects (v2)
- Handle project settings and configurations
- Manage project visibility and access
-
Project Resources
- Issues and milestones management
- Sprint planning and tracking
- Custom fields and views
- Resource versioning and locking
-
MCP Implementation
- Full MCP specification compliance
- Standardized tool definitions with Zod validation
- Resource state management
- Progressive response handling
- Comprehensive error handling
-
GitHub Integration
- GraphQL API integration with pagination support
- Intelligent rate limit handling
- Optimistic concurrency
- Webhook support (planned)
Installation
# Install dependencies
npm install
# or
pnpm install
# Set up environment variables
cp .env.example .env
# Edit .env with your GitHub token and details
Configuration
Required environment variables:
GITHUB_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name
The GitHub token requires these permissions:
repo(Full repository access)project(Project access)write:org(Organization access)
Usage
# Start the MCP server
npm start
# Run tests
npm test
npm run test:e2e
See the User Guide for detailed usage instructions.
Architecture
The server follows Clean Architecture principles with distinct layers:
- Domain Layer: Core entities, repository interfaces, and Zod schemas
- Infrastructure Layer: GitHub API integration and implementations
- Service Layer: Business logic coordination
- MCP Layer: Tool definitions and request handling
See ARCHITECTURE.md for detailed architecture documentation.
Current Status
Core Features
| Feature | Status | Notes |
|---|---|---|
| Project Creation | ✅ Complete | Full support for v2 projects |
| Milestone Management | ✅ Complete | CRUD operations implemented |
| Sprint Planning | ✅ Complete | Including metrics tracking |
| Issue Management | ✅ Complete | With custom fields support |
| Resource Versioning | ✅ Complete | With optimistic locking and schema validation |
| Webhook Integration | 📅 Planned | Real-time updates |
MCP Implementation
| Component | Status | Notes |
|---|---|---|
| Tool Definitions | ✅ Complete | All core tools implemented with Zod validation |
| Resource Management | ✅ Complete | With optimistic locking and relationship tracking |
| Response Handling | ✅ Complete | Rich content formatting with multiple content types |
| Error Handling | ✅ Complete | Comprehensive error mapping to MCP error codes |
| State Management | ✅ Complete | With conflict resolution and rate limiting |
Recent Improvements
-
Enhanced Resource System:
- Added Zod schema validation for all resource types
- Implemented resource relationship tracking
- Created a centralized ResourceFactory for consistent resource access
-
Improved GitHub API Integration:
- Added intelligent rate limiting with automatic throttling
- Implemented pagination support for REST and GraphQL APIs
- Enhanced error handling with specific error types
-
Advanced Tool System:
- Created tool definition registry with Zod validation
- Implemented standardized tool response formatting
- Added example-based documentation for all tools
-
Rich Response Formatting:
- Added support for multiple content types (JSON, Markdown, HTML, Text)
- Implemented progress updates for long-running operations
- Added pagination support for large result sets
Identified Functional Gaps
The following functional gaps are prioritized for future development:
-
Persistent Caching Strategy:
- Current in-memory caching lacks persistence across restarts
- No distributed caching for multi-instance deployments
- Missing cache eviction policies for memory management
-
Real-time Event Processing:
- No webhook integration for real-time updates from GitHub
- Missing event-based subscription system for clients
- Lack of server-sent events (SSE) support for streaming updates
-
Advanced GitHub Projects v2 Features:
- Limited support for custom field types and validation
- Incomplete integration with GitHub's newer Projects v2 field types
- Missing automation rule management
-
Performance Optimization:
- No query batching for related resources
- Missing background refresh for frequently accessed resources
- Incomplete prefetching for related resources
-
Data Visualization and Reporting:
- No built-in visualization generators for metrics
- Missing report generation capabilities
- Limited time-series data analysis
See docs/mcp/gaps-analysis.md for detailed implementation status.
Documentation
- User Guide - Detailed usage instructions
- API Reference - Comprehensive tool documentation
- Tutorials - Step-by-step guides
- Examples - Code examples for common tasks
- Architecture - System architecture and design
- Contributing - Development guidelines
- MCP Documentation - MCP-specific details
Interactive Documentation
For an interactive exploration of the API, open the API Explorer in your browser.
Development
Testing
# Unit tests
npm test
# Integration tests
npm run test:integration
# End-to-end tests
npm run test:e2e
Code Quality
# Lint code
npm run lint
# Type check
npm run type-check
# Format code
npm run format
Contributing
We welcome contributions to the GitHub Project Manager MCP Server! Please see our Contributing Guide for details on:
- Development Workflow
- Code Standards
- Testing Guidelines
- Documentation Guidelines
License
MIT