Github To MCP

🚀 GitHub to MCP

将任何 GitHub 仓库在数秒内转换为 MCP 服务器，让 Claude、ChatGPT、Cursor、Windsurf、Cline 等所有 AI 助手能够即时访问任意代码库。

🚀 快速开始

🌐 Web UI（最简单的方式）

访问 github-to-mcp.vercel.app，粘贴任意 GitHub URL，点击“生成”，然后下载你的 MCP 服务器。

💻 CLI（一键操作）

npx @nirholas/github-to-mcp https://github.com/stripe/stripe-node

📦 编程式调用（用于自动化）

import { generateFromGithub } from '@nirholas/github-to-mcp';

const result = await generateFromGithub('https://github.com/stripe/stripe-node');
console.log(`Generated ${result.tools.length} tools`);
await result.save('./my-mcp-server');

✨ 主要特性

🔬 仓库分析

• 自动对仓库类型进行分类（API、库、CLI 工具、MCP 服务器、文档）
• 检测并解析 OpenAPI/Swagger 规范
• 提取 GraphQL 模式并生成查询/变更工具
• 解析 gRPC/Protobuf 服务定义
• 支持 AsyncAPI 规范，用于事件驱动的 API
• 进行源代码分析以提取函数

🌍 多语言支持

输入仓库支持的语言：

• TypeScript 和 JavaScript
• Python
• Go
• Java 和 Kotlin
• Rust
• Ruby
• C# 和 F#

输出的 MCP 服务器支持的语言：

• TypeScript（使用官方 MCP SDK）
• Python（使用 MCP Python SDK）
• Go（使用社区 MCP 库）

🔧 工具提取

• OpenAPI 端点转换为可调用的工具，并带有类型化参数
• GraphQL 查询和变更转换为带有输入验证的工具
• 保留使用 @mcp.tool 装饰的 Python 函数
• README 中记录的 CLI 命令转换为可执行工具
• 检测流行框架中的 HTTP 路由处理程序

⚡ 代码生成

• 生成包含所有依赖的完整、可运行的 MCP 服务器代码
• 为 Claude Desktop、Cursor 等客户端生成配置文件
• 提供 Docker 部署模板
• 为所有生成的工具生成 TypeScript 类型定义

📦 安装指南

从源代码安装

克隆仓库并安装依赖：

git clone https://github.com/nirholas/github-to-mcp.git
cd github-to-mcp
pnpm install
pnpm build

使用 Web 界面

Web 应用部署在 github-to-mcp.vercel.app，可使用基于浏览器的界面，无需本地安装。

💻 使用示例

🌐 Web 界面

Web 界面提供了最简单的仓库转换方式：

1. 访问 Web 应用。
2. 输入 GitHub 仓库 URL（例如 https://github.com/owner/repo）。
3. 可选择配置提取选项。
4. 点击“生成”以分析仓库。
5. 查看生成的工具和代码。
6. 下载 MCP 服务器包或复制配置。

Web 界面还提供了一个交互式游乐场，可在下载前测试生成的工具。

💻 命令行界面

在本地构建项目后，可使用 CLI：

# 基本用法
node packages/core/dist/cli.mjs https://github.com/owner/repo

# 指定输出目录
node packages/core/dist/cli.mjs https://github.com/owner/repo --output ./my-mcp-server

# 生成 Python 而不是 TypeScript
node packages/core/dist/cli.mjs https://github.com/owner/repo --language python

# 仅包含特定的提取源
node packages/core/dist/cli.mjs https://github.com/owner/repo --sources openapi,readme

# 使用 GitHub 令牌访问私有仓库或提高速率限制
GITHUB_TOKEN=ghp_xxx node packages/core/dist/cli.mjs https://github.com/owner/repo

📦 编程式 API

在自己的 TypeScript 或 JavaScript 代码中导入生成器：

import { GithubToMcpGenerator } from '@nirholas/github-to-mcp';

const generator = new GithubToMcpGenerator({
  githubToken: process.env.GITHUB_TOKEN,
  sources: ['openapi', 'readme', 'code', 'graphql', 'grpc', 'mcp'],
  outputLanguage: 'typescript'
});

const result = await generator.generate('https://github.com/owner/repo');

console.log(`Repository: ${result.name}`);
console.log(`Classification: ${result.classification.type}`);
console.log(`Generated ${result.tools.length} tools`);

