GitHub MCP TypeScript SDK Server

GitHub MCP TypeScript SDK 服务器

一个针对GitHub的综合模型上下文协议（MCP）服务器，通过标准化接口提供对仓库、问题、拉取请求、提交和用户信息的访问。该服务器使用TypeScript和官方MCP SDK构建。

🚀 功能特点

📋 可用工具（共10个）

• get_my_info - 获取已认证的GitHub用户信息
• get_repo_info - 获取有关GitHub仓库的详细信息
• list_repo_issues - 列出存储库中的问题（带状态过滤）
• list_repo_prs - 列出仓库中的拉取请求
• list_repo_commits - 列出仓库中的最近提交
• search_repositories - 在GitHub上搜索仓库
• get_user_info - 获取任何GitHub用户的资料
• list_user_repos - 列出属于某个用户的仓库
• get_my_repos - 列出认证用户所属的仓库
• get_github_stats - 获取用户的全面GitHub统计数据

🔧 能力

• ✅ 表示“正确”或“确认”。 仓库信息 - 名称、描述、星级、分支、语言、可见性
• ✅ 问题管理 - 列出、筛选和查看问题详情
• ✅ 拉取请求跟踪 - 查看PR状态、作者及详细信息
• ✅ 提交历史 - 浏览最近的提交，查看作者和信息
• ✅ 用户配置文件 - 访问用户信息和统计数据
• ✅ 仓库搜索 - 带有筛选和排序功能的高级搜索
• ✅ 统计与分析 - 全面的用户和仓库指标
• ✅ 表示正确、确认或完成的标志。 错误处理 - 强大的错误处理机制，附带描述性信息
• ✅ 表示“正确”或“已完成”。 自然语言查询 - 用通俗易懂的英语提问

📦 安装

先决条件

• Node.js 18及以上版本
• npm 或 yarn
• GitHub 个人访问令牌

设置

1. 克隆仓库：

   git clone 
   cd github-mcp-ts-sdk

1. 安装依赖项：

   npm install

1. 设置环境变量：

   cp env.example .env
   # Edit .env and add your GitHub token

1. 构建项目：

   npm run build

🔑 GitHub 令牌设置

1. 首选
2. 点击“生成新令牌（经典版）”
3. 选择以下范围：

- repo （完全控制私有仓库） - user （读取所有用户资料数据） - read:org （阅读组织和团队成员信息）

1. 复制生成的令牌并将其添加到您的 .env 文件：

GITHUB_TOKEN=your_github_token_here
GITHUB_USERNAME=your_username_here  # Optional

🚀 使用方法

开发模式

npm run dev

生产模式

npm run build
npm start

观察模式（用于开发）

npm run build:watch

测试服务器

npm test
npm run simple-test
npm run interactive-test
npm run demo

🛠 工具示例

用户信息

获取你的GitHub个人资料

{
  "tool": "get_my_info",
  "arguments": {}
}

回答：

👤 **My GitHub Profile**

**Username:** Om-Shree-0709
**Name:** Om Shree
**Bio:** Full Stack Developer
**Followers:** 25
**Following:** 50
**Public Repositories:** 15
**Profile URL:** https://github.com/Om-Shree-0709

获取用户信息

{
  "tool": "get_user_info",
  "arguments": {
    "username": "microsoft"
  }
}

仓库信息

获取仓库详细信息

{
  "tool": "get_repo_info",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode"
  }
}

回答：

📁 **Repository: microsoft/vscode**

**Description:** Visual Studio Code
**Language:** TypeScript
**Visibility:** public
**Stars:** ⭐ 150000
**Forks:** 🍴 25000
**Watchers:** 👀 5000
**Created:** 1/1/2015
**Updated:** 12/15/2024
**URL:** https://github.com/microsoft/vscode

搜索仓库

{
  "tool": "search_repositories",
  "arguments": {
    "query": "language:typescript stars:>1000",
    "limit": 10
  }
}

高级搜索示例：

