AI导哈

GitHub集成服务

一个基于MCP协议的GitHub集成服务器，提供创建GitHub问题、探索仓库和文档等功能，适用于AI助手和其他MCP客户端。

  • by Johnwainey7
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 Johnwainey7/Mcp-Config

使用说明

GitHub MCP服务器

一个模型上下文协议（MCP）服务器，提供GitHub集成功能，专门用于通过MCP接口创建GitHub问题。

概述

此MCP服务器允许AI助手和其他MCP客户端通过创建问题和探索存储库/文档与GitHub存储库进行交互。它实现了MCP协议，为GitHub操作提供了一个标准化的接口。

特性

  • 创建GitHub问题：在GitHub存储库中创建新问题
  • 发现存储库：列出用户/组织存储库并搜索公共存储库
  • 阅读文档：获取README和markdown文档，或任意文件
  • 输入验证：使用Zod模式进行稳健的参数验证
  • 错误处理：使用适当的MCP错误代码进行全面的错误处理
  • 类型安全：具有严格类型检查的完整TypeScript实现

先决条件

  • Node.js（v18或更高版本）
  • npm或纱线
  • GitHub个人访问令牌

安装

  1. 克隆存储库：
git clone <repository-url>
cd git_mcp
  1. 安装依赖项：
npm install
  1. 设置环境变量：
cp .env.example .env
  1. 编辑 .env 并添加您的GitHub令牌：
GITHUB_TOKEN=your_github_token_here

配置

GitHub令牌设置

  1. 转到GitHub设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
  2. 生成具有以下作用域的新令牌：
    • repo （完全控制私有存储库）
    • public_repo （访问公共存储库）
  3. 复制令牌并将其添加到您的 .env 文件

环境变量

变量 描述 必填
GITHUB_TOKEN 您的GitHub个人访问令牌 是

用法

发展模式

以热重新加载的开发模式运行服务器：

npm run dev

生产模式

  1. 构建项目：
npm run build
  1. 启动服务器：
npm start

MCP客户端集成

