@mrfentmen/figma-mcp 1.0.0 → 1.1.0

package/README.md

@@ -4,9 +4,17 @@ Query the Figma API (token; set FIGMA_ACCESS_TOKEN, X-Figma-Token): profile, fil
 
 ## Tools
 
-- `me` — Figma user.
-- `get_file` — File metadata.
-- `project_files` — Files in a project.
+- `me` — The Figma user the access token belongs to.
+- `get_file` — File metadata: name, pages and last modified date.
+- `project_files` — Figma files inside one project id.
+
+- `team_projects` — Projects in a team.
+- `file_comments` — Comments on a file.
+- `file_versions` — Version history.
+- `file_components` — Published components.
+- `file_styles` — Published styles.
+- `file_nodes` — Nodes by IDs.
+- `file_images` — PNG renders.
 
 ## Source
 

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+export declare class FigmaError extends Error {
+    constructor(message: string);
+}
+export declare function errorMessage(e: unknown): string;
+export declare function me(): Promise<string>;
+export declare function getFile(fileKey: string): Promise<string>;
+export declare function projectFiles(projectId: string): Promise<string>;
+export declare function teamProjects(teamId: string): Promise<string>;
+export declare function fileComments(fileKey: string): Promise<string>;
+export declare function fileVersions(fileKey: string): Promise<string>;
+export declare function fileComponents(fileKey: string): Promise<string>;
+export declare function fileStyles(fileKey: string): Promise<string>;
+export declare function fileNodes(fileKey: string, nodeIds: string): Promise<string>;
+export declare function fileImages(fileKey: string, nodeIds: string): Promise<string>;

package/dist/api.js

@@ -0,0 +1,63 @@
+export class FigmaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FigmaError";
+    }
+}
+export function errorMessage(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+const UA = { "User-Agent": "awesome-mcps/1.0" };
+function headers() {
+    const k = process.env.FIGMA_ACCESS_TOKEN;
+    if (!k)
+        throw new FigmaError("Set FIGMA_ACCESS_TOKEN (Figma personal token).");
+    return { ...UA, Accept: "application/json", "X-Figma-Token": k };
+}
+async function get(path) {
+    let res;
+    try {
+        res = await fetch("https://api.figma.com/v1" + path, {
+            headers: headers(),
+            signal: AbortSignal.timeout(25000),
+        });
+    }
+    catch (e) {
+        throw new FigmaError(`Network error: ${e.message}`);
+    }
+    if (!res.ok) {
+        const body = (await res.text()).slice(0, 300);
+        throw new FigmaError(`HTTP ${res.status}: ${body}`);
+    }
+    return (await res.text()).slice(0, 12000);
+}
+export function me() {
+    return get("/me");
+}
+export function getFile(fileKey) {
+    return get(`/files/${encodeURIComponent(fileKey)}`);
+}
+export function projectFiles(projectId) {
+    return get(`/projects/${encodeURIComponent(projectId)}/files`);
+}
+export function teamProjects(teamId) {
+    return get(`/teams/${encodeURIComponent(teamId)}/projects`);
+}
+export function fileComments(fileKey) {
+    return get(`/files/${encodeURIComponent(fileKey)}/comments`);
+}
+export function fileVersions(fileKey) {
+    return get(`/files/${encodeURIComponent(fileKey)}/versions`);
+}
+export function fileComponents(fileKey) {
+    return get(`/files/${encodeURIComponent(fileKey)}/components`);
+}
+export function fileStyles(fileKey) {
+    return get(`/files/${encodeURIComponent(fileKey)}/styles`);
+}
+export function fileNodes(fileKey, nodeIds) {
+    return get(`/files/${encodeURIComponent(fileKey)}/nodes?ids=${encodeURIComponent(nodeIds)}`);
+}
+export function fileImages(fileKey, nodeIds) {
+    return get(`/files/${encodeURIComponent(fileKey)}/images?ids=${encodeURIComponent(nodeIds)}&format=png`);
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function createServer(): McpServer;

package/dist/server.js

@@ -0,0 +1,163 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { errorMessage, me, getFile, projectFiles, teamProjects, fileComments, fileVersions, fileComponents, fileStyles, fileNodes, fileImages, } from "./api.js";
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const textError = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+const READ_ONLY = { readOnlyHint: true, openWorldHint: true };
+export function createServer() {
+    const server = new McpServer({
+        name: "figma-mcp",
+        version: "1.0.0",
+    });
+    server.registerTool("me", {
+        title: "My profile",
+        description: "The Figma user the access token belongs to.",
+        inputSchema: z.object({}),
+        annotations: READ_ONLY,
+    }, async ({}) => {
+        try {
+            return text(await me());
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("get_file", {
+        title: "Get file",
+        description: "File metadata: name, pages and last modified date.",
+        inputSchema: z.object({
+            file_key: z.string().describe("File key from URL.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ file_key }) => {
+        try {
+            return text(await getFile(file_key));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("project_files", {
+        title: "Project files",
+        description: "Figma files inside one project id.",
+        inputSchema: z.object({
+            project_id: z.string().describe("Project ID from the Figma URL")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ project_id }) => {
+        try {
+            return text(await projectFiles(project_id));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("team_projects", {
+        title: "Team projects",
+        description: "Projects in a team.",
+        inputSchema: z.object({
+            team_id: z.string().describe("Team ID.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ team_id }) => {
+        try {
+            return text(await teamProjects(team_id));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("file_comments", {
+        title: "File comments",
+        description: "Comments on a file.",
+        inputSchema: z.object({
+            file_key: z.string().describe("File key.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ file_key }) => {
+        try {
+            return text(await fileComments(file_key));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("file_versions", {
+        title: "File versions",
+        description: "Version history.",
+        inputSchema: z.object({
+            file_key: z.string().describe("File key.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ file_key }) => {
+        try {
+            return text(await fileVersions(file_key));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("file_components", {
+        title: "Components",
+        description: "Published components.",
+        inputSchema: z.object({
+            file_key: z.string().describe("File key.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ file_key }) => {
+        try {
+            return text(await fileComponents(file_key));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("file_styles", {
+        title: "Styles",
+        description: "Published styles.",
+        inputSchema: z.object({
+            file_key: z.string().describe("File key.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ file_key }) => {
+        try {
+            return text(await fileStyles(file_key));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("file_nodes", {
+        title: "File nodes",
+        description: "Nodes by IDs.",
+        inputSchema: z.object({
+            file_key: z.string().describe("File key."),
+            node_ids: z.string().describe("Comma-separated node IDs.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ file_key, node_ids }) => {
+        try {
+            return text(await fileNodes(file_key, node_ids));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    server.registerTool("file_images", {
+        title: "Render nodes",
+        description: "PNG renders.",
+        inputSchema: z.object({
+            file_key: z.string().describe("File key."),
+            node_ids: z.string().describe("Comma-separated node IDs.")
+        }),
+        annotations: READ_ONLY,
+    }, async ({ file_key, node_ids }) => {
+        try {
+            return text(await fileImages(file_key, node_ids));
+        }
+        catch (e) {
+            return textError(errorMessage(e));
+        }
+    });
+    return server;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrfentmen/figma-mcp",
-  "version": "1.0.0",
-  "description": "Figma me, files, projects. Token.",
+  "version": "1.1.0",
+  "description": "Query the Figma API (token; set FIGMA_ACCESS_TOKEN, X-Figma-Token): profile, file details, project files.",
   "type": "module",
   "mcpName": "io.github.mrfentmen/figma-mcp",
   "repository": {