MCP Deployable

GitHub MCP服务器

用于GitHub操作的模型上下文协议（MCP）服务器，使LLM能够通过标准化的接口与GitHub存储库进行交互。可部署到Cloudflare Workers以供生产使用。

特性

• 🔌 符合MCP协议：适用于任何兼容MCP的LLM（OpenAI、Claude、Cursor等）
• 🚀 9 GitHub运营：全面的公关管理能力
• ✅ 类型安全：使用Zod进行运行时验证的完整TypeScript
• ☁️ Cloudflare员工就绪：无需配置即可部署到边缘
• 🧪 已测试：模式和行为验证的黄金测试
• 🔐 安全：GitHub个人访问令牌身份验证

可用工具

1. list_prs -列出带过滤器的拉取请求（状态、基、头）
2. get_pr -获取详细的公关信息
3. create_pr -创建新的pull请求
4. update_pr -更新PR标题、描述、状态或基本分支
5. add_pr_注释 -向PR添加评论
6. merge_r -使用指定方法合并PR（合并/挤压/重基）
7. request_pr_viewers -请求PR审阅者（用户或团队）
8. add_pr_labels -向PR添加标签
9. 移除_pr_标签 -从PR中删除标签

建筑

┌─────────────┐
│     LLM     │  (OpenAI, Claude, Cursor, etc.)
│  (Client)   │
└──────┬──────┘
       │ MCP Protocol
       │ (stdio or HTTP)
       ▼
┌─────────────────┐
│   MCP Server    │
│  (This repo)    │
├─────────────────┤
│ • Tool Registry │
│ • Validation    │
│ • Error Handler │
└──────┬──────────┘
       │
       │ Octokit REST API
       ▼
┌─────────────────┐
│   GitHub API    │
└─────────────────┘

设置

先决条件

• Node.js 18+
• 具有适当权限的GitHub个人访问令牌

安装

# Clone or create project
npm install

# Set GitHub token
export GITHUB_TOKEN="ghp_your_token_here"

# Build project
npm run build

创建GitHub令牌

1. 转到GitHub设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
2. 生成具有以下作用域的新令牌：

- repo （完全控制私有存储库） - read:org （如果与组织repo合作）

1. 复制令牌并设置为 GITHUB_TOKEN 环境变量

用法

地方发展（stdio）

使用stdio传输在本地运行MCP服务器：

export GITHUB_TOKEN="your_token"
npm run dev

服务器将在stdio上运行，可以通过MCP客户端连接。

测试客户端

运行示例测试客户端以查看服务器的运行情况：

export GITHUB_TOKEN="your_token"
npm run client

这将：

1. 启动MCP服务器
2. 通过stdio传输连接
3. 列出可用工具
4. 执行示例操作（列出PR，获取PR详细信息）
5. 显示结果

与Cursor集成

要与Cursor一起使用，请在MCP配置中添加：

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

与OpenAI集成

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'child_process';
import OpenAI from 'openai';

// Start MCP server
const serverProcess = spawn('node', ['dist/server/index.js'], {
  env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
});

// Connect MCP client
const client = new Client({
  name: 'openai-github-client',
  version: '1.0.0',
}, { capabilities: {} });

const transport = new StdioClientTransport({ command: serverProcess });
await client.connect(transport);

// Get available tools
const tools = await client.listTools();

// Use with OpenAI
const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: 'gpt-4',
  messages: [
    { role: 'user', content: 'List open PRs in owner/repo' }
  ],
  tools: tools.tools.map(tool => ({
    type: 'function',
    function: {
      name: tool.name,
      description: tool.description,
      parameters: tool.inputSchema,
    },
  })),
});

// Execute tool if requested
if (response.choices[0].message.tool_calls) {
  const toolCall = response.choices[0].message.tool_calls[0];
  const result = await client.callTool({
    name: toolCall.function.name,
    arguments: JSON.parse(toolCall.function.arguments),
  });
  console.log(result);
}

Cloudflare员工部署

先决条件

• Cloudflare帐户
• Wrangler CLI已安装(npm install -g wrangler)

部署

# Build worker bundle
npm run build:worker

