@alsania-io/gateway

Node.js MCP Bridge for connecting to AlsaniaMCP core services.

🌐 Overview

The @alsania-io/gateway package provides a Node.js bridge for connecting to AlsaniaMCP core services. It implements the MCP (Model Context Protocol) client functionality, allowing Node.js applications to interact with MCP servers through the AlsaniaMCP gateway.

🚀 Features

• ✅ MCP Protocol Support - Full MCP client implementation with A2A (Agent-to-Agent) communication
• ✅ AlsaniaMCP Integration - Connect to AlsaniaMCP core running on port 8050
• ✅ Tool Execution - Call MCP tools with automatic fallback mechanisms
• ✅ Resource Management - Access MCP resources and prompts
• ✅ TypeScript Support - Full TypeScript definitions included
• ✅ Error Handling - Comprehensive error handling and timeout management

🚀 Features

• ✅ Universal Proxy Server - Proxy any HTTP API with full request/response forwarding
• ✅ MCP Server Integration - Route requests to multiple configured MCP servers
• ✅ JSON Configuration - Easily add/manage MCP servers via config/mcp_servers.json
• ✅ Auto MCP Management - Supervisor automatically starts/stops MCP servers
• ✅ OpenAPI Schema - Fully compliant OpenAPI 3.1.0 for GPT actions
• ✅ Production Ready - Live deployment with Cloudflare tunnel and SSL
• ✅ Security First - URL validation, timeout handling, and error management

📦 Installation

npm install @alsania-io/gateway

Prerequisites

• Node.js 18+
• Running AlsaniaMCP core service on port 8050 (default)
• axios dependency (automatically installed)

🚀 Quick Start

import { alsaniaBridge } from '@alsania-io/gateway';

// Ensure connection to MCP core
await alsaniaBridge.ensureConnected();

// List available tools
const tools = await alsaniaBridge.getTools();
console.log('Available tools:', tools);

// Call a tool
const result = await alsaniaBridge.callTool('example_tool', { param: 'value' });
console.log('Tool result:', result);

TypeScript Usage

import { AlsaniaMCPBridge } from '@alsania-io/gateway';

const bridge = new AlsaniaMCPBridge();

// Customize connection URL if needed
bridge.alsaniamcpBaseUrl = 'http://localhost:8050'; // default

await bridge.ensureConnected();

📖 API Reference

AlsaniaMCPBridge Class

The main bridge class for MCP communication.

Constructor

const bridge = new AlsaniaMCPBridge();

Properties

• alsaniamcpBaseUrl: string - MCP core URL (default: "http://localhost:8050")
• isConnected: boolean - Connection status
• a2aPeerId: string - Unique peer identifier

Methods

ensureConnected(): Promise<void>

Establishes connection to MCP core and registers as A2A peer.

callTool(toolName: string, args: any): Promise<any>

Calls an MCP tool with the given arguments. Automatically falls back from A2A to HTTP if needed.

Parameters:

• toolName: Name of the tool to call
• args: Arguments object for the tool

Returns: Tool execution result

getTools(): Promise<any[]>

Retrieves list of available MCP tools.

Returns: Array of tool definitions

registerAsPeer(): Promise<void>

Registers the bridge as an A2A peer with the MCP core.

handleA2AResponse(response: any): void

Handles incoming A2A responses (used internally).

Exported Instances

alsaniaBridge: AlsaniaMCPBridge

Pre-configured singleton instance ready for immediate use.

import { alsaniaBridge } from '@alsania-io/gateway';

await alsaniaBridge.ensureConnected();
// Ready to use

🔧 Configuration

Environment Variables

# Override MCP core URL
export ALSANIAMCP_URL=http://localhost:8050

# Override peer ID
export A2A_PEER_ID=my-custom-peer

Custom Configuration

import { AlsaniaMCPBridge } from '@alsania-io/gateway';

const bridge = new AlsaniaMCPBridge();