// 访问生成的代码
console.log(result.code);

// 保存到磁盘
await result.save('./output-directory');

interface GithubToMcpOptions {
  // GitHub 个人访问令牌，用于 API 认证
  githubToken?: string;
  
  // 从哪些源提取工具
  // 默认值: ['openapi', 'readme', 'code', 'graphql', 'mcp']
  sources?: Array<'openapi' | 'readme' | 'code' | 'graphql' | 'grpc' | 'mcp'>;
  
  // 生成服务器的输出语言
  // 默认值: 'typescript'
  outputLanguage?: 'typescript' | 'python' | 'go';
  
  // 包含通用工具（read_file、list_files 等）
  // 默认值: true
  includeUniversalTools?: boolean;
  
  // 生成工具的最大数量
  // 默认值: 100
  maxTools?: number;
  
  // 要分析的特定分支
  // 默认值: 仓库的默认分支
  branch?: string;
}

📚 详细文档

⚙️ 工作原理

转换过程分为以下几个阶段：

🏷️ 仓库分类

生成器首先分析仓库，确定其类型和结构：

1. 从 GitHub API 获取仓库元数据。
2. 下载并解析 README 文件。
3. 检查 package.json、setup.py、go.mod 或其他清单文件。
4. 扫描 API 规范文件（openapi.json、schema.graphql 等）。
5. 将仓库分类为以下类型之一： | 分类 | 描述 | |----------------|-------------| | mcp-server | 现有的 MCP 服务器实现 | | api-sdk | API 的客户端库 | | cli-tool | 命令行应用程序 | | library | 通用代码库 | | documentation | 主要是文档内容 | | data | 数据文件或数据集 | | unknown | 未分类的仓库 |

分类会影响提取策略的优先级和工具的命名。

🔍 工具提取

工具从仓库的多个源中提取：

🏗️ 代码生成

提取工具后，生成器会生成：

1. 实现 MCP 协议的主服务器文件。
2. 每个提取工具的工具处理函数。
3. 所有输入和输出模式的类型定义。
4. 包含所需依赖的 package.json 或等效文件。
5. 流行 MCP 客户端的配置文件。
6. 可选的 Docker 部署文件。

生成的代码完整且无需修改即可运行。

🛠️ 生成的工具

🌐 通用工具

每个生成的 MCP 服务器都包含以下用于仓库探索的基础工具：

这些工具确保即使未检测到 API 或函数，AI 助手仍能探索和理解仓库。

🔧 提取的工具

根据仓库内容生成其他工具：

从 OpenAPI 规范中提取

每个 API 端点成为一个工具：

POST /users      →  create_user(name: string, email: string)
GET /users/{id}  →  get_user(id: string)
PUT /users/{id}  →  update_user(id: string, name?: string, email?: string)
DELETE /users/{id} →  delete_user(id: string)
GET /users       →  list_users(page?: number, limit?: number)

从 GraphQL 模式中提取

查询和变更成为工具：

type Query {
  user(id: ID!): User         →  get_user(id: string)
  users(first: Int): [User]   →  list_users(first?: number)
}

type Mutation {
  createUser(input: CreateUserInput!): User  →  create_user(input: object)
}

从 Python 代码中提取

@server.tool()
async def analyze_sentiment(text: str) -> str:
    """Analyze the sentiment of the given text."""
    # Implementation

变为：analyze_sentiment(text: string) → "分析给定文本的情感。"

从 README 示例中提取

README 中记录的 CLI 命令：

# Create a new project
mycli create --name myproject --template typescript

变为：mycli_create(name: string, template?: string)

⚙️ 配置

🔐 环境变量

GitHub 令牌

没有令牌时，GitHub API 请求限制为每小时 60 次。使用令牌时，限制提高到每小时 5000 次。对于私有仓库，需要具有适当访问权限的令牌。 在 https://github.com/settings/tokens 创建令牌。 所需权限范围：

• repo（用于私有仓库）
• public_repo（仅用于公共仓库）

🎛️ 生成器选项

使用编程式 API 时，可以进行如下配置：

const generator = new GithubToMcpGenerator({
  // 认证
  githubToken: process.env.GITHUB_TOKEN,
  
  // 启用的提取源
  sources: ['openapi', 'readme', 'code', 'graphql', 'grpc', 'mcp'],
  
  // 输出配置
  outputLanguage: 'typescript', // 或 'python', 'go'
  
  // 工具过滤
  includeUniversalTools: true,
  maxTools: 100,
  
  // 仓库选项
  branch: 'main', // 要分析的特定分支
});

