Xeku.MCP.WebApi 0.0.0.7

Xeku.MCP.WebApi

Xeku.MCP.WebApi is the bridge between the Model Context Protocol (MCP) and XAF's Web API. It provides a specialized controller that translates MCP JSON-RPC requests into XAF business logic executions and OData operations.

Features

• MCP Bridge Controller: Exposes a standard endpoint for MCP clients to interact with XAF.
• Auto-Discovery Integration: Leverages Xeku.MCP services to expose marked Business Objects as MCP resources and tools.
• OData Proxy: Automatically forwards Create and Save actions to XAF's native OData engine for maximum compatibility and transaction support.
• Deep Association Support: Handles complex JSON payloads, mapping them recursively to XPO business objects.

Installation

dotnet add package Xeku.MCP.WebApi

Registration

In your Startup.cs (ASP.NET Core / Web API project):

public void ConfigureServices(IServiceCollection services)
{
    // ... other services
    services.AddXekuMcp(); // Registers discovery services and HttpClient
}

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    // ... other middleware
    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

AI Agent Integration

This module is designed to be consumed by AI Agents (like Claude, ChatGPT, or custom LLM-based tools) through the Model Context Protocol.

Use Cases

1. Direct Data Manipulation: Agents can create, read, and update XAF business objects using natural language commands translated into MCP tool calls.
2. Workflow Automation: Trigger custom XAF actions (marked with [McpAction]) to execute complex server-side logic.
3. Data Analysis: Broaden the context for the AI by exposing relevant Business Objects as resources.

API Integration Guide

The bridge endpoint is typically located at: POST /api/mcp/protocol

AI Agents should be configured to use this endpoint with JSON-RPC 2.0.

Architecture

The diagram below illustrates how the MCP Bridge acts as a translator between external AI requests and the XAF ecosystem.

graph TD
    subgraph "Presentation / UI"
        A["AI Agent (MCP Client)"]:::ui
    end

    subgraph "Service / Logic"
        B["MCP Bridge Controller"]:::logic
        C["Discovery Service"]:::logic
        D["OData Engine (Native XAF)"]:::logic
    end

    subgraph "Data / Entity"
        E["Business Objects (XPO)"]:::data
    end

    A -- "JSON-RPC (tools/call)" --> B
    B -- "List available BOs" --> C
    C -- "Inspect Attributes" --> E
    B -- "Create/Save Proxy" --> D
    D -- "Commit" --> E

    classDef ui fill:#e1f5ff,stroke:#01579b
    classDef logic fill:#fff4e1,stroke:#ff8f00
    classDef data fill:#e8f5e9,stroke:#2e7d32

Best Practices

• Security: Always ensure the /api/mcp route is protected by appropriate authentication (e.g., JWT, Keycloak, or ApiKey).
• Stability: Use [McpVisible] and [McpInclude] selectively to expose only necessary data to the AI context.
• Error Handling: The bridge translates XAF ValidationException into structured MCP error responses, which help agents understand and fix data entry issues.