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 構建