金大哥 - github-to-mcp MCP 详情

article

README

🚀 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 界面提供了最简单的仓库转换方式：

访问 Web 应用。
输入 GitHub 仓库 URL（例如 https://github.com/owner/repo）。
可选择配置提取选项。
点击“生成”以分析仓库。
查看生成的工具和代码。
下载 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;
}

📚 详细文档

⚙️ 工作原理

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

🏷️ 仓库分类

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

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

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

🔍 工具提取

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

📄 OpenAPI/Swagger 提取

当找到 OpenAPI 规范时：

解析规范（JSON 或 YAML，v2 或 v3）。
将每个端点提取为潜在工具。
将路径参数、查询参数和请求体转换为工具输入模式。
根据操作摘要和描述生成描述。
将 HTTP 方法映射到适当的工具语义。

🔷 GraphQL 提取

当找到 GraphQL 模式时：

解析 .graphql 或 .gql 模式文件。
提取 Query 类型字段作为只读工具。
提取 Mutation 类型字段作为写工具。
将 GraphQL 输入类型转换为 JSON 模式，用于工具输入。
处理嵌套类型和自定义标量。

📖 README 提取

分析 README 以获取：

显示 CLI 使用模式的代码块。
使用 curl 或 fetch 的 API 端点示例。
带有参数的函数调用示例。
安装和使用说明。

提取的示例成为带有推断参数模式的工具。

💻 源代码提取

对于支持的语言，分析源代码：

Python：使用 @mcp.tool、@server.tool 或类似装饰器的函数。
TypeScript：带有 JSDoc 注释的导出函数。
Go：来自 Gin、Echo、Chi、Fiber 或 Gorilla Mux 的 HTTP 处理程序。
Java/Kotlin：使用 @GetMapping、@PostMapping 等注释的方法。
Rust：来自 Actix-web、Axum 或 Rocket 的路由处理程序。

🔌 MCP 服务器自省

如果仓库已经是 MCP 服务器：

检测 server.tool() 定义。
提取工具名称、描述和模式。
尽可能保留现有的工具实现。

🏗️ 代码生成

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

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

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

🛠️ 生成的工具

🌐 通用工具

每个生成的 MCP 服务器都包含以下用于仓库探索的基础工具： | 工具 | 描述 | 参数 | |------|-------------|------------| | get_readme | 获取仓库的 README 内容 | 无 | | list_files | 列出给定路径下的文件和目录 | path（可选，默认为根目录） | | read_file | 读取特定文件的内容 | path（必需） | | search_code | 在仓库中搜索模式 | query（必需），path（可选） |

这些工具确保即使未检测到 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_TOKEN | 用于 API 访问的 GitHub 个人访问令牌 | 否（但建议使用） | | GITHUB_API_URL | 企业版的自定义 GitHub API URL | 否 |

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 配置中： | 平台 | 配置路径 | |----------|-------------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

{
  "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 应用包含一个交互式游乐场，用于测试生成的工具：

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

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

🔗 共享游乐场会话

可以与他人共享生成的工具： | 参数 | 描述 | |-----------|-------------| | ?code=<base64> | 经过 Base64 编码的 TypeScript 服务器代码 | | ?gist=<id> | 包含服务器代码的 GitHub Gist ID | | ?name=<name> | 服务器的显示名称 |

示例：

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               # 测试配置

🔨 开发

先决条件

| 要求 | 版本 | |-------------|---------| | Node.js | 22.x 或更高版本 | | pnpm | 10.x 或更高版本 | | Git | 2.x 或更高版本 |

本地设置

# 克隆仓库
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 规范

| 格式 | 文件模式 | 版本支持 | |--------|---------------|-----------------| | OpenAPI | openapi.json, openapi.yaml, swagger.json, swagger.yaml, api.json, api.yaml | 2.0, 3.0.x, 3.1.x | | GraphQL | schema.graphql, *.gql, schema.json | 2018 年 6 月规范 | | gRPC | *.proto | proto3 | | AsyncAPI | asyncapi.json, asyncapi.yaml | 2.x |

源代码语言

| 语言 | 框架检测 | |----------|---------------------| | TypeScript/JavaScript | Express, Fastify, Hono, Next.js API 路由 | | Python | FastAPI, Flask, Django REST, MCP SDK 装饰器 | | Go | Gin, Echo, Chi, Fiber, Gorilla Mux | | Java | Spring Boot, JAX-RS, Micronaut | | Kotlin | Ktor, Spring Boot | | Rust | Actix-web, Axum, Rocket | | Ruby | Rails, Sinatra, Grape |

📤 输出格式

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())

配置文件

每个生成的服务器都包含： | 文件 | 描述 | |------|-------------| | claude_desktop_config.json | Claude Desktop 配置片段 | | cursor_config.json | Cursor 编辑器配置 | | package.json 或 requirements.txt | 依赖项 | | Dockerfile（可选） | 容器部署 |

⚠️ 限制

🔄 GitHub API 速率限制

未认证请求：每小时 60 次
认证请求：每小时 5000 次
大型仓库可能需要多次 API 调用

提供 GITHUB_TOKEN 以提高速率限制。

📦 仓库大小

非常大的仓库（>1GB）在分析过程中可能会超时
包含数千个文件的仓库可能会达到 API 限制
对于单体仓库，考虑分析特定子目录

🎯 工具提取准确性

OpenAPI 规范生成的工具最准确
README 提取依赖于一致的文档格式
源代码分析可能会错过动态定义的路由
置信度分数表示提取的可靠性

🌍 语言支持

TypeScript 输出最成熟
Python 输出功能正常，但可能需要少量编辑
Go 输出处于实验阶段

🔧 故障排除

❌ "速率限制已超出" 错误

提供 GitHub 令牌：

export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

❌ "仓库未找到" 错误

验证 URL 是否正确
对于私有仓库，确保你的令牌具有 repo 权限范围
检查仓库是否存在且可访问

❌ "未提取到工具" 结果

验证仓库是否包含 API 定义或记录的端点
尝试启用所有提取源：--sources openapi,readme,code,graphql,mcp
检查规范文件是否遵循标准命名约定

❌ 生成的服务器无法启动

确保安装了 Node.js 22+
在生成的目录中运行 npm install
使用 npx tsc --noEmit 检查 TypeScript 编译错误

❌ Claude Desktop 未显示服务器

验证 claude_desktop_config.json 中的路径是否为绝对路径
修改配置后重启 Claude Desktop
检查 Claude Desktop 日志中的连接错误

🤝 贡献

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

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

🐛 报告问题

报告问题时，请包括：

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

📄 许可证

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

🔗 链接

| 资源 | URL | |----------|-----| | 📖 文档 | docs-github-to-mcp.vercel.app | | 🌐 Web 应用 | github-to-mcp.vercel.app | | 📦 npm 包 | npmjs.com/package/@nirholas/github-to-mcp | | 🔗 MCP 规范 | modelcontextprotocol.io | | 📘 MCP TypeScript SDK | github.com/modelcontextprotocol/typescript-sdk | | 🐍 MCP Python SDK | github.com/modelcontextprotocol/python-sdk | | 💬 讨论 | github.com/nirholas/github-to-mcp/discussions |

由 nich 构建