mcp-http-webhook 1.0.0

package/.eslintrc.json

@@ -0,0 +1,16 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-unused-vars": ["error", { "argsIgnorePattern": "^_" }]
+  }
+}

package/.prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 100,
+  "tabWidth": 2,
+  "arrowParens": "always"
+}

package/ARCHITECTURE.md

@@ -0,0 +1,269 @@
+# MCP HTTP Webhook Architecture
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         MCP Client                               │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │  - Calls tools via HTTP POST                              │  │
+│  │  - Reads resources via HTTP POST                          │  │
+│  │  - Subscribes with callback URL                           │  │
+│  │  - Receives notifications via webhook                     │  │
+│  └──────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+         │                                              ▲
+         │ HTTP POST /mcp/tools/call                   │
+         │ HTTP POST /mcp/resources/read               │
+         │ HTTP POST /mcp/resources/subscribe          │
+         │                                              │ HTTP POST
+         ▼                                              │ (notification)
+┌─────────────────────────────────────────────────────────────────┐
+│                    MCP HTTP Webhook Server                       │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                  Express Application                      │  │
+│  │  ┌────────────┐ ┌─────────────┐ ┌──────────────────┐    │  │
+│  │  │ Protocol   │ │ Subscription│ │ Webhook          │    │  │
+│  │  │ Handler    │ │ Manager     │ │ Manager          │    │  │
+│  │  └────────────┘ └─────────────┘ └──────────────────┘    │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                           │                                      │
+│                           ▼                                      │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │              Key-Value Store Interface                    │  │
+│  │         (Redis / DynamoDB / PostgreSQL)                  │  │
+│  │  - Subscription data                                      │  │
+│  │  - User indexes                                           │  │
+│  │  - Metadata                                               │  │
+│  └──────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+         │                                              ▲
+         │ Register webhook                            │
+         │ (onSubscribe)                               │ HTTP POST
+         │                                              │ (third-party event)
+         ▼                                              │
+┌─────────────────────────────────────────────────────────────────┐
+│                    Third-Party Services                          │
+│  ┌────────────┐  ┌──────────┐  ┌──────┐  ┌──────────────┐     │
+│  │   GitHub   │  │  Slack   │  │ Drive│  │  PostgreSQL  │     │
+│  │  Webhooks  │  │  Events  │  │ Push │  │   NOTIFY     │     │
+│  └────────────┘  └──────────┘  └──────┘  └──────────────┘     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Subscription Flow
+
+### 1. Subscribe Request
+
+```
+Client                    MCP Server                Third-Party
+  │                           │                          │
+  │ POST /resources/subscribe │                          │
+  │ {                         │                          │
+  │   uri: "...",             │                          │
+  │   callbackUrl: "..."      │                          │
+  │ }                         │                          │
+  │──────────────────────────>│                          │
+  │                           │                          │
+  │                           │ Generate subscriptionId  │
+  │                           │ Create webhook URL       │
+  │                           │                          │
+  │                           │ Register webhook         │
+  │                           │─────────────────────────>│
+  │                           │                          │
+  │                           │ Store in KV store        │
+  │                           │                          │
+  │ Response:                 │                          │
+  │ { subscriptionId: "..." } │                          │
+  │<──────────────────────────│                          │
+```
+
+### 2. Webhook Notification Flow
+
+```
+Third-Party              MCP Server                  Client
+  │                           │                          │
+  │ POST /webhooks/incoming/  │                          │
+  │      {subscriptionId}     │                          │
+  │──────────────────────────>│                          │
+  │                           │                          │
+  │                           │ Load subscription        │
+  │                           │ from KV store            │
+  │                           │                          │
+  │                           │ Process webhook          │
+  │                           │ (onWebhook handler)      │
+  │                           │                          │
+  │ 200 OK                    │                          │
+  │<──────────────────────────│                          │
+  │                           │                          │
+  │                           │ POST to callbackUrl      │
+  │                           │ {                        │
+  │                           │   subscriptionId,        │
+  │                           │   resourceUri,           │
+  │                           │   changeType,            │
+  │                           │   data                   │
+  │                           │ }                        │
+  │                           │─────────────────────────>│
+  │                           │                          │
+  │                           │        200 OK            │
+  │                           │<─────────────────────────│
+```
+
+## Component Interaction
+
+### Protocol Handler
+- Handles MCP protocol messages
+- Validates input using JSON Schema
+- Executes tool handlers
+- Reads resources
+- Returns formatted responses
+
+### Subscription Manager
+- Creates and deletes subscriptions
+- Manages subscription lifecycle
+- Stores data in KV store
+- Maintains user indexes
+- Verifies ownership
+
+### Webhook Manager
+- Processes incoming webhooks
+- Verifies signatures
+- Calls client callbacks
+- Implements retry logic
+- Handles timeouts
+
+### Key-Value Store
+- Stores subscription data
+- Maintains indexes
+- Supports TTL
+- Provides scan functionality
+- Enables horizontal scaling
+
+## Data Flow
+
+### Tool Call
+
+```
+1. Client sends HTTP POST to /mcp/tools/call
+2. Server authenticates request
+3. ProtocolHandler validates input against JSON Schema
+4. Tool handler executes
+5. Response returned to client
+```
+
+### Resource Read
+
+```
+1. Client sends HTTP POST to /mcp/resources/read
+2. Server authenticates request
+3. ProtocolHandler finds resource by URI
+4. Resource read handler executes
+5. Contents returned to client
+```
+
+### Subscription Creation
+
+```
+1. Client sends HTTP POST to /mcp/resources/subscribe
+2. Server authenticates request
+3. SubscriptionManager generates ID and webhook URL
+4. Resource onSubscribe handler called
+5. Handler registers with third-party service
+6. Subscription stored in KV store
+7. Subscription ID returned to client
+```
+
+### Notification Delivery
+
+```
+1. Third-party sends webhook to /webhooks/incoming/{id}
+2. Server loads subscription from KV store
+3. Resource onWebhook handler processes payload
+4. WebhookManager signs and sends to client callback
+5. Retry on failure with exponential backoff
+6. Dead letter queue if all retries fail
+```
+
+## Scaling Strategy
+
+### Horizontal Scaling
+
+```
+┌─────────────┐
+│Load Balancer│
+└──────┬──────┘
+       │
+       ├──────────┬──────────┬──────────┐
+       │          │          │          │
+       ▼          ▼          ▼          ▼
+   ┌─────┐    ┌─────┐    ┌─────┐    ┌─────┐
+   │MCP 1│    │MCP 2│    │MCP 3│    │MCP N│
+   └──┬──┘    └──┬──┘    └──┬──┘    └──┬──┘
+      │          │          │          │
+      └──────────┴──────────┴──────────┘
+                 │
+                 ▼
+           ┌──────────┐
+           │  Redis   │
+           │ Cluster  │
+           └──────────┘
+```
+
+Benefits:
+- No session affinity required
+- Simple round-robin load balancing
+- Shared state in Redis
+- Independent instance scaling
+- Zero-downtime deployments
+
+## Security Layers
+
+```
+┌─────────────────────────────────────┐
+│     HTTPS/TLS (Required)            │
+└─────────────────────────────────────┘
+┌─────────────────────────────────────┐
+│  Authentication Middleware          │
+│  (JWT, API Key, OAuth2)             │
+└─────────────────────────────────────┘
+┌─────────────────────────────────────┐
+│  Webhook Signature Verification     │
+│  (HMAC SHA-256, Timing-Safe)        │
+└─────────────────────────────────────┘
+┌─────────────────────────────────────┐
+│  Input Validation                   │
+│  (JSON Schema, AJV)                 │
+└─────────────────────────────────────┘
+┌─────────────────────────────────────┐
+│  Rate Limiting                      │
+│  (Optional Middleware)              │
+└─────────────────────────────────────┘
+```
+
+## Performance Optimizations
+
+1. **Connection Pooling**
+   - HTTP keep-alive
+   - Redis connection pool
+   - Database connection pool
+
+2. **Caching**
+   - Resource read results
+   - Tool metadata
+   - Configuration data
+
+3. **Async Processing**
+   - Non-blocking I/O
+   - Promise-based handlers
+   - Background webhook delivery
+
+4. **Retry Strategy**
+   - Exponential backoff
+   - Circuit breaker pattern
+   - Dead letter queue
+
+5. **Monitoring**
+   - Prometheus metrics
+   - Structured logging
+   - Health check endpoints
+   - Distributed tracing

