svrnty-mcp-gateway/AGENT-PRIMER.md

# AGENT-PRIMER: OpenHarbor.MCP.Gateway Automated Setup

**Purpose**: Guide AI agents to automatically analyze a target system and configure OpenHarbor.MCP.Gateway integration.

**Target Audience**: AI assistants (Claude, ChatGPT, etc.) helping developers set up MCP gateway/proxy infrastructure.

---

## Overview

OpenHarbor.MCP.Gateway is a **standalone .NET library** that provides proxy and routing infrastructure for MCP traffic, enabling centralized management between MCP clients and servers.

**What you'll automate:**
1. System analysis (detect .NET version, network requirements)
2. Configuration generation (appsettings.json, routing rules, Program.cs)
3. Sample routing strategies based on deployment scenario
4. Environment setup and validation

---

## Step 1: System Analysis

### Tasks for AI Agent:

#### 1.1 Detect .NET Environment
```bash
dotnet --version  # Required: .NET 8.0+
dotnet --list-sdks
```

#### 1.2 Analyze Deployment Scenario

Ask user to identify scenario:
- **Scenario A**: Single gateway routing to multiple backend servers
- **Scenario B**: Load balancing across server instances
- **Scenario C**: A/B testing different server versions
- **Scenario D**: Multi-tenant routing based on client identity

#### 1.3 Identify Backend Servers

```bash
# Detect existing MCP servers
find . -name "*McpServer*" -type d
```

**Output**: JSON summary
```json
{
  "dotnetVersion": "8.0.100",
  "scenario": "LoadBalancing",
  "backendServers": [
    {
      "name": "codex-server-1",
      "transport": "Stdio",
      "path": "/path/to/server1"
    },
    {
      "name": "codex-server-2",
      "transport": "Http",
      "url": "https://api.example.com/mcp"
    }
  ]
}
```

---

## Step 2: Generate Configuration

### 2.1 appsettings.json Configuration

```json
{
  "Mcp": {
    "Gateway": {
      "Name": "MyMcpGateway",
      "Version": "1.0.0",
      "ListenAddress": "http://localhost:8080"
    },
    "Servers": [
      {
        "Id": "server-1",
        "Name": "Primary Server",
        "Transport": {
          "Type": "Http",
          "Command": "dotnet",
          "Args": ["run", "--project", "/path/to/server"]
        },
        "Enabled": true
      }
    ],
    "Routing": {
      "Strategy": "RoundRobin",
      "HealthCheckInterval": "00:00:30"
    },
    "Security": {
      "EnableAuthentication": false,
      "RateLimit": {
        "RequestsPerMinute": 100
      }
    }
  }
}
```

### 2.2 Program.cs Integration

```csharp
using OpenHarbor.MCP.Gateway.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddMcpGateway(builder.Configuration.GetSection("Mcp"));

var app = builder.Build();

app.MapMcpGateway();
app.MapHealthChecks("/health");

app.Run();
```

---

## Step 3: Generate Routing Strategy

### 3.1 Round-Robin Load Balancing

```csharp
public class RoundRobinRouter : IRoutingStrategy
{
    private int _index = 0;

    public string SelectServer(
        RoutingContext context,
        IEnumerable<ServerInfo> servers)
    {
        var list = servers.Where(s => s.IsHealthy).ToList();
        var index = Interlocked.Increment(ref _index) % list.Count;
        return list[index].Id;
    }
}
```

### 3.2 Tool-Based Routing

```csharp
public class ToolBasedRouter : IRoutingStrategy
{
    public string SelectServer(
        RoutingContext context,
        IEnumerable<ServerInfo> servers)
    {
        return context.ToolName switch
        {
            var t when t.StartsWith("search_") => "search-server",
            var t when t.StartsWith("db_") => "database-server",
            _ => servers.First().Id
        };
    }
}
```

---

## Step 4: Validation

```bash
# Build gateway
dotnet build

# Run tests
dotnet test

# Start gateway
dotnet run

# Check health
curl http://localhost:8080/health
```

---

## Step 5: AI Agent Workflow

1. **Analyze** → Detect scenario and backend servers
2. **Confirm** → Show configuration, ask approval
3. **Generate** → Create files from Steps 2-3
4. **Validate** → Run Step 4 tests
5. **Report** → "Gateway configured. Ready to route MCP traffic."

---

**Document Version**: 1.0.0
**Last Updated**: 2025-10-19
**Target**: OpenHarbor.MCP.Gateway