@parlex/collector-sdk 0.1.0

package/README.md

@@ -0,0 +1,194 @@
+# @mcp-server/collector-sdk
+
+Express middleware for collecting API traffic and sending it to an MCP server for automatic tool generation.
+
+## Installation
+
+```bash
+npm install @mcp-server/collector-sdk
+# or
+pnpm add @mcp-server/collector-sdk
+# or
+yarn add @mcp-server/collector-sdk
+```
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import { createCollector } from '@mcp-server/collector-sdk';
+
+const app = express();
+
+// Add the collector middleware
+app.use(createCollector({
+  mcpUrl: process.env.MCP_SERVER_URL,      // e.g., 'https://mcp.example.com'
+  apiKey: process.env.COLLECTOR_API_KEY,   // Your collector API key
+  debug: process.env.NODE_ENV !== 'production'
+}));
+
+// Your API routes
+app.get('/api/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+app.listen(3000);
+```
+
+## Configuration
+
+### Required Options
+
+- **`mcpUrl`** (string): Base URL of your MCP server
+- **`apiKey`** (string): API key for authenticating with the collector endpoint
+
+### Optional Options
+
+- **`collectPath`** (string): Custom collector endpoint path (default: `'/collect'`)
+- **`debug`** (boolean): Enable debug logging (default: `false`)
+- **`timeout`** (number): Request timeout in milliseconds (default: `5000`)
+- **`shouldCollect`** (function): Filter which requests to collect
+
+## Advanced Usage
+
+### Filtering Requests
+
+Only collect specific endpoints:
+
+```typescript
+app.use(createCollector({
+  mcpUrl: process.env.MCP_SERVER_URL,
+  apiKey: process.env.COLLECTOR_API_KEY,
+  shouldCollect: (req) => {
+    // Only collect /api/* endpoints
+    return req.path.startsWith('/api/');
+  }
+}));
+```
+
+### Environment Variables
+
+```bash
+# .env
+MCP_SERVER_URL=https://mcp.yourcompany.com
+COLLECTOR_API_KEY=your-secret-key-here
+```
+
+```typescript
+import { config } from 'dotenv';
+config();
+
+app.use(createCollector({
+  mcpUrl: process.env.MCP_SERVER_URL!,
+  apiKey: process.env.COLLECTOR_API_KEY!,
+  debug: process.env.NODE_ENV !== 'production'
+}));
+```
+
+### Debug Mode
+
+Enable detailed logging:
+
+```typescript
+app.use(createCollector({
+  mcpUrl: 'https://mcp.example.com',
+  apiKey: 'your-key',
+  debug: true
+}));
+
+// Output:
+// [MCP Collector] Initialized with URL: https://mcp.example.com/collect
+// [MCP Collector] Capturing: GET /api/users
+// [MCP Collector] Sending: GET /api/users - Status: 200 - Duration: 45ms
+// [MCP Collector] ✓ Sent: GET /api/users
+```
+
+## What Gets Collected
+
+For each request/response, the following data is collected:
+
+```typescript
+{
+  method: 'GET',
+  path: '/api/users?page=1',
+  query: { page: '1' },
+  body: null,
+  response: { users: [...] },
+  status: 200,
+  durationMs: 45,
+  timestamp: '2026-01-22T10:30:00.000Z'
+}
+```
+
+## Error Handling
+
+The collector middleware:
+- ✅ Never blocks your API responses
+- ✅ Sends data asynchronously after the response is sent
+- ✅ Logs errors only, doesn't throw
+- ✅ Won't crash your app if MCP server is down
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```typescript
+import { CollectorConfig, CollectorEntry } from '@mcp-server/collector-sdk';
+
+const config: CollectorConfig = {
+  mcpUrl: 'https://mcp.example.com',
+  apiKey: 'your-key'
+};
+```
+
+## Examples
+
+### Express + TypeScript
+
+```typescript
+import express, { Express } from 'express';
+import { createCollector } from '@mcp-server/collector-sdk';
+
+const app: Express = express();
+
+app.use(express.json());
+app.use(createCollector({
+  mcpUrl: process.env.MCP_SERVER_URL!,
+  apiKey: process.env.COLLECTOR_API_KEY!
+}));
+
+app.get('/api/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+### With Custom Timeout
+
+```typescript
+app.use(createCollector({
+  mcpUrl: 'https://mcp.example.com',
+  apiKey: 'your-key',
+  timeout: 10000  // 10 seconds
+}));
+```
+
+### Excluding Health Checks
+
+```typescript
+app.use(createCollector({
+  mcpUrl: 'https://mcp.example.com',
+  apiKey: 'your-key',
+  shouldCollect: (req) => {
+    // Don't collect health check endpoints
+    return !req.path.startsWith('/health');
+  }
+}));
+```
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @mcp-server/collector-sdk
+ *
+ * Express middleware for collecting API traffic and sending to MCP server
+ * for automatic tool generation.
+ */
+export { createCollector, collectorMiddleware } from './middleware.js';
+export type { CollectorConfig, CollectorEntry } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACvE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * @mcp-server/collector-sdk
+ *
+ * Express middleware for collecting API traffic and sending to MCP server
+ * for automatic tool generation.
+ */
+export { createCollector, collectorMiddleware } from './middleware.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/middleware.d.ts

@@ -0,0 +1,27 @@
+import { Request, Response, NextFunction } from 'express';
+import { CollectorConfig } from './types.js';
+/**
+ * Create Express middleware that collects request/response data
+ * and sends it to an MCP server
+ *
+ * @param config - Collector configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import { createCollector } from '@mcp-server/collector-sdk';
+ *
+ * app.use(createCollector({
+ *   mcpUrl: 'https://mcp.example.com',
+ *   apiKey: process.env.COLLECTOR_API_KEY,
+ *   debug: true
+ * }));
+ * ```
+ */
+export declare function createCollector(config: CollectorConfig): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Legacy function name for backward compatibility
+ * @deprecated Use createCollector instead
+ */
+export declare function collectorMiddleware(mcpUrl: string, apiKey: string): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAkB,MAAM,YAAY,CAAC;AAE7D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,IAgB7C,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UAmFxD;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,SAzFnD,OAAO,OAAO,QAAQ,QAAQ,YAAY,UA2FxD"}

package/dist/middleware.js

@@ -0,0 +1,102 @@
+import axios from 'axios';
+/**
+ * Create Express middleware that collects request/response data
+ * and sends it to an MCP server
+ *
+ * @param config - Collector configuration
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * import { createCollector } from '@mcp-server/collector-sdk';
+ *
+ * app.use(createCollector({
+ *   mcpUrl: 'https://mcp.example.com',
+ *   apiKey: process.env.COLLECTOR_API_KEY,
+ *   debug: true
+ * }));
+ * ```
+ */
+export function createCollector(config) {
+    const { mcpUrl, apiKey, collectPath = '/collect', debug = false, timeout = 5000, shouldCollect = () => true } = config;
+    const collectorUrl = `${mcpUrl}${collectPath}`;
+    if (debug) {
+        console.log(`[MCP Collector] Initialized with URL: ${collectorUrl}`);
+    }
+    return (req, res, next) => {
+        // Skip if filter says no
+        if (!shouldCollect(req)) {
+            return next();
+        }
+        const start = Date.now();
+        // Save the request body before Express processes it
+        const requestBody = req.body;
+        // Capture response body
+        let responseBody;
+        const originalSend = res.send;
+        res.send = function (body) {
+            responseBody = body;
+            return originalSend.call(this, body);
+        };
+        if (debug) {
+            console.log(`[MCP Collector] Capturing: ${req.method} ${req.originalUrl}`);
+        }
+        // When the response is finished
+        res.on('finish', async () => {
+            try {
+                // Try to parse response if it's a JSON string
+                let finalResponse = responseBody;
+                try {
+                    if (typeof responseBody === 'string' &&
+                        (responseBody.startsWith('{') || responseBody.startsWith('['))) {
+                        finalResponse = JSON.parse(responseBody);
+                    }
+                }
+                catch (e) {
+                    // If parsing fails, use original body
+                }
+                const entry = {
+                    method: req.method,
+                    path: req.originalUrl,
+                    query: req.query,
+                    body: requestBody,
+                    response: finalResponse,
+                    status: res.statusCode,
+                    durationMs: Date.now() - start,
+                    timestamp: new Date().toISOString(),
+                };
+                if (debug) {
+                    console.log(`[MCP Collector] Sending: ${req.method} ${req.originalUrl} ` +
+                        `- Status: ${res.statusCode} - Duration: ${entry.durationMs}ms`);
+                }
+                // Send to collector asynchronously without blocking
+                await axios.post(collectorUrl, entry, {
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'x-collector-key': apiKey
+                    },
+                    timeout
+                });
+                if (debug) {
+                    console.log(`[MCP Collector] ✓ Sent: ${req.method} ${req.originalUrl}`);
+                }
+            }
+            catch (error) {
+                // Log error but don't fail the request
+                const axiosError = error;
+                if (debug || axiosError.response?.status === 401) {
+                    console.error(`[MCP Collector] ✗ Failed to send: ${req.method} ${req.originalUrl}`, axiosError.message, axiosError.response?.status === 401 ? '(Unauthorized - check API key)' : '');
+                }
+            }
+        });
+        next();
+    };
+}
+/**
+ * Legacy function name for backward compatibility
+ * @deprecated Use createCollector instead
+ */
+export function collectorMiddleware(mcpUrl, apiKey) {
+    return createCollector({ mcpUrl, apiKey });
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Entry data collected from a request/response cycle
+ */
+export interface CollectorEntry {
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+    /** Request path with query string */
+    path: string;
+    /** Query parameters */
+    query: Record<string, any>;
+    /** Request body */
+    body: any;
+    /** Response body */
+    response?: any;
+    /** HTTP status code */
+    status: number;
+    /** Request duration in milliseconds */
+    durationMs: number;
+    /** ISO timestamp */
+    timestamp: string;
+}
+/**
+ * Configuration options for the collector middleware
+ */
+export interface CollectorConfig {
+    /** Base URL of the MCP server (e.g., 'https://mcp.example.com') */
+    mcpUrl: string;
+    /** API key for authenticating with the collector endpoint */
+    apiKey: string;
+    /** Optional: Custom endpoint path (default: '/collect') */
+    collectPath?: string;
+    /** Optional: Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Optional: Timeout for collector requests in ms (default: 5000) */
+    timeout?: number;
+    /** Optional: Filter function to determine which requests to collect */
+    shouldCollect?: (req: any) => boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IAEf,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE3B,mBAAmB;IACnB,IAAI,EAAE,GAAG,CAAC;IAEV,oBAAoB;IACpB,QAAQ,CAAC,EAAE,GAAG,CAAC;IAEf,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IAEf,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IAEnB,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IAEf,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IAEf,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,sDAAsD;IACtD,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,uEAAuE;IACvE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC;CACvC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@parlex/collector-sdk",
+  "version": "0.1.0",
+  "description": "Express middleware for collecting API traffic and sending to MCP server",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "collector",
+    "express",
+    "middleware",
+    "api",
+    "traffic"
+  ],
+  "author": "",
+  "license": "ISC",
+  "peerDependencies": {
+    "express": "^4.0.0"
+  },
+  "dependencies": {
+    "axios": "^1.7.7"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3"
+  }
+}