AI导哈

GitHub项目管理工具

一个用于管理GitHub项目、问题和拉取请求的工具，提供与GitHub仓库交互的接口。

  • by Monsoft-Solutions
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Monsoft-Solutions/model-context-protocols

使用说明

GitHub项目经理

一个用于管理GitHub项目和问题的模型上下文协议（MCP）实现。此包为AI助手和应用程序提供了与GitHub仓库、问题、拉取请求和项目进行交互的无缝接口。

项目v2 API更新

此包已更新，使用GitHub的Projects v2 API，而非已弃用的经典Projects API。

主要变更：

  • 使用GraphQL API而不是REST API
  • 需要一个带有（某种权限或信息的）令牌 project 范围
  • 返回不同的ID格式（GraphQL节点ID）
  • API调用中的不同参数名称

获取项目ID：

要找到用于此API的项目ID，您可以使用以下GraphQL查询：

query {
    organization(login: "YOUR_ORG_NAME") {
        projectV2(number: PROJECT_NUMBER) {
            id
        }
    }
}

或者对于用户项目：

query {
    user(login: "YOUR_USERNAME") {
        projectV2(number: PROJECT_NUMBER) {
            id
        }
    }
}

替换 PROJECT_NUMBER 使用您项目URL中的数字（例如，对于 https://github.com/orgs/your-org/projects/5，使用 5)。

特点/功能

GitHub 问题管理

  • 创建问题
  • 更新问题
  • 列出带有过滤选项的问题
  • 获取问题详情
  • 为问题添加评论
  • 解决问题

GitHub Pull Request 管理

  • 创建拉取请求
  • 更新拉取请求
  • 列出带有过滤选项的拉取请求
  • 获取拉取请求详情
  • 合并拉取请求
  • 检查拉取请求是否已被合并
  • 创建和管理拉取请求审查
  • 添加并列出评论意见
  • 请求并移除评审者
  • 更新拉取请求分支

GitHub 项目管理

  • 创建项目
  • 将问题添加到项目中
  • 更新项目条目（在列之间移动）
  • 列出项目条目

安装

npm install @monsoft/mcp-github-project-manager

使用

使用 npx 快速入门

使用 GitHub 项目管理器的最快方式是直接通过 npx：

npx -y @monsoft/mcp-github-project-manager --GITHUB_PERSONAL_TOKEN=your_github_token_here

这启动了MCP服务器，之后MCP客户端可以连接到该服务器。

交通方式选项

GitHub 项目经理支持两种传输方法：

标准I/O传输（默认）

这是默认传输方式，非常适合直接CLI集成和本地使用：

# Start with default Stdio transport
npx -y @monsoft/mcp-github-project-manager --GITHUB_PERSONAL_TOKEN=your_github_token_here

服务器发送事件（SSE）传输

对于远程设置和网页集成，您可以使用SSE传输，它会启动一个HTTP服务器：

# Start with SSE transport on default port (3010)
npx -y @monsoft/mcp-github-project-manager --GITHUB_PERSONAL_TOKEN=your_github_token_here --RUN_SSE=1

# Start with SSE transport on a custom port
npx -y @monsoft/mcp-github-project-manager --GITHUB_PERSONAL_TOKEN=your_github_token_here --RUN_SSE=1 --PORT=8080

当使用SSE（Server-Sent Events）传输时，服务器可通过以下地址访问：

  • SSE 端点： http://localhost:<PORT>/sse
  • 消息端点： http://localhost:<PORT>/messages

使用MCP客户端进行设置

要与Anthropic的Claude或Cursor等AI助手一起使用：

# Start the MCP server in your terminal
npx -y @monsoft/mcp-github-project-manager --GITHUB_PERSONAL_TOKEN=your_github_token_here

然后，将您的AI助手配置为使用此MCP服务器。具体的配置方法取决于您所使用的客户端。

程序化使用

要在您的代码中使用GitHub项目管理器：

import { GitHubProjectManager } from '@monsoft/mcp-github-project-manager';

// The token will be automatically loaded from command line arguments
const manager = new GitHubProjectManager();

// Now you can use the manager to interact with GitHub projects

在运行您的应用程序时，请将GitHub令牌作为命令行参数提供：

node your-app.js --GITHUB_PERSONAL_TOKEN=your_github_token_here

您还可以指定传输类型和其他选项：

# Use SSE transport
node your-app.js --GITHUB_PERSONAL_TOKEN=your_github_token_here --RUN_SSE=1 --PORT=3010

# Use default Stdio transport
node your-app.js --GITHUB_PERSONAL_TOKEN=your_github_token_here

如果您需要通过编程方式启动服务器并指定特定的传输选项：

import {
    startGitHubProjectManagerServer,
    startGitHubProjectManagerServerSSE,
} from '@monsoft/mcp-github-project-manager';

// Start with Stdio transport
await startGitHubProjectManagerServer('your_github_token_here');

