@supaproxy/connections

Plugin package for SupaProxy MCP connection types. Connections are the bridge between SupaProxy and external tool servers using the Model Context Protocol.

Each connection plugin handles connecting to an MCP server, discovering available tools, and calling those tools during AI conversations.

Installation

npm install @supaproxy/connections

Quick start

import { registry } from '@supaproxy/connections'

// All built-in plugins are auto-registered on import.

// List available connection types
console.log(registry.types()) // ['http', 'stdio', 'authenticated']

// Test connectivity and discover tools
const http = registry.get('http')
const result = await http.test({ url: 'https://mcp.example.com/sse' })

if (result.ok) {
  console.log(`Found ${result.tools} tools: ${result.toolNames?.join(', ')}`)
}

// Establish a live connection
const connection = await http.connect({ url: 'https://mcp.example.com/sse' })

// Discover tools
console.log(connection.tools)

// Call a tool
const result = await connection.callTool('search', { query: 'hello' })

// Close the connection
await connection.close()

API reference

ConnectionPlugin

The interface every connection type must implement.

interface ConnectionPlugin {
  readonly type: string          // Unique identifier: 'http', 'stdio', etc.
  readonly name: string          // Human-readable name
  readonly description: string   // Short description
  readonly configSchema: { fields: ConfigField[] }

  test(config: Record<string, string>): Promise<TestResult>
  connect(config: Record<string, string>): Promise<McpConnection>
}

McpConnection

A live connection to an MCP server.

interface McpConnection {
  readonly tools: ToolDefinition[]
  callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>
  close(): Promise<void>
}

ToolDefinition

interface ToolDefinition {
  name: string
  description: string
  inputSchema: Record<string, unknown>
}

ToolCallResult

interface ToolCallResult {
  content: Array<{ type: string; text?: string }>
  isError: boolean
}

TestResult

interface TestResult {
  ok: boolean
  tools?: number          // Number of tools discovered
  toolNames?: string[]    // Names of discovered tools
  server?: string         // Server identifier
  error?: string          // Error message if test failed
}

ConfigField

interface ConfigField {
  name: string
  label: string
  type: 'text' | 'password' | 'select'
  required: boolean
  placeholder?: string
  helpText?: string
  options?: string[]
}

Registry methods

| Method | Returns | Description | |--------|---------|-------------| | registry.list() | ConnectionPlugin[] | All registered plugins | | registry.get(type) | ConnectionPlugin | Get plugin by type (throws if not found) | | registry.has(type) | boolean | Check if a plugin type is registered | | registry.types() | string[] | List all registered type identifiers | | registry.schemas() | Array<{type, name, description, configSchema}> | Config schemas for dashboard forms | | registry.register(plugin) | void | Register a custom plugin |

Available plugins

| Plugin | Type | Description | |--------|------|-------------| | HTTP | http | Connects to MCP servers over HTTP (Streamable HTTP / SSE transport). | | STDIO | stdio | Connects to MCP servers via standard input/output. For locally running tool servers. | | Authenticated | authenticated | HTTP connection with authentication headers. Supports API key and bearer token auth for secured MCP servers. |

Adding a new connection type

Create a file that implements ConnectionPlugin:

import type { ConnectionPlugin, McpConnection, TestResult } from '@supaproxy/connections'

export const myPlugin: ConnectionPlugin = {
  type: 'my-transport',
  name: 'My Transport',
  description: 'Custom MCP transport',
  configSchema: {
    fields: [
      { name: 'url', label: 'Server URL', type: 'text', required: true },
    ],
  },

  async test(config) {
    // Probe the server and discover tools
    return { ok: true, tools: 3, toolNames: ['a', 'b', 'c'] }
  },

  async connect(config) {
    // Establish a live connection
    return {
      tools: [],
      async callTool(name, args) {
        return { content: [{ type: 'text', text: 'result' }], isError: false }
      },
      async close() {
        // Cleanup
      },
    }
  },
}

Then register it:

import { registry } from '@supaproxy/connections'
import { myPlugin } from './my-plugin.js'

registry.register(myPlugin)

Contributing

See the SupaProxy contributing guide for development workflow, code standards, and PR process.

License

MIT