LemonadeStand

A lightweight .NET 10 dispatching facade providing a thin OpenAI-compatible API gateway. It utilizes Microsoft.Extensions.AI (v10+) to orchestrate "Named Agents" that dynamically resolve system instructions and enrich with tools from MCP (Model Context Protocol) servers.

Requirements

• .NET 10 SDK or later
• OpenAI API Key (or any OpenAI-compatible endpoint)

Quick Start

1. Build and Run

dotnet build
dotnet run

The server will start on https://localhost:5001 and http://localhost:5000.

2. Configure Environment Variables

Create an appsettings.json file or set environment variables for the OpenAI API key:

Using appsettings.json:

{
  "OpenAI": {
    "ApiKey": "your-api-key-here"
  }
}

Using Environment Variables (PowerShell):

$env:OpenAI__ApiKey = "your-api-key-here"

Using Environment Variables (Command Line):

export OpenAI__ApiKey="your-api-key-here"

3. Configure Agent Profiles

Agent profiles are configured via appsettings.json and automatically registered at startup. No code changes are required to add new agents!

Example appsettings.json:

{
  "AgentProfiles": {
    "Profiles": [
      {
        "Id": "helpful-assistant",
        "SystemPrompt": "You are a helpful and knowledgeable assistant.",
        "McpServers": []
      },
      {
        "Id": "dungeon-master",
        "SystemPrompt": "You are a dungeon master with access to a rich world of fantasy settings.",
        "McpServers": [
          {
            "Name": "dmtools",
            "Url": "http://localhost:8089"
          }
        ]
      }
    ]
  }
}

To add a new agent:

1. Edit appsettings.json and add a new entry to the Profiles array
2. Restart the application
3. The agent will be automatically registered and available

Configuration Options:

• Id: Unique identifier for the agent (used in the model field of API requests)
• SystemPrompt: System instructions for the agent
• McpServers: Array of MCP server configurations (optional)
  • Name: Server identifier
  • Url: HTTP endpoint URL for the MCP server

Configuration Options

OpenAI Endpoint

The proxy uses OpenAI's gpt-4o model by default. To customize:

Using appsettings.json:

{
  "OpenAI": {
    "Endpoint": "https://your-endpoint.openai.azure.com/",
    "ApiKey": "your-api-key"
  }
}

Using Environment Variables (PowerShell):

$env:OpenAI__ApiKey = "your-api-key"
# For Azure OpenAI, also set:
$env:OpenAI__Endpoint = "https://your-resource.openai.azure.com/"

Custom Models and Endpoints (No Code Changes Required):

To use a different model or custom endpoint (including Azure OpenAI or local servers):

Using appsettings.json:

{
  "OpenAI": {
    "ApiKey": "your-api-key",
    "Endpoint": "https://your-custom-endpoint.com/v1",
    "Model": "gpt-4o-mini"
  }
}

Using Environment Variables (PowerShell):

$env:OpenAI__ApiKey = "your-api-key"
$env:OpenAI__Endpoint = "https://your-custom-endpoint.com/v1"
$env:OpenAI__Model = "gpt-4o-mini"

Examples:

• Standard OpenAI: Leave Endpoint empty, set Model to gpt-4o or gpt-4o-mini
• Azure OpenAI: Set Endpoint to your Azure endpoint URL, set Model to your deployment name
• Local Server: Set Endpoint to http://localhost:1234/v1, set Model to your local model name

API Endpoints

Chat Completions

POST /v1/chat/completions
Content-Type: application/json

{
  "model": "my-agent",
  "messages": [
    { "role": "user", "content": "Hello!" }
  ]
}

Response format follows the OpenAI API specification.

Project Structure

LemonadeStand/
├── Extensions/
│   └── OpenAIChatCompletionExtensions.cs  # OpenAI endpoint mapping
├── Models/
│   ├── AgentProfile.cs           # Agent configuration
│   ├── AgentConfigOptions.cs     # Agent configuration model
│   └── OpenAIConfigOptions.cs    # OpenAI settings
├── Services/
│   ├── AgentRegistry.cs          # Agent profile registry
│   ├── AgentRoutingChatClient.cs # Agent routing logic
│   └── McpDiscoveryService.cs    # MCP tool discovery & management
├── Program.cs                    # Application entry point
└── LemonadeStand.csproj          # Project configuration

Adding New Agents

Simply add a new agent configuration to the AgentProfiles.Profiles array in appsettings.json:

{
  "AgentProfiles": {
    "Profiles": [
      // ... existing agents ...
      {
        "Id": "your-new-agent",
        "SystemPrompt": "Your system instructions here",
        "McpServers": [ /* ... */ ]
      }
    ]
  }
}

Then restart the application. All agents are automatically discovered and registered at startup.

The model field in your OpenAI request must match the agent's Id.

Troubleshooting

MCP Server Connection Issues

• Ensure the MCP server command is available in your PATH
• Check that all required arguments are provided
• Verify SSE endpoints are accessible

OpenAI API Errors

• Validate your API key is correct
• Check network connectivity to OpenAI endpoints
• Review rate limits and quotas

Build Errors

• Ensure you have .NET 10 SDK installed: dotnet --version
• Restore packages: dotnet restore
• Clean and rebuild: dotnet clean && dotnet build

Attribution

AI-Generated Code and Documentation

All code and documentation in this project was written by artificial intelligence under human direction and supervision.

AI Tools Used:

• GitHub Copilot - Code completion and suggestions
• Roo Code - Development assistance
• Qwen3.5-35B-A3B - Code generation and analysis
• Qwen3.5-122B-A10B - Advanced code generation and architectural guidance

Human Oversight: Human direction, architecture decisions, code review, and final approval will be provided by human developers. All AI-generated content is being reviewed and validated for correctness, security, and maintainability.

---

License

MIT License - see LICENSE file for details.