GAIIA Expert Proxy

GAIIA Expert MCP Server is a Model Context Protocol (MCP) server that enables high-fidelity code audits, refactors, and architectural analysis using specialized Proxy Experts in conjunction with a remote LLM.

Features

• Expert Selection: List and choose from a registry of Proxy Experts with different specialties (e.g., security, performance, architecture).
• Code Transformation: Send code blocks to experts for auditing or refactoring based on their specific manifests.
• Project Analysis: Perform deep architectural audits, automated repository-wide refactors, and vector ingestions on local directories. (Note: Large audits and refactors run asynchronously in the cloud.)
• API Interrogation: Intelligently fuzz and discover schemas for unknown API endpoints using reinforcement learning.
• Workflow Execution: Trigger and list BPMN business process workflows registered in the GAIIA ecosystem.
• Authentication: Users must authenticate with their GAIIA account to access the expert registry and processing tasks.

Installation

Prerequisites

• Node.js (v20 or higher)
• npm
• An GAIIA account (sign up at https://gaiia.dev)

Steps

1. Clone or copy this directory to your machine.
2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

Authentication

Run the following command to log in and cache your authentication tokens:

npm run login

Follow the prompts to enter your credentials. This will store the session in a local ~/.gaiia/auth.json file. If you do not have credentials sign up at https://gaiia.dev.

[!CAUTION] The auth.json file stores your session tokens in plain text. Ensure this file is kept secure and never committed to version control.

Usage with MCP Clients (e.g., Claude Desktop)

Add the following to your MCP settings configuration:

{
  "mcpServers": {
    "gaiia-logic-proxy": {
      "command": "node",
      "args": ["c:/path/to/gaiia-mcp-server/build/index.js"]
    }
  }
}

Available Tools

gaiia_list_experts

Lists all available AI experts in the GAIIA registry.

• Args: query (optional string) - Search for experts by their email address, name, or specific architectural styles/keywords (e.g., 'Clean Architecture', 'Node.js', 'CQRS').

sync_specs

Synchronizes all locally fuzzed and discovered API specifications in the specs/ directory back to the cloud GAIIA Registry.

Note: The specs/ directory contains schemas auto-generated by the interrogate_endpoint tool.

• Args: None

gaiia_set_active_expert

Sets the expert to be used for subsequent code transformations.

• Args: email (required string) - The email address of the expert proxy.

gaiia_transform

Processes a single block of code with the active expert.

• Args:
  • code (required string) - The source code block to process.
  • instructions (required string) - Specific refactoring, audit, or generation instructions.

gaiia_analyze_project

Audits or refactors an entire local directory.

[!WARNING] Running this tool in refactor mode will silently overwrite your local files. Ensure your working directory is clean and fully committed to version control (e.g., Git) before proceeding.

• Args:
  • directory_path (required string) - Absolute path to the local project folder.
  • mode (optional string) - "audit" or "refactor". Default is "audit".

gaiia_ingest_project

Scans a local project directory and ingests its code samples into the active expert's memory for context retention.

• Args:
  • directory_path (required string) - Absolute path to the project directory.

interrogate_endpoint

Intelligently interrogates APIs to discover schemas and generate A2A/MCP tools via reinforcement learning fuzzing.

[!CAUTION] This tool performs active fuzzing. Do not run this against production environments unless authorized, as it may cause unintended data mutations or Denial of Service (DoS).

• Args:
  • url (required string) - The full API URL (supports http://, https://, grpc://, or tcp:// for sockets).
  • method (required string) - HTTP Method: GET, POST, PUT, PATCH, DELETE, GRAPHQL, or AUTO.
  • auth_header (optional string) - Optional authentication header (e.g., Bearer token).
  • base_payload (optional object) - Starting template payload to fuzz.
  • extra_headers (optional object) - Map of custom headers.

Supported Protocols

1. REST (JSON): Fully supported with automatic OpenAPI synthesis.
2. GraphQL: Auto-detected and introspected. Converts the GraphQL schema into standard MCP Tools.
3. XML/SOAP: Auto-fetches .xsd or .wsdl from error messages and uses them as LLM hints.
4. gRPC (Protobuf): Requires grpc:// URL. Constraint: Server must have grpc.reflection.v1alpha.ServerReflection enabled or the .proto schema must be provided. Fuzzing raw binary protobuf without field indexes is computationally impractical.
5. OData: Auto-fetches the Entity Data Model from /$metadata.
6. Bulk CSV (ERP): Handles text/csv requirements natively.
7. EDI (ANSI X12): Handles raw text application/edi-x12 by iteratively guessing missing segments (e.g. ISA, GS, ST) from clear-text errors.
8. JSON-RPC / XML-RPC: Iteratively builds valid RPC envelopes and dynamically extracts the inner method for specific tool naming.
9. ISO 8583 (TCP Sockets): Requires tcp:// URL. Bypasses HTTP entirely to establish raw socket connections for payment gateway fuzzing.

gaiia_list_processes

List all registered BPMN process blueprints/templates in the GAIIA registry for the authenticated workspace.

• Args: None

gaiia_start_process

Starts/triggers an active execution instance of a registered BPMN process blueprint in the cloud with an initial business payload context.

• Args:
  • process_type (required string) - The unique processType/slug of the BPMN template (e.g. employee-onboarding or pax-terminal-procurement).
  • payload (optional object) - Initial custom JSON payload context for the process run.

Testing

Currently, this repository does not include an automated test suite. Contributors should manually verify changes using an MCP client (e.g., Claude Desktop) before submitting pull requests.

License

MIT