Conduit 🌉

Unchain your GraphQL API for Large Language Models.

Conduit is a lightweight, automated bridge that exposes any GraphQL API as a set of tools consumable by Large Language Models (LLMs) via the Model Context Protocol (MCP).

It's a "set-it-and-forget-it" microservice. Simply point it at your GraphQL endpoint, and it handles the rest. Whenever you update your API, Conduit automatically discovers the new queries and mutations and exposes them to your AI agents with zero maintenance required.

✨ Features

• Zero-Maintenance: Automatically discovers your API's capabilities using introspection. No manual tool definition is needed.

• Protocol Compliant: Implements the core MCP endpoints (/listTools, /getToolSchema, /executeTool) out of the box.

• Dynamic Execution: Translates LLM tool calls into valid GraphQL queries/mutations and executes them against your API.

• Smart Port Management: Automatically detects port conflicts and finds available alternatives with detailed error reporting.

• WebSocket Support: Optional WebSocket server for real-time MCP communication alongside HTTP transport.

• Enhanced Logging: Comprehensive logging system with configurable levels and formatted output for better debugging.

• Container-Ready: Comes with a Dockerfile and Kubernetes manifests for easy deployment alongside your existing services.

• Lightweight & Fast: Built with Express.js for a minimal footprint and reliable performance.

🏗️ Architecture

The Conduit bridge is a stateless microservice that sits between your LLM client and your GraphQL API.

🚀 Quick Start

Prerequisites

• Node.js 18+

• Yarn or npm

• A GraphQL API endpoint

Installation & Setup

1. Clone and install dependencies:

   git clone <repository-url> cd conduit yarn install

2. Configure your environment:

   cp .env.example .env # Edit .env with your settings

3. Start the development server:

   yarn dev

The server will automatically:

• Check for port availability

• Find alternative ports if needed

• Set up HTTP and optionally WebSocket servers

• Provide detailed startup information

⚙️ Configuration

Environment Variables

Create a .env file based on .env.example:

Port Management Features

Conduit includes intelligent port management to handle the common "Port is already in use" error:

• Automatic Detection: Checks if preferred ports are available before starting

• Smart Alternatives: Automatically finds alternative ports within a configurable range

• Process Information: Shows which processes are using conflicting ports

• Detailed Logging: Provides clear error messages and troubleshooting suggestions

Handling Port Conflicts

When a port conflict occurs, Conduit will:

1. Check the preferred port (from PORT environment variable)

2. Show conflicting processes with PID information

3. Search for alternatives in the specified range

4. Provide helpful suggestions:

   💡 Suggestions: 1. Kill the process using: kill -9 <PID> 2. Use a different port with: PORT=<new_port> npm run dev 3. Set environment variable: export PORT=<new_port>

🔌 WebSocket Support

Conduit supports both HTTP and WebSocket transports for MCP communication:

Enabling WebSocket

WebSocket Features

• Automatic Port Management: Finds available ports for WebSocket server

• Real-time Communication: Persistent connections for better performance

• Full MCP Protocol Support: All MCP methods work over WebSocket

• Connection Monitoring: Detailed logging of client connections and disconnections

• Error Handling: Graceful handling of connection issues

Usage Examples

HTTP Transport:

WebSocket Transport:

📊 Enhanced Logging

Conduit provides comprehensive logging with multiple levels and formatted output:

Log Levels

• ERROR: Critical errors and failures

• WARN: Warnings and non-critical issues

• INFO: General information and status updates

• DEBUG: Detailed debugging information

Log Categories

Each log entry is categorized for easy filtering:

• [SERVER] - HTTP server events

• [WS] - WebSocket server events

• [MCP] - MCP protocol messages

• [PORT] - Port management operations

Example Output

🔧 Troubleshooting

Common Issues

"WebSocket server error: Port is already in use"

This error occurs when the WebSocket server cannot bind to its configured port.

Solutions:

1. Check what's using the port:

   # The server will automatically show this information lsof -i :5174 # macOS/Linux netstat -ano | findstr :5174 # Windows

2. Use a different port:

   WS_PORT=5175 npm run dev

3. Let Conduit auto-assign a port:

   # Remove WS_PORT from .env or set it to empty ENABLE_WEBSOCKET=true # WS_PORT= # Auto-assigned

4. Disable WebSocket if not needed:

   ENABLE_WEBSOCKET=false

"GraphQL API not responding"

Check your configuration:

Enable debug logging for detailed information:

Port Conflict Prevention

To avoid port conflicts:

1. Use non-standard ports: Start with ports like 8000+ instead of common ones

2. Check running services: Use lsof -i or netstat to see what's running

3. Use port ranges: Configure PORT_RANGE to search a wider range

4. Environment-specific ports: Use different ports per environment

🚦 Server Status Information

When Conduit starts successfully, you'll see: