github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/reference/config.md

@@ -0,0 +1,223 @@
+# Configuration Options
+
+Complete reference for all configuration options.
+
+## CLI Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-o, --output` | `string` | `./output` | Output directory |
+| `-l, --language` | `'typescript' \| 'python'` | `'typescript'` | Output language |
+| `-t, --token` | `string` | `$GITHUB_TOKEN` | GitHub token |
+| `--include-tools` | `string` | All | Comma-separated tools to include |
+| `--exclude-tools` | `string` | None | Comma-separated tools to exclude |
+| `--no-universal` | `boolean` | `false` | Skip universal tools |
+| `--force` | `boolean` | `false` | Overwrite existing output |
+| `--dry-run` | `boolean` | `false` | Preview without writing |
+| `--verbose` | `boolean` | `false` | Verbose output |
+| `--quiet` | `boolean` | `false` | Suppress non-error output |
+
+## Programmatic Options
+
+### GeneratorOptions
+
+```typescript
+interface GeneratorOptions {
+  // Authentication
+  token?: string;
+  
+  // Output
+  language?: 'typescript' | 'python';
+  
+  // Tool filtering
+  includeTools?: string[];
+  excludeTools?: string[];
+  includeUniversalTools?: boolean;
+  
+  // Extraction sources
+  extractFromOpenAPI?: boolean;
+  extractFromGraphQL?: boolean;
+  extractFromCode?: boolean;
+  extractFromReadme?: boolean;
+  
+  // Performance
+  maxDepth?: number;
+  maxFileSize?: number;
+  maxFiles?: number;
+  timeout?: number;
+  
+  // Advanced
+  forceType?: RepositoryType;
+  baseUrl?: string;
+  userAgent?: string;
+}
+```
+
+### Option Details
+
+#### token
+
+GitHub personal access token for authentication.
+
+- Increases rate limit from 60 to 5000 requests/hour
+- Required for private repositories
+- Can be set via `GITHUB_TOKEN` environment variable
+
+#### language
+
+Output language for the generated server.
+
+| Value | Description |
+|-------|-------------|
+| `'typescript'` | Generate TypeScript server (default) |
+| `'python'` | Generate Python server |
+
+#### includeTools
+
+Array of tool names to include. If specified, only these tools are generated.
+
+```typescript
+{
+  includeTools: ['read_file', 'search_code', 'create_customer']
+}
+```
+
+#### excludeTools
+
+Array of tool names to exclude from generation.
+
+```typescript
+{
+  excludeTools: ['get_readme']  // Skip README tool
+}
+```
+
+#### includeUniversalTools
+
+Whether to include universal tools (`read_file`, `list_files`, etc.).
+
+| Value | Description |
+|-------|-------------|
+| `true` | Include universal tools (default) |
+| `false` | Only include extracted tools |
+
+#### extractFromOpenAPI
+
+Enable extraction from OpenAPI/Swagger specifications.
+
+| Value | Description |
+|-------|-------------|
+| `true` | Parse OpenAPI specs (default) |
+| `false` | Skip OpenAPI extraction |
+
+#### extractFromGraphQL
+
+Enable extraction from GraphQL schemas.
+
+| Value | Description |
+|-------|-------------|
+| `true` | Parse GraphQL schemas (default) |
+| `false` | Skip GraphQL extraction |
+
+#### extractFromCode
+
+Enable extraction from source code analysis.
+
+| Value | Description |
+|-------|-------------|
+| `true` | Analyze source code (default) |
+| `false` | Skip code analysis |
+
+#### extractFromReadme
+
+Enable extraction from README documentation.
+
+| Value | Description |
+|-------|-------------|
+| `true` | Parse README (default) |
+| `false` | Skip README parsing |
+
+#### maxDepth
+
+Maximum directory depth to scan.
+
+| Value | Description |
+|-------|-------------|
+| `3` | Default depth |
+| `1` | Only root directory |
+| `10` | Deep scanning (slower) |
+
+#### maxFileSize
+
+Maximum file size to read (in bytes).
+
+| Value | Description |
+|-------|-------------|
+| `100000` | 100KB (default) |
+| `50000` | 50KB (for faster processing) |
+| `500000` | 500KB (for larger files) |
+
+#### maxFiles
+
+Maximum number of files to process.
+
+| Value | Description |
+|-------|-------------|
+| `1000` | Default limit |
+| `100` | Faster processing |
+| `5000` | Large repos |
+
+#### timeout
+
+Request timeout in milliseconds.
+
+| Value | Description |
+|-------|-------------|
+| `30000` | 30 seconds (default) |
+| `60000` | 60 seconds (for slow connections) |
+
+#### forceType
+
+Override automatic repository classification.
+
+```typescript
+{
+  forceType: 'api-sdk'  // Force API SDK classification
+}
+```
+
+Values: `'mcp-server'`, `'api-sdk'`, `'cli-tool'`, `'library'`, `'documentation'`, `'data'`
+
+---
+
+## Configuration File
+
+You can create a configuration file for repeated use:
+
+### github-to-mcp.config.js
+
+```javascript
+module.exports = {
+  token: process.env.GITHUB_TOKEN,
+  language: 'typescript',
+  includeUniversalTools: true,
+  extractFromOpenAPI: true,
+  extractFromGraphQL: true,
+  maxDepth: 3,
+  maxFileSize: 100000,
+};
+```
+
+### Usage
+
+```bash
+github-to-mcp <url> --config ./github-to-mcp.config.js
+```
+
+---
+
+## See Also
+
+- [Environment Variables](env.md) - Environment configuration
+- [CLI Reference](../cli/index.md) - Command-line usage
+- [API Reference](../api/core.md) - Programmatic API