// Configure custom MCP core URL
bridge.alsaniamcpBaseUrl = 'https://my-mcp-core.com';

// Configure custom peer ID
bridge.a2aPeerId = 'my-app-peer';

await bridge.ensureConnected();

🔄 A2A Communication

The bridge implements Agent-to-Agent (A2A) communication protocol for efficient MCP interactions:

• Primary: A2A messaging with correlation IDs and TTL
• Fallback: Direct HTTP calls to MCP endpoints
• Timeout: 25 seconds for A2A requests, 30 seconds for HTTP
• Peer Registration: Automatic registration as "gateway-bridge" peer

🌐 Connection Requirements

MCP Core Service

The bridge requires a running AlsaniaMCP core service:

# Start MCP core (separate service)
npx @alsania-io/mcp server start -p 8050

Connection URLs

| Environment | URL | Notes | | --------------- | ------------------------ | ---------------------------------- | | Local Dev | http://localhost:8050 | Default development setup | | Production | https://mcp-core.com | HTTPS recommended for production | | Docker | http://mcp-core:8050 | Container networking |

Peer Registration

The bridge automatically registers as an A2A peer with these capabilities:

• execute_tool - Execute MCP tools
• list_tools - List available tools
• list_resources - Access MCP resources

🤝 Integration Examples

Express.js Application

const express = require('express');
const { alsaniaBridge } = require('@alsania-io/gateway');

const app = express();
app.use(express.json());

app.post('/api/tool', async (req, res) => {
  try {
    await alsaniaBridge.ensureConnected();
    const result = await alsaniaBridge.callTool(req.body.toolName, req.body.args);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => console.log('Server running on port 3000'));

React Component

import React, { useState, useEffect } from 'react';
import { alsaniaBridge } from '@alsania-io/gateway';

function ToolCaller() {
  const [tools, setTools] = useState([]);
  const [result, setResult] = useState(null);

  useEffect(() => {
    const loadTools = async () => {
      try {
        await alsaniaBridge.ensureConnected();
        const toolList = await alsaniaBridge.getTools();
        setTools(toolList);
      } catch (error) {
        console.error('Failed to load tools:', error);
      }
    };
    loadTools();
  }, []);

  const callTool = async (toolName, args) => {
    const response = await alsaniaBridge.callTool(toolName, args);
    setResult(response);
  };

  return (
    <div>
      {/* Your component JSX */}
    </div>
  );
}

📝 Testing

# Install dependencies
npm install

# Run your application tests
npm test

# Test MCP connection
node -e "
const { alsaniaBridge } = require('@alsania-io/gateway');
alsaniaBridge.ensureConnected().then(() => {
  console.log('✅ Connected to MCP core');
  return alsaniaBridge.getTools();
}).then(tools => {
  console.log('Available tools:', tools.length);
}).catch(console.error);
"

🔒 Security

• Connection Validation - Verifies MCP core availability before operations
• Timeout Protection - A2A requests timeout at 25s, HTTP at 30s
• Error Sanitization - Sensitive data not exposed in error messages
• Peer Authentication - A2A peer registration with unique identifiers

📊 Error Handling

The bridge implements comprehensive error handling:

• Connection Failures - Automatic retry with fallback mechanisms
• A2A Timeouts - Graceful degradation to HTTP transport
• Tool Errors - Detailed error reporting with correlation IDs
• Network Issues - Robust axios configuration with retries

🪪 License

Licensed under MIT License.

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

• Use TypeScript for new code
• Add comprehensive error handling
• Include JSDoc comments for public APIs
• Test your changes thoroughly
• Follow existing code style and patterns

📞 Support

Built for the Alsania Echo-Sys by Sigma and Echo.

For issues and questions:

• Check MCP core is running on port 8050
• Verify network connectivity to MCP endpoints
• Review error messages for specific failure modes

Aligned with the Alsania AI Protocol v1.0

Imagined by Sigma. Powered by Echo.