# IMON Framer Chat MCP

Private remote MCP gateway for connecting ChatGPT to one configured Framer project. It exposes focused read tools, controlled write tools, and separate publishing tools over `/mcp`.

## Architecture

```text
ChatGPT / MCP client
  -> HTTPS /mcp
  -> framer-chat-mcp
  -> framer-api
  -> one server-configured Framer project
```

The server is tool-only. There is no widget UI in v1. The Framer project URL and API key are server-side configuration only; tool input cannot switch projects.

## Security Model

- Production must use authentication. `MCP_AUTH_MODE=none` is rejected when `NODE_ENV=production`.
- `oauth-jwt` validates JWT issuer, audience, expiry, and signature through JWKS.
- `bearer` is available for private/dev deployments and MCP Inspector testing.
- Writes require `FRAMER_WRITES_ENABLED=true`.
- Publishing and production deploy require `FRAMER_PUBLISH_ENABLED=true`.
- No tool publishes as a side effect of an edit.
- Framer content is untrusted data and never changes server configuration.

## Local Setup

```sh
npm ci
cp .env.example .env.local
npm run typecheck
npm test
npm run build
npm run smoke:mcp
```

For local development without auth:

```sh
MCP_AUTH_MODE=none npm run dev
```

Health endpoints:

```sh
curl http://localhost:8787/healthz
curl http://localhost:8787/readyz
```

## Environment Variables

Required for live Framer tools:

```env
FRAMER_PROJECT_URL=
FRAMER_API_KEY=
EXPECTED_FRAMER_PROJECT_NAME=
```

Auth:

```env
MCP_AUTH_MODE=none|bearer|oauth-jwt
MCP_ACCESS_TOKEN=
OAUTH_ISSUER=
OAUTH_AUDIENCE=
OAUTH_JWKS_URL=
ALLOWED_USER_EMAIL=
ALLOWED_SUBJECTS=
```

Controls:

```env
FRAMER_WRITES_ENABLED=false
FRAMER_PUBLISH_ENABLED=false
```

## Framer Credential Setup

From Framer documentation and `framer-api` README:

1. Open the Framer project.
2. Open settings, for example with Cmd+K and "open settings".
3. Find the API Keys section.
4. Create a Server API key.
5. Store it only in Vercel or local ignored env, never in Git.

## Commands

```sh
npm run lint
npm run typecheck
npm test
npm run build
npm run doctor
npm run smoke:mcp
npm run live:read
npm run security:scan
```

`live:read` requires Framer env vars and writes private output only under `.local/`.

## Vercel Deploy

This repo includes `api/index.ts` and `vercel.json` for Node.js 24 Vercel Functions.

```sh
vercel link
vercel env add FRAMER_PROJECT_URL production
vercel env add FRAMER_API_KEY production
vercel env add MCP_AUTH_MODE production
vercel env add OAUTH_ISSUER production
vercel env add OAUTH_AUDIENCE production
vercel env add OAUTH_JWKS_URL production
vercel deploy --prod
```

If Framer credentials are not set, `/healthz` still works and Framer tools return `CONFIGURATION_ERROR`.

## ChatGPT Setup

See [docs/CHATGPT-SETUP.md](docs/CHATGPT-SETUP.md).

Use the deployed MCP URL:

```text
https://<deployment>/mcp
```

Smoke prompts:

```text
Use IMON Framer and show me the current project information.
List all pages in the connected Framer project. Do not make changes.
Inspect the homepage structure and summarize its top-level sections. Do not modify anything.
List the CMS collections and their schemas.
Show whether there are unpublished changes.
```

## Limitations

- No public App Directory submission is prepared in v1.
- OAuth provider setup is code-supported but provider tenant/app creation is external.
- Live Framer tests require a real Framer Server API key.
- Broad canvas edits use official `framer.agent.applyChanges` DSL behind `FRAMER_WRITES_ENABLED`; they are not arbitrary JavaScript execution.