GitHub Projects MCP

GitHub项目MCP服务器

MCP（模型上下文协议）服务器，使AI代理能够使用GitHub projects创建和管理基于敏捷Sprint的项目。

特性

• GitHub项目v2 API：完全支持GitHub的GraphQL Projects v2 API
• GitHub问题：创建、阅读和更新GitHub问题
• GitHub存储库：获取存储库详细信息
• 类型安全：使用TypeScript构建，以实现最大的类型安全性

项目结构

此MCP服务器采用分层架构构建，可分离关注点并提高可维护性。代码库提供对GitHub的GraphQL API的类型化访问，并具有全面的错误处理和安全功能。

目录概述

├── src/                       # Source code directory
│   ├── index.ts               # MCP server entry point & tool registration
│   ├── operations/            # Business logic layer
│   │   ├── github-client.ts   # GitHub API client wrapper
│   │   ├── issues.ts          # Issue operations & schemas
│   │   ├── projects.ts        # Project v2 operations & schemas
│   │   ├── repositories.ts    # Repository operations & schemas
│   │   └── index.ts           # Operations barrel exports
│   ├── graphql/               # GraphQL queries & mutations
│   │   ├── issues/            # Issue-related GraphQL files
│   │   ├── projects/          # Project-related GraphQL files
│   │   └── repositories/      # Repository-related GraphQL files
│   ├── types/                 # TypeScript type definitions
│   │   ├── github-api-types.ts # Auto-generated GitHub API types
│   │   └── graphql.d.ts       # GraphQL type declarations
│   ├── utils/                 # Utility functions
│   │   └── graphql-loader.ts  # GraphQL file loader utility
│   └── common/                # Shared utilities
│       ├── errors.ts          # Error handling utilities
│       └── utils.ts           # Common helper functions
├── build/                     # Compiled output directory
├── package.json               # Project configuration & dependencies
├── tsconfig.json              # TypeScript compiler configuration
├── codegen.ts                 # GraphQL code generation configuration
├── build.ts                   # Custom build script with GraphQL plugin
├── smithery.yaml              # Smithery package configuration
├── schema.docs.graphql        # GitHub GraphQL schema for code generation
├── .env.example               # Environment variable template
└── .gitignore                 # Git ignore patterns

关键组件

MCP服务器层(src/index.ts)

配置和启动MCP服务器的主要入口点。使用模式和处理程序注册所有可用工具，为敏捷工作流定义可重用的提示，并管理与MCP客户端的通信。

业务逻辑层(src/operations/)

包含将MCP服务器接口与GitHub API连接起来的核心业务逻辑。每个文件都专注于一个特定的GitHub域，通过存储库分配提供全面的错误处理和安全性。

• github-client.ts：使用Octokit的集中式GitHub API客户端，支持GraphQL和REST
• issues.ts：具有CRUD功能的问题管理操作
• projects.ts：全面的GitHub Projects v2操作，具有完整的生命周期管理
• repositories.ts：存储库信息检索操作

GraphQL层(src/graphql/)

按照GitHub的GraphQL API结构，按功能域组织GraphQL查询和突变。每 .graphql 文件对应于特定的操作，索引文件提供干净的导入。

类型系统(src/types/)

使用混合方法确保整个应用程序的类型安全：

• 自动生成的类型：使用GraphQL代码生成器从GitHub的GraphQL模式创建
• 手动申报：启用导入 .graphql 文件作为TypeScript模块

配置文件

控制构建过程和项目设置的基本配置文件：

• package.json：项目元数据、依赖关系和生成脚本
• tsconfig.json：带有NodeNext模块的ES2022目标的TypeScript编译器设置
• codegen.ts：用于从GitHub模式自动生成类型的GraphQL代码生成器配置
• build.ts：使用GraphQL文件处理插件自定义esbuild配置
• smithery.yaml：Smithery MCP服务器注册表的包配置
• schema.docs.graphql：GitHub的GraphQL模式用于类型生成
• .env.example：显示所需环境变量的模板

建筑流程

MCP Client Request → MCP Server → Operations Layer → GitHub Client → GitHub API
                                       ↓
                               Type Validation (Zod Schemas)
                                       ↓
                               GraphQL Queries/Mutations

该系统遵循清晰的请求响应模式，每层都有验证门，确保从MCP接口到GitHub API的类型安全，同时通过存储库允许列表和全面的错误处理来维护安全。

安装

通过Smithery安装

通过以下方式自动安装GitHub Projects MCP Server for Claude Desktop 史密瑟里:

npx -y @smithery/cli install taylor-lindores-reeves/mcp-github-projects --client claude

用法

手动安装

1. 克隆此存储库：

   git clone https://github.com/taylor-lindores-reeves/mcp-github-projects.git
   cd mcp-github-projects

1. 安装依赖项：

   bun install

1. 创建一个 .env 使用您的GitHub令牌的文件：

   GITHUB_TOKEN=your_github_personal_access_token
   GITHUB_OWNER=your_github_username
   GITHUB_OWNER_TYPE=org
   ALLOWED_REPOS=owner/repo,another/repo

1. 构建服务器：

   bun run build

1. 使用以下设置配置MCP客户端：

{
  "mcpServers": {
    "GitHubProjects": {
      "command": "bun",
      "args": [
        "/path/to/your/directory/mcp-github-projects-main/build/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token",
        "GITHUB_OWNER": "your_github_username_or_org",
        "GITHUB_OWNER_TYPE": "org",
        "ALLOWED_REPOS": "owner/repo,another/repo"
      }
    }
  }
}

环境变量

• GITHUB_TOKEN：具有适当权限的GitHub个人访问令牌
• GITHUB_OWNER：GitHub用户名或组织名称
• GITHUB_OWNER_TYPE：（可选）设置为 user （默认）或 org。控制是为用户还是为组织完成项目列表和管理。吃起来 org 如果你的项目位于GitHub组织中。
• ALLOWED_REPOS：（可选）逗号分隔的允许存储库块列表（例如。 owner/repo,another/repo).所有写入操作（创建/更新问题、向项目添加项目等）都仅限于这些存储库。如果未设置或为空，则默认情况下允许所有存储库。

例子：

GITHUB_TOKEN=your_github_personal_access_token
GITHUB_OWNER=the-troops
GITHUB_OWNER_TYPE=org
ALLOWED_REPOS=the-troops/sms-troopers,manuelbiermann/convo-run

如果您尝试对不在此列表中的存储库执行写入操作，服务器将抛出错误并阻止该操作。

GitHub令牌权限

此MCP服务器需要具有以下权限的GitHub个人访问令牌（经典）：

• project -完全控制项目
• read:project -项目的读取权限
• repo -完全控制私有存储库
• repo:status -访问提交状态
• repo_deployment -访问部署状态
• public_repo -访问公共存储库
• repo:invite -访问存储库邀请
• security_events -读写安全事件

发展

命令

• 构建： bun run build
• 生成GraphQL类型： bun run graphql-codegen

可用操作

项目

• 创建、读取、更新和删除GitHub项目
• 管理项目字段、项目和状态更新
• 将草稿问题转化为实际问题
• 归档和非归档项目项

问题

• 获取问题详细信息
• 向项目添加问题

仓库

• 获取存储库信息