🤖 与 AI 助手集成

Claude Desktop

将生成的服务器添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "my-repo": {
      "command": "node",
      "args": ["/absolute/path/to/generated/server.mjs"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxx"
      }
    }
  }
}

⚠️ 修改配置后，请重启 Claude Desktop。

Cursor

Cursor 通过其设置支持 MCP 服务器。在 Cursor 的 MCP 配置面板中添加服务器路径，或直接编辑配置文件：

{
  "mcp": {
    "servers": {
      "my-repo": {
        "command": "node",
        "args": ["/path/to/server.mjs"]
      }
    }
  }
}

💻 VS Code 与 Continue 扩展

如果使用 VS Code 的 Continue 扩展：

{
  "models": [...],
  "mcpServers": {
    "my-repo": {
      "command": "node",
      "args": ["/path/to/server.mjs"]
    }
  }
}

🔌 其他 MCP 客户端

任何兼容 MCP 的客户端都可以使用生成的服务器。服务器默认通过 stdio 进行通信，在 stdin 上接受 JSON-RPC 消息并在 stdout 上响应。 手动运行：

node server.mjs

服务器将在 stdin 上等待 MCP 协议消息。

🎮 交互式游乐场

Web 应用包含一个交互式游乐场，用于测试生成的工具：

1. 从仓库生成工具后，点击“在游乐场中打开”。
2. 从列表中选择一个工具。
3. 填写所需参数。
4. 点击“执行”以运行工具。
5. 查看 JSON 响应。

游乐场在沙盒环境中执行工具，并实时显示结果。

🔗 共享游乐场会话

可以与他人共享生成的工具：

示例：

https://github-to-mcp.vercel.app/playground?gist=abc123&name=My%20API

📁 项目结构

github-to-mcp/
├── 📂 apps/
│   ├── 📂 web/                    # Next.js 网页应用
│   │   ├── 📂 app/                # Next.js 应用路由页面
│   │   │   ├── 📂 api/            # 用于转换的 API 路由
│   │   │   ├── 📂 convert/        # 转换页面
│   │   │   ├── 📂 playground/     # 交互式游乐场
│   │   │   └── 📂 dashboard/      # 用户仪表盘
│   │   ├── 📂 components/         # React 组件
│   │   ├── 📂 hooks/              # 自定义 React 钩子
│   │   ├── 📂 lib/                # 实用函数
│   │   └── 📂 types/              # TypeScript 类型定义
│   └── 📂 vscode/                 # VS Code 扩展（开发中）
│
├── 📂 packages/
│   ├── 📂 core/                   # 主要转换引擎
│   │   └── 📂 src/
│   │       ├── index.ts           # GithubToMcpGenerator 类
│   │       ├── github-client.ts   # GitHub API 客户端
│   │       ├── readme-extractor.ts    # README 解析
│   │       ├── code-extractor.ts      # 源代码分析
│   │       ├── graphql-extractor.ts   # GraphQL 模式解析
│   │       ├── mcp-introspector.ts    # 现有 MCP 服务器检测
│   │       ├── python-generator.ts    # Python 输出生成
│   │       ├── go-generator.ts        # Go 输出生成
│   │       └── types.ts               # 类型定义
│   │
│   ├── 📂 openapi-parser/         # OpenAPI 规范解析器
│   │   └── 📂 src/
│   │       ├── parser.ts          # OpenAPI 解析逻辑
│   │       ├── analyzer.ts        # 端点分析
│   │       ├── transformer.ts     # 模式转换
│   │       └── generator.ts       # 工具生成
│   │
│   ├── 📂 mcp-server/             # MCP 服务器实用工具
│   │   └── 📂 src/
│   │       ├── server.ts          # 基础 MCP 服务器实现
│   │       └── tools.ts           # 工具注册助手
│   │
│   └── 📂 registry/               # 工具注册表管理
│       └── 📂 src/
│           └── index.ts           # 注册表操作
│
├── 📂 mkdocs/                     # 文档网站（MkDocs）
│   ├── 📂 docs/                   # Markdown 文档
│   └── mkdocs.yml                 # MkDocs 配置
│
├── 📂 tests/                      # 集成测试
│   ├── 📂 fixtures/               # 测试用仓库
│   │   ├── 📂 express-app/        # Express.js 测试应用
│   │   ├── 📂 fastapi-app/        # FastAPI 测试应用
│   │   ├── 📂 graphql/            # GraphQL 测试模式
│   │   └── 📂 openapi/            # OpenAPI 测试规范
│   └── 📂 integration/            # 集成测试文件
│
├── 📂 templates/                  # 代码生成模板
│   ├── Dockerfile.python.template
│   └── Dockerfile.typescript.template
│
├── package.json                   # 根包配置
├── pnpm-workspace.yaml            # pnpm 工作区配置
├── tsconfig.json                  # TypeScript 配置
└── vitest.config.ts               # 测试配置