// Or start with SSE transport
await startGitHubProjectManagerServerSSE('your_github_token_here', 3010);

API 参考文档

问题管理

创建一个问题

const newIssue = await manager.createIssue({
    owner: 'organization-name',
    repo: 'repository-name',
    title: 'Issue title',
    body: 'Detailed description of the issue',
    labels: ['bug', 'priority-high'],
    assignees: ['username1', 'username2'],
});

获取问题详情

const issue = await manager.getIssue({
    owner: 'organization-name',
    repo: 'repository-name',
    issue_number: 123,
});

更新一个问题

await manager.updateIssue({
    owner: 'organization-name',
    repo: 'repository-name',
    issue_number: 123,
    title: 'Updated title',
    body: 'Updated description',
    state: 'closed',
});

列出问题

const issues = await manager.listIssues({
    owner: 'organization-name',
    repo: 'repository-name',
    state: 'open',
    labels: ['bug'],
    sort: 'created',
    direction: 'desc',
});

添加问题评论

await manager.addIssueComment({
    owner: 'organization-name',
    repo: 'repository-name',
    issue_number: 123,
    body: 'This is a comment',
});

拉取请求管理

创建拉取请求

const pr = await manager.createPullRequest({
    owner: 'organization-name',
    repo: 'repository-name',
    title: 'Pull request title',
    body: 'Description of changes',
    head: 'feature-branch',
    base: 'main',
});

获取拉取请求详情

const pullRequest = await manager.getPullRequest({
    owner: 'organization-name',
    repo: 'repository-name',
    pull_number: 456,
});

合并拉取请求

await manager.mergePullRequest({
    owner: 'organization-name',
    repo: 'repository-name',
    pull_number: 456,
    merge_method: 'squash',
});

撰写评论

await manager.createPullRequestReview({
    owner: 'organization-name',
    repo: 'repository-name',
    pull_number: 456,
    event: 'APPROVE',
    body: 'LGTM! Great work.',
});

项目管理

创建一个项目

const project = await manager.createProject({
    owner: 'organization-name',
    name: 'Project Name',
    body: 'Project description',
});

获取项目字段和列

// Get all fields in a project including Status, Assignees, etc.
const fields = await manager.getProjectFields({
    projectId: 'graphql-project-id',
});

// Get just the Status field and its column options
const { statusFieldId, columns } = await manager.getProjectColumns({
    projectId: 'graphql-project-id',
});

console.log('Status Field ID:', statusFieldId);
console.log('Available Columns:', columns);
// Example output:
// [
//   { id: 'f75ad846', name: 'Todo' },
//   { id: '47fc9ee4', name: 'In Progress' },
//   { id: '98236657', name: 'Done' }
// ]

向项目中添加项目项

// Simple add without specifying column
await manager.addProjectItem({
    projectId: 'graphql-project-id',
    contentId: 'graphql-issue-id',
});

// Add and place in a specific column in one operation
await manager.addProjectItemWithColumn({
    projectId: 'graphql-project-id',
    contentId: 'graphql-issue-id',
    fieldId: 'status-field-id', // Get this from getProjectColumns
    columnId: 'column-id', // Get this from getProjectColumns
});

在列之间移动项目

await manager.updateProjectItem({
    projectId: 'graphql-project-id',
    itemId: 'graphql-item-id',
    fieldId: 'status-field-id', // Get this from getProjectColumns
    columnId: 'target-column-id', // Get this from getProjectColumns
});

列出项目条目

const items = await manager.listProjectItems({
    projectId: 'graphql-project-id',
    first: 50, // Optionally limit number of results
});

错误处理

该包提供了自定义错误类，用于处理常见的错误场景：

try {
    // GitHub operations
} catch (error) {
    if (error instanceof MissingGitHubTokenError) {
        console.error('GitHub token is missing. Please provide one via command line.');
    } else if (error instanceof AuthenticationError) {
        console.error('Failed to authenticate with GitHub. Check your token.');
    } else if (error instanceof RateLimitError) {
        console.error('GitHub API rate limit exceeded.');
    } else {
        console.error('An unexpected error occurred:', error.message);
    }
}

可用的错误类别：

  • MissingGitHubTokenError当未提供GitHub令牌时抛出
  • AuthenticationError当认证失败时抛出
  • ResourceNotFoundError当请求的资源不存在时抛出此异常
  • ValidationError当输入验证失败时抛出
  • RateLimitError当GitHub API速率限制超出时抛出
  • NetworkError当网络通信出现问题时抛出
  • GitHubApiErrorGitHub API问题的通用错误

GitHub 令牌权限

您的GitHub个人访问令牌需要以下权限：

  • repo - 完全访问存储库
  • project - 项目访问权限
  • issues - 访问问题（或议题）

发展

建筑

npm run build

验证

npm run validate

测试

npm test

代码检查（或代码规范检查）

npm run lint

许可证

麻省理工学院（MIT）

相关 MCP