Skip to content

docs: MCP vs CLI feature comparison (#20) #26

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
let-sunny merged 3 commits into from
Mar 24, 2026
Merged

docs: MCP vs CLI feature comparison (#20) #26

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7d94948
docs: MCP vs CLI feature comparison (#20)
let-sunny Mar 24, 2026
56cb4f7
docs: address PR review for MCP vs CLI documentation
let-sunny Mar 24, 2026
182a501
docs: address CodeRabbit review comments on MCP vs CLI docs
let-sunny Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .claude/skills/canicode/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,22 @@ Note: The first time you connect, Figma OAuth will prompt you to authorize in th

Do NOT proceed with analysis if Figma MCP is not available. Do NOT fall back to CLI `--mcp` mode.

## CLI vs this skill (Figma MCP)

This skill is the **MCP path** only. For some goals, `canicode analyze` with **FIGMA_TOKEN** (CLI) is a better fit:

| Feature | CLI (REST API) | This skill (Figma MCP) |
|---------|:-:|:-:|
| Node structure | ✅ Full tree | ✅ XML metadata |
| Style values | ✅ Raw Figma JSON | ✅ React+Tailwind from design context |
| Component metadata (name, desc) | ✅ | ❌ |
| Component master trees | ✅ `componentDefinitions` | ❌ |
| Annotations (dev mode) | ❌ private beta | ✅ `data-annotations` in code |
| Screenshots | ✅ via API | ✅ `get_screenshot` |
| FIGMA_TOKEN | Required for live API | Not required when Figma MCP is connected |
Comment on lines +37 to +45
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify the Screenshots row presence across all comparison tables

echo "=== README.md Screenshots row ==="
rg -n "Screenshots" README.md

echo -e "\n=== SKILL.md Screenshots row ==="
rg -n "Screenshots" .claude/skills/canicode/SKILL.md

echo -e "\n=== CLAUDE.md Screenshots row ==="
rg -n "Screenshots" CLAUDE.md

Repository: let-sunny/canicode

Length of output: 268

Add the missing Screenshots row to the feature comparison table.

The feature comparison table in SKILL.md is missing the Screenshots row that appears in README.md and CLAUDE.md. Since the skill includes get_screenshot functionality, add the row for consistency:

| Screenshots | ✅ via API | ✅ `get_screenshot` |
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.claude/skills/canicode/SKILL.md around lines 37 - 44, Add a new
"Screenshots" row to the feature comparison table in SKILL.md so it matches
README/CLAUDE.md; insert a table row reading "| Screenshots | ✅ via API | ✅
`get_screenshot` |" into the existing markdown table (keep the pipe-aligned
format and the header separator row intact) and ensure the `get_screenshot` cell
uses backticks like other code items.


Use **CLI + token** when the user needs accurate component analysis. Use **this skill** for fast checks and workflows that rely on dev annotations.

## How to Analyze a Figma URL

When the user provides a Figma URL, follow these steps:
Expand Down
19 changes: 19 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,8 @@ app/ # Browser runtime
- Output: HTML report (opens in browser)
- Options: `--preset`, `--token`, `--output`, `--custom-rules`, `--config`
- Also: `canicode save-fixture` to save Figma data as JSON for offline analysis
- Component master resolution: fetches `componentDefinitions` for accurate component analysis
- Annotations: NOT available (REST API annotations field is private beta)

**2. MCP Server (`canicode-mcp`)**
- Install: `claude mcp add canicode -- npx -y -p canicode canicode-mcp`
Expand All @@ -62,6 +64,23 @@ app/ # Browser runtime
- No FIGMA_TOKEN needed when using Figma MCP
- Also works standalone with FIGMA_TOKEN (REST API fallback via `input` param)

**CLI vs MCP Feature Comparison**

| Feature | CLI (REST API) | MCP (Figma MCP) |
|---------|:-:|:-:|
| Node structure | ✅ Full tree | ✅ XML metadata |
| Style values | ✅ Raw Figma JSON | ✅ React+Tailwind code |
| Component metadata (name, desc) | ✅ | ❌ |
| Component master trees | ✅ `componentDefinitions` | ❌ |
| Annotations (dev mode) | ❌ private beta | ✅ `data-annotations` |
| Screenshots | ✅ via API | ✅ `get_screenshot` |
| FIGMA_TOKEN required | ✅ | ❌ |

**When to use which:**
- Accurate component analysis (style overrides, missing-component) → **CLI with FIGMA_TOKEN**
- Quick structure/style check, annotation-aware workflows → **MCP**
- Offline/CI analysis → **CLI with saved fixtures**

**3. Claude Code Skill (`/canicode`)**
- Location: `.claude/skills/canicode/SKILL.md` (copy to any project)
- Requires: Official Figma MCP (`https://mcp.figma.com/mcp`) at project level
Expand Down
22 changes: 22 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,28 @@ The rules themselves run deterministically on every analysis — no tokens consu
| Add to CI/CD | **[GitHub Action](https://github.com/marketplace/actions/canicode-action)** |
| Full control | **CLI** |

<details>
<summary><strong>CLI vs MCP</strong> (feature comparison)</summary>

Same detail as in [`CLAUDE.md`](CLAUDE.md); summarized here for quick reference.

| Feature | CLI (REST API) | MCP (Figma MCP) |
|---------|:-:|:-:|
| Node structure | ✅ Full tree | ✅ XML metadata |
| Style values | ✅ Raw Figma JSON | ✅ React+Tailwind code |
| Component metadata (name, desc) | ✅ | ❌ |
| Component master trees | ✅ `componentDefinitions` | ❌ |
| Annotations (dev mode) | ❌ private beta | ✅ `data-annotations` |
| Screenshots | ✅ via API | ✅ `get_screenshot` |
| FIGMA_TOKEN required | ✅ | ❌ |

**When to use which:**
- Accurate component analysis (style overrides, missing-component rules) → **CLI with FIGMA_TOKEN**
- Quick structure/style checks or annotation-aware flows → **MCP**
- Offline/CI → **CLI with saved fixtures** (`save-fixture`)

</details>

<details>
<summary><strong>CLI</strong></summary>

Expand Down
13 changes: 12 additions & 1 deletion src/mcp/server.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -281,7 +281,18 @@ claude mcp add -s project -t http figma https://mcp.figma.com/mcp
With Figma API token (no Figma MCP needed):
\`\`\`bash
claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y -p canicode canicode-mcp
\`\`\``,
\`\`\`

## CLI vs MCP

| Feature | CLI (FIGMA_TOKEN) | MCP (Figma MCP) |
|---------|:-:|:-:|
| Component master trees | ✅ | ❌ |
| Component metadata | ✅ | ❌ |
| Annotations (dev mode) | ❌ private beta | ✅ data-annotations |
| FIGMA_TOKEN required | ✅ | ❌ |

Use CLI for accurate component analysis. Use MCP for quick checks and annotation-aware workflows.`,
Comment on lines +284 to +295
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai bot Mar 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

CLI vs MCP comparison added to setup documentation.

The inline comparison table provides focused, context-relevant guidance for MCP users. The subset of rows (4 vs 7 in CLAUDE.md) appropriately highlights component-related differences critical for choosing between CLI and MCP workflows.

Minor: Inconsistent capitalization with CLAUDE.md.

Line 292 uses lowercase "private beta" while CLAUDE.md line 75 uses "Private beta" (capitalized). Consider standardizing the capitalization across both files for consistency.

✍️ Suggested capitalization fix 
-| Annotations (dev mode) | ❌ private beta | ✅ data-annotations |
+| Annotations (dev mode) | ❌ Private beta | ✅ data-annotations |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
\`\`\`
## CLI vs MCP
| Feature | CLI (FIGMA_TOKEN) | MCP (Figma MCP) |
|---------|:-:|:-:|
| Component master trees | ✅ | ❌ |
| Component metadata | ✅ | ❌ |
| Annotations (dev mode) | ❌ private beta | ✅ data-annotations |
| FIGMA_TOKEN required | ✅ | ❌ |
Use CLI for accurate component analysis. Use MCP for quick checks and annotation-aware workflows.`,
``
## CLI vs MCP
| Feature | CLI (FIGMA_TOKEN) | MCP (Figma MCP) |
|---------|:-:|:-:|
| Component master trees | ✅ | ❌ |
| Component metadata | ✅ | ❌ |
| Annotations (dev mode) | ❌ Private beta | ✅ data-annotations |
| FIGMA_TOKEN required | ✅ | ❌ |
Use CLI for accurate component analysis. Use MCP for quick checks and annotation-aware workflows.`,
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@src/mcp/server.ts` around lines 284 - 295, Update the capitalization in the
MCP vs CLI table: change the lowercase phrase "private beta" in the table row
for "Annotations (dev mode)" to "Private beta" so it matches the capitalization
used in CLAUDE.md; locate the string in src/mcp/server.ts inside the CLI vs MCP
table text and replace only that token to preserve surrounding formatting and
punctuation.


"visual-compare": `# Visual Compare

Expand Down
Loading