内容
# GitHub 项目 MCP 服务器
[](https://smithery.ai/server/taylor-lindores-reeves/mcp-github-projects)
一个 MCP(模型上下文协议)服务器,使 AI 代理能够使用 GitHub 项目创建和管理基于敏捷冲刺的项目。
<a href="https://glama.ai/mcp/servers/86aw338aa5">
<img width="380" height="200" src="https://glama.ai/mcp/servers/86aw338aa5/badge" alt="GitHub 项目服务器 MCP 服务器" />
</a>
## 功能
- **GitHub 项目 v2 API**:完全支持 GitHub 的 GraphQL 项目 v2 API
- **GitHub 问题**:创建、读取和更新 GitHub 问题
- **GitHub 仓库**:获取仓库详细信息
- **类型安全**:使用 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 服务器。注册所有可用的工具及其模式和处理程序,定义敏捷工作流的可重用提示,并管理与 MCP 客户端的通信。
#### 业务逻辑层(`src/operations/`)
包含连接 MCP 服务器接口与 GitHub API 的核心业务逻辑。每个文件都关注特定的 GitHub 领域,具有全面的错误处理和安全功能,通过仓库允许列表实现。
- **`github-client.ts`**:使用 Octokit 的集中式 GitHub API 客户端,支持 GraphQL 和 REST
- **`issues.ts`**:具有 CRUD 功能的问题管理操作
- **`projects.ts`**:具有完整生命周期管理的综合 GitHub 项目 v2 操作
- **`repositories.ts`**:仓库信息检索操作
#### GraphQL 层(`src/graphql/`)
按功能领域组织 GraphQL 查询和变异,遵循 GitHub 的 GraphQL API 结构。每个 `.graphql` 文件对应一个特定的操作,索引文件提供干净的导入。
#### 类型系统(`src/types/`)
通过混合方法确保整个应用程序的类型安全:
- **自动生成类型**:使用 GraphQL 代码生成器从 GitHub 的 GraphQL 模式创建
- **手动声明**:启用将 `.graphql` 文件导入为 TypeScript 模块
#### 配置文件
控制构建过程和项目设置的配置文件:
- **`package.json`**:项目元数据、依赖项和构建脚本
- **`tsconfig.json`**:TypeScript 编译器设置为 ES2022 目标,模块为 NodeNext
- **`codegen.ts`**:GraphQL 代码生成器配置,从 GitHub 的模式自动生成类型
- **`build.ts`**:自定义 esbuild 配置,带有 GraphQL 文件处理插件
- **`smithery.yaml`**:Smithery MCP 服务器注册包配置
- **`schema.docs.graphql`**:GitHub 的 GraphQL 模式,用于类型生成
- **`.env.example`**:显示所需环境变量的模板
### 架构流程
```
MCP 客户端请求 → MCP 服务器 → 操作层 → GitHub 客户端 → GitHub API
↓
类型验证(Zod 模式)
↓
GraphQL 查询/变异
```
系统遵循清晰的请求-响应模式,在每个层面上都有验证门户,确保从 MCP 接口到 GitHub API 的类型安全,同时通过仓库允许列表和全面的错误处理来维持安全性。
## 安装
### 通过 Smithery 安装
要通过 [Smithery](https://smithery.ai/server/taylor-lindores-reeves/mcp-github-projects) 自动安装 GitHub 项目 MCP 服务器以适用于 Claude Desktop:
```bash
npx -y @smithery/cli install taylor-lindores-reeves/mcp-github-projects --client claude
```
## 用法
### 手动安装
1. 克隆此仓库:
```bash
git clone https://github.com/taylor-lindores-reeves/mcp-github-projects.git
cd mcp-github-projects
```
2. 安装依赖项:
```bash
bun install
```
3. 使用 GitHub 令牌创建 `.env` 文件:
```
GITHUB_TOKEN=your_github_personal_access_token
GITHUB_OWNER=your_github_username
GITHUB_OWNER_TYPE=org
ALLOWED_REPOS=owner/repo,another/repo
```
4. 构建服务器:
```bash
bun run build
```
5. 使用以下设置配置您的 MCP 客户端:
```json
{
"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 项目
- 管理项目字段、项目和状态更新
- 将草稿问题转换为实际问题
- 存档和取消存档项目
### 问题
- 获取问题详情
- 将问题添加到项目中
### 仓库
- 获取仓库信息