# MCP Server for LimeSurvey

This MCP server enables interaction with the LimeSurvey API while adhering to the [Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18) specifications. It exposes core LimeSurvey functionality through standardized MCP endpoints.

## Features

- 🚀 Survey creation
- ❓ Question and answer management
- 📋 Question group handling
- ✅ Survey activation
- 📊 Response exporting
- 🔍 List available surveys

## Prerequisites

- Python 3.7+
- Access to a LimeSurvey instance (version 3.X+)
- LimeSurvey admin account

## Installation

1. Clone the repository:

```bash
git clone https://gitlab.com/mehdi_guiraud/mcp-limesurvey.git
cd mcp-limesurvey
```

2. Configure environment variables:

```bash
cp .env.example .env
# Edit .env with your LimeSurvey credentials
nano .env
```

3. Install dependencies:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

## Starting the Server

```bash
./start_server.sh
```

The server will be available at `http://localhost:8080`

## Integration with Claude Desktop

### Step 1: Add the MCP Server in Claude Desktop

1. Open Claude Desktop
2. Navigate to **Settings** → **Model Context Protocol**
3. Click **Add Custom Server**
4. Provide server details:
   - **Server Name**: LimeSurvey MCP
   - **Base URL**: `http://localhost:8080/mcp`
   - **Specification URL**: `http://localhost:8080/spec`

### Step 2: Usage with Claude Desktop

Interact with LimeSurvey directly from Claude Desktop using MCP syntax:

#### Create a new survey

```json
{
  "model": "limesurvey",
  "action": "create_survey",
  "parameters": {
    "survey_title": "Customer Feedback",
    "survey_language": "en"
  }
}
```

#### Add a question

```json
{
  "model": "limesurvey",
  "action": "add_question",
  "parameters": {
    "survey_id": 123456,
    "group_id": 1,
    "question_text": "How satisfied are you with our service?",
    "question_type": "5",
    "question_options": {
      "subquestions": ["Very satisfied", "Satisfied", "Neutral", "Unsatisfied", "Very unsatisfied"]
    }
  }
}
```

#### Activate a survey

```json
{
  "model": "limesurvey",
  "action": "activate_survey",
  "parameters": {
    "survey_id": 123456
  }
}
```

#### Export responses

```json
{
  "model": "limesurvey",
  "action": "export_responses",
  "parameters": {
    "survey_id": 123456,
    "format": "json"
  }
}
```

## Available MCP Endpoints

| Action | Required Parameters | Description |
|--------|---------------------|-------------|
| `create_survey` | `survey_title`, `survey_language` | Create a new survey |
| `add_question` | `survey_id`, `group_id`, `question_text`, `question_type` | Add a question to a survey |
| `add_group` | `survey_id`, `group_title`, `group_description` | Add a question group |
| `activate_survey` | `survey_id` | Activate a survey |
| `list_surveys` | None | List all surveys |
| `export_responses` | `survey_id` | Export survey responses |

## Technical Specification

The server fully implements the MCP specification (2025-06-18). Access the complete specification at:

```http
GET http://localhost:8080/spec
```

## Security

1. **Authentication**: Uses credentials stored in `.env`
2. **Validation**: All requests are validated against the MCP schema
3. **Session Management**: Automatically caches and recycles LimeSurvey sessions

## Customization

To add new API methods:

1. Add the endpoint in `config/config.yaml`
2. Implement the method in `app/main.py`
3. Update documentation in the `get_mcp_spec` function

## Troubleshooting

- Ensure RPC API is enabled in LimeSurvey (`Configuration → Interfaces → Enable RPC API`)
- Verify correct credentials in `.env`
- Check server logs for detailed error messages

## License

This project is licensed under MIT. See [LICENSE](LICENSE) for details.