mcp playground

# MCP-HFspace Proxy Server

This is a proxy server that forwards MCP (Model Context Protocol) requests to Hugging Face Spaces through mcp-hfspace.

## Features

- Accepts MCP requests via HTTP
- Forwards requests to configured Hugging Face Spaces
- Handles file uploads and downloads
- Supports multiple Spaces simultaneously
- Provides health check endpoint

## Installation

1. Install dependencies:
```bash
npm install
```

2. Create a workspace directory:
```bash
mkdir workspace
```

3. (Optional) Set up your Hugging Face token:
```bash
export HF_TOKEN=your_token_here
```

## Configuration

Edit `src/index.ts` to configure:
- Port number
- List of Hugging Face Spaces to use
- Working directory
- Hugging Face token (optional)

Example configuration:
```typescript
const config = {
  port: 3000,
  hfSpaces: [
    "shuttleai/shuttle-jaguar",
    "Qwen/Qwen2.5-72B-Instruct",
    "parler-tts/parler_tts"
  ],
  workDir: "./workspace",
  hfToken: process.env.HF_TOKEN
};
```

## Usage

1. Start the server:
```bash
npm run dev
```

2. The server will be available at `http://localhost:3000`

3. Endpoints:
   - `POST /mcp` - Main MCP endpoint
   - `GET /health` - Health check endpoint

4. Example MCP request:
```json
{
  "method": "tools/call",
  "params": {
    "name": "shuttleai/shuttle-jaguar",
    "arguments": {
      "prompt": "a beautiful sunset"
    }
  }
}
```

## How it Works

1. The proxy server accepts MCP requests via HTTP
2. It uses mcp-hfspace to translate these requests to Gradio API calls
3. The requests are forwarded to the appropriate Hugging Face Space
4. Responses are translated back to MCP format and returned

## Error Handling

The server includes error handling for:
- Invalid requests
- Space connection issues
- File handling errors
- API errors

Errors are returned in the format:
```json
{
  "error": "Error message",
  "details": "Additional error details"
}
```