package/CONTRIBUTING.md

@@ -0,0 +1,136 @@
+# Contributing to MCP HTTP Webhook
+
+Thank you for your interest in contributing! This document provides guidelines and instructions for contributing.
+
+## Development Setup
+
+1. **Fork and Clone**
+   ```bash
+   git clone https://github.com/your-username/mcp-http-webhook.git
+   cd mcp-http-webhook
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   npm install
+   # or
+   pnpm install
+   ```
+
+3. **Build**
+   ```bash
+   npm run build
+   ```
+
+4. **Run Tests**
+   ```bash
+   npm test
+   ```
+
+## Code Style
+
+We use ESLint and Prettier for code formatting:
+
+```bash
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+
+# Type check
+npm run type-check
+```
+
+### TypeScript Guidelines
+
+- Use explicit types for public APIs
+- Prefer `const` over `let`
+- Use async/await over promises
+- Document public APIs with JSDoc comments
+
+Example:
+
+```typescript
+/**
+ * Creates a new MCP server instance
+ * @param config - Server configuration
+ * @returns Configured MCP server
+ */
+export function createMCPServer(config: MCPServerConfig): MCPServer {
+  // ...
+}
+```
+
+## Testing
+
+- Write tests for all new features
+- Maintain >80% code coverage
+- Use descriptive test names
+
+```typescript
+describe('SubscriptionManager', () => {
+  it('should create a new subscription', async () => {
+    // Test implementation
+  });
+});
+```
+
+## Commit Messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+feat: add webhook retry backoff configuration
+fix: resolve subscription cleanup race condition
+docs: update subscription flow diagram
+test: add tests for webhook signature verification
+chore: update dependencies
+```
+
+## Pull Request Process
+
+1. **Create a Branch**
+   ```bash
+   git checkout -b feature/my-new-feature
+   ```
+
+2. **Make Changes**
+   - Write code following style guidelines
+   - Add/update tests
+   - Update documentation
+
+3. **Run Quality Checks**
+   ```bash
+   npm run lint
+   npm run format
+   npm test
+   npm run type-check
+   ```
+
+4. **Commit Changes**
+   ```bash
+   git commit -m "feat: add my new feature"
+   ```
+
+5. **Push to Fork**
+   ```bash
+   git push origin feature/my-new-feature
+   ```
+
+6. **Create Pull Request**
+   - Provide clear description of changes
+   - Link related issues
+   - Include screenshots/examples if applicable
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Questions?
+
+Feel free to open an issue or ask in our [Discord community](https://discord.gg/mcp-webhook).
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.