github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/getting-started/configuration.md

@@ -0,0 +1,235 @@
+# Configuration
+
+Customize how GitHub to MCP generates your MCP servers.
+
+## CLI Options
+
+```bash
+github-to-mcp <url> [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --output <dir>` | Output directory | `./output` |
+| `-l, --language <lang>` | Output language (`typescript` or `python`) | `typescript` |
+| `-t, --token <token>` | GitHub personal access token | `$GITHUB_TOKEN` |
+| `--include-tools <tools>` | Comma-separated list of tools to include | All |
+| `--exclude-tools <tools>` | Comma-separated list of tools to exclude | None |
+| `--no-universal` | Skip universal tools (read_file, etc.) | `false` |
+| `-v, --verbose` | Enable verbose output | `false` |
+| `-h, --help` | Show help | |
+
+### Examples
+
+Generate with specific output directory:
+
+```bash
+github-to-mcp https://github.com/owner/repo -o ./my-mcp-server
+```
+
+Generate Python server instead of TypeScript:
+
+```bash
+github-to-mcp https://github.com/owner/repo -l python
+```
+
+Only include specific tools:
+
+```bash
+github-to-mcp https://github.com/owner/repo --include-tools read_file,search_code
+```
+
+---
+
+## Programmatic Options
+
+When using the JavaScript API:
+
+```typescript
+import { generateFromGithub, type GeneratorOptions } from '@nirholas/github-to-mcp';
+
+const options: GeneratorOptions = {
+  // GitHub authentication
+  token: process.env.GITHUB_TOKEN,
+  
+  // Output configuration
+  language: 'typescript',  // or 'python'
+  
+  // Tool filtering
+  includeTools: ['read_file', 'search_code'],
+  excludeTools: [],
+  includeUniversalTools: true,
+  
+  // Extraction options
+  extractFromOpenAPI: true,
+  extractFromGraphQL: true,
+  extractFromCode: true,
+  extractFromReadme: true,
+  
+  // Advanced
+  maxDepth: 3,           // Max directory depth to scan
+  maxFileSize: 100000,   // Max file size in bytes
+  timeout: 30000,        // Request timeout in ms
+};
+
+const result = await generateFromGithub(
+  'https://github.com/owner/repo',
+  options
+);
+```
+
+### GeneratorOptions Reference
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `token` | `string` | `undefined` | GitHub personal access token |
+| `language` | `'typescript' \| 'python'` | `'typescript'` | Output language |
+| `includeTools` | `string[]` | `[]` | Only include these tools |
+| `excludeTools` | `string[]` | `[]` | Exclude these tools |
+| `includeUniversalTools` | `boolean` | `true` | Include base tools |
+| `extractFromOpenAPI` | `boolean` | `true` | Extract from OpenAPI specs |
+| `extractFromGraphQL` | `boolean` | `true` | Extract from GraphQL schemas |
+| `extractFromCode` | `boolean` | `true` | Extract from code analysis |
+| `extractFromReadme` | `boolean` | `true` | Extract from README |
+| `maxDepth` | `number` | `3` | Max directory depth |
+| `maxFileSize` | `number` | `100000` | Max file size (bytes) |
+| `timeout` | `number` | `30000` | Request timeout (ms) |
+
+---
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `GITHUB_TOKEN` | GitHub personal access token | No (but recommended) |
+| `OPENAI_API_KEY` | OpenAI API key for enhanced extraction | No |
+| `LOG_LEVEL` | Logging verbosity (`debug`, `info`, `warn`, `error`) | No |
+
+### Setting Environment Variables
+
+=== "macOS/Linux"
+
+    ```bash
+    # Add to ~/.bashrc or ~/.zshrc
+    export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+    export LOG_LEVEL=debug
+    ```
+
+=== "Windows"
+
+    ```powershell
+    # PowerShell
+    $env:GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
+    $env:LOG_LEVEL="debug"
+    ```
+
+=== ".env file"
+
+    ```bash
+    # Create .env file in your project
+    GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+    LOG_LEVEL=debug
+    ```
+
+---
+
+## Output Configuration
+
+### TypeScript Output
+
+When `language: 'typescript'`:
+
+```
+output/
+├── package.json
+├── tsconfig.json
+├── server.ts
+├── server.mjs      # Compiled output
+└── tools/
+    ├── index.ts
+    └── *.ts
+```
+
+### Python Output
+
+When `language: 'python'`:
+
+```
+output/
+├── pyproject.toml
+├── requirements.txt
+├── server.py
+└── tools/
+    ├── __init__.py
+    └── *.py
+```
+
+---
+
+## Tool Filtering
+
+### Include Specific Tools
+
+Only generate certain tools:
+
+```typescript
+const result = await generateFromGithub(url, {
+  includeTools: ['read_file', 'search_code', 'create_customer']
+});
+```
+
+### Exclude Tools
+
+Generate all tools except specific ones:
+
+```typescript
+const result = await generateFromGithub(url, {
+  excludeTools: ['get_readme']  // Skip README tool
+});
+```
+
+### Skip Universal Tools
+
+Only generate extracted tools:
+
+```typescript
+const result = await generateFromGithub(url, {
+  includeUniversalTools: false
+});
+```
+
+---
+
+## Advanced Configuration
+
+### Custom Extraction
+
+Control what sources are scanned:
+
+```typescript
+const result = await generateFromGithub(url, {
+  extractFromOpenAPI: true,   // Check for openapi.json, swagger.yaml
+  extractFromGraphQL: true,   // Check for schema.graphql
+  extractFromCode: true,      // Analyze source code
+  extractFromReadme: false,   // Skip README parsing
+});
+```
+
+### Performance Tuning
+
+For large repositories:
+
+```typescript
+const result = await generateFromGithub(url, {
+  maxDepth: 2,           // Limit directory depth
+  maxFileSize: 50000,    // Skip files > 50KB
+  timeout: 60000,        // Increase timeout to 60s
+});
+```
+
+---
+
+## Next Steps
+
+- [CLI Reference](../cli/index.md) — Full command-line documentation
+- [API Reference](../api/index.md) — Detailed programmatic API

