STARWARCLOUD STARWAR.AI
返回市场
麦普吉比特项目

麦普吉比特项目

作者：taylor-lindores-reeves30 星标更新：2025-09-18
安装使用来源：spider==github.com

项目介绍

GitHub Projects MCP Server

smithery 徽章

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

<a href="https://glama.ai/mcp/servers/86aw338aa5"> <img width="380" height="200" src="https://gips0.baidu.com/it/u=1568264409,2743005109&fm=3081&app=3081&f=PNG?w=760&h=400" alt="GitHub Projects Server MCP 服务器" /> </a>

功能

  • GitHub Projects v2 API: 完全支持GitHub的GraphQL Projects v2 API
  • GitHub Issues: 创建、读取和更新GitHub问题
  • GitHub Repositories: 获取仓库详细信息
  • 类型安全: 使用TypeScript构建以实现最大类型安全性

项目结构

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

目录概述

├── src/                       # 源代码目录
│   ├── index.ts               # MCP服务器入口点及工具注册
│   ├── operations/            # 业务逻辑层
│   │   ├── github-client.ts   # GitHub API客户端包装器
│   │   ├── issues.ts          # 问题操作及模式
│   │   ├── projects.ts        # 项目v2操作及模式
│   │   ├── repositories.ts    # 仓库操作及模式
│   │   └── index.ts           # 操作桶导出
│   ├── graphql/               # GraphQL查询及突变
│   │   ├── issues/            # 与问题相关的GraphQL文件
│   │   ├── projects/          # 与项目相关的GraphQL文件
│   │   └── repositories/      # 与仓库相关的GraphQL文件
│   ├── types/                 # TypeScript类型定义
│   │   ├── github-api-types.ts # 自动生成的GitHub API类型
│   │   └── graphql.d.ts       # GraphQL类型声明
│   ├── utils/                 # 工具函数
│   │   └── graphql-loader.ts  # GraphQL文件加载工具
│   └── common/                # 共享工具
│       ├── errors.ts          # 错误处理工具
│       └── utils.ts           # 常用辅助函数
├── build/                     # 编译输出目录
├── package.json               # 项目配置及依赖项
├── tsconfig.json              # TypeScript编译器配置
├── codegen.ts                 # GraphQL代码生成配置
├── build.ts                   # 自定义构建脚本，带有GraphQL插件
├── smithery.yaml              # Smithery包配置
├── schema.docs.graphql        # 用于代码生成的GitHub GraphQL模式
├── .env.example               # 环境变量模板
└── .gitignore                 # Git忽略模式

关键组件

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/)

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

类型系统 (src/types/)

在整个应用程序中确保类型安全，采用混合方法：

  • 自动生成的类型: 从GitHub的GraphQL模式使用GraphQL代码生成器创建
  • 手动声明: 使.graphql文件可以作为TypeScript模块导入

配置文件

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

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

架构流程

MCP客户端请求 → MCP服务器 → 操作层 → GitHub客户端 → GitHub API
                                       ↓
                               类型验证（Zod模式）
                                       ↓
                               GraphQL查询/突变

该系统遵循清晰的请求-响应模式，在每一层都有验证门，确保从MCP接口到GitHub API的类型安全，同时通过仓库白名单和全面的错误处理来维持安全性。

安装

通过Smithery安装

要通过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

  2. 安装依赖项：

    bun install

  3. 创建一个.env文件，其中包含您的GitHub令牌：

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

  4. 构建服务器：

    bun run build

  5. 使用以下设置配置您的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。控制项目列表和管理是针对用户还是组织进行的。如果您的项目位于GitHub组织中，请将其设置为org。
  • ALLOWED_REPOS: （可选）允许的仓库slug的逗号分隔列表（例如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项目
  • 管理项目字段、项目项和状态更新
  • 将草稿问题转换为实际问题
  • 归档和取消归档项目项

问题

  • 获取问题详情
  • 将问题添加到项目

仓库

  • 获取仓库信息