README.md

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

```markdown
---
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

```javascript
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](https://github.com/Coral-Protocol/coral-server)
- [Coral Protocol Website](https://coralprotocol.org)
- [Discord Community](https://discord.gg/coral-protocol)

## 💡 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)

```yaml
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)

```bash
#!/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