# Set GitHub token as secret
wrangler secret put GITHUB_TOKEN

# Deploy to Cloudflare Workers
npm run deploy

HTTP API

部署后，worker将公开这些端点：

健康检查

curl https://your-worker.workers.dev/health

列出工具

curl https://your-worker.workers.dev/tools

调用工具

curl -X POST https://your-worker.workers.dev/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "list_prs",
    "arguments": {
      "owner": "octocat",
      "repo": "hello-world",
      "state": "open"
    }
  }'

发展

项目结构

mcp-deployable/
├── src/
│   ├── server/
│   │   ├── index.ts          # MCP server (stdio)
│   │   ├── tools/
│   │   │   └── github-tools.ts  # GitHub API operations
│   │   └── schemas/
│   │       └── tools.ts      # Zod schemas
│   ├── client/
│   │   └── test-client.ts    # Example client
│   ├── types/
│   │   └── github.ts         # TypeScript types
│   └── worker.ts             # Cloudflare Workers entry
├── tests/
│   └── golden/
│       ├── github-tools.test.ts  # Golden tests
│       └── fixtures/         # Mock responses
├── wrangler.toml             # Workers config
├── package.json
└── tsconfig.json

运行测试

# Run all tests
npm test

# Run golden tests only
npm run test:golden

# Run tests in watch mode
npm test -- --watch

脚本

• npm run build -构建TypeScript和worker包
• npm run dev -在本地运行MCP服务器（stdio）
• npm run client -运行测试客户端
• npm test -运行测试套件
• npm run deploy -部署到Cloudflare Workers

工具示例

列出拉取请求

{
  "tool": "list_prs",
  "arguments": {
    "owner": "modelcontextprotocol",
    "repo": "typescript-sdk",
    "state": "open",
    "per_page": 10
  }
}

获取拉取请求详细信息

{
  "tool": "get_pr",
  "arguments": {
    "owner": "modelcontextprotocol",
    "repo": "typescript-sdk",
    "pull_number": 42
  }
}

创建拉取请求

{
  "tool": "create_pr",
  "arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "title": "Add new feature",
    "body": "This PR adds feature X",
    "head": "feature-branch",
    "base": "main",
    "draft": false
  }
}

更新拉取请求

{
  "tool": "update_pr",
  "arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "pull_number": 42,
    "title": "Updated title",
    "body": "Updated description"
  }
}

添加评论

{
  "tool": "add_pr_comment",
  "arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "pull_number": 42,
    "body": "Great work! LGTM 👍"
  }
}

合并拉取请求

{
  "tool": "merge_pr",
  "arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "pull_number": 42,
    "merge_method": "squash",
    "commit_title": "feat: add new feature"
  }
}

请求审阅者

{
  "tool": "request_pr_reviewers",
  "arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "pull_number": 42,
    "reviewers": ["user1", "user2"],
    "team_reviewers": ["team-alpha"]
  }
}

管理标签

{
  "tool": "add_pr_labels",
  "arguments": {
    "owner": "myorg",
    "repo": "myrepo",
    "pull_number": 42,
    "labels": ["bug", "high-priority"]
  }
}

错误处理

所有工具都包括全面的错误处理：

• 验证错误：使用Zod模式验证输入参数
• GitHub API错误：捕获并格式化来自GitHub API的HTTP错误
• 速率限制：GitHub API速率限制错误正确浮出水面
• 身份验证错误：缺少或无效的令牌返回明确的错误消息

错误响应示例：

{
  "error": "GitHub API error (404): Not Found",
  "code": "INTERNAL_ERROR"
}

安全

• 认证：使用GitHub个人访问令牌（PAT）
• 最小权限：仅配置具有必要作用域的令牌
• 环境变量：秘密存储在env变量中，从未提交
• 输入验证：在GitHub API调用之前验证的所有输入

许可证

麻省理工学院

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 确保所有测试通过
5. 提交拉取请求

支持

对于问题或疑问：

• 在GitHub上打开一个问题
• 检查现有问题的解决方案
• 审查MCP协议文件：https://modelcontextprotocol.io