package/mkdocs/docs/reference/env.md

@@ -0,0 +1,192 @@
+# Environment Variables
+
+Configure GitHub to MCP using environment variables.
+
+## Required Variables
+
+None! All environment variables are optional, but some are highly recommended.
+
+## Recommended Variables
+
+### GITHUB_TOKEN
+
+GitHub personal access token for API authentication.
+
+```bash
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
+```
+
+| Without Token | With Token |
+|---------------|------------|
+| 60 requests/hour | 5,000 requests/hour |
+| Public repos only | Private repos accessible |
+| Basic metadata | Full repository access |
+
+**Creating a Token:**
+
+1. Go to [GitHub Settings → Developer Settings → Personal Access Tokens](https://github.com/settings/tokens)
+2. Generate new token (classic)
+3. Select scopes: `repo` (private) or `public_repo` (public only)
+4. Copy the token
+
+---
+
+## Optional Variables
+
+### LOG_LEVEL
+
+Control logging verbosity.
+
+```bash
+export LOG_LEVEL=debug
+```
+
+| Value | Description |
+|-------|-------------|
+| `debug` | All messages including debug |
+| `info` | Informational messages (default) |
+| `warn` | Warnings and errors only |
+| `error` | Errors only |
+| `silent` | No output |
+
+---
+
+### OPENAI_API_KEY
+
+OpenAI API key for enhanced extraction (experimental).
+
+```bash
+export OPENAI_API_KEY=sk-xxxxxxxxxxxxx
+```
+
+Used for:
+- Improved tool descriptions
+- Better README parsing
+- Code understanding
+
+---
+
+### GITHUB_API_URL
+
+Custom GitHub API URL for GitHub Enterprise.
+
+```bash
+export GITHUB_API_URL=https://github.mycompany.com/api/v3
+```
+
+Default: `https://api.github.com`
+
+---
+
+### HTTP_PROXY / HTTPS_PROXY
+
+Proxy server for HTTP requests.
+
+```bash
+export HTTP_PROXY=http://proxy.example.com:8080
+export HTTPS_PROXY=http://proxy.example.com:8080
+```
+
+---
+
+### NO_COLOR
+
+Disable colored output.
+
+```bash
+export NO_COLOR=1
+```
+
+---
+
+## Setting Environment Variables
+
+### Temporary (Current Session)
+
+=== "macOS/Linux"
+
+    ```bash
+    export GITHUB_TOKEN=ghp_xxxxx
+    ```
+
+=== "Windows PowerShell"
+
+    ```powershell
+    $env:GITHUB_TOKEN="ghp_xxxxx"
+    ```
+
+=== "Windows CMD"
+
+    ```cmd
+    set GITHUB_TOKEN=ghp_xxxxx
+    ```
+
+### Permanent
+
+=== "macOS/Linux"
+
+    Add to `~/.bashrc` or `~/.zshrc`:
+    ```bash
+    export GITHUB_TOKEN=ghp_xxxxx
+    export LOG_LEVEL=info
+    ```
+
+=== "Windows"
+
+    Use System Properties → Environment Variables
+
+### Per-Project
+
+Create a `.env` file:
+
+```bash title=".env"
+GITHUB_TOKEN=ghp_xxxxx
+LOG_LEVEL=debug
+```
+
+!!! warning "Security"
+    Add `.env` to `.gitignore` to avoid committing secrets.
+
+---
+
+## Using with Claude Desktop
+
+Pass environment variables to MCP servers:
+
+```json title="claude_desktop_config.json"
+{
+  "mcpServers": {
+    "my-repo": {
+      "command": "node",
+      "args": ["/path/to/server.mjs"],
+      "env": {
+        "GITHUB_TOKEN": "ghp_xxxxx",
+        "LOG_LEVEL": "debug"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Variable Precedence
+
+1. CLI flags (highest priority)
+2. Environment variables
+3. Config file
+4. Defaults (lowest priority)
+
+```bash
+# CLI flag overrides environment variable
+export LOG_LEVEL=error
+github-to-mcp <url> --verbose  # Uses verbose, not error
+```
+
+---
+
+## See Also
+
+- [Configuration Options](config.md) - All options
+- [Private Repos](../guides/private-repos.md) - Token setup
+- [CLI Reference](../cli/index.md) - Command-line usage

package/mkdocs/docs/reference/index.md

@@ -0,0 +1,102 @@
+# Reference
+
+Quick reference documentation for GitHub to MCP.
+
+## Quick Links
+
+- [Generated Tools](tools.md) - All tool definitions
+- [Configuration Options](config.md) - Full options reference
+- [Environment Variables](env.md) - Environment configuration
+
+## FAQ
+
+### General
+
+<details>
+<summary><strong>What is GitHub to MCP?</strong></summary>
+
+GitHub to MCP is a tool that converts any GitHub repository into a Model Context Protocol (MCP) server, enabling AI assistants to interact with the codebase.
+</details>
+
+<details>
+<summary><strong>What AI assistants support MCP?</strong></summary>
+
+- Claude Desktop
+- Cursor
+- Cline
+- Continue
+- Windsurf
+- Any tool implementing the MCP specification
+</details>
+
+<details>
+<summary><strong>Is this free to use?</strong></summary>
+
+Yes! GitHub to MCP is open source under the MIT license. The web app is free, and you can self-host.
+</details>
+
+### Technical
+
+<details>
+<summary><strong>Does this work with private repositories?</strong></summary>
+
+Yes! Set the `GITHUB_TOKEN` environment variable with a token that has access to your private repos. See [Private Repos Guide](../guides/private-repos.md).
+</details>
+
+<details>
+<summary><strong>What languages can the generated server be?</strong></summary>
+
+TypeScript (default) or Python. Use the `-l python` flag for Python output.
+</details>
+
+<details>
+<summary><strong>Can I customize the generated tools?</strong></summary>
+
+Yes! The generated code is plain TypeScript/Python — edit it however you want. See [Custom Tools Guide](../guides/custom-tools.md).
+</details>
+
+<details>
+<summary><strong>What's the difference between tools and resources?</strong></summary>
+
+**Tools** are callable functions with parameters (like `read_file`). **Resources** are static data the AI can access. GitHub to MCP generates tools, not resources.
+</details>
+
+### Troubleshooting
+
+<details>
+<summary><strong>I'm getting rate limit errors</strong></summary>
+
+Set a GitHub token for 5000 requests/hour instead of 60:
+
+```bash
+export GITHUB_TOKEN=ghp_xxxxx
+```
+</details>
+
+<details>
+<summary><strong>The server won't start</strong></summary>
+
+1. Make sure you ran `npm install` in the output directory
+2. Check Node.js version (18+ required)
+3. Verify the path to `server.mjs` is correct
+</details>
+
+<details>
+<summary><strong>Claude doesn't see my tools</strong></summary>
+
+1. Check config file location and JSON syntax
+2. Use absolute paths, not relative
+3. Restart Claude Desktop completely
+4. Enable MCP logs in Claude settings
+</details>
+
+<details>
+<summary><strong>No tools were extracted</strong></summary>
+
+The repo may not have detectable patterns. Check:
+- Is there an OpenAPI spec?
+- Is there a GraphQL schema?
+- For MCP servers, are tools registered correctly?
+
+Use `--verbose` to see what was analyzed.
+</details>