# FrancoLabs MCP Server

Connect AI assistants to [FrancoLabs](https://francolabs.vercel.app) — a UX
research platform — over the [Model Context Protocol](https://modelcontextprotocol.io).
Let Claude, ChatGPT and other MCP clients create and manage studies, browse
templates, read participant responses and analytics, run AI-grounded analysis,
and turn insights into product opportunities on your behalf.

- **Endpoint:** `https://francolabs.vercel.app/mcp`
- **Transport:** Streamable HTTP (MCP protocol `2025-06-18`)
- **Auth:** OAuth 2.1 (Dynamic Client Registration + PKCE) or Personal Access Token
- **Registry:** `io.github.glauberfrancodesign/francolabs`

---

## Connect

### Claude (claude.ai / Desktop)

Settings → **Connectors** → *Add custom connector* → URL:

```
https://francolabs.vercel.app/mcp
```

Complete the OAuth consent screen — you choose exactly which scopes to grant and
can toggle read-only access.

### ChatGPT

Enable **Developer Mode**, then Settings → **Connectors** → *Add* → same URL.
Authenticate via the OAuth flow.

### Claude Code / Cursor (manual token)

Generate a Personal Access Token in
[Settings → Integrations](https://francolabs.vercel.app/settings/integrations), then:

```bash
claude mcp add --transport http francolabs \
  "https://francolabs.vercel.app/mcp" \
  --header "Authorization: Bearer <your-token>"
```

---

## Tools

| Tool | Scope | Description |
|------|-------|-------------|
| `list_question_types` | `templates:read` | List question/block types and their settings |
| `list_templates` | `templates:read` | List study templates, optionally by category |
| `list_workspaces` | `projects:read` | List the workspaces (teams) you belong to and your role in each |
| `list_projects` | `projects:read` | List your projects |
| `get_project` | `projects:read` | Get a single project by id |
| `create_project` | `projects:write` | Create a new project (optionally in a specific workspace) |
| `list_studies` | `studies:read` | List studies (filter by status/project) |
| `get_study` | `studies:read` | Get a full study with blocks and settings |
| `create_study` | `studies:write` | Create a study (auto-scaffolds welcome + thank-you) |
| `update_study` | `studies:write` | Update title, blocks, settings or project |
| `set_study_status` | `studies:write` | Launch / pause / resume / complete a study |
| `delete_study` | `studies:write` | Permanently delete a study and its responses |
| `list_responses` | `responses:read` | List participant responses (most recent first) |
| `get_study_analytics` | `responses:read` | Aggregated KPIs: NPS, completion, distributions |
| `get_study_digest` | `responses:read` | Deterministic, PII-free statistical digest of a study's results |
| `run_universal_analysis` | `responses:read` | Run/refresh the full AI analysis (digest + grounded synthesis) |
| `analysis_chat` | `responses:read` | Ask a natural-language question, grounded in the study's analysis |
| `get_insights` | `responses:read` | List curated insight cards for a study |
| `upsert_insight` | `studies:write` | Create or update a curated insight card |
| `generate_study_from_objective` | `studies:read` | Turn a research objective into a typed study skeleton |
| `review_study_quality` | `studies:read` | Review a study's questionnaire for survey-design issues |
| `list_opportunities` | `responses:read` | List product opportunities distilled from a study's insights |
| `create_opportunity_from_insights` | `studies:write` | Distill insights into decision-ready product opportunities |

`create_project` and `create_study` write into a workspace — pass `workspaceId`
(see `list_workspaces`), or omit it to use your oldest workspace by default.

Two resources are also exposed: `francolabs://templates` and
`francolabs://question-types`.

## Scopes

`templates:read` · `projects:read` · `projects:write` · `studies:read` ·
`studies:write` · `responses:read`

Tools you didn't grant are hidden from `tools/list`. A **read-only** grant blocks
every write tool server-side, regardless of scopes.

## Security

- Tokens are stored only as SHA-256 hashes — never in plaintext.
- Each request mints a short-lived (5 min) JWT so all data access runs under
  per-user row-level security; the service role is used only for the token lookup.
- Access is revocable anytime from Settings → Integrations.
- OAuth follows RFC 9728 (protected-resource discovery), RFC 8414 (AS metadata),
  RFC 7591 (dynamic client registration) and PKCE S256.

## Source

This repository mirrors the server's source for transparency. The server runs as
a Supabase Edge Function (`src/mcp`, `src/mcp-oauth`, `src/_shared`).

---

© FrancoLabs. All rights reserved.