服务器通过stdio传输进行通信，使其与任何MCP客户端兼容。以下是如何在MCP客户端中配置它：

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["dist/github-mcp-server.js"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

api参考

可用工具

创建问题

在指定的存储库中创建新的GitHub问题。

参数：

  • title （string，必填）：问题的标题
  • body （string，可选）：问题的正文/描述
  • owner （字符串，必填）：存储库所有者（用户名或组织）
  • repo （string，必填）：存储库名称
  • labels （字符串数组，可选）：要添加到问题中的标签
  • assignees （字符串数组，可选）：要分配给问题的用户名

示例用法：

{
  "name": "create-issue",
  "arguments": {
    "title": "Fix login bug",
    "body": "Users are unable to log in with their credentials",
    "owner": "myorg",
    "repo": "myproject",
    "labels": ["bug", "high-priority"],
    "assignees": ["developer1"]
  }
}

答复：

{
  "content": [
    {
      "type": "text",
      "text": "Successfully created issue #123: Fix login bug\nURL: https://github.com/myorg/myproject/issues/123"
    }
  ]
}

列出用户存储库

列出用户或经过身份验证的用户的存储库。

参数：

  • username （string，可选）：如果省略，则列出经过身份验证的用户的存储库
  • visibility （“all”|“public”|“private”，可选，默认为“all”）
  • per_page （整数，1-100，默认值50）
  • page （整数，默认值1）

例子：

{ "name": "list-user-repos", "arguments": { "visibility": "public" } }

列出组织仓库

列出组织中的存储库。

参数：

  • org （字符串，必填）
  • type （“全部”|“公共”|“私有”|“分支”|“源”|“成员”，默认为“全部”）
  • per_page （整数，1-100，默认值50）
  • page （整数，默认值1）

例子：

{ "name": "list-org-repos", "arguments": { "org": "myorg", "type": "public" } }

搜索仓库

使用GitHub搜索语法搜索公共存储库。

参数：

  • q （string，必填）：查询，例如。 "lang:ts topic:mcp sdk"
  • sort （“星号”|“叉号”|“求助问题”|“已更新”）
  • order （“desc”|“asc”，默认为“desc“）
  • per_page （整数，1-100，默认值30）
  • page （整数，默认值1）

例子：

{ "name": "search-repos", "arguments": { "q": "mcp in:name language:TypeScript" } }

获取自述文件

从存储库中获取README文件作为文本。

参数：

  • owner （字符串，必填）
  • repo （字符串，必填）
  • ref （字符串，可选）：分支、标记或SHA

例子：

{ "name": "get-readme", "arguments": { "owner": "myorg", "repo": "myrepo" } }

列出文档

列出常用文档目录和根目录中的markdown文档文件。

参数：

  • owner （字符串，必填）
  • repo （字符串，必填）
  • ref （字符串，可选）

例子：

{ "name": "list-docs", "arguments": { "owner": "myorg", "repo": "myrepo" } }

获取文件

将任意存储库文件作为文本获取。

参数：

  • owner （字符串，必填）
  • repo （字符串，必填）
  • path （字符串，必填）
  • ref （字符串，可选）

例子：

{ "name": "get-file", "arguments": { "owner": "myorg", "repo": "myrepo", "path": "docs/intro.md" } }

错误处理

服务器实现了全面的错误处理：

  • 无效参数：退货 InvalidParams 带有详细验证消息的错误代码
  • GitHub API错误：退货 InternalError 带有GitHub API错误详细信息
  • 身份验证错误：退货 InternalError GitHub令牌无效时
  • 未知工具：退货 MethodNotFound 对于不受支持的工具请求

发展

项目结构

src/
├── github-mcp-server.ts    # Main server implementation
package.json                # Dependencies and scripts
tsconfig.json              # TypeScript configuration
README.md                  # This documentation

关键组件

  1. GitHubMCPServer类：处理MCP协议的主服务器类
  2. 架构验证：使用Zod进行稳健的参数验证
  3. 错误处理：使用适当的MCP错误代码进行全面的错误处理
  4. 传输层：使用stdio传输进行MCP通信

代码更改

1.修复语法错误

问题：双人间 this 第34行的关键字

// Before (incorrect)
this this.server.setRequestHandler(...)

// After (correct)
this.server.setRequestHandler(...)

2.添加了模式定义

问题：缺失 CreateIssueRequestSchema 定义 解决方案：创建了全面的Zod模式并进行了验证：

const CreateIssueRequestSchema = z.object({
  title: z.string().describe("The title of the issue"),
  body: z.string().optional().describe("The body/description of the issue"),
  owner: z.string().describe("The repository owner (username or organization)"),
  repo: z.string().describe("The repository name"),
  labels: z.array(z.string()).optional().describe("Labels to add to the issue"),
  assignees: z.array(z.string()).optional().describe("Usernames to assign to the issue"),
});

3.已实现的工具处理程序

问题：空 handleRequest() 方法 解决方案：通过以下方式完成实施：

  • 使用Zod进行参数验证
  • GitHub API集成
  • 正确的错误处理
  • 符合MCP的响应

4.添加了服务器启动

问题：服务器已创建但从未启动 解决方案：添加了完整的启动顺序：

  • 传输初始化
  • 服务器连接
  • 主要执行功能
  • 优雅的停机处理

5.进口增加

问题：缺少类型导入导致linter错误 解决方案：独立的运行时和类型导入：

import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
import type { Tool, CallToolResult, TextContent } from "@modelcontextprotocol/sdk/types.js";

已添加依赖关系

  • 动物圈：用于健壮参数检查的运行时模式验证
  • @类型/节点：Node.js的TypeScript定义

测试

手动测试

  1. 启动服务器：
npm run dev
  1. 使用支持创建问题工具的MCP客户端进行测试

集成测试

通过发送正确的MCP协议消息，可以使用任何符合MCP的客户端对服务器进行测试。

故障排除

常见问题

  1. “GITHUB_TOKEN环境变量是必需的”

    • 确保您的 .env 文件包含有效 GITHUB_TOKEN
    • 验证令牌是否具有所需的权限

  2. “创建问题失败：404未找到”

    • 检查存储库所有者和名称是否正确
    • 确保令牌可以访问存储库

  3. “无效参数”

    • 验证是否提供了所有必需的参数
    • 检查参数类型是否与架构匹配

调试模式

通过设置启用调试日志记录 DEBUG 环境变量：

DEBUG=* npm run dev

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

ISC许可证-有关详细信息，请参阅许可证文件

支持

对于问题和疑问：

  1. 检查故障排除部分
  2. 查看GitHub API文档
  3. 在存储库中打开问题

更新日志

v1.0.0

  • 初始版本
  • GitHub问题创建功能
  • MCP协议合规性
  • 全面的错误处理
  • TypeScript实现

相关 MCP