github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/guides/private-repos.md

@@ -0,0 +1,221 @@
+# Working with Private Repositories
+
+Use GitHub to MCP with private repositories using authentication.
+
+## GitHub Token Setup
+
+To access private repositories, you need a GitHub Personal Access Token (PAT).
+
+### Creating a Token
+
+1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens)
+2. Click **"Generate new token (classic)"**
+3. Give it a descriptive name (e.g., "GitHub to MCP")
+4. Select scopes:
+   - `repo` - Full control of private repositories
+   - Or `read:packages` for read-only access
+5. Click **"Generate token"**
+6. **Copy the token immediately** (you won't see it again!)
+
+### Token Scopes
+
+| Scope | Description | Use Case |
+|-------|-------------|----------|
+| `repo` | Full access to private repos | Read/write operations |
+| `public_repo` | Access to public repos only | Higher rate limits |
+| `read:packages` | Read packages | Package registries |
+
+## Using Your Token
+
+### Environment Variable (Recommended)
+
+Set the `GITHUB_TOKEN` environment variable:
+
+=== "macOS/Linux"
+
+    ```bash
+    # Add to ~/.bashrc or ~/.zshrc
+    export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+    ```
+
+=== "Windows PowerShell"
+
+    ```powershell
+    $env:GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
+    ```
+
+=== "Windows CMD"
+
+    ```cmd
+    set GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+    ```
+
+Then use normally:
+
+```bash
+npx @nirholas/github-to-mcp https://github.com/your-org/private-repo
+```
+
+### CLI Flag
+
+Pass the token directly:
+
+```bash
+npx @nirholas/github-to-mcp https://github.com/your-org/private-repo \
+  --token ghp_xxxxxxxxxxxxx
+```
+
+!!! warning "Security Warning"
+    Don't commit tokens to version control or share them in logs.
+
+### Programmatic
+
+```typescript
+import { generateFromGithub } from '@nirholas/github-to-mcp';
+
+const result = await generateFromGithub(
+  'https://github.com/your-org/private-repo',
+  { token: process.env.GITHUB_TOKEN }
+);
+```
+
+## Web UI Authentication
+
+On the [web interface](https://github-to-mcp.vercel.app):
+
+1. Click the **"Settings"** gear icon
+2. Enter your GitHub token in the **"GitHub Token"** field
+3. The token is stored locally in your browser (not sent to servers)
+4. Generate private repos normally
+
+## GitHub Enterprise
+
+For GitHub Enterprise Server, use the full URL:
+
+```bash
+npx @nirholas/github-to-mcp https://github.your-company.com/org/repo \
+  --token ghp_xxxxxxxxxxxxx
+```
+
+## Rate Limits
+
+| Authentication | Rate Limit |
+|---------------|------------|
+| Anonymous | 60 requests/hour |
+| With Token | 5,000 requests/hour |
+| GitHub Enterprise | Varies by instance |
+
+!!! tip "Always Use a Token"
+    Even for public repos, using a token gives you 83x more API calls.
+
+## Organization Repositories
+
+### SSO-Enabled Organizations
+
+If your organization uses SAML SSO:
+
+1. Create your token normally
+2. Go to [Token Settings](https://github.com/settings/tokens)
+3. Find your token and click **"Enable SSO"**
+4. Authorize for your organization
+
+### Fine-Grained Tokens
+
+For better security, use fine-grained tokens:
+
+1. Go to [Fine-grained tokens](https://github.com/settings/tokens?type=beta)
+2. Click **"Generate new token"**
+3. Select specific repositories
+4. Choose minimal permissions:
+   - `Contents: Read-only`
+   - `Metadata: Read-only`
+
+## Security Best Practices
+
+### 1. Rotate Tokens Regularly
+
+Set a reminder to regenerate tokens every 90 days.
+
+### 2. Use Minimum Scopes
+
+Only request the permissions you need.
+
+### 3. Never Commit Tokens
+
+Add to `.gitignore`:
+
+```gitignore
+.env
+.env.local
+*.token
+```
+
+### 4. Use Environment Variables
+
+Never hardcode tokens in your code.
+
+### 5. Audit Token Usage
+
+Check [Security Log](https://github.com/settings/security-log) for token activity.
+
+## Troubleshooting
+
+### "Bad credentials" Error
+
+- Token may be expired
+- Token may lack required scopes
+- SSO may not be authorized
+
+### "Not Found" Error
+
+- Repo doesn't exist or is private
+- Token lacks `repo` scope
+- Token not authorized for organization
+
+### Rate Limit Exceeded
+
+- Wait for the limit to reset (usually 1 hour)
+- Use a token if not already
+- Check for API-heavy operations
+
+### Check Token Validity
+
+```bash
+curl -H "Authorization: token ghp_xxxxx" \
+  https://api.github.com/user
+```
+
+Should return your user information.
+
+---
+
+## Example: Private Repo Workflow
+
+Complete workflow for a private repository:
+
+```bash
+# 1. Set token
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+
+# 2. Generate MCP server
+npx @nirholas/github-to-mcp https://github.com/my-company/internal-api \
+  -o ~/mcp-servers/internal-api
+
+# 3. Install dependencies
+cd ~/mcp-servers/internal-api
+npm install
+
+# 4. Test the server
+npm start
+
+# 5. Add to Claude Desktop
+# Edit claude_desktop_config.json
+```
+
+---
+
+## Next Steps
+
+- [Custom Tools](custom-tools.md) - Extend your MCP server
+- [Claude Desktop](claude-desktop.md) - Connect your server
+- [Configuration](../getting-started/configuration.md) - More options

package/mkdocs/docs/guides/vscode.md

@@ -0,0 +1,247 @@
+# VS Code Integration
+
+Use GitHub to MCP with Visual Studio Code for enhanced AI-assisted development.
+
+## Overview
+
+VS Code can use MCP servers through several methods:
+
+1. **GitHub Copilot Chat** - Native MCP support (coming soon)
+2. **Continue Extension** - MCP-enabled coding assistant
+3. **Custom Extensions** - Build your own integration
+
+## Method 1: Continue Extension
+
+[Continue](https://continue.dev) is an open-source coding assistant that supports MCP.
+
+### Installation
+
+1. Install the [Continue extension](https://marketplace.visualstudio.com/items?itemName=Continue.continue)
+2. Open VS Code command palette: `Cmd/Ctrl + Shift + P`
+3. Search "Continue: Open Configuration"
+
+### Configuration
+
+Edit `~/.continue/config.json`:
+
+```json
+{
+  "models": [...],
+  "mcpServers": [
+    {
+      "name": "my-repo",
+      "command": "node",
+      "args": ["/path/to/my-repo-mcp/server.mjs"]
+    }
+  ]
+}
+```
+
+### Usage
+
+1. Open Continue panel (`Cmd/Ctrl + L`)
+2. Ask questions referencing your MCP server
+3. Continue will use MCP tools automatically
+
+## Method 2: MCP Inspector
+
+For testing and debugging MCP servers in VS Code:
+
+### Install MCP Inspector
+
+```bash
+npm install -g @modelcontextprotocol/inspector
+```
+
+### Use with VS Code Terminal
+
+```bash
+# Start your MCP server
+cd ~/mcp-servers/my-repo
+node server.mjs
+
+# In another terminal, inspect
+mcp-inspector ws://localhost:3000
+```
+
+## Method 3: Custom Task
+
+Create a VS Code task to manage MCP servers:
+
+### .vscode/tasks.json
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Start MCP Server",
+      "type": "shell",
+      "command": "node",
+      "args": ["${workspaceFolder}/mcp-server/server.mjs"],
+      "isBackground": true,
+      "problemMatcher": [],
+      "presentation": {
+        "reveal": "always",
+        "panel": "dedicated"
+      }
+    },
+    {
+      "label": "Generate MCP Server",
+      "type": "shell",
+      "command": "npx",
+      "args": [
+        "@nirholas/github-to-mcp",
+        "${input:repoUrl}",
+        "-o",
+        "${workspaceFolder}/mcp-server"
+      ]
+    }
+  ],
+  "inputs": [
+    {
+      "id": "repoUrl",
+      "type": "promptString",
+      "description": "GitHub repository URL"
+    }
+  ]
+}
+```
+
+### Usage
+
+1. `Cmd/Ctrl + Shift + P` → "Tasks: Run Task"
+2. Select "Generate MCP Server" or "Start MCP Server"
+
+## Workspace Setup
+
+### Project Structure
+
+Recommended structure for projects using MCP:
+
+```
+my-project/
+├── src/
+├── .vscode/
+│   ├── tasks.json      # MCP server tasks
+│   └── settings.json   # Continue/MCP config
+├── mcp-server/         # Generated MCP server
+│   ├── server.mjs
+│   └── package.json
+└── package.json
+```
+
+### Generate on Clone
+
+Add a setup script to package.json:
+
+```json
+{
+  "scripts": {
+    "setup:mcp": "npx @nirholas/github-to-mcp https://github.com/owner/repo -o ./mcp-server",
+    "mcp:start": "node ./mcp-server/server.mjs"
+  }
+}
+```
+
+## GitHub Copilot Integration
+
+!!! note "Coming Soon"
+    Native MCP support in GitHub Copilot Chat is planned. Until then, use Continue or custom integrations.
+
+### Current Workaround
+
+Use MCP-generated code as context for Copilot:
+
+1. Generate server for a reference repo
+2. Keep the `tools/` directory open in VS Code
+3. Copilot will use it as context when generating code
+
+## Tips for VS Code Users
+
+### 1. Use Multi-Root Workspaces
+
+Add MCP servers as workspace folders:
+
+```json
+// my-project.code-workspace
+{
+  "folders": [
+    { "path": "." },
+    { "path": "../mcp-servers/stripe", "name": "Stripe MCP" },
+    { "path": "../mcp-servers/openai", "name": "OpenAI MCP" }
+  ]
+}
+```
+
+### 2. Create Snippets
+
+Add snippets for MCP generation:
+
+```json
+// .vscode/snippets/mcp.code-snippets
+{
+  "Generate MCP": {
+    "prefix": "genmcp",
+    "body": [
+      "npx @nirholas/github-to-mcp $1 -o ./$2-mcp"
+    ],
+    "description": "Generate MCP server command"
+  }
+}
+```
+
+### 3. Terminal Profiles
+
+Add a profile for MCP development:
+
+```json
+// settings.json
+{
+  "terminal.integrated.profiles.osx": {
+    "MCP Dev": {
+      "path": "bash",
+      "args": ["-l"],
+      "env": {
+        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Extension Not Finding Server
+
+Ensure the path is absolute and the server is executable:
+
+```bash
+chmod +x /path/to/server.mjs
+```
+
+### Node Version Issues
+
+Specify Node version in your launch config:
+
+```json
+{
+  "mcpServers": [
+    {
+      "name": "my-repo",
+      "command": "/usr/local/bin/node",
+      "args": ["/path/to/server.mjs"]
+    }
+  ]
+}
+```
+
+---
+
+## Next Steps
+
+- [Private Repos](private-repos.md) - Work with authentication
+- [Custom Tools](custom-tools.md) - Extend your MCP server
+- [CLI Reference](../cli/index.md) - Command-line options

package/mkdocs/docs/index.md

@@ -0,0 +1,175 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+<style>
+.md-content__button {
+  display: none;
+}
+</style>
+
+<div class="hero" markdown>
+
+# GitHub to MCP 🚀
+
+**Convert any GitHub repository into an MCP server in seconds**
+
+Give Claude, ChatGPT, Cursor, Windsurf, Cline, and any AI assistant instant access to any codebase.
+
+[Get Started](getting-started/index.md){ .md-button .md-button--primary }
+[Try Web App](https://github-to-mcp.vercel.app){ .md-button }
+
+</div>
+
+---
+
+## What is GitHub to MCP?
+
+**GitHub to MCP** converts any GitHub repository into a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server. MCP is the open standard that lets AI assistants like **Claude**, **ChatGPT**, **Cursor**, **Windsurf**, and **Cline** interact with external tools and data.
+
+**In plain English:** Paste a GitHub URL → Get an MCP server → Your AI can now read files, search code, and use the repo's APIs.
+
+---
+
+## Why use this?
+
+<div class="feature-grid" markdown>
+
+<div class="feature-card" markdown>
+
+### 🚀 Instant Setup
+
+No manual configuration required. Just paste a URL and you're ready to go.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### 🤖 Works with Any AI
+
+Claude Desktop, ChatGPT, Cursor, VS Code Copilot, Cline, Continue, and more.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### 📦 Zero Config
+
+Generates a complete, runnable MCP server with all dependencies included.
+
+</div>
+
+<div class="feature-card" markdown>
+
+### 🔍 Smart Extraction
+
+Automatically finds APIs, tools, and functions from OpenAPI specs, code, and docs.
+
+</div>
+
+</div>
+
+---
+
+## Quick Start
+
+### Web UI (Easiest)
+
+Visit **[github-to-mcp.vercel.app](https://github-to-mcp.vercel.app)** — Paste any GitHub URL, click Generate, download your MCP server.
+
+### CLI (One Command)
+
+```bash
+npx @nirholas/github-to-mcp https://github.com/stripe/stripe-node
+```
+
+### Programmatic (For Automation)
+
+```typescript
+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');
+```
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     GitHub Repository                        │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│  1. Fetch & Classify  →  Detect repo type (API/CLI/Lib)     │
+│  2. Extract Tools     →  OpenAPI, GraphQL, Code, README     │
+│  3. Generate Server   →  TypeScript or Python MCP server    │
+│  4. Bundle Output     →  Complete package with dependencies │
+└─────────────────────────────────────────────────────────────┘
+                              ↓
+┌─────────────────────────────────────────────────────────────┐
+│              Ready-to-use MCP Server + Config               │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| 🔄 **Universal Conversion** | Every repo gets 4 base tools: `read_file`, `list_files`, `search_code`, `get_readme` |
+| 🔍 **Smart Detection** | Extracts tools from OpenAPI/Swagger specs, GraphQL schemas, Python decorators, and README docs |
+| 🏷️ **Auto Classification** | Identifies repo type (API, MCP server, CLI, library, docs) to optimize extraction |
+| 🐍 **Multi-language Output** | Generate TypeScript or Python MCP servers |
+| ⚡ **Instant Deploy** | One-click Vercel deployment for hosted MCP servers |
+
+---
+
+## Use Cases
+
+- **"I want Claude to understand my codebase"** → Generate an MCP server, add to Claude Desktop
+- **"I want to query the Stripe API from ChatGPT"** → Convert stripe/stripe-node, get typed tools
+- **"I want Cursor to use my internal SDK"** → Point at your private repo (with token)
+- **"I want to wrap any REST API for AI"** → Convert any repo with an OpenAPI spec
+
+---
+
+<div class="quick-links" markdown>
+
+[:fontawesome-solid-rocket: **Getting Started**](getting-started/index.md)
+Learn how to install and use GitHub to MCP
+
+[:fontawesome-solid-book: **Guides**](guides/index.md)
+Integration tutorials for Claude, Cursor, VS Code
+
+[:fontawesome-solid-terminal: **CLI Reference**](cli/index.md)
+Command-line tool documentation
+
+[:fontawesome-solid-code: **API Reference**](api/index.md)
+Programmatic API for automation
+
+</div>
+
+---
+
+## Related Projects
+
+- [Model Context Protocol](https://modelcontextprotocol.io) — The protocol specification
+- [MCP Servers](https://github.com/modelcontextprotocol/servers) — Official MCP server examples
+- [Claude Desktop](https://claude.ai/download) — AI assistant with MCP support
+
+---
+
+<div style="text-align: center; margin-top: 3rem;" markdown>
+
+**Built by [nirholas](https://github.com/nirholas)** • MIT License
+
+[:fontawesome-brands-github: GitHub](https://github.com/nirholas/github-to-mcp){ .md-button }
+[:fontawesome-brands-npm: npm](https://www.npmjs.com/package/@nirholas/github-to-mcp){ .md-button }
+
+</div>