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

GAIIA Expert Proxy (MCP Server)