mcp-http-webhook 1.0.0

package/examples/GITHUB_LIVE_EXAMPLE.md

@@ -0,0 +1,308 @@
+# GitHub Live Webhook Integration Example
+
+This example demonstrates a **real, working integration** between MCP and GitHub using live webhooks.
+
+## What This Does
+
+1. **Connects to GitHub API** - Uses your personal access token to interact with real repositories
+2. **Auto-configures ngrok** - Sets up a public URL automatically for webhook delivery
+3. **Creates Real Webhooks** - Registers actual GitHub webhooks on your repository
+4. **Live Updates** - Receives real-time notifications when issues are created, updated, or closed
+5. **Resource Subscriptions** - Demonstrates MCP's webhook-based resource subscription pattern
+
+## Prerequisites
+
+### 1. GitHub Personal Access Token
+
+Create a token at: https://github.com/settings/tokens/new
+
+**Required Scopes:**
+- `repo` - Full control of private repositories
+- `admin:repo_hook` - Full control of repository hooks
+
+**Steps:**
+1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
+2. Click "Generate new token (classic)"
+3. Set expiration (for testing, 30 days is fine)
+4. Select scopes: `repo` and `admin:repo_hook`
+5. Click "Generate token"
+6. **Copy the token immediately** (you won't see it again!)
+
+### 2. Test Repository
+
+You'll need a GitHub repository you own for testing. You can:
+- Use an existing test repository
+- Create a new one at: https://github.com/new
+- Recommended: Create a dedicated test repo like `mcp-webhook-test`
+
+### 3. ngrok (Optional Account)
+
+The example works without an ngrok account, but you can:
+- Sign up for free at: https://ngrok.com
+- Get your auth token from: https://dashboard.ngrok.com/get-started/your-authtoken
+- Set it: `export NGROK_AUTH_TOKEN="your_token_here"`
+
+## Running the Example
+
+### Step 1: Start the Server
+
+```bash
+cd /data/work/kaman3.0/packages/plugins/mcp-proxy
+npx tsx examples/github-server-live.ts
+```
+
+### Step 2: Provide Information
+
+The script will ask you for:
+
+1. **GitHub Personal Access Token**: Paste your token (input is hidden)
+2. **Repository Owner**: Your GitHub username
+3. **Repository Name**: The repository to monitor
+4. **Webhook Secret**: Press Enter for random, or provide your own
+
+Example interaction:
+```
+Enter your GitHub Personal Access Token: ghp_xxxxxxxxxxxxx
+Enter repository owner (your GitHub username): yourusername
+Enter repository name: test-repo
+Enter webhook secret (or press enter for random): [Enter]
+```
+
+### Step 3: Server Starts
+
+You'll see output like:
+```
+✅ Authenticated as: yourusername
+✅ Repository found: yourusername/test-repo
+🌐 Starting ngrok tunnel...
+✅ Public URL: https://abc123.ngrok.io
+
+╔═══════════════════════════════════════════════════════════╗
+║  🎉 GitHub MCP Server is LIVE!                          ║
+╚═══════════════════════════════════════════════════════════╝
+
+📍 MCP Endpoint:
+   https://abc123.ngrok.io/mcp
+
+🔍 Test with MCP Inspector:
+   npx @modelcontextprotocol/inspector https://abc123.ngrok.io/mcp
+```
+
+## Testing the Integration
+
+### Method 1: MCP Inspector (Recommended)
+
+1. **Open MCP Inspector:**
+   ```bash
+   npx @modelcontextprotocol/inspector https://your-ngrok-url.ngrok.io/mcp
+   ```
+
+2. **List Resources:**
+   - Click "List Resources"
+   - You'll see your repository issues resource
+
+3. **Subscribe to Issues:**
+   - Go to the Resources tab
+   - Click on the GitHub resource
+   - Click "Subscribe" (if available in Inspector)
+   - Or use curl (see Method 2)
+
+4. **Create an Issue:**
+   - Use the "create_issue" tool in Inspector
+   - Fill in title and body
+   - Execute
+   - Watch the console for webhook delivery!
+
+### Method 2: Manual API Calls
+
+**List Issues:**
+```bash
+curl -X POST https://your-ngrok-url.ngrok.io/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "list_issues",
+      "arguments": {
+        "state": "open"
+      }
+    }
+  }'
+```
+
+**Create an Issue:**
+```bash
+curl -X POST https://your-ngrok-url.ngrok.io/mcp \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 2,
+    "method": "tools/call",
+    "params": {
+      "name": "create_issue",
+      "arguments": {
+        "title": "Test issue from MCP",
+        "body": "This was created via MCP webhook integration!"
+      }
+    }
+  }'
+```
+
+**Subscribe to Resource:**
+```bash
+curl -X POST https://your-ngrok-url.ngrok.io/mcp/resources/subscribe \
+  -H "Content-Type: application/json" \
+  -d '{
+    "uri": "github://repo/yourusername/yourrepo/issues",
+    "callbackUrl": "https://your-client-url.com/webhook",
+    "callbackSecret": "your-secret"
+  }'
+```
+
+### Method 3: GitHub UI
+
+1. **Go to your repository on GitHub**
+2. **Create a new issue manually**
+3. **Watch your server console** - you'll see the webhook notification!
+
+Example output:
+```
+📬 Received GitHub webhook
+   Event: issues
+   Subscription: sub_abc123
+   Action: opened
+   Issue: #42 - Test issue from MCP
+```
+
+## How It Works
+
+### Architecture
+
+```
+┌─────────────────┐         ┌──────────────┐         ┌─────────────┐
+│  MCP Client     │         │  Your MCP    │         │   GitHub    │
+│  (Inspector)    │◄───────►│   Server     │◄───────►│    API      │
+└─────────────────┘         └──────────────┘         └─────────────┘
+                                   │                         │
+                                   │                         │
+                            ┌──────▼───────┐         ┌──────▼──────┐
+                            │    ngrok     │         │   Webhook   │
+                            │   Tunnel     │◄────────│   Delivery  │
+                            └──────────────┘         └─────────────┘
+```
+
+### Subscription Flow
+
+1. **Client subscribes** to `github://repo/owner/repo/issues`
+2. **Server receives** subscription request
+3. **Server calls GitHub API** to create webhook pointing to ngrok URL
+4. **GitHub confirms** webhook creation
+5. **Server stores** webhook ID and subscription mapping
+6. **When issue changes**, GitHub sends webhook to ngrok URL
+7. **ngrok forwards** to your local server
+8. **Server processes** webhook, extracts issue data
+9. **Server notifies** original MCP client via their callback URL
+
+### Resource Template Pattern
+
+The URI `github://repo/{owner}/{repo}/issues` is a **resource template**:
+- `{owner}` and `{repo}` are variables
+- The `list()` function returns specific instances
+- The `read()` function fetches data for a specific instance
+- The `subscription` object handles webhook lifecycle
+
+## Webhook Security
+
+### Incoming (from GitHub)
+
+GitHub signs webhooks with HMAC-SHA256:
+```typescript
+X-Hub-Signature-256: sha256=<signature>
+```
+
+The server verifies this signature using your webhook secret.
+
+### Outgoing (to Client)
+
+When notifying your MCP client, the server signs the payload:
+```typescript
+X-Webhook-Signature: sha256=<signature>
+```
+
+Your client should verify this using the `callbackSecret` they provided.
+
+## Monitoring
+
+Watch the console for real-time logs:
+
+```
+📝 Creating GitHub issue: Test issue
+✅ Issue created: #42
+
+🔔 Setting up GitHub webhook...
+   Resource: github://repo/owner/repo/issues
+   Subscription ID: sub_abc123def
+✅ GitHub webhook created: ID 12345
+
+📬 Received GitHub webhook
+   Event: issues
+   Subscription: sub_abc123def
+   Action: opened
+   Issue: #42 - Test issue
+```
+
+## Cleanup
+
+**Press Ctrl+C** to stop the server.
+
+The server will automatically:
+1. Delete all GitHub webhooks it created
+2. Stop ngrok tunnel
+3. Clean up resources
+
+Output:
+```
+🧹 Shutting down...
+✅ Deleted webhook: 12345
+👋 Goodbye!
+```
+
+## Troubleshooting
+
+### "Failed to verify GitHub access"
+- Check your personal access token is correct
+- Ensure token has `repo` and `admin:repo_hook` scopes
+- Verify the repository owner/name are correct
+
+### "Failed to create webhook"
+- Ensure you have admin access to the repository
+- Check your GitHub token scopes
+- Verify ngrok tunnel is working
+
+### Webhooks not arriving
+- Check GitHub webhook delivery page: `https://github.com/owner/repo/settings/hooks`
+- Click on the webhook and view "Recent Deliveries"
+- Check for error messages
+- Verify ngrok tunnel is still active
+
+### ngrok connection issues
+- Free ngrok URLs expire after 2 hours
+- Restart the server to get a new URL
+- Consider creating an ngrok account for longer sessions
+
+## Next Steps
+
+- **Add more event types**: Handle PR events, comments, etc.
+- **Multiple repositories**: Monitor multiple repos with one server
+- **Client implementation**: Build a client that receives webhook notifications
+- **Production deployment**: Deploy to a real server (no ngrok needed)
+- **Database storage**: Replace InMemoryStore with Redis for persistence
+
+## Learning Resources
+
+- [MCP Specification](https://spec.modelcontextprotocol.io/)
+- [GitHub Webhooks Docs](https://docs.github.com/en/webhooks)
+- [Octokit REST API](https://octokit.github.io/rest.js/)
+- [ngrok Documentation](https://ngrok.com/docs)

package/examples/GITHUB_LIVE_SETUP.md

@@ -0,0 +1,253 @@
+# 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

@@ -0,0 +1,130 @@
+# 🚀 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! 🚀**