github-to-mcp-monorepo 1.0.0

package/mkdocs/docs/cli/generate.md

@@ -0,0 +1,148 @@
+# generate
+
+Generate an MCP server from a GitHub repository.
+
+## Usage
+
+```bash
+github-to-mcp generate <url> [options]
+# or shorthand
+github-to-mcp <url> [options]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `url` | GitHub repository URL | Yes |
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-o, --output <dir>` | Output directory | `./output` |
+| `-l, --language <lang>` | Output language (`typescript` \| `python`) | `typescript` |
+| `-t, --token <token>` | GitHub personal access token | `$GITHUB_TOKEN` |
+| `--include-tools <tools>` | Comma-separated tools to include | All |
+| `--exclude-tools <tools>` | Comma-separated tools to exclude | None |
+| `--no-universal` | Skip universal tools | `false` |
+| `--force` | Overwrite existing output | `false` |
+| `--dry-run` | Preview without writing files | `false` |
+
+## Examples
+
+### Basic Generation
+
+```bash
+github-to-mcp https://github.com/stripe/stripe-node
+```
+
+### Specify Output Directory
+
+```bash
+github-to-mcp https://github.com/stripe/stripe-node -o ./stripe-mcp
+```
+
+### Generate Python Server
+
+```bash
+github-to-mcp https://github.com/openai/openai-python -l python -o ./openai-mcp
+```
+
+### Private Repository
+
+```bash
+github-to-mcp https://github.com/my-org/private-repo -t ghp_xxxxx
+```
+
+Or using environment variable:
+
+```bash
+export GITHUB_TOKEN=ghp_xxxxx
+github-to-mcp https://github.com/my-org/private-repo
+```
+
+### Filter Tools
+
+Only include specific tools:
+
+```bash
+github-to-mcp https://github.com/stripe/stripe-node \
+  --include-tools read_file,search_code,create_customer
+```
+
+Exclude specific tools:
+
+```bash
+github-to-mcp https://github.com/stripe/stripe-node \
+  --exclude-tools get_readme
+```
+
+### Dry Run
+
+Preview what would be generated:
+
+```bash
+github-to-mcp https://github.com/stripe/stripe-node --dry-run
+```
+
+Output:
+
+```
+Dry run - would generate:
+  Output: ./output
+  Language: typescript
+  Tools: 12
+    - get_readme
+    - list_files
+    - read_file
+    - search_code
+    - create_customer
+    - list_customers
+    ...
+```
+
+## Output Structure
+
+### TypeScript Output
+
+```
+output/
+├── package.json
+├── tsconfig.json
+├── server.ts
+├── server.mjs          # Compiled
+└── tools/
+    ├── index.ts
+    ├── read_file.ts
+    ├── list_files.ts
+    └── ...
+```
+
+### Python Output
+
+```
+output/
+├── pyproject.toml
+├── requirements.txt
+├── server.py
+└── tools/
+    ├── __init__.py
+    ├── read_file.py
+    └── ...
+```
+
+## Exit Codes
+
+| Code | Description |
+|------|-------------|
+| `0` | Success |
+| `1` | General error |
+| `2` | Invalid arguments |
+| `3` | GitHub API error |
+| `4` | File system error |
+
+## See Also
+
+- [`inspect`](inspect.md) - Preview tools without generating
+- [`serve`](serve.md) - Run a generated server

package/mkdocs/docs/cli/index.md

@@ -0,0 +1,52 @@
+# CLI Reference
+
+Command-line interface for GitHub to MCP.
+
+## Installation
+
+```bash
+# Use directly with npx
+npx @nirholas/github-to-mcp <command>
+
+# Or install globally
+npm install -g @nirholas/github-to-mcp
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| [`generate`](generate.md) | Generate MCP server from a repository |
+| [`inspect`](inspect.md) | Inspect a repository without generating |
+| [`serve`](serve.md) | Start a generated MCP server |
+
+## Global Options
+
+These options work with all commands:
+
+| Option | Description |
+|--------|-------------|
+| `-v, --version` | Show version number |
+| `-h, --help` | Show help |
+| `--verbose` | Enable verbose output |
+| `--quiet` | Suppress non-error output |
+
+## Quick Examples
+
+```bash
+# Generate MCP server
+npx @nirholas/github-to-mcp generate https://github.com/stripe/stripe-node
+
+# Inspect without generating
+npx @nirholas/github-to-mcp inspect https://github.com/openai/openai-node
+
+# Start a generated server
+npx @nirholas/github-to-mcp serve ./my-mcp-server
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_TOKEN` | GitHub authentication token |
+| `LOG_LEVEL` | Logging verbosity (debug, info, warn, error) |

package/mkdocs/docs/cli/inspect.md

@@ -0,0 +1,164 @@
+# inspect
+
+Inspect a repository and preview extracted tools without generating a server.
+
+## Usage
+
+```bash
+github-to-mcp inspect <url> [options]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `url` | GitHub repository URL | Yes |
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-t, --token <token>` | GitHub personal access token | `$GITHUB_TOKEN` |
+| `--format <format>` | Output format (`table` \| `json` \| `yaml`) | `table` |
+| `--verbose` | Show detailed extraction info | `false` |
+
+## Examples
+
+### Basic Inspection
+
+```bash
+github-to-mcp inspect https://github.com/stripe/stripe-node
+```
+
+Output:
+
+```
+Repository: stripe/stripe-node
+Type: api-sdk
+Stars: 3,456
+Language: TypeScript
+
+Extracted Tools (15):
+┌─────────────────────┬─────────────────────────────────────┬──────────┐
+│ Name                │ Description                          │ Source   │
+├─────────────────────┼─────────────────────────────────────┼──────────┤
+│ get_readme          │ Get the repository README            │ universal│
+│ list_files          │ List files in a directory            │ universal│
+│ read_file           │ Read file contents                   │ universal│
+│ search_code         │ Search for code patterns             │ universal│
+│ create_customer     │ Create a new Stripe customer         │ openapi  │
+│ list_charges        │ List all charges                     │ openapi  │
+│ create_payment_int… │ Create a payment intent              │ openapi  │
+└─────────────────────┴─────────────────────────────────────┴──────────┘
+```
+
+### JSON Output
+
+```bash
+github-to-mcp inspect https://github.com/stripe/stripe-node --format json
+```
+
+```json
+{
+  "repository": {
+    "owner": "stripe",
+    "name": "stripe-node",
+    "url": "https://github.com/stripe/stripe-node",
+    "type": "api-sdk",
+    "stars": 3456,
+    "language": "TypeScript"
+  },
+  "tools": [
+    {
+      "name": "get_readme",
+      "description": "Get the repository README",
+      "source": "universal",
+      "inputSchema": {...}
+    },
+    ...
+  ],
+  "sources": {
+    "universal": 4,
+    "openapi": 11
+  }
+}
+```
+
+### Verbose Mode
+
+```bash
+github-to-mcp inspect https://github.com/stripe/stripe-node --verbose
+```
+
+Shows additional details:
+
+- Files scanned
+- OpenAPI specs found
+- GraphQL schemas detected
+- Extraction time per source
+
+## Use Cases
+
+### Preview Before Generating
+
+Check what tools will be created:
+
+```bash
+# Inspect first
+github-to-mcp inspect https://github.com/owner/repo
+
+# If satisfied, generate
+github-to-mcp generate https://github.com/owner/repo
+```
+
+### Compare Repositories
+
+```bash
+# Inspect multiple repos
+github-to-mcp inspect https://github.com/stripe/stripe-node --format json > stripe.json
+github-to-mcp inspect https://github.com/openai/openai-node --format json > openai.json
+
+# Compare tool counts
+jq '.tools | length' stripe.json openai.json
+```
+
+### CI/CD Validation
+
+```bash
+# Ensure a repo has expected tools
+tools=$(github-to-mcp inspect $REPO_URL --format json | jq '.tools | length')
+if [ "$tools" -lt 4 ]; then
+  echo "Error: Expected at least 4 tools"
+  exit 1
+fi
+```
+
+## Output Formats
+
+### Table (Default)
+
+Human-readable tabular format for terminal viewing.
+
+### JSON
+
+Machine-readable JSON for scripting and automation.
+
+### YAML
+
+YAML format for configuration files:
+
+```yaml
+repository:
+  owner: stripe
+  name: stripe-node
+  type: api-sdk
+tools:
+  - name: get_readme
+    description: Get the repository README
+    source: universal
+```
+
+## See Also
+
+- [`generate`](generate.md) - Generate MCP server
+- [Repository Classification](../concepts/classification.md) - How repos are classified

package/mkdocs/docs/cli/serve.md

@@ -0,0 +1,136 @@
+# serve
+
+Start a generated MCP server.
+
+## Usage
+
+```bash
+github-to-mcp serve <path> [options]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `path` | Path to generated MCP server | Yes |
+
+## Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --port <port>` | Port to listen on | `3000` |
+| `--stdio` | Use stdio transport instead of HTTP | `false` |
+| `--verbose` | Enable verbose logging | `false` |
+
+## Examples
+
+### Start Server
+
+```bash
+github-to-mcp serve ./my-mcp-server
+```
+
+Output:
+
+```
+MCP Server started
+  Transport: HTTP
+  Port: 3000
+  Tools: 12
+  URL: http://localhost:3000
+
+Press Ctrl+C to stop
+```
+
+### Custom Port
+
+```bash
+github-to-mcp serve ./my-mcp-server -p 8080
+```
+
+### Stdio Mode
+
+For direct integration with clients that support stdio:
+
+```bash
+github-to-mcp serve ./my-mcp-server --stdio
+```
+
+This mode reads from stdin and writes to stdout, compatible with Claude Desktop's config.
+
+## Transport Modes
+
+### HTTP (Default)
+
+Starts an HTTP server that accepts MCP JSON-RPC requests:
+
+```bash
+# Start server
+github-to-mcp serve ./my-mcp-server -p 3000
+
+# Test with curl
+curl -X POST http://localhost:3000 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
+```
+
+### Stdio
+
+For direct process communication:
+
+```bash
+# Start in stdio mode
+github-to-mcp serve ./my-mcp-server --stdio
+
+# Claude Desktop config
+{
+  "mcpServers": {
+    "my-repo": {
+      "command": "github-to-mcp",
+      "args": ["serve", "/path/to/my-mcp-server", "--stdio"]
+    }
+  }
+}
+```
+
+## Health Check
+
+When running in HTTP mode, the server provides a health endpoint:
+
+```bash
+curl http://localhost:3000/health
+```
+
+Response:
+
+```json
+{
+  "status": "ok",
+  "server": "my-repo-mcp",
+  "tools": 12,
+  "uptime": 123.45
+}
+```
+
+## Alternative: Direct Node
+
+You can also run the server directly:
+
+```bash
+cd ./my-mcp-server
+npm install
+node server.mjs
+```
+
+Or for Python servers:
+
+```bash
+cd ./my-mcp-server
+pip install -r requirements.txt
+python server.py
+```
+
+## See Also
+
+- [`generate`](generate.md) - Generate MCP server
+- [Claude Desktop Integration](../guides/claude-desktop.md) - Connect to Claude