🔨 开发

先决条件

本地设置

# 克隆仓库
git clone https://github.com/nirholas/github-to-mcp.git
cd github-to-mcp

# 安装依赖
pnpm install

# 构建所有包
pnpm build

# 启动开发服务器
pnpm dev

Web 应用将在 http://localhost:3000 可用。

构建

# 构建所有包
pnpm build

# 构建特定包
pnpm --filter @nirholas/github-to-mcp build
pnpm --filter @github-to-mcp/openapi-parser build
pnpm --filter web build

测试

# 运行所有测试
pnpm test

# 以监视模式运行测试
pnpm test:watch

# 运行带覆盖率的测试
pnpm test:coverage

# 运行特定测试文件
pnpm test -- tests/integration/openapi-conversion.test.ts

代码质量

# 运行代码检查
pnpm lint

# 类型检查
pnpm typecheck

🏗️ 架构概述

系统遵循管道架构：

输入 (GitHub URL)
       │
       ▼
┌──────────────────┐
│  GitHub 客户端   │  获取仓库元数据、文件和 README
└──────────────────┘
       │
       ▼
┌──────────────────┐
│   分类器         │  确定仓库类型和结构
└──────────────────┘
       │
       ▼
┌──────────────────┐
│   提取器         │  多个提取器并行运行：
│  ├─ OpenAPI      │  • 解析 API 规范
│  ├─ GraphQL      │  • 解析 GraphQL 模式
│  ├─ README       │  • 从文档中提取示例
│  ├─ 代码         │  • 分析源代码
│  └─ MCP          │  • 检测现有的 MCP 工具
└──────────────────┘
       │
       ▼
┌──────────────────┐
│  去重器          │  移除重复工具，合并相似工具
└──────────────────┘
       │
       ▼
┌──────────────────┐
│   验证器         │  验证工具模式，添加置信度分数
└──────────────────┘
       │
       ▼
┌──────────────────┐
│   生成器         │  以目标语言生成输出代码
└──────────────────┘
       │
       ▼
输出 (MCP 服务器代码 + 配置)

每个提取器生成具有标准化模式的 ExtractedTool 对象列表。去重器和验证器确保一致性，然后生成器生成最终输出。

📥 支持的输入格式

API 规范

源代码语言

📤 输出格式

TypeScript 服务器

默认输出是使用官方 @modelcontextprotocol/sdk 包的 TypeScript MCP 服务器：

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = new Server({
  name: 'generated-server',
  version: '1.0.0',
}, {
  capabilities: {
    tools: {},
  },
});

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [/* 生成的工具 */],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  // 工具调度逻辑
});

const transport = new StdioServerTransport();
await server.connect(transport);

Python 服务器

Python 输出使用 MCP Python SDK：

from mcp.server import Server
from mcp.server.stdio import stdio_server

server = Server("generated-server")

@server.tool()
async def example_tool(param: str) -> str:
    """工具描述。"""
    # 实现
    
async def main():
    async with stdio_server() as (read_stream, write_stream):
        await server.run(read_stream, write_stream)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

配置文件

每个生成的服务器都包含：

⚠️ 限制

🔧 故障排除

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

🤝 贡献

欢迎贡献！请参阅 CONTRIBUTING.md 以获取详细的指南，包括：

• 设置开发环境
• 代码风格和格式化要求
• 测试要求
• 拉取请求流程

🐛 报告问题

报告问题时，请包括：

• 导致问题的仓库 URL（如果是公共仓库）
• 错误消息或意外行为
• Node.js 和 pnpm 版本
• 操作系统

📄 许可证

本项目采用 Apache 2.0 许可证。详情请参阅 LICENSE。

🔗 链接

由 nich 构建