# coral-protocol/coral-server architecture

> Architecture diagram of the GitHub repository coral-protocol/coral-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coral-protocol/coral-server
- Repository: https://github.com/coral-protocol/coral-server

## Overview

##### Main Components
- Server Core: The main entry point is the Main.kt file under the package org.coralprotocol.agentfuzzyp2ptools. This core component initializes the server, processes command-line arguments (e.g., --stdio, --sse-server), and selects the operating mode.
- Communication Interfaces: Two primary interfaces are supported:
- Standard I/O (stdio mode)
- SSE (Server Sent Events) interfaces using Ktor (or a plain configuration). Also, a client (MCP Inspector) can connect via an HTTP URL.
- Tool Modules: The project provides several “tools” in the tools directory (inside src/main/kotlin/.../tools). These include:
- Agent Management Tools (e.g., RegisterAgentTool, ListAgentsTool)
- Thread Management Tools (CreateThreadTool, AddParticipantTool, RemoveParticipantTool, CloseThreadTool)
- Messaging Tools (SendMessageTool, WaitForMentionsTool)
- Tool Management/Registry: A registry component (ThreadToolsRegistry.kt) coordinates and probably dispatches tool calls as commands are received.
- Testing: Although not part of the runtime architecture, the tests in src/test/kotlin provide additional context on how the components interact.

##### Inter-component Relationships
- The Server Core (Main.kt) acts as a dispatcher. It interprets run modes and initiates the corresponding server instance.
- Input flows into the Server (either via stdio or the SSE endpoint), where command messages trigger specific tool operations.
- The dispatched tools implement various functions such as registering agents, managing threads, and sending messages. These are likely invoked by registering with the ThreadToolsRegistry.
- Output paths include sending responses back to the agent interface (e.g., pushing SSE events to the connected MCP Inspector or writing to stdout).

##### Key Architectural Patterns and Principles
- Modularity: The separation between the core server logic, the tool registry, and individual tool implementations demonstrates the use of a modular design pattern.
- Command Pattern: Tools that encapsulate specific operations (e.g., sending a message, creating a thread) suggest that the system may leverage command invocations to execute these features.
- Mode-based Operation: The ability to run in different modes illustrates design flexibility in handling multiple integration scenarios (local stdio vs. remote SSE modes).

##### Technologies and Frameworks
- Kotlin: The primary language, with source files under src/main/kotlin.
- Gradle: Used as the build system (see build.gradle.kts, gradlew scripts).
- Ktor (implied): For the SSE server mode.
- Standard Java runtime for executing the packaged JAR.
- Additionally, Python examples in the examples directory indicate support material or client demonstration scripts that interact with the server.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Coral MCP Server (Agent Fuzzy A2A Tools)"
        subgraph "Core Layer"
            ServerCore["Server Core"]:::core
            CommunicationInterfaces["Communication Interfaces"]:::core
            StdIO["StdIO Input/Output"]:::interface
            SSE["SSE Server (via Ktor)"]:::interface
            MCPClient["MCP Inspector/Client"]:::core

            ServerCore -->|"mode_selection"| CommunicationInterfaces
            CommunicationInterfaces -->|"io_dispatch"| ServerCore
            StdIO -->|"stdio_msgs"| CommunicationInterfaces
            SSE -->|"sse_events"| CommunicationInterfaces
            MCPClient -->|"http_connect"| SSE
        end

        subgraph "Tool Management"
            ToolRegistry["Tool Registry & Dispatch"]:::registry

            subgraph "Agent Management Tools"
                RegisterAgent["RegisterAgentTool"]:::tool
                ListAgents["ListAgentsTool"]:::tool
            end

            subgraph "Thread Management Tools"
                CreateThread["CreateThreadTool"]:::tool
                AddParticipant["AddParticipantTool"]:::tool
                RemoveParticipant["RemoveParticipantTool"]:::tool
                CloseThread["CloseThreadTool"]:::tool
            end

            subgraph "Messaging Tools"
                SendMessage["SendMessageTool"]:::tool
                WaitForMentions["WaitForMentionsTool"]:::tool
            end

            ServerCore -->|"dispatch_cmds"| ToolRegistry
            ToolRegistry -->|"agent_cmd"| RegisterAgent
            ToolRegistry -->|"agent_cmd"| ListAgents
            ToolRegistry -->|"thread_cmd"| CreateThread
            ToolRegistry -->|"thread_cmd"| AddParticipant
            ToolRegistry -->|"thread_cmd"| RemoveParticipant
            ToolRegistry -->|"thread_cmd"| CloseThread
            ToolRegistry -->|"msg_cmd"| SendMessage
            ToolRegistry -->|"msg_cmd"| WaitForMentions

            RegisterAgent -->|"response"| ServerCore
            ListAgents -->|"response"| ServerCore
            CreateThread -->|"response"| ServerCore
            AddParticipant -->|"response"| ServerCore
            RemoveParticipant -->|"response"| ServerCore
            CloseThread -->|"response"| ServerCore
            SendMessage -->|"response"| ServerCore
            WaitForMentions -->|"async_update"| ServerCore
        end

        subgraph "Additional Components"
            PythonClient["Python Client Example"]:::extra
            TestSuite["Test Suite"]:::extra
            ServerCore ---|"validated_by"| TestSuite
        end
    end

    %% Click Events
    click ServerCore "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/Main.kt"
    click CommunicationInterfaces "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/ThreadInputs.kt"
    click RegisterAgent "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/RegisterAgentTool.kt"
    click ListAgents "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/ListAgentsTool.kt"
    click CreateThread "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/CreateThreadTool.kt"
    click AddParticipant "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/AddParticipantTool.kt"
    click RemoveParticipant "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/RemoveParticipantTool.kt"
    click CloseThread "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/CloseThreadTool.kt"
    click SendMessage "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/SendMessageTool.kt"
    click WaitForMentions "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/WaitForMentionsTool.kt"
    click ToolRegistry "https://github.com/coral-protocol/coral-server/blob/master/src/main/kotlin/org/coralprotocol/agentfuzzyp2ptools/tools/ThreadToolsRegistry.kt"
    click PythonClient "https://github.com/coral-protocol/coral-server/tree/master/examples/camel-search-maths"

    %% Styles
    classDef core fill:#fceabb,stroke:#e8a317,stroke-width:2px;
    classDef interface fill:#c1f7ed,stroke:#0b8274,stroke-width:2px;
    classDef registry fill:#d3bdf0,stroke:#7d3c98,stroke-width:2px;
    classDef tool fill:#d5e8d4,stroke:#82b366,stroke-width:2px;
    classDef extra fill:#f8cecc,stroke:#b85450,stroke-width:2px;
    
    class ServerCore,CommunicationInterfaces,MCPClient core;
    class StdIO,SSE interface;
    class ToolRegistry registry;
    class RegisterAgent,ListAgents,CreateThread,AddParticipant,RemoveParticipant,CloseThread,SendMessage,WaitForMentions tool;
    class PythonClient,TestSuite extra;
```
