GitHub 项目管理器

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

特性

GitHub 问题管理

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

GitHub 拉取请求管理

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

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 项目管理器支持两种传输方式：

标准输入输出传输（默认）

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

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

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

对于远程设置和 Web 集成，您可以使用 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 传输时，服务器可以通过以下地址访问：

• 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 token：

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',
});

将项添加到项目

await manager.addProjectItem({
    project_id: 12345,
    content_id: issue.id,
    content_type: 'Issue',
});

列出项目项

const items = await manager.listProjectItems({
    project_id: 12345,
});

错误处理

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

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: 当发生网络通信问题时抛出
• GitHubApiError: GitHub API 问题的一般错误

GitHub 令牌权限

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

• repo - 对仓库的完全访问权限
• project - 对项目的访问权限
• issues - 对问题的访问权限

开发

构建

npm run build

验证

npm run validate

测试

npm test

代码检查

npm run lint

许可证

MIT