@parlex/collector-sdk

Express middleware for collecting API traffic and sending it to an MCP server for automatic tool generation.

Installation

npm install @parlex/collector-sdk
# or
pnpm add @parlex/collector-sdk
# or
yarn add @parlex/collector-sdk

Quick Start

import express from 'express';
import { createCollector } from '@parlex/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:

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

# .env
MCP_SERVER_URL=https://mcp.yourcompany.com
COLLECTOR_API_KEY=your-secret-key-here

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:

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:

{
  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:

import { CollectorConfig, CollectorEntry } from '@parlex/collector-sdk';

const config: CollectorConfig = {
  mcpUrl: 'https://mcp.example.com',
  apiKey: 'your-key'
};

Examples

Express + TypeScript

import express, { Express } from 'express';
import { createCollector } from '@parlex/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

app.use(createCollector({
  mcpUrl: 'https://mcp.example.com',
  apiKey: 'your-key',
  timeout: 10000  // 10 seconds
}));

Excluding Health Checks

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