package/mkdocs/docs/getting-started/index.md

@@ -0,0 +1,54 @@
+# Getting Started
+
+Welcome to GitHub to MCP! This section will help you get up and running in minutes.
+
+## What is GitHub to MCP?
+
+GitHub to MCP is a tool that converts any GitHub repository into a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server. This allows AI assistants like Claude, ChatGPT, Cursor, and others to interact with your code.
+
+## Prerequisites
+
+Before you begin, make sure you have:
+
+- **Node.js 18+** installed
+- **npm** or **pnpm** package manager
+- (Optional) A **GitHub token** for private repos or higher rate limits
+
+## Quick Navigation
+
+<div class="feature-grid" markdown>
+
+<div class="feature-card" markdown>
+
+### [Installation](installation.md)
+
+Install the CLI tool and set up your environment
+
+</div>
+
+<div class="feature-card" markdown>
+
+### [Quick Start](quickstart.md)
+
+Generate your first MCP server in 60 seconds
+
+</div>
+
+<div class="feature-card" markdown>
+
+### [Configuration](configuration.md)
+
+Customize output and behavior
+
+</div>
+
+</div>
+
+## Next Steps
+
+1. [Install the tool](installation.md)
+2. [Generate your first server](quickstart.md)
+3. [Connect to Claude Desktop](../guides/claude-desktop.md)
+
+!!! tip "Try the Web UI"
+    Don't want to install anything? Use the [web interface](https://github-to-mcp.vercel.app) to convert repos directly in your browser.

package/mkdocs/docs/getting-started/installation.md

@@ -0,0 +1,145 @@
+# Installation
+
+There are multiple ways to install and use GitHub to MCP depending on your needs.
+
+## Web UI (No Installation)
+
+The easiest way to get started — no installation required:
+
+👉 **[github-to-mcp.vercel.app](https://github-to-mcp.vercel.app)**
+
+Simply paste a GitHub URL, configure options, and download your generated MCP server.
+
+---
+
+## CLI Installation
+
+### Using npx (Recommended)
+
+Run directly without installing:
+
+```bash
+npx @nirholas/github-to-mcp https://github.com/owner/repo
+```
+
+### Global Installation
+
+Install globally for repeated use:
+
+=== "npm"
+
+    ```bash
+    npm install -g @nirholas/github-to-mcp
+    ```
+
+=== "pnpm"
+
+    ```bash
+    pnpm add -g @nirholas/github-to-mcp
+    ```
+
+=== "yarn"
+
+    ```bash
+    yarn global add @nirholas/github-to-mcp
+    ```
+
+Then use the `github-to-mcp` command:
+
+```bash
+github-to-mcp https://github.com/stripe/stripe-node
+```
+
+---
+
+## Programmatic Installation
+
+Add as a dependency to your project:
+
+=== "npm"
+
+    ```bash
+    npm install @nirholas/github-to-mcp
+    ```
+
+=== "pnpm"
+
+    ```bash
+    pnpm add @nirholas/github-to-mcp
+    ```
+
+=== "yarn"
+
+    ```bash
+    yarn add @nirholas/github-to-mcp
+    ```
+
+Then import in your code:
+
+```typescript
+import { generateFromGithub } from '@nirholas/github-to-mcp';
+```
+
+---
+
+## Verify Installation
+
+Check that the CLI is installed correctly:
+
+```bash
+github-to-mcp --version
+```
+
+You should see the version number printed:
+
+```
+@nirholas/github-to-mcp v1.0.0
+```
+
+---
+
+## System Requirements
+
+| Requirement | Version |
+|-------------|---------|
+| Node.js | 18.0.0 or higher |
+| npm | 9.0.0 or higher |
+| Operating System | macOS, Linux, Windows |
+
+---
+
+## Environment Setup
+
+### GitHub Token (Optional)
+
+For private repositories or to increase API rate limits (60/hr → 5000/hr), set a GitHub token:
+
+=== "macOS/Linux"
+
+    ```bash
+    export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+    ```
+
+=== "Windows (PowerShell)"
+
+    ```powershell
+    $env:GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
+    ```
+
+=== "Windows (CMD)"
+
+    ```cmd
+    set GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+    ```
+
+!!! tip "Creating a GitHub Token"
+    1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens)
+    2. Click "Generate new token (classic)"
+    3. Select scopes: `repo` (for private repos) or `public_repo` (for public only)
+    4. Copy and save the token
+
+---
+
+## Next Steps
+
+Now that you have GitHub to MCP installed, continue to the [Quick Start](quickstart.md) guide to generate your first MCP server!

