GAIIA Unified MCP Server (v2.0.0)

The GAIIA Unified MCP Server is an enterprise-grade Model Context Protocol (MCP) server that connects AI coding assistants and autonomous agents to the GAIIA ecosystem. It enables expert-guided code audits, project transformations, BPMN process triggering, and multi-protocol API interrogation.

🌟 Capabilities & Features

  • Expert Selection & Manifest Routing: Browse and select from a registry of Proxy Experts (e.g. Clean Architecture, Security, Performance, Transit domain).
  • Code Transformation & Auditing: Transform individual code blocks or conduct repository-wide audits against immutable architectural standards.
  • Multi-Protocol API Interrogation: Fuzz and discover schemas across diverse protocols:
    • REST (JSON): OpenAPI v3 synthesis.
    • GraphQL: Schema introspection and automatic tool generation.
    • gRPC (Protobuf): Server reflection inspection (src/mock/mock-grpc-server.ts).
    • ISO 8583 (TCP Sockets): Raw socket communication for payment gateways (src/mock/mock-tcp-server.ts).
    • XML / SOAP: Automatic .xsd and .wsdl parsing.
    • EDI (ANSI X12): Segment repair for legacy enterprise supply chain formats.
    • OData & ERP: Enterprise metadata resolution (src/mock/mock-erp-server.ts).
  • BPMS Process Orchestration: List BPMN blueprints and trigger workflow executions in gaiia-process-management.
  • Telemetry & Context Retention: In-memory context tracking and telemetry logging via src/services/telemetry-service.ts.

⚙️ Installation & Build

Prerequisites

  • Node.js: v20+ LTS
  • npm: v9+
  • A registered GAIIA account for cloud registry sync

Setup

# 1. Navigate to directory
cd gaiia-mcp-server

# 2. Install dependencies
npm install

# 3. Build TypeScript
npm run build

🔐 Authentication

Authenticate with the GAIIA platform to cache session tokens locally:

npm run login

Tokens are cached securely at ~/.gaiia/auth.json.

🔧 Environment Configuration (.env)

GAIIA_GRAPHQL_ENDPOINT=https://<api-id>.appsync-api.ap-southeast-2.amazonaws.com/graphql
AWS_REGION=ap-southeast-2
USER_POOL_ID=ap-southeast-2_xxxxxxxxx
APP_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx

🔌 MCP Client Configuration (e.g., Claude Desktop)

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "gaiia-unified-mcp": {
      "command": "node",
      "args": ["c:/programming/aiia/gaiia-mcp-server/build/index.js"]
    }
  }
}

🛠️ Available MCP Tools Reference

Tool Name Purpose Key Arguments
gaiia_list_experts Lists all available AI experts in the registry query (optional string: name, email, or architecture keywords)
gaiia_set_active_expert Sets the active expert for transformations email (required string)
gaiia_transform Audits, refactors, or generates code with the active expert code (string), instructions (string)
gaiia_analyze_project Performs deep architectural audit or automated refactor on a directory directory_path (string), mode ("audit" | "refactor")
gaiia_ingest_project Ingests directory code samples into active expert memory directory_path (string)
interrogate_endpoint Multi-protocol API fuzzing and schema synthesis url (string), method (string), auth_header (optional), base_payload (optional)
sync_specs Synchronizes locally discovered schemas in specs/ to cloud registry None
gaiia_list_processes Lists registered BPMN templates in the workspace None
gaiia_start_process Triggers a BPMN workflow run with initial context process_type (string), payload (optional object)

🧪 Local Testing & Multi-Protocol Mock Servers

The server includes standalone mock servers in src/mock/ for testing complex protocols without external dependencies:

# Start mock gRPC server
npx tsx src/mock/mock-grpc-server.ts

# Start mock ISO 8583 TCP socket server
npx tsx src/mock/mock-tcp-server.ts

# Start mock ERP / OData server
npx tsx src/mock/mock-erp-server.ts

📄 License

MIT © 2026 GAIIA Engineering