README.md

metadata

title: Coral Server
emoji: 😻
colorFrom: green
colorTo: yellow
sdk: docker
app_port: 5555
pinned: false

---
title: Coral Protocol MCP Server
emoji: 🪸
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
license: apache-2.0
tags:
  - mcp
  - multi-agent
  - coral-protocol
  - ai-agents
---

# 🪸 Coral Protocol MCP Server

This Space hosts a **Coral Protocol MCP (Model Context Protocol) Server** that enables multi-agent communication and coordination.

## 🚀 Features

- **MCP-compliant server** with SSE (Server-Sent Events) transport
- **Multi-agent communication** through thread-based messaging
- **RESTful API** for agent management
- **Real-time event streaming** for agent interactions
- **Production-ready** nginx reverse proxy setup

## 📡 Endpoints

### Status Check
- **GET** `/` - Server status page
- **GET** `/health` - Health check endpoint

### MCP SSE Endpoint
- **GET** `/devmode/exampleApplication/privkey/session1/sse` - Main SSE endpoint for MCP communication

### API Endpoints
- **POST** `/api/agents` - Register new agent
- **GET** `/api/agents` - List all agents
- **POST** `/api/threads` - Create new thread
- **POST** `/api/messages` - Send message

## 🔧 Technical Details

- **Framework**: Coral Server (Kotlin/Gradle)
- **Transport**: Server-Sent Events (SSE)
- **Proxy**: Nginx reverse proxy
- **Port**: 7860 (proxied from internal port 5555)

## 📚 Documentation

For detailed documentation, visit:
- [Coral Protocol Documentation](https://docs.coralprotocol.org)
- [Quickstart Guide](https://docs.coralprotocol.org/setup/quickstart)
- [Server Applications](https://docs.coralprotocol.org/setup/coral-server-applications)

## 🤝 Integration

### Using with MCP Clients

```python
import requests
import sseclient

# Connect to SSE endpoint
url = "https://[your-space-name].hf.space/devmode/exampleApplication/privkey/session1/sse"
response = requests.get(url, stream=True)
client = sseclient.SSEClient(response)

# Listen for events
for event in client.events():
    print(f"Event: {event.event}")
    print(f"Data: {event.data}")

Using with Coral SDK

const CoralClient = require('@coral-protocol/sdk');

const client = new CoralClient({
  serverUrl: 'https://[your-space-name].hf.space',
  transport: 'sse'
});

await client.connect();

🌟 About Coral Protocol

Coral Protocol is an open and decentralized infrastructure designed to enable:

• Communication between AI agents
• Coordination of multi-agent tasks
• Trust mechanisms for agent interactions
• Payments for agent services

📝 License

This project is licensed under the Apache License 2.0.

🔗 Links

• GitHub Repository
• Coral Protocol Website
• Discord Community

💡 Status

Current Status: 🟢 Active

Last Updated: 2024

## 3. **.gitignore** (Optional but recommended)

```gitignore
# Gradle
.gradle/
build/
!gradle/wrapper/gradle-wrapper.jar
!**/src/main/**/build/
!**/src/test/**/build/

# IDE
.idea/
*.iml
*.ipr
*.iws
.vscode/
*.swp
*.swo

# OS
.DS_Store
Thumbs.db

# Logs
logs/
*.log

# Temporary files
tmp/
temp/
*.tmp

# Environment variables
.env
.env.local

# Node (if using any JS tools)
node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# Python (if using any Python tools)
__pycache__/
*.py[cod]
*$py.class
.Python
venv/
ENV/

# Hugging Face
.huggingface/

4. docker-compose.yml (Optional - for local testing)

version: '3.8'

services:
  coral-server:
    build: .
    ports:
      - "7860:7860"
    environment:
      - CONFIG_PATH=/app/coral-config/
      - GRADLE_USER_HOME=/home/user/.gradle
    volumes:
      - ./coral-config:/app/coral-config
      - gradle-cache:/home/user/.gradle
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:7860/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

volumes:
  gradle-cache:

5. test.sh (Optional - Test script)

#!/bin/bash

# Test script for Coral Server endpoints
SERVER_URL="${1:-http://localhost:7860}"

echo "🪸 Testing Coral Server at: $SERVER_URL"
echo "================================"

# Test 1: Health check
echo -n "Testing health endpoint... "
if curl -s -f "$SERVER_URL/health" > /dev/null; then
    echo "✅ OK"
else
    echo "❌ FAILED"
fi

# Test 2: Root endpoint
echo -n "Testing root endpoint... "
if curl -s "$SERVER_URL/" | grep -q "Coral Server"; then
    echo "✅ OK"
else
    echo "❌ FAILED"
fi

# Test 3: SSE endpoint (just check if it connects)
echo -n "Testing SSE endpoint... "
if curl -s -N --max-time 2 "$SERVER_URL/devmode/exampleApplication/privkey/session1/sse" 2>/dev/null; then
    echo "✅ OK (Connected)"
else
    echo "⚠️  Timeout (Expected for SSE)"
fi

echo "================================"
echo "Test complete!"

Deployment Instructions:

1. Create a new Space on Hugging Face:

   • Go to https://huggingface.co/spaces
   • Click "Create new Space"
   • Choose "Docker" as the SDK
   • Set visibility (public/private)

2. Upload the files:

   • Upload the Dockerfile to the root of your Space
   • Upload the README.md to the root of your Space
   • Optionally upload .gitignore and other files

3. Wait for build:

   • Hugging Face will automatically build and deploy your Space
   • Check the logs for any errors
   • The build process might take 5-10 minutes

4. Access your server:

   • Once deployed, access at: https://[your-username]-[space-name].hf.space/
   • Test the SSE endpoint: https://[your-username]-[space-name].hf.space/devmode/exampleApplication/privkey/session1/sse

5. Monitor logs:

   • Use the "Logs" tab in your Space to monitor both build and runtime logs
   • Check for any startup errors or connection issues

This complete setup should work properly on Hugging Face Spaces. The key improvements include:

• Proper supervisor configuration for managing multiple processes
• Correct nginx configuration for SSE/MCP protocol
• Better error handling and logging
• Health checks and status endpoints
• Proper permissions for non-root user execution