Skip to content

README.md

Latest commit

 

History

History
283 lines (228 loc) · 11.7 KB

README.md

File metadata and controls

283 lines (228 loc) · 11.7 KB

Spawn

Application for building AI capable applications on the fly with UI, models and mcp servers.

Overview

Spawn is a Spring Boot application that enables you to configure, build, and deploy new AI applications built on the Spring Boot / Spring AI framework. The application provides a web-based UI with server-side rendered HTML pages to manage applications, AI models, and MCP (Model Context Protocol) servers.

Main Workflow

  1. Browse available models - View the list of AI models loaded from CSV (e.g., OpenAI, Anthropic Claude, Azure OpenAI)
  2. Browse available MCP servers - View the list of MCP servers loaded from CSV (e.g., GitHub, Notion, Stripe)
  3. Create a new application with a name and select a model provider
  4. Add MCP servers to your application from the available list
  5. Build and deploy a new application based on the configuration

Technology Stack

  • Java 17
  • Spring Boot 3.2.0
  • Spring Data JPA
  • H2 Database (in-memory)
  • J2HTML 1.6.0 (server-side HTML rendering)
  • Maven

Getting Started

Prerequisites

  • Java 17 or higher
  • Maven 3.6 or higher

Build and Run

  1. Clone the repository

  2. Build the application:

    mvn clean install

  3. Run the application:

    mvn spring-boot:run

The application will start on http://localhost:8080

H2 Console

Access the H2 database console at: http://localhost:8080/h2-console

  • JDBC URL: jdbc:h2:mem:spawndb
  • Username: sa
  • Password: (empty)

Web UI

The application provides a web-based user interface with the following pages:

Models (/models)

  • Read-only list of AI model providers loaded from src/main/resources/models/models.csv
  • Displays model capabilities: multimodality, tools/functions, streaming, retry, observability, etc.
  • No create, edit, or delete operations - models are configuration-only

MCP Servers (/mcp-servers)

  • Read-only list of MCP servers loaded from src/main/resources/mcp/mcp_servers.csv
  • Displays server icons and descriptions
  • Includes 48+ servers from the GitHub MCP registry (GitHub, Notion, Stripe, etc.)
  • No create, edit, or delete operations - servers are configuration-only
  • View configuration templates for MCP servers that have templates available

MCP Templates

MCP server configuration templates are JSON files stored in src/main/resources/mcp/templates/. Templates provide pre-configured server definitions with input placeholders that can be customized for deployment. The template system supports multiple naming strategies for matching templates to servers:

  1. Exact match: Template filename matches the server name exactly (e.g., GitHub.json for "GitHub" server)
  2. Case-insensitive match: Template is found regardless of case differences
  3. Normalized match: Spaces and special characters are normalized to hyphens (e.g., azure-mcp-server.json matches "Azure MCP Server")

Templates include:

  • Server configuration with placeholders using ${input:id} syntax
  • Input definitions specifying required configuration values, types, and defaults
  • Preview capability showing templates with placeholders replaced (password fields masked with *****)

Access templates via the "View Template" button on the MCP Servers list page for servers with available templates.

Applications (/applications)

  • Full CRUD operations for AI applications
  • Create applications with a name and model provider
  • View, edit, and delete applications
  • Add/remove MCP servers from applications
  • Each application stores:
    • Name
    • Model provider (reference to CSV)
    • Set of MCP server names (references to CSV)
    • Creation timestamp

Agents (/agents)

  • New domain: Agents represent tailored expertise for specific tasks.
  • Each Agent stores:
    • name (required)
    • description (optional)
    • systemPrompt (long text, stored as CLOB)
    • createdAt timestamp
    • A per-agent persisted list of MCP server names (free-form strings) stored in agent_mcp_servers table
  • Endpoints (server-rendered HTML):
    • GET /agents — List all agents
    • GET /agents/new — Show creation form (dropdown of known MCP servers + "Other" free-form add)
    • POST /agents — Create agent (redirect on success)
    • GET /agents/{id} — Detail page showing full system prompt and attached MCP names (unknown names highlighted with a warning badge)
    • GET /agents/{id}/edit — Edit form (pre-filled)
    • POST /agents/{id} — Update agent
    • POST /agents/{id}/delete — Delete agent
    • POST /agents/{id}/mcp-servers/add — Attach an MCP name to an agent
    • POST /agents/{id}/mcp-servers/{mcpName}/remove — Remove an MCP name from an agent
  • MCP servers list used for dropdown is loaded from CSV (read-only). Agents accept free-form MCP names; UI highlights names that don't match any known MCP server.

Data Architecture

CSV-Based Configuration (Read-Only)

Models and MCP Servers are loaded from CSV files at application startup:

  • Models CSV (src/main/resources/models/models.csv):

    • Columns: Provider, Multimodality, Tools/Functions, Streaming, Retry, Observability, Built-in JSON, Local, OpenAI API Compatible
    • Example: OpenAI,"In: text, image, audio Out: text, audio",yes,yes,yes,yes,yes,no,yes

  • MCP Servers CSV (src/main/resources/mcp/mcp_servers.csv):

    • Columns: Name, Icon, Description
    • Example: GitHub,https://avatars.githubusercontent.com/u/9919?v=4,"Official GitHub MCP Server..."

Database Entities (CRUD)

Applications are stored in the H2 database:

  • Application name
  • Model provider name (validated against CSV)
  • Collection of MCP server names (validated against CSV)
  • Creation timestamp