package/mkdocs/docs/getting-started/quickstart.md

@@ -0,0 +1,160 @@
+# Quick Start
+
+Generate your first MCP server in under 60 seconds!
+
+## Step 1: Choose a Repository
+
+Pick any GitHub repository you want to convert. For this example, we'll use the Stripe Node.js SDK:
+
+```
+https://github.com/stripe/stripe-node
+```
+
+## Step 2: Generate the MCP Server
+
+### Using the Web UI
+
+1. Go to [github-to-mcp.vercel.app](https://github-to-mcp.vercel.app)
+2. Paste the repository URL
+3. Click **Generate**
+4. Download the generated server
+
+### Using the CLI
+
+```bash
+npx @nirholas/github-to-mcp https://github.com/stripe/stripe-node -o ./stripe-mcp
+```
+
+This will create a complete MCP server in the `./stripe-mcp` directory.
+
+### Using the API
+
+```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`);
+console.log('Tools:', result.tools.map(t => t.name));
+
+// Save to disk
+await result.save('./stripe-mcp');
+```
+
+## Step 3: Explore the Output
+
+The generated MCP server includes:
+
+```
+stripe-mcp/
+├── package.json          # Dependencies and scripts
+├── server.mjs            # Main MCP server code
+├── tools/                # Generated tool implementations
+│   ├── read_file.mjs
+│   ├── list_files.mjs
+│   ├── search_code.mjs
+│   └── get_readme.mjs
+└── README.md             # Usage instructions
+```
+
+## Step 4: Test the Server
+
+Start the MCP server locally:
+
+```bash
+cd stripe-mcp
+npm install
+npm start
+```
+
+The server is now running and ready to accept MCP connections!
+
+## Step 5: Connect to an AI Assistant
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "stripe": {
+      "command": "node",
+      "args": ["/path/to/stripe-mcp/server.mjs"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, and you'll see the tools available:
+
+![Claude with MCP tools](https://github-to-mcp.vercel.app/docs/claude-tools.png)
+
+### Cursor
+
+Add to your Cursor MCP configuration:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "stripe": {
+        "command": "node",
+        "args": ["/path/to/stripe-mcp/server.mjs"]
+      }
+    }
+  }
+}
+```
+
+---
+
+## What Tools Were Generated?
+
+For the Stripe SDK, you'll get these tools:
+
+### Universal Tools (Always Included)
+
+| Tool | Description |
+|------|-------------|
+| `get_readme` | Fetch the README content |
+| `list_files` | Browse directory structure |
+| `read_file` | Read any file's contents |
+| `search_code` | Search for code patterns |
+
+### Extracted Tools (From OpenAPI Spec)
+
+Since Stripe has an OpenAPI specification, additional tools are extracted:
+
+| Tool | Description |
+|------|-------------|
+| `create_customer` | Create a new customer |
+| `list_charges` | List all charges |
+| `create_payment_intent` | Create a payment intent |
+| ... | And many more! |
+
+---
+
+## Example Conversations
+
+Once connected, you can have conversations like:
+
+> **You:** What's in the Stripe SDK readme?
+>
+> **Claude:** *Uses `get_readme` tool* The Stripe Node.js SDK provides access to the Stripe API...
+
+> **You:** Show me how to create a customer
+>
+> **Claude:** *Uses `search_code` and `read_file` tools* Here's the code for creating a customer...
+
+> **You:** List all the API files
+>
+> **Claude:** *Uses `list_files` tool* Here are the files in the `lib/resources/` directory...
+
+---
+
+## Next Steps
+
+- [Configure your server](configuration.md) — Customize output options
+- [Connect to Claude Desktop](../guides/claude-desktop.md) — Detailed integration guide
+- [Use with private repos](../guides/private-repos.md) — Work with your own code