• language:javascript - 按编程语言搜索
• stars:>5000 - 按最低星级筛选
• user:octocat - 在特定用户的仓库中搜索
• language:python stars:>1000 forks:>100 - 组合过滤器
• created:>2023-01-01 - 按创建日期筛选
• topic:react - 按主题标签搜索

问题和拉取请求

列出仓库问题

{
  "tool": "list_repo_issues",
  "arguments": {
    "owner": "facebook",
    "repo": "react",
    "state": "open"
  }
}

列出拉取请求

{
  "tool": "list_repo_prs",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode",
    "state": "open"
  }
}

提交历史

列出最近的提交

{
  "tool": "list_repo_commits",
  "arguments": {
    "owner": "nodejs",
    "repo": "node",
    "limit": 20
  }
}

统计

获取用户统计数据

{
  "tool": "get_github_stats",
  "arguments": {
    "username": "torvalds"
  }
}

回应：

📊 **GitHub Statistics for torvalds**

**User Info:**
• Followers: 50000
• Following: 0
• Public Repos: 1

**Repository Stats:**
• Total Repositories: 1
• Total Stars Received: ⭐ 200000
• Total Forks: 🍴 80000
• Average Stars per Repo: 200000.0

**Top Languages:**
C: 1

📚 资源

存储库资源

通过URI访问仓库数据： github://repository/{owner}/{repo}

示例：

• github://repository/microsoft/vscode
• github://repository/facebook/react

用户资源

通过URI访问用户数据： github://user/{username}

示例：

• github://user/octocat
• github://user/Om-Shree-0709

💬 提示/指令

自然语言查询

用自然语言对GitHub数据提出问题：

{
  "prompt": "github_query",
  "arguments": {
    "query": "Show me my most starred repositories"
  }
}

支持的查询：

• “显示我星标最多的仓库”
• “搜索TypeScript仓库”
• “微软/vscode 中有哪些未解决的问题？”
• “列出我的存储库”
• “获取用户octocat的统计数据”

🔧 配置

环境变量

创建一个 .env 与……一起存档：

# Required
GITHUB_TOKEN=your_github_token_here

# Optional
GITHUB_USERNAME=your_username_here

GitHub 令牌作用域

您的GitHub令牌需要以下范围权限：

• repo - 完全控制私有仓库
• user - 读取所有用户资料数据
• read:org - 读取组织和团队成员身份

🏗 建筑学

服务器是使用以下技术构建的：

• TypeScript - 类型安全的开发
• MCP SDK（MCP软件开发工具包） - 模型上下文协议框架
• Octokit（注：Octokit是一个用于与GitHub API交互的库，通常不直接翻译其名称，但在此按照要求给出中文表达）—— GitHub API交互库 官方GitHub API客户端
• 佐德 - 模式验证
• Stdio 传输（或“标准I/O传输”，具体翻译可能根据上下文有所调整） - 标准输入/输出通信

项目结构

src/
├── server.ts          # Main server implementation with all tools and resources

dist/                  # Compiled JavaScript
node_modules/          # Dependencies

🔗 集成

使用 Claude Desktop

在您的Claude桌面配置中添加：

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

与其他MCP客户端一起

服务器通过标准输入输出（stdio）进行通信，并遵循MCP协议规范。它与任何能够发送JSON-RPC请求的MCP兼容客户端都能协同工作。

直接使用 JSON-RPC

向您的服务器发送 JSON-RPC 2.0 请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_repo_info",
    "arguments": {
      "owner": "microsoft",
      "repo": "vscode"
    }
  }
}

🛡 错误处理

该服务器包含全面的错误处理机制：

• ✅ 认证错误 - 明确提示无效令牌的信息
• ✅ 速率限制 优雅地处理GitHub API速率限制
• ✅ 网络错误 - 妥善处理连接问题
• ✅（勾选符号，表示正确、确认或完成） 验证错误 - 输入验证，并提供有用的错误信息
• ✅ GitHub API错误 - 来自GitHub的详细错误报告

📈 性能特性

• 高效使用API - 对请求进行了优化，采用了适当的分页方式
• 适合缓存 - 为便于缓存而设计的响应
• 了解速率限制 - 尊重GitHub API的速率限制
• 批处理操作 - 高效处理多个请求

🎯 实际应用场景

1. 仓库研究

{"tool": "get_repo_info", "arguments": {"owner": "microsoft", "repo": "vscode"}}
{"tool": "list_repo_issues", "arguments": {"owner": "microsoft", "repo": "vscode", "state": "open"}}
{"tool": "list_repo_prs", "arguments": {"owner": "microsoft", "repo": "vscode", "state": "open"}}

2. 用户分析

{"tool": "get_user_info", "arguments": {"username": "torvalds"}}
{"tool": "get_github_stats", "arguments": {"username": "torvalds"}}
{"tool": "list_user_repos", "arguments": {"username": "torvalds", "type": "all"}}

3. 项目发现

{"tool": "search_repositories", "arguments": {"query": "language:typescript stars:>1000"}}
{"tool": "search_repositories", "arguments": {"query": "topic:machine-learning created:>2023-01-01"}}

4. 您自己的数据

{"tool": "get_my_info", "arguments": {}}
{"tool": "get_my_repos", "arguments": {"type": "all"}}
{"tool": "get_github_stats", "arguments": {"username": "Om-Shree-0709"}}

📝 开发

可用脚本

• npm run build - 构建TypeScript项目
• npm run build:watch - 使用文件监视进行构建
• npm run dev - 在开发模式下运行
• npm start - 运行编译后的服务器
• npm test - 测试服务器
• npm run setup - 运行安装脚本
• npm run demo - 运行演示脚本
• npm run interactive-test - 运行交互式测试

添加新工具

1. 在（某处）创建一个新函数 src/server.ts
2. 将工具注册到 server.registerTool()
3. 添加适当的错误处理
4. 更新这个README文件

测试

# Build and test
npm run build
npm start

# Test with various scripts
npm test
npm run simple-test
npm run interactive-test
npm run demo

🚨 故障排除

常见问题

1. “找不到模块”错误

- 跑 npm install 安装依赖项 - 跑 npm run build 编译TypeScript

1. 身份验证失败

- 检查你的GitHub令牌是否有效 - 确保令牌具有所需的范围 - 验证 .env 文件存在且可读

1. 速率限制错误

- 在提出更多请求之前请稍等 - 考虑使用具有更高速率限制的令牌

1. 未找到存储库

- 检查所有者和仓库名称是否正确 - 确保仓库是公开的，或者你有访问权限

调试模式

以开发模式运行以获取详细日志记录：

npm run dev

📊 响应格式

所有工具均以MCP标准格式返回响应，并且 content 包含文本块的数组：

{
  "content": [
    {
      "type": "text",
      "text": "📁 **Repository: microsoft/vscode**\n\n**Description:** Visual Studio Code\n**Stars:** ⭐ 150000\n..."
    }
  ]
}

🤝 贡献（或：参与贡献）

1. 为仓库创建分支（或“克隆仓库”）
2. 创建一个特性分支
3. 添加您的更改
4. 彻底测试
5. 提交拉取请求

📄 许可证

MIT 许可证 - 详情请参见 LICENSE 文件

🆘 支持

• 问题通过 GitHub Issues 报告错误和功能请求
• 文档查阅MCP规范以获取协议详情
• GitHub API参考

🔗 相关链接

• 模型上下文协议
• Octokit.js
• TypeScript

______________________________________________________________________

编程愉快！ 🚀

您的GitHub MCP服务器已就绪，配备10款强大工具！您可以：

• ✅ 获取任何仓库信息
• ✅ 使用高级过滤器搜索仓库
• ✅ 列出问题和拉取请求
• ✅ 浏览提交历史
• ✅ 获取用户资料和统计数据
• ✅ 访问您自己的GitHub数据
• ✅ 使用自然语言查询