Add CLAUDE.md for Claude Code guidance#204
Open
apietosi wants to merge 1 commit intoahujasid:mainfrom
Open
Conversation
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Review Summary by QodoAdd CLAUDE.md documentation for Claude Code guidance
WalkthroughsDescription• Adds comprehensive CLAUDE.md guidance document for Claude Code • Documents project architecture with two-component design overview • Includes development commands, environment variables, and key file roles • Provides instructions for adding new MCP tools and telemetry system details Diagramflowchart LR
A["CLAUDE.md<br/>Documentation"] --> B["Project Overview<br/>Architecture"]
A --> C["Development<br/>Commands"]
A --> D["MCP Tools<br/>Integration Guide"]
A --> E["Telemetry<br/>System Details"]
B --> F["Blender Addon<br/>+ MCP Server"]
C --> G["UV Package Manager<br/>Environment Variables"]
File Changes1. CLAUDE.md
|
Code Review by Qodo
1. Telemetry decorator name wrong
|
📝 WalkthroughWalkthroughA new documentation file CLAUDE.md is added detailing Claude Code integration with BlenderMCP, covering architecture, communication flow, socket behavior, environment variables, main components, instructions for extending MCP tools, and telemetry configuration details. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
CLAUDE.md (3)
35-35: Clarify timeout scope.The "180s timeout" is accurate based on the code, but consider clarifying that this is a per-command timeout for both sending and receiving responses, not a connection timeout. This helps developers understand what happens when long-running Blender operations are invoked.
📝 Suggested clarification
-Commands are sent as JSON and responses are received in chunks (180s timeout). +Commands are sent as JSON and responses are received in chunks (180s per-command timeout for send/receive operations).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` at line 35, Update the CLAUDE.md description to state that the "180s timeout" in server.py's BlenderConnection is a per-command timeout applied to both sending the JSON command and receiving the response (send/recv calls), not a connection-level timeout; mention that long-running Blender operations may trigger this per-command timeout (resulting in a timeout error for that command) while the TCP connection itself remains a singleton and persistent unless explicitly closed.
38-39: Remove brittle file size and line count metrics.The specific metrics "111KB" and "1,185 lines" will quickly become outdated and require manual maintenance. These numbers don't add meaningful context for understanding the codebase. Focus on the functional descriptions instead.
♻️ Proposed simplification
-- `addon.py` — Blender extension (111KB): socket server, all actual Blender operations, asset downloads, AI model generation API calls -- `src/blender_mcp/server.py` — MCP server (1,185 lines): 22 tool definitions using FastMCP, `BlenderConnection` class, server lifecycle management +- `addon.py` — Blender extension: socket server, all actual Blender operations, asset downloads, AI model generation API calls +- `src/blender_mcp/server.py` — MCP server: MCP tool definitions using FastMCP, `BlenderConnection` class, server lifecycle management🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 38 - 39, Remove the brittle size/line-count annotations from the listed file descriptions (the entries referencing `addon.py` and `src/blender_mcp/server.py`) and keep only the functional descriptions; for example, change "`addon.py` — Blender extension (111KB): socket server, ...`" to "`addon.py` — Blender extension: socket server, all actual Blender operations, asset downloads, AI model generation API calls`" and similarly remove "(1,185 lines)" from the `src/blender_mcp/server.py` entry while preserving its functional summary and mentions of `BlenderConnection` and FastMCP tool definitions.
56-57: Consider clarifying the consent model.The "two-tier consent model" is mentioned but not explained. Clarify how users grant consent and what triggers the transition between tiers. This helps developers understand the telemetry behavior when debugging or extending the system.
📝 Suggested clarification
-The telemetry system stores to Supabase. Without user consent: only tool name, success/failure, duration. With consent: prompts, code, screenshots. +The telemetry system stores to Supabase with a two-tier consent model. Basic tier (default): only tool name, success/failure, duration. Enhanced tier (with explicit user consent): prompts, code, screenshots.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@CLAUDE.md` around lines 56 - 57, Update the "Telemetry" section in CLAUDE.md to explicitly describe the two-tier consent model: state who can grant consent (end-user vs admin), how consent is granted (e.g., interactive prompt on first run, a CLI flag, or setting a config/env var), what exact action transitions telemetry from the minimal tier to the full-data tier (e.g., user accepts consent prompt or sets BLENDER_MCP_ENABLE_TELEMETRY=true), and whether consent is persisted (reference customer UUID storage at ~/.local/share/BlenderMCP/customer_uuid.txt) and how it can be revoked (removing env vars or a config toggle); mention the three env vars DISABLE_TELEMETRY, BLENDER_MCP_DISABLE_TELEMETRY, MCP_DISABLE_TELEMETRY and the precedence if multiple are set.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Around line 22-26: Update the environment variables section in CLAUDE.md to
document all supported telemetry opt-out variables by adding
BLENDER_MCP_DISABLE_TELEMETRY and MCP_DISABLE_TELEMETRY alongside
DISABLE_TELEMETRY, and clarify that any one of these three (DISABLE_TELEMETRY,
BLENDER_MCP_DISABLE_TELEMETRY, MCP_DISABLE_TELEMETRY) will disable telemetry;
modify the block that currently shows DISABLE_TELEMETRY to list the three
variables and a brief note like "Telemetry opt-out (any of these work)" so
readers can find all supported options.
---
Nitpick comments:
In `@CLAUDE.md`:
- Line 35: Update the CLAUDE.md description to state that the "180s timeout" in
server.py's BlenderConnection is a per-command timeout applied to both sending
the JSON command and receiving the response (send/recv calls), not a
connection-level timeout; mention that long-running Blender operations may
trigger this per-command timeout (resulting in a timeout error for that command)
while the TCP connection itself remains a singleton and persistent unless
explicitly closed.
- Around line 38-39: Remove the brittle size/line-count annotations from the
listed file descriptions (the entries referencing `addon.py` and
`src/blender_mcp/server.py`) and keep only the functional descriptions; for
example, change "`addon.py` — Blender extension (111KB): socket server, ...`" to
"`addon.py` — Blender extension: socket server, all actual Blender operations,
asset downloads, AI model generation API calls`" and similarly remove "(1,185
lines)" from the `src/blender_mcp/server.py` entry while preserving its
functional summary and mentions of `BlenderConnection` and FastMCP tool
definitions.
- Around line 56-57: Update the "Telemetry" section in CLAUDE.md to explicitly
describe the two-tier consent model: state who can grant consent (end-user vs
admin), how consent is granted (e.g., interactive prompt on first run, a CLI
flag, or setting a config/env var), what exact action transitions telemetry from
the minimal tier to the full-data tier (e.g., user accepts consent prompt or
sets BLENDER_MCP_ENABLE_TELEMETRY=true), and whether consent is persisted
(reference customer UUID storage at ~/.local/share/BlenderMCP/customer_uuid.txt)
and how it can be revoked (removing env vars or a config toggle); mention the
three env vars DISABLE_TELEMETRY, BLENDER_MCP_DISABLE_TELEMETRY,
MCP_DISABLE_TELEMETRY and the precedence if multiple are set.
Comment on lines
+22
to
+26
| ```bash | ||
| BLENDER_HOST=localhost # default | ||
| BLENDER_PORT=9876 # default | ||
| DISABLE_TELEMETRY=true # opt-out of telemetry | ||
| ``` |
There was a problem hiding this comment.
Document all telemetry disable environment variables.
Line 25 only mentions DISABLE_TELEMETRY, but line 57 (and the telemetry code) support three variants: DISABLE_TELEMETRY, BLENDER_MCP_DISABLE_TELEMETRY, and MCP_DISABLE_TELEMETRY. For completeness, document all three options in the environment variables section.
📝 Suggested addition
Environment variables:
```bash
BLENDER_HOST=localhost # default
BLENDER_PORT=9876 # default
-DISABLE_TELEMETRY=true # opt-out of telemetry
+# Telemetry opt-out (any of these work):
+DISABLE_TELEMETRY=true
+BLENDER_MCP_DISABLE_TELEMETRY=true
+MCP_DISABLE_TELEMETRY=true</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **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.
```suggestion
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@CLAUDE.md` around lines 22 - 26, Update the environment variables section in
CLAUDE.md to document all supported telemetry opt-out variables by adding
BLENDER_MCP_DISABLE_TELEMETRY and MCP_DISABLE_TELEMETRY alongside
DISABLE_TELEMETRY, and clarify that any one of these three (DISABLE_TELEMETRY,
BLENDER_MCP_DISABLE_TELEMETRY, MCP_DISABLE_TELEMETRY) will disable telemetry;
modify the block that currently shows DISABLE_TELEMETRY to list the three
variables and a brief note like "Telemetry opt-out (any of these work)" so
readers can find all supported options.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
CLAUDE.mdfile to help Claude Code understand the project structure and conventions when working in this repositoryWhat's included
🤖 Generated with Claude Code
Summary by CodeRabbit