dsh-figma-mcp
by yoobinkim541
README.md
# dsh-figma-mcp
Figma MCP over **stdio**, for DeepSeek Harness and any other MCP client.
| | |
|---|---|
| Upstream | `https://mcp.figma.com/mcp` (official Figma MCP, streamable HTTP) |
| Downstream | stdio, MCP `2025-06-18` |
| Tools exposed | 47 — Figma's list, unmodified schemas |
| LLM turns per call | **0** — the bridge talks HTTP directly |
| Credentials | reused from the host that already authorized Figma |
---
## Why this exists
DSH's `@deepseek-ai/dsh-mcp-client` speaks `stdio` and `streamable-http` with a **static** header set. Figma's MCP needs an OAuth bearer token that expires, and a proxy cannot mint one:
```console
$ curl -X POST https://api.figma.com/v1/oauth/mcp/register -d '…'
Forbidden # HTTP 403 — no dynamic client registration
$ curl -X POST https://api.figma.com/v1/oauth/token \
-d 'grant_type=refresh_token&refresh_token=…&client_id=…'
{"error":"Client ID and client secret are required"} # no secret to send
```
Both were measured against the live service. A `refresh_token` grant with a bare `client_id` is refused, and the registration endpoint is closed, so a new client cannot bootstrap itself. The only working path is to **reuse the credential an already-authorized client stored** — which is exactly what this bridge does, then republishes Figma's tools over stdio with a token it can refresh-by-reconnect.
The alternative in most setups is pointing an agent CLI at Figma and paying a model turn per call. Here a `use_figma` push costs zero tokens.
## Install
```bash
git clone https://github.com/yoobinkim541/dsh-figma-mcp.git
cd dsh-figma-mcp
npm install
node bin/dsh-figma-mcp.js doctor
```
`doctor` prints every credential it can see and then calls `whoami` upstream:
```console
credentials
keyring:Codex MCP Credentials/Figma|d39d3b62 access=figu… refresh=yes expires in 90d client=pADEsf…
upstream https://mcp.figma.com/mcp
ok: 47 tools, user yoobin kim
```
No build step. No native compilation — the keyring binding ships prebuilt binaries for Linux, macOS and Windows.
## Getting a credential
The bridge reads, in order:
1. `DSH_FIGMA_TOKEN` (or `FIGMA_MCP_TOKEN`) — an access token, for CI.
2. `~/.dsh-figma-mcp/credentials.json` — written by `dsh-figma-mcp login`.
3. The OS keyring entry `Codex MCP Credentials` / `Figma|*` — what `codex mcp login Figma` writes.
4. `~/.claude/.credentials.json` and `~/.claude.json` — Claude Code / desktop `mcpOAuth` entries.
Any one is enough. The most common setup is to authorize Figma **once** in a host that stores an OAuth token:
```bash
codex mcp login Figma # once; the bridge then reuses that credential
```
If you already have a token, store it directly and skip the keyring entirely:
```bash
DSH_FIGMA_TOKEN=figu_… node bin/dsh-figma-mcp.js login
```
`login` verifies the token against the live server **before** writing it, so a stored credential is never one that fails at the first call.
Discovery is read-only: it never writes into another tool's store.
## Connect to DeepSeek Harness
Append to `~/.dsh/cordis.patch.yml` (all profiles) or `~/.dsh/profiles/<name>/cordis.patch.yml`:
```yaml
- insert:
- id: figma-mcp
name: "@deepseek-ai/dsh-mcp-client"
config:
serverName: figma
transport: stdio
# Absolute path: DSH scrubs the ambient environment, so a bare `node`
# from a version manager may not resolve.
command: /usr/bin/node
args:
- /absolute/path/to/dsh-figma-mcp/bin/dsh-figma-mcp.js
toolCallTimeoutMs: 120000
failOnStartupError: true
```
Restart the harness. Each Figma tool appears as `mcp__figma__<tool>`:
```console
$ dsh headless "Call mcp__figma__whoami and report the handle."
- Handle: yoobin kim · Plan: … (student, Full seat, admin)
```
Two configuration notes that cost real debugging time:
- **`failOnStartupError: true`** — without it a credential problem leaves the harness running with *zero* Figma tools and no error in the tool list. The model then reports "no Figma MCP server is connected", which is technically true but hides the cause.
- **No `env:` block** — `dsh-mcp-client` validates `env` values as strings, and `!!js … || undefined` produces `undefined`, which fails schema validation at load. Credentials come from discovery, so the block is unnecessary.
### Other MCP clients
The bridge is a plain stdio server, so the same command works anywhere:
```jsonc
// Claude Code / Claude Desktop ~/.claude.json
{
"mcpServers": {
"figma": {
"command": "node",
"args": ["/absolute/path/to/dsh-figma-mcp/bin/dsh-figma-mcp.js"]
}
}
}
```
```toml
# Codex ~/.codex/config.toml
[mcp_servers.figma]
command = "node"
args = ["/absolute/path/to/dsh-figma-mcp/bin/dsh-figma-mcp.js"]
```
## CLI
```
dsh-figma-mcp run the stdio bridge
dsh-figma-mcp doctor credentials + upstream reachability
dsh-figma-mcp tools print the 47 upstream tool names
dsh-figma-mcp login verify and store a token
```
| Variable | Meaning |
|---|---|
| `DSH_FIGMA_TOKEN` / `FIGMA_MCP_TOKEN` | access token; overrides discovery |
| `DSH_FIGMA_REFRESH_TOKEN` | optional refresh token to pair with it |
| `DSH_FIGMA_URL` | upstream URL (default `https://mcp.figma.com/mcp`) |
| `DSH_FIGMA_CREDENTIALS` | where `login` writes |
| `DSH_FIGMA_CODEX_CREDENTIALS` / `DSH_FIGMA_CLAUDE_CREDENTIALS` | extra discovery paths |
## How it works
```
MCP client ──stdio──▶ dsh-figma-mcp ──HTTPS+Bearer──▶ mcp.figma.com/mcp
│
├── credentials.js discover + normalize every store
├── upstream.js connect, list, call, reconnect on 401
└── server.js expose tools verbatim + provenance
```
Three behaviours are deliberate:
**Tool schemas pass through untouched.** Only a one-line provenance prefix is added to each description. Rewriting `use_figma`'s arguments would break the Figma plugin-API contract, and the `nodeId` strings the rest of the tool set expects are exact.
**A 401 reconnects once, then retries.** The SDK's streamable transport takes a static `requestInit`, so there is no per-request hook to refresh mid-flight; reconnecting with a freshly discovered credential is the equivalent. The retry is safe because an auth failure means the request never reached a tool.
**Errors surface as MCP errors.** A failed call throws with a hint; nothing is turned into a silent empty result, which would look to the model like a tool that succeeded with no output.
## Limitations
- **No dynamic registration.** `POST /v1/oauth/mcp/register` is 403, so `login` needs a token you already obtained. There is no browser-based "click to authorize" flow in this package.
- **Token lifetime is the host's.** With a token from `codex mcp login Figma`, the bridge inherits its ~90-day lifetime. When it expires, re-authorize in that host; the bridge picks up the new value on the next start.
- **`refresh_token` is unused.** Figma requires a client secret alongside it, and no supported store keeps one. A `refreshToken` is carried through `normalize()` for future use but never spent.
- **Resources and prompts are empty.** Figma exposes tools only; those two namespaces answer with empty lists.
- **Linux keyring needs a running Secret Service.** On a headless box use `DSH_FIGMA_TOKEN`; `doctor` says so when discovery comes up empty.
## Tests
```bash
npm test # 10 checks: normalization, auth detection, stdio handshake
DSH_FIGMA_SKIP_LIVE=1 npm test # skip the live handshake (no network / no credential)
```
The live check spawns the real binary over stdio and asserts the `initialize` handshake, so a broken entry point fails the suite rather than shipping.
## Upstream
DeepSeek Harness does not accept external pull requests at the moment (`CONTRIBUTING.md`: *"we cannot accept external pull requests at the moment"*). The supported route is the ecosystem: this repository is tagged **`dsh-plugin`** so it is discoverable, and the harness README's own guidance is to treat the official repo as a source of inspiration rather than a gate.
If the upstream policy changes, `src/` is dependency-light and framework-agnostic; `server.js` is ~120 lines over the MCP SDK.
## License
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues