# Feedback Hub MCP

An [MCP](https://modelcontextprotocol.io) server that lets AI assistants like Claude read and analyze the data in [Feedback Hub](https://github.com/aydin-omer/feedback-hub), a feedback collection app that classifies incoming feedback with AI.

Once connected, you can ask Claude questions like:

- "How many feedback entries do we have, and what's the breakdown by type?"
- "Show me the urgent bugs."
- "What are people asking for most?"

Claude picks the right tool, queries the live database and answers in plain language, often adding its own prioritization ("#4 blocks a whole team, look at it first").

## Tools

| Tool | What it does |
|---|---|
| `get_feedback_stats` | Total number of entries, broken down by type and classification status. |
| `list_feedback` | Individual entries, newest first, with the original message, AI summary and classification. Optional filters: `type`, `urgency`, `sentiment`, `limit` (max 50). |

## Security by design

Giving an AI access to a database deserves care. This server is built so that safety does not depend on the code being bug-free:

- **Read-only at the platform level.** The Cloudflare API token only has the `D1 Read` permission. Any attempt to change data is rejected by Cloudflare itself, even if the code or the AI tried to.
- **No personal data leaves the server.** Submitter email addresses are never selected from the database, so they never reach the AI's context.
- **Constrained inputs.** Filters only accept a fixed list of values, and every value is passed to SQL as a bound parameter (`?`), never concatenated into the query.
- **No secrets in the repo.** All credentials live in a git-ignored `.env` file. Only an empty template (`.env.example`) is committed.

## Setup

### Prerequisites

- A deployed [Feedback Hub](https://github.com/aydin-omer/feedback-hub) instance with its D1 database
- Node.js 20.12 or later
- [Claude Desktop](https://claude.ai/download)

### 1. Install

```bash
git clone https://github.com/aydin-omer/feedback-hub-mcp.git
cd feedback-hub-mcp
npm install
```

### 2. Create a read-only Cloudflare API token

In the Cloudflare dashboard, go to **My Profile → API Tokens → Create Token** and create a custom token with a single permission: **Account → D1 → Read**. Copy the token; it is only shown once.

### 3. Configure

```bash
cp .env.example .env
```

Fill in the three values in `.env`:

- `CLOUDFLARE_ACCOUNT_ID`: run `npx wrangler whoami`
- `D1_DATABASE_ID`: run `npx wrangler d1 list` and copy the ID of your Feedback Hub database
- `CLOUDFLARE_API_TOKEN`: the read-only token from step 2

### 4. Test with MCP Inspector (optional)

```bash
npx @modelcontextprotocol/inspector node src/index.js
```

In the browser window that opens, click **Connect**, then **Tools → List Tools**, and run `get_feedback_stats`.

### 5. Connect to Claude Desktop

In Claude Desktop, open **Settings → Developer → Edit Config** and add a `mcpServers` entry to `claude_desktop_config.json`. Use absolute paths; run `which node` to find yours:

```json
{
  "mcpServers": {
    "feedback-hub": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/to/feedback-hub-mcp/src/index.js"]
    }
  }
}
```

If the file already contains other settings, add `mcpServers` next to them rather than replacing the file.

Quit Claude Desktop completely (Cmd+Q on macOS), reopen it and start a new chat. Claude reads the server list only on startup, and the tool list at the start of each chat.

## Troubleshooting

- **Claude doesn't see a new tool:** restart Claude Desktop and start a new chat.
- **Server doesn't start:** run `npm start` in the project folder. A "Missing configuration" message means `.env` is missing or incomplete.
- **Logs:** on macOS, Claude Desktop writes the server's log to `~/Library/Logs/Claude/mcp-server-feedback-hub.log`.

## License

[MIT](LICENSE)