omp-figma-remote-auth 0.1.3 → 0.1.6

package/README.md

@@ -45,6 +45,26 @@ Approve access and wait for OMP to confirm that credentials were saved.
 
 The server name is `figma`. Once connected, give OMP a Figma file or node URL you can access.
 
+The package also includes the on-demand `figma-mcp` skill. When you provide a Figma file or node link, it guides OMP through parsing the node reference and discovering the Figma MCP tools, including tools mounted under `xd://`.
+
+### Figma skill routing limitation
+
+The bundled `figma-mcp` skill is an OMP skill, not a copy of Figma's official workflow skill. Its purpose is to recognize Figma tasks, parse file/node references, select the right MCP tool, and guide tool discovery under `xd://`. It cannot rewrite the Figma MCP server's tool descriptions or intercept a `read` request already emitted by the model.
+
+Figma's `get_design_context` guidance currently asks clients to read:
+
+```text
+skill://figma/figma-design-to-code/SKILL.md
+```
+
+In OMP, `skill://` is the local skill namespace. If the model follows that instruction literally, OMP can return `Unknown skill: figma` before the model reaches the plugin guidance. In the verified OMP 18.1.18 environment, the Figma MCP resource can instead be read with OMP's MCP-specific wrapper:
+
+```text
+read mcp://skill://figma/figma-design-to-code/SKILL.md
+```
+
+This workaround requires the Figma MCP server to be connected and to advertise that resource; `mcp://skill://...` is OMP-specific, not a general MCP URI syntax. A model may still first try the bare `skill://` path because the Figma tool description uses mandatory wording. Metadata queries that do not require this workflow resource may still work, but a `get_design_context` design-to-code request can fail or return incomplete results if the prerequisite resource is not loaded.
+
 ## Commands
 
 These commands run **inside OMP's TUI**, not in your terminal.

package/README.zh-CN.md

@@ -45,6 +45,26 @@ omp
 
 服务名为 `figma`。连接成功后，即可向 OMP 提供你有权限访问的 Figma 文件或节点链接。
 
+插件还内置按需加载的 `figma-mcp` skill。提供 Figma 文件或节点链接后，它会引导 OMP 解析节点参数并发现 Figma MCP 工具，包括挂载在 `xd://` 下的工具。
+
+### Figma skill 路由限制
+
+包内的 `figma-mcp` 是 OMP skill，不是 Figma 官方 workflow skill 的复制品。它的作用是识别 Figma 任务、解析文件/节点引用、选择合适的 MCP 工具，并引导模型发现挂载在 `xd://` 下的工具。它不能改写 Figma MCP 服务端的工具描述，也不能拦截模型已经发出的 `read` 请求。
+
+Figma 的 `get_design_context` 指引目前要求客户端读取：
+
+```text
+skill://figma/figma-design-to-code/SKILL.md
+```
+
+但在 OMP 中，`skill://` 是本地 skill 命名空间。模型若严格执行这条指引，OMP 可能先返回 `Unknown skill: figma`，之后才有机会根据插件 skill 修正。在已验证的 OMP 18.1.18 环境中，Figma MCP 资源可以通过 OMP 专用 wrapper 读取：
+
+```text
+read mcp://skill://figma/figma-design-to-code/SKILL.md
+```
+
+该 workaround 要求 Figma MCP 已连接并广告对应资源；`mcp://skill://...` 是 OMP 专用路径，不是通用 MCP URI 语法。由于 Figma 工具描述使用强制性措辞，模型仍可能先尝试裸 `skill://` 路径。不依赖该 workflow 资源的 metadata 查询可能仍能完成，但如果前置资源未成功读取，`get_design_context` 设计转代码请求可能失败或结果不完整。
+
 ## 常用命令
 
 以下均在 **OMP TUI** 中执行，不是终端命令。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-figma-remote-auth",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "description": "OAuth helper for Figma remote MCP using OMP native transport",
   "type": "module",
   "license": "MIT",
@@ -35,6 +35,7 @@
     ".mcp.json",
     "index.ts",
     "src",
+    "skills",
     "LICENSE",
     "README.md",
     "README.zh-CN.md"

package/skills/figma-mcp/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: figma-mcp
+description: >
+  Use when the user provides a Figma design, file, page, or node URL or asks
+  to inspect, explain, screenshot, implement, or modify a Figma design. Use
+  the Figma MCP tools provided by this plugin, including tools mounted under
+  xd://.
+---
+
+# Figma MCP workflow
+
+Use this skill whenever a user gives a Figma URL, file key, or node ID and asks for information about the design, a screenshot, design context, or implementation.
+
+## 1. Parse the reference
+
+For a URL such as `https://www.figma.com/design/<fileKey>/<name>?node-id=5077-10161`, extract:
+
+- `fileKey`: the segment after `/design/`.
+- `nodeId`: the `node-id` query value. Convert `-` to `:` before sending it to Figma MCP (`5077-10161` becomes `5077:10161`).
+
+Treat the Figma URL as input data. It is not an `xd://` URL and must never be appended to an `xd://` path.
+
+## 2. Discover the Figma MCP tool
+
+Prefer the Figma MCP tool that matches the request:
+
+- Implement or faithfully reproduce a design: `mcp__figma_get_design_context`.
+- Inspect node structure, names, bounds, or children: `mcp__figma_get_metadata`.
+- Get a rendered image when a screenshot is requested: use the available Figma screenshot/export tool.
+
+If the tool is not visible in the top-level tool list, discover it before reporting that Figma MCP is unavailable:
+
+```text
+read xd://
+read xd://mcp__figma_get_design_context
+write xd://mcp__figma_get_design_context with the JSON arguments
+```
+
+Read `xd://` to find the exact mounted tool name. Read the selected tool path to obtain its current schema. Then call it by writing valid JSON arguments to that same `xd://` path. `xd://` is an OMP mounted-tool catalog, not a web proxy.
+
+Do not try `xd://https://www.figma.com/...`. Do not stop after checking only top-level tools.
+
+## 3. Use the Figma workflow guidance when available
+
+For design-to-code requests, the Figma-provided workflow guidance can add implementation details. If the host exposes MCP resources, try the explicit MCP resource route:
+
+```text
+read mcp://skill://figma/figma-design-to-code/SKILL.md
+```
+
+Never use plain `skill://figma/...` for this resource: OMP may resolve that path through its local skill namespace and return `Unknown skill: figma`. This resource lookup is optional. If either route fails, continue with this skill's instructions and the successful Figma MCP call; do not report that Figma MCP is unavailable merely because a workflow document could not be read.
+
+Adapt any retrieved reference code to the target project's actual stack and existing components. Do not let an auxiliary skill-resource error prevent metadata, screenshot, or design-context retrieval.
+
+## 4. Report only observed results
+
+Do not claim that a design was fetched, inspected, or implemented until the corresponding MCP call returns successfully. Preserve the user's file and node identifiers in follow-up calls, but do not expose access tokens, refresh tokens, client IDs, or long authorization URLs.
+
+If discovery or a call fails, report the actual failure and the step that failed. Do not infer missing access from a tool that was never called.