uservoice-mcp/README.md

Model Context Protocol (MCP) server for UserVoice feedback and suggestion management

# UserVoice MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides access to UserVoice feedback and suggestion data. This server enables AI assistants like Claude to search and retrieve UserVoice suggestions, making it easy to analyze user feedback and feature requests.

## Features

- 🔍 **Search UserVoice suggestions** by query terms
- 📊 **Retrieve detailed feedback** including votes, status, and creation dates
- 🎯 **Exact query matching** with `EXACT:query` syntax for precise searches
- ⏰ **Time period filtering** with natural language (last week, past 3 days, etc.)
- 🔒 **Secure configuration** via environment variables
- ⚡ **Fast API responses** with proper error handling
- 🌐 **URL encoding** for special characters and spaces

## Installation

### From npm

```bash
npm install -g uservoice-mcp
```

### From source

```bash
git clone https://github.com/cjohnson/uservoice-mcp.git
cd uservoice-mcp
npm install
npm run build
```

## Configuration

### Environment Variables

The server requires two environment variables:

- `UV_API_BASE`: Your UserVoice API base URL
- `UV_TOKEN`: Your UserVoice API token (without "Bearer" prefix)

### Example Configuration

```bash
export UV_API_BASE="https://yourcompany.uservoice.com/api/v2/admin"
export UV_TOKEN="your_api_token_here"
```

### MCP Client Configuration

Add to your MCP client configuration (e.g., `~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "uservoice-mcp": {
      "command": "uservoice-mcp",
      "env": {
        "UV_API_BASE": "https://yourcompany.uservoice.com/api/v2/admin",
        "UV_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

Or if installed locally:

```json
{
  "mcpServers": {
    "uservoice-mcp": {
      "command": "node",
      "args": ["/path/to/uservoice-mcp/build/index.js"],
      "env": {
        "UV_API_BASE": "https://yourcompany.uservoice.com/api/v2/admin",
        "UV_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

## Usage

### Available Tools

#### `get-feedback`

Search for UserVoice suggestions and feedback.

**Parameters:**
- `query` (string, min 2 chars): Search query for feedback

**Query Formats:**

⚠️ **Important Note**: LLMs (Claude, Cursor) often strip special characters like brackets and quotes from tool parameters. Use the `EXACT:` prefix for precise searches.

- `mobile app` - Normal search
- `EXACT:mobile app` - Exact search (recommended for precise matching)
- `mobile app last week` - Search with time period
- `EXACT:mobile app last week` - Exact search with time period

**Time Period Support:**
- `last week`, `past week` - Last 7 days
- `last 3 days`, `past 5 days` - Specific number of days
- `last month`, `past month` - Last 30 days
- `last year`, `past year` - Last 365 days
- `from the last week`, `in the past month` - Alternative phrasing

### Examples

```javascript
// Exact search (recommended)
{
  "query": "EXACT:mobile app"
}

// Search with spaces and special characters
{
  "query": "EXACT:feature request"
}

// Time period searches
{
  "query": "mobile app feedback from the last week"
}

// Exact search with time period
{
  "query": "EXACT:mobile app last 3 days"
}

// Alternative time period phrasing
{
  "query": "dashboard in the past month"
}
```

### Response Format

```json
{
  "content": [
    {
      "type": "text",
      "text": "Active suggestions for query: mobile app\n\nTitle: FEATURE REQUEST - Mobile App\nStatus: Under Review\nVotes: 15\nID: 12345\nCreated At: 2025-06-01T17:33:13Z\nBody: Would love to see dark mode support in the mobile application!\nURL: https://yourcompany.uservoice.com/admin/v3/suggestions/12345"
    }
  ]
}
```

## Known Issues

### LLM Character Stripping

**Issue**: LLMs (Claude, Cursor) automatically strip special characters from tool parameters, including:
- `[[ ]]` double brackets
- `" "` double quotes
- `' '` single quotes
- Other special delimiters

**Solution**: Use the `EXACT:` prefix instead:
- ❌ `[[mobile app]]` → Gets stripped to `mobile app`
- ✅ `EXACT:mobile app`

## Support

- **Issues**: [GitHub Issues](https://github.com/cjohnson/uservoice-mcp/issues)
- **Documentation**: [MCP Documentation](https://modelcontextprotocol.io)
- **UserVoice API**: [UserVoice API Documentation](https://developer.uservoice.com)