Agents are stored in the H2 database:

  • Agent name
  • Description
  • System prompt
  • Creation timestamp
  • Collection of MCP server names (free-form, validated against CSV)

Example Workflow

Using the web UI:

  1. View Available Models

    • Navigate to http://localhost:8080/models
    • Browse the list of available AI model providers

  2. View Available MCP Servers

    • Navigate to http://localhost:8080/mcp-servers
    • Browse the list of available MCP servers with descriptions

  3. Create an Application

    • Navigate to http://localhost:8080/applications
    • Click "Create New Application"
    • Enter application name: "My AI Assistant"
    • Select model provider: "OpenAI"
    • Click "Save"

  4. Add MCP Servers

    • Click "View" on your application
    • Select an MCP server from the dropdown (e.g., "GitHub")
    • Click "Add Server"
    • Repeat to add more servers

  5. View Application Configuration

    • The application detail page shows:
      • Application details (ID, name, model provider, created date)
      • Associated MCP servers with icons and descriptions
      • Option to add/remove servers

  6. Create an Agent

    • Navigate to http://localhost:8080/agents
    • Click "Create New Agent"
    • Enter agent name: "Code Reviewer"
    • Optionally, enter a description
    • Enter the system prompt
    • Select MCP servers from the dropdown
    • Click "Save"

  7. View Agent Details

    • Click "View" on your agent
    • See the full system prompt and attached MCP servers
    • Option to edit or delete the agent

Testing

Run the tests:

mvn test

The test suite includes:

  • Controller integration tests for all domains
  • Service tests for CSV loading
  • End-to-end workflow test demonstrating the full application lifecycle
  • All tests use MockMvc for controller testing

Project Structure

src/
├── main/
│   ├── java/dev/rebelcraft/ai/spawn/
│   │   ├── SpawnApplication.java          # Main application class
│   │   ├── apps/                          # Applications domain
│   │   │   ├── Application.java           # JPA entity
│   │   │   ├── ApplicationController.java # Web controller
│   │   │   ├── ApplicationService.java    # Business logic
│   │   │   ├── ApplicationRepository.java # Spring Data repository
│   │   │   ├── ApplicationRequest.java    # DTO
│   │   │   ├── ApplicationResponse.java   # DTO
│   │   │   ├── ApplicationFormPage.java   # J2HTML view
│   │   │   ├── ApplicationDetailPage.java # J2HTML view
│   │   │   └── ApplicationsListPage.java  # J2HTML view
│   │   ├── models/                        # Models domain (read-only CSV)
│   │   │   ├── Model.java                 # Plain POJO
│   │   │   ├── ModelController.java       # Web controller
│   │   │   ├── ModelService.java          # CSV loader
│   │   │   ├── ModelResponse.java         # DTO
│   │   │   └── ModelsListPage.java        # J2HTML view
│   │   ├── mcp/                           # MCP Servers domain (read-only CSV)
│   │   │   ├── McpServer.java             # Plain POJO
│   │   │   ├── McpServerController.java   # Web controller
│   │   │   ├── McpServerService.java      # CSV loader
│   │   │   ├── McpServerResponse.java     # DTO
│   │   │   ├── McpServersListPage.java    # J2HTML view
│   │   │   ├── McpTemplate.java           # Template POJO
│   │   │   ├── McpTemplateService.java    # Template loader
│   │   │   ├── McpTemplateController.java # Template controller
│   │   │   └── McpServerTemplatePage.java # J2HTML view
│   │   ├── agents/                        # Agents domain
│   │   │   ├── Agent.java                 # JPA entity
│   │   │   ├── AgentController.java       # Web controller
│   │   │   ├── AgentService.java          # Business logic
│   │   │   ├── AgentRepository.java       # Spring Data repository
│   │   │   ├── AgentRequest.java          # DTO
│   │   │   ├── AgentResponse.java         # DTO
│   │   │   ├── AgentFormPage.java         # J2HTML view
│   │   │   ├── AgentDetailPage.java       # J2HTML view
│   │   │   └── AgentsListPage.java        # J2HTML view
│   │   ├── web/                           # Cross-cutting web concerns
│   │   │   ├── IndexController.java       # Home page
│   │   │   └── view/                      # Shared view components
│   │   ├── utils/                         # Utilities
│   │   │   └── ResourceNotFoundException.java
│   │   └── config/                        # Configuration
│   └── resources/
│       ├── application.properties         # Application configuration
│       ├── models/
│       │   └── models.csv                 # AI model providers
│       └── mcp/
│           ├── mcp_servers.csv            # MCP servers
│           └── templates/                 # MCP configuration templates
│               ├── GitHub.json            # GitHub MCP template
│               └── azure-mcp-server.json  # Azure MCP template
└── test/
    └── java/dev/rebelcraft/ai/spawn/      # Test classes

Database Schema

The application uses an in-memory H2 database with the following schema:

  • applications: Stores AI application configurations
    • id, name, model_provider, created_at
  • application_mcp_servers: Stores MCP server names for each application
    • application_id, mcp_server_name
  • agents: Stores agent configurations
    • id, name, description, system_prompt, created_at
  • agent_mcp_servers: Stores MCP server names for each agent
    • agent_id, mcp_server_name

Note: Models and MCP servers are NOT stored in the database. They are loaded from CSV files at startup.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.