mcp-http-webhook 1.0.28 → 1.0.30

package/examples/GITHUB_LIVE_SETUP.md

@@ -1,253 +0,0 @@
-# GitHub Live Integration Setup Guide
-
-This guide will help you set up the GitHub MCP server with real webhooks.
-
-## 🎯 Quick Start Checklist
-
-- [ ] GitHub Personal Access Token
-- [ ] Test GitHub Repository
-- [ ] ngrok Account (free)
-- [ ] Run the example
-
----
-
-## 📋 Step-by-Step Setup
-
-### 1. Create GitHub Personal Access Token
-
-1. Go to: https://github.com/settings/tokens/new
-2. **Token Name**: `MCP GitHub Test`
-3. **Expiration**: 30 days (for testing)
-4. **Select Scopes**:
-   - ✅ `repo` - Full control of private repositories
-   - ✅ `admin:repo_hook` - Full control of repository hooks
-5. Click **Generate token**
-6. **Copy the token** - you won't see it again!
-
-Example token format: `ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
-
-### 2. Prepare a Test Repository
-
-You need a GitHub repository you own for testing webhooks.
-
-**Option A: Use Existing Repo**
-- Any repository you own
-- Example: `your-username/test-repo`
-
-**Option B: Create New Test Repo**
-```bash
-# Via GitHub CLI
-gh repo create mcp-webhook-test --public
-
-# Or manually at:
-# https://github.com/new
-```
-
-### 3. Get ngrok Auth Token (FREE)
-
-ngrok is required to expose your localhost to GitHub's webhooks.
-
-1. **Sign up** (free): https://dashboard.ngrok.com/signup
-2. **Get your auth token**: https://dashboard.ngrok.com/get-started/your-authtoken
-3. **Copy the token**
-
-Example token format: `2abc123def456ghi789jkl_0MnOpQrStUvWxYz`
-
-**Set as environment variable** (optional):
-```bash
-export NGROK_AUTH_TOKEN="your_ngrok_token_here"
-```
-
-### 4. Run the Example
-
-```bash
-cd packages/plugins/mcp-proxy
-npx tsx examples/github-server-live.ts
-```
-
-You'll be prompted for:
-
-1. **GitHub Personal Access Token**: `ghp_...` (from step 1)
-2. **Repository owner**: Your GitHub username
-3. **Repository name**: Your test repo name
-4. **ngrok auth token**: Your ngrok token (or press Enter if set in env)
-5. **Webhook secret**: Press Enter for auto-generated
-
----
-
-## 🧪 Testing the Integration
-
-### Step 1: Server Starts
-
-You should see:
-```
-✅ Authenticated as: your-username
-✅ Repository found: your-username/test-repo
-✅ Public URL: https://abc123.ngrok.io
-🚀 MCP Server started on port 3000
-```
-
-### Step 2: Test with MCP Inspector
-
-Open in browser:
-```
-http://localhost:3000/mcp
-```
-
-Or use MCP Inspector:
-```bash
-npx @modelcontextprotocol/inspector http://localhost:3000/mcp
-```
-
-### Step 3: Subscribe to Issues
-
-In MCP Inspector or via curl:
-
-```bash
-curl -X POST http://localhost:3000/mcp/resources/subscribe \
-  -H "Content-Type: application/json" \
-  -H "Authorization: Bearer test-token" \
-  -d '{
-    "uri": "github://repo/your-username/test-repo/issues",
-    "callbackUrl": "https://your-client.com/webhook",
-    "callbackSecret": "client-secret-123"
-  }'
-```
-
-This will:
-1. Create a real GitHub webhook in your repository
-2. Subscribe to issue events
-3. Return a subscription ID
-
-### Step 4: Create a Test Issue
-
-Create an issue in your GitHub repo:
-
-1. Go to: `https://github.com/your-username/test-repo/issues/new`
-2. Title: "Test MCP Webhook"
-3. Click **Submit new issue**
-
-### Step 5: Verify Webhook Received
-
-Check the server logs - you should see:
-```
-📥 Received GitHub webhook for subscription: sub_abc123
-📤 Notifying client at: https://your-client.com/webhook
-✅ Successfully notified client
-```
-
----
-
-## 🔍 Troubleshooting
-
-### ngrok Error: "failed to start tunnel"
-
-**Problem**: ngrok requires authentication
-
-**Solution**:
-1. Sign up at https://dashboard.ngrok.com/signup
-2. Get auth token from https://dashboard.ngrok.com/get-started/your-authtoken
-3. Provide it when prompted, or set environment variable:
-   ```bash
-   export NGROK_AUTH_TOKEN="your_token"
-   ```
-
-### GitHub API Error: "Bad credentials"
-
-**Problem**: Invalid or expired token
-
-**Solution**:
-1. Verify token hasn't expired
-2. Regenerate token with correct scopes: `repo`, `admin:repo_hook`
-3. Copy the full token including `ghp_` prefix
-
-### GitHub API Error: "Not Found"
-
-**Problem**: Repository doesn't exist or token doesn't have access
-
-**Solution**:
-1. Verify repository exists: `https://github.com/owner/repo`
-2. Ensure you own the repository
-3. Check token has `repo` scope
-
-### Webhook Not Received
-
-**Problem**: GitHub can't reach your localhost
-
-**Checks**:
-1. ✅ ngrok tunnel is running
-2. ✅ Server is running on port 3000
-3. ✅ GitHub webhook was created (check repo settings)
-4. ✅ Check GitHub webhook deliveries
-
-**View webhook deliveries**:
-1. Go to: `https://github.com/owner/repo/settings/hooks`
-2. Click on the webhook
-3. Check **Recent Deliveries** tab
-4. Look for errors
-
----
-
-## 🎓 Advanced Usage
-
-### Using Multiple Repositories
-
-Subscribe to multiple repos:
-
-```typescript
-// Subscribe to repo 1
-POST /mcp/resources/subscribe
-{
-  "uri": "github://repo/owner1/repo1/issues",
-  "callbackUrl": "https://client.com/webhook",
-  "callbackSecret": "secret1"
-}
-
-// Subscribe to repo 2
-POST /mcp/resources/subscribe
-{
-  "uri": "github://repo/owner2/repo2/issues",
-  "callbackUrl": "https://client.com/webhook",
-  "callbackSecret": "secret2"
-}
-```
-
-### Custom Webhook Events
-
-Modify the example to subscribe to different events:
-
-```typescript
-events: ['issues', 'pull_request', 'push', 'release']
-```
-
-### Production Deployment
-
-For production, replace ngrok with:
-
-1. **Deploy to cloud** (AWS, GCP, Azure)
-2. **Use real domain** with SSL
-3. **Store webhook IDs** in database (not in-memory)
-4. **Add rate limiting**
-5. **Add monitoring**
-
----
-
-## 📚 Resources
-
-- **MCP Specification**: https://spec.modelcontextprotocol.io/
-- **GitHub Webhooks**: https://docs.github.com/en/webhooks
-- **Octokit REST API**: https://octokit.github.io/rest.js/
-- **ngrok Documentation**: https://ngrok.com/docs
-
----
-
-## ❓ Need Help?
-
-If you encounter issues:
-
-1. Check the server logs for errors
-2. Verify all prerequisites are met
-3. Check GitHub webhook deliveries for errors
-4. Review this troubleshooting guide
-
-Happy testing! 🚀

package/examples/QUICKSTART.md

@@ -1,130 +0,0 @@
-# 🚀 Quick Start - GitHub MCP Live Integration
-
-## What You Need (5 minutes setup)
-
-### 1️⃣ GitHub Personal Access Token
-```
-🔗 Create at: https://github.com/settings/tokens/new
-
-✅ Scopes to select:
-   - repo
-   - admin:repo_hook
-
-📋 Format: ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-```
-
-### 2️⃣ ngrok Auth Token (FREE)
-```
-🔗 Sign up: https://dashboard.ngrok.com/signup
-🔗 Get token: https://dashboard.ngrok.com/get-started/your-authtoken
-
-📋 Format: 2abc123def456ghi789jkl_0MnOpQrStUvWxYz
-
-💡 Set as env variable (optional):
-   export NGROK_AUTH_TOKEN="your_token"
-```
-
-### 3️⃣ Test Repository
-```
-Use any GitHub repo you own, or create one:
-
-   gh repo create mcp-webhook-test --public
-```
-
----
-
-## Run the Example
-
-```bash
-cd packages/plugins/mcp-proxy
-npx tsx examples/github-server-live.ts
-```
-
-### You'll be prompted for:
-1. **GitHub Token**: Paste your `ghp_...` token
-2. **Repo Owner**: Your GitHub username
-3. **Repo Name**: Your test repo name  
-4. **ngrok Token**: Your ngrok token (or Enter if in env)
-5. **Webhook Secret**: Just press Enter (auto-generated)
-
----
-
-## What Happens
-
-```
-✅ Connects to GitHub API
-✅ Verifies repo access
-✅ Starts ngrok tunnel (gets public URL)
-✅ Starts MCP server on port 3000
-✅ Ready to create webhooks!
-```
-
----
-
-## Test It
-
-### Option 1: Use MCP Inspector
-```bash
-# In browser, open:
-http://localhost:3000/mcp
-```
-
-### Option 2: Subscribe to Issues
-```bash
-curl -X POST http://localhost:3000/mcp/resources/subscribe \
-  -H "Content-Type: application/json" \
-  -d '{
-    "uri": "github://repo/YOUR_USERNAME/YOUR_REPO/issues",
-    "callbackUrl": "https://webhook.site/unique-url",
-    "callbackSecret": "test123"
-  }'
-```
-
-This creates a REAL GitHub webhook!
-
-### Option 3: Create Test Issue
-```
-1. Go to: https://github.com/YOUR_USERNAME/YOUR_REPO/issues/new
-2. Create a new issue
-3. Watch the server logs - you'll see the webhook arrive! 🎉
-```
-
----
-
-## Expected Output
-
-```
-╔═══════════════════════════════════════════════════════════╗
-║  GitHub MCP Server - Live Integration with Webhooks     ║
-╚═══════════════════════════════════════════════════════════╝
-
-✅ Authenticated as: your-username
-✅ Repository found: your-username/test-repo
-✅ Public URL: https://abc123.ngrok.io
-🚀 MCP Server started on port 3000
-
-📡 Ready to receive webhooks!
-```
-
----
-
-## Troubleshooting
-
-**ngrok Error "failed to start tunnel"**
-→ You need an ngrok auth token. Sign up at ngrok.com (it's free!)
-
-**GitHub "Bad credentials"**
-→ Check your token hasn't expired and has the right scopes
-
-**GitHub "Not Found"**
-→ Verify repo exists and you own it
-
----
-
-## 🎓 Learn More
-
-Full setup guide: `examples/GITHUB_LIVE_SETUP.md`
-
----
-
-**Ready? Let's do this! 🚀**