`README.md`

67 lines
# filemaker-mcp

MCP server + CLI that lets Claude **read** and **(confirmed) update** Designer
Wallcoverings' FileMaker Cloud files — `Clients`, `invoice`, `WALLPAPER` — via the
FileMaker Data API.

Host: `designerwallcoverings.account.filemaker-cloud.com` (Claris FileMaker Cloud).

## Auth model

FileMaker Cloud does **not** accept Basic auth on the Data API. It requires a
Claris ID (Amazon Cognito, USER_SRP_AUTH) → `idToken` → exchanged for a per-file
Data API session token.

```
Claris email+pw --SRP--> Cognito idToken (~1h) --FMID--> Data API session (15m) --Bearer--> record ops
```

Cognito pool (public Claris constants): pool `us-west-2_NqkuZcXQY`, client
`4l9rvl4mv5es1eep1qe97cautn`, region `us-west-2`.

## Prerequisites (one-time, in FileMaker Cloud admin)

1. **Data API enabled** on the deployment.
2. A **dedicated Claris ID** (e.g. `claude-api@designerwallcoverings.com`) added to
   the team, **MFA OFF**, with a permanent password.
3. That account granted access to each file with the **`fmrest`** extended
   privilege (Manage → Security in each of Clients / invoice / WALLPAPER).
4. Password routed via the `secrets` skill into `.env` as `FM_CLARIS_PASSWORD`.

## Verify (CLI)

```sh
cp .env.example .env   # then fill FM_CLARIS_PASSWORD via the secrets skill
node bin/fm.js ping            # proves Cognito auth + a Data API session
node bin/fm.js layouts Clients # discover layout names → set defaultLayout in config.json
node bin/fm.js get Clients <layout> <recordId>
```

## Write safety

- Every write tool defaults to **`dryRun:true`** — `fm_update_record` returns a
  before→after diff and commits only on a second call with `dryRun:false`.
- `FM_READONLY=1` is a hard kill-switch that forbids all writes.
- `config.json` is a **whitelist** — a file not listed is rejected; per-file
  `writable:false` makes it read-only.

## MCP registration

Add to `~/.claude.json` `mcpServers` (env injected, not committed):

```json
"filemaker": {
  "command": "node",
  "args": ["/Users/stevestudio2/Projects/filemaker-mcp/src/index.js"],
  "env": {
    "FM_CLOUD_HOST": "designerwallcoverings.account.filemaker-cloud.com",
    "FM_CLARIS_EMAIL": "claude-api@designerwallcoverings.com",
    "FM_CLARIS_PASSWORD": "…",
    "FM_READONLY": "0"
  }
}
```

Tools: `fm_databases`, `fm_layouts`, `fm_field_metadata`, `fm_get_record`,
`fm_list_records`, `fm_find`, `fm_update_record` (gated), `fm_create_record` (gated).