yet-another-figma-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with code in this repository.

Environment Variables

• FIGMA_API_TOKEN (必須): Figma API の Personal Access Token。cache コマンドで Figma API にアクセスする際に必要

export FIGMA_API_TOKEN="figd_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Cache Directory

キャッシュデータはデフォルトで ~/.yet_another_figma_mcp/ に保存される。

~/.yet_another_figma_mcp/
└── <file_id>/
    ├── file_raw.json      # Figma API レスポンス (生データ)
    ├── nodes_index.json   # 検索用インデックス
    └── cache_meta.json    # キャッシュメタデータ (タイムスタンプ)

--cache-dir オプションで変更可能。

CLI Commands

# Figma ファイルをキャッシュ (単一ファイル)
yet-another-figma-mcp cache -f <file_id>

# 複数ファイルをキャッシュ
yet-another-figma-mcp cache -f <file_id_1> -f <file_id_2>

# ファイルリストからキャッシュ
yet-another-figma-mcp cache -l file_ids.txt

# キャッシュを強制更新
yet-another-figma-mcp cache -f <file_id> --refresh

# キャッシュ状態を確認
yet-another-figma-mcp status

# MCP サーバーを起動
yet-another-figma-mcp serve

# 詳細ログ付きで起動
yet-another-figma-mcp serve --verbose

Build and Development Commands

# Install dependencies (uses PEP 735 dependency groups)
uv sync --group dev

# Run all tests
uv run pytest

# Run tests in parallel (faster for large test suites)
uv run pytest -n auto

# Run a single test file
uv run pytest tests/cache/store_test.py

# Run a specific test function
uv run pytest tests/cache/store_test.py::TestCacheStore::test_cache_store_loads_from_disk

# Detect flaky tests (run each test multiple times)
uv run pytest --flake-finder --flake-runs=10

# Reproduce test order from a specific random seed
uv run pytest --randomly-seed=<seed>

# Type checking
uv run pyright

# Lint and format
uv run ruff check --fix .
uv run ruff format .

# Run all pre-commit hooks
uv run pre-commit run --all-files

Architecture

Figma MCP サーバーで、Figma 無料プランの API 制限 (月 6 回) を回避するためにファイルを事前キャッシュする。

Core Flow

1. CLI (cli/) → cache, serve, status コマンドを提供
2. FigmaClient (figma/client.py) → API 呼び出しと JSON 保存
3. Index Builder (cache/index.py) → by_id, by_name, by_frame_title の 3 種類のインデックス生成
4. CacheStore (cache/store.py) → ディスクからキャッシュをロード、インメモリで保持
5. MCP Server (server.py) → 5 つのツールを MCP プロトコルで公開