From 182ca334f0b22961f171621d0758753471e06b80 Mon Sep 17 00:00:00 2001 From: Shayan Rais Date: Mon, 2 Mar 2026 13:15:36 +0500 Subject: [PATCH] added more concepts --- .claude/settings.json | 2 +- .gitignore | 2 +- .mcp.json | 24 ++++ README.md | 48 +------ .../claude-cli-startup-flags.md | 8 +- best-practice/claude-mcp.md | 119 ++++++++++++++++++ 6 files changed, 157 insertions(+), 46 deletions(-) create mode 100644 .mcp.json rename {reports => best-practice}/claude-cli-startup-flags.md (96%) create mode 100644 best-practice/claude-mcp.md diff --git a/.claude/settings.json b/.claude/settings.json index 86aeec5..379ef96 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -66,7 +66,7 @@ "outputStyle": "Explanatory", "statusLine": { "type": "command", - "command": "echo 'this is a status line'", + "command": "echo 'shayan's best practice status line'", "padding": 0 }, "attribution": { diff --git a/.gitignore b/.gitignore index c23d465..8b13789 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1 @@ -.mcp.json + diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..3b20d11 --- /dev/null +++ b/.mcp.json @@ -0,0 +1,24 @@ +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp"] + }, + "reddit-mcp-server": { + "type": "http", + "url": "http://144.91.76.33:8080/mcp" + }, + "tavily-web-search": { + "type": "http", + "url": "https://mcp.tavily.com/mcp/?tavilyApiKey=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" + }, + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + }, + "deepwiki": { + "command": "npx", + "args": ["-y", "deepwiki-mcp"] + } + } +} diff --git a/README.md b/README.md index 0bd5380..9f41cb2 100644 --- a/README.md +++ b/README.md @@ -26,14 +26,17 @@ practice makes claude perfect | [**Commands**](https://code.claude.com/docs/en/skills) | `.claude/commands/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-commands.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-commands-implementation.md) Entry-point prompts for workflows — invoke with `/command-name` | | [**Sub-Agents**](https://code.claude.com/docs/en/sub-agents) | `.claude/agents/.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-subagents.md) [![Implemented](!/tags/implemented.svg)](implementation/claude-subagents-implementation.md) Custom agents with their own name, color, tools, permissions, and model · [Agent Teams](https://code.claude.com/docs/en/agent-teams) | | [**Skills**](https://code.claude.com/docs/en/skills) | `.claude/skills//SKILL.md` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-commands.md#skills-frontmatter-fields) [![Implemented](!/tags/implemented.svg)](implementation/claude-skills-implementation.md) Reusable knowledge, workflows, and slash commands — load on-demand or invoke with `/skill-name` | +| [**Workflows**](https://code.claude.com/docs/en/common-workflows) | [`.claude/commands/weather-orchestrator.md`](.claude/commands/weather-orchestrator.md) | [![Orchestration Workflow](!/tags/orchestration-workflow.svg)](orchestration-workflow/orchestration-workflow.md) | | [**Hooks**](https://code.claude.com/docs/en/hooks) | `.claude/hooks/` | [![Best Practice](!/tags/best-practice.svg)](https://github.com/shanraisshan/claude-code-voice-hooks) [![Implemented](!/tags/implemented.svg)](.claude/hooks/) Deterministic scripts that run outside the agentic loop on specific events | -| [**MCP Servers**](https://code.claude.com/docs/en/mcp) | `.claude/settings.json`, `.mcp.json` | [![Implemented](!/tags/implemented.svg)](.mcp.json) Model Context Protocol connections to external tools, databases, and APIs | +| [**MCP Servers**](https://code.claude.com/docs/en/mcp) | `.claude/settings.json`, `.mcp.json` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-mcp.md) [![Implemented](!/tags/implemented.svg)](.mcp.json) Model Context Protocol connections to external tools, databases, and APIs | | [**Plugins**](https://code.claude.com/docs/en/plugins) | distributable packages | Bundles of skills, subagents, hooks, and MCP servers · [Marketplaces](https://code.claude.com/docs/en/discover-plugins) | | [**Settings**](https://code.claude.com/docs/en/settings) | `.claude/settings.json` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-settings.md) [![Implemented](!/tags/implemented.svg)](.claude/settings.json) Hierarchical configuration system · [Permissions](https://code.claude.com/docs/en/permissions) · [Model Config](https://code.claude.com/docs/en/model-config) · [Output Styles](https://code.claude.com/docs/en/output-styles) · [Sandboxing](https://code.claude.com/docs/en/sandboxing) · [Keybindings](https://code.claude.com/docs/en/keybindings) · [Fast Mode](https://code.claude.com/docs/en/fast-mode) | | [**Status Line**](https://code.claude.com/docs/en/statusline) | `.claude/settings.json` | [![Best Practice](!/tags/best-practice.svg)](https://github.com/shanraisshan/claude-code-status-line) [![Implemented](!/tags/implemented.svg)](.claude/settings.json) Customizable status bar showing context usage, model, cost, and session info | | [**Memory**](https://code.claude.com/docs/en/memory) | `CLAUDE.md`, `~/.claude/projects//memory/` | [![Implemented](!/tags/implemented.svg)](CLAUDE.md) Persistent context via CLAUDE.md files and `@path` imports · [Auto Memory](https://code.claude.com/docs/en/memory) · [Rules](https://code.claude.com/docs/en/memory#organize-rules-with-clauderules) | | [**Checkpointing**](https://code.claude.com/docs/en/checkpointing) | automatic (git-based) | Automatic tracking of file edits with rewind (`Esc Esc` or `/rewind`) and targeted summarization | | [**Remote Control**](https://code.claude.com/docs/en/remote-control) | CLI / claude.ai | Continue local sessions from any device — phone, tablet, or browser · [Headless Mode](https://code.claude.com/docs/en/headless) | +| [**CLI Startup Flags**](https://code.claude.com/docs/en/cli-reference) | `claude [flags]` | [![Best Practice](!/tags/best-practice.svg)](best-practice/claude-cli-startup-flags.md) Command-line flags, subcommands, and environment variables for launching Claude Code | +| [**Best Practices**](https://code.claude.com/docs/en/best-practices) | | Official best practices · [Extend Claude Code](https://code.claude.com/docs/en/features-overview) | > **Note:** Custom slash commands have been merged into skills. Files in `.claude/commands/` still work, but skills (`.claude/skills/`) are recommended as they support additional features like supporting files, invocation control, and subagent execution. @@ -123,53 +126,13 @@ See [orchestration-workflow](orchestration-workflow/orchestration-workflow.md) f [**See Complete List →**](https://github.com/shanraisshan/claude-code-codex-cursor-gemini/blob/main/reports/ai-terms.md) -## CLI STARTUP FLAGS - -| | | | | | -|---|---|---|---|---| -| `--dangerously-skip-permissions` | `--model` | `--print` | `--resume` | `--continue` | -| `--system-prompt` | `--verbose` | `--debug` | `--init` | `--max-turns` | - -[**See Complete List →**](reports/claude-cli-startup-flags.md) - -## CLAUDE COMMANDS - -| | | | | | -|---|---|---|---|---| -| `/compact` | `/context` | `/model` | `/plan` | `/config` | -| `/clear` | `/cost` | `/memory` | `/doctor` | `/rewind` | - -[**See Complete List →**](best-practice/claude-commands.md) - - -## CLAUDE SETTINGS - -| | | -|---|---| -| [**Claude Settings**](best-practice/claude-settings.md) | [**Global vs Project Settings**](reports/claude-global-vs-project-settings.md) | - - -## MCP SERVERS FOR DAILY USE - -> *"Went overboard with 15 MCP servers thinking more = better. Ended up using only 4 daily."* — [r/mcp](https://reddit.com/r/mcp/comments/1mj0fxs/) (682 upvotes) - -| MCP Server | What It Does | Resources | -|------------|-------------|-----------| -| [**Context7**](https://github.com/upstash/context7) | Fetches up-to-date library docs into context. Prevents hallucinated APIs from outdated training data | [Reddit: "by far the best MCP for coding"](https://reddit.com/r/mcp/comments/1qarjqm/) · [npm](https://www.npmjs.com/package/@upstash/context7-mcp) | -| [**Playwright**](https://github.com/microsoft/playwright-mcp) | Browser automation — implement, test, and verify UI features autonomously. Screenshots, navigation, form testing | [Reddit: essential for frontend](https://reddit.com/r/mcp/comments/1m59pk0/) · [Docs](https://playwright.dev/) | -| [**Claude in Chrome**](https://github.com/nicobailon/claude-code-in-chrome-mcp) | Connects Claude to your real Chrome browser — inspect console, network, DOM. Debug what users actually see | [Reddit: "game changer" for debugging](https://reddit.com/r/mcp/comments/1qarjqm/5_mcps_that_have_genuinely_made_me_10x_faster/nza0i7t/) · [Comparison Report](reports/claude-in-chrome-v-chrome-devtools-mcp.md) | -| [**DeepWiki**](https://github.com/devanshusemwal/deepwiki-mcp) | Fetches structured wiki-style documentation for any GitHub repo — architecture, API surface, relationships | [Reddit: "put it behind a gateway with Context7"](https://reddit.com/r/mcp/comments/1qarjqm/) | -| [**Excalidraw**](https://github.com/antonpk1/excalidraw-mcp-app) | Generate architecture diagrams, flowcharts, and system designs as hand-drawn Excalidraw sketches from prompts | [GitHub](https://github.com/antonpk1/excalidraw-mcp-app) | - -Research (Context7/DeepWiki) -> Debug (Playwright/Chrome) -> Document (Excalidraw) - ## REPORTS | Report | Description | |--------|-------------| | [Agent SDK vs CLI System Prompts](reports/claude-agent-sdk-vs-cli-system-prompts.md) | Why Claude CLI and Agent SDK outputs may differ—system prompt architecture and determinism | | [Browser Automation MCP Comparison](reports/claude-in-chrome-v-chrome-devtools-mcp.md) | Comparison of Playwright, Chrome DevTools, and Claude in Chrome for automated testing | -| [Claude Code CLI Startup Flags](reports/claude-cli-startup-flags.md) | Complete reference of all CLI flags, subcommands, and environment variables | +| [CLI Startup Flags Best Practice](best-practice/claude-cli-startup-flags.md) | Complete reference of all CLI flags, subcommands, and environment variables | | [CLAUDE.md Loading in Monorepos](reports/claude-md-for-larger-mono-repos.md) | Understanding ancestor vs descendant loading behavior for CLAUDE.md files | | [Global vs Project Settings](reports/claude-global-vs-project-settings.md) | Which features are global-only (`~/.claude/`) vs dual-scope, including Tasks and Agent Teams | | [Skills Discovery in Monorepos](reports/claude-skills-for-larger-mono-repos.md) | How skills are discovered and loaded in large monorepo projects | @@ -180,3 +143,4 @@ Research (Context7/DeepWiki) -> Debug (Playwright/Chrome) -> Document (Excalidra | [Commands Reference](best-practice/claude-commands.md) | Complete reference for Claude Code commands — command definitions, frontmatter fields, and all built-in slash commands | | [Claude Code Settings Reference](best-practice/claude-settings.md) | Comprehensive guide to all `settings.json` configuration options | | [Subagents Reference](best-practice/claude-subagents.md) | Complete reference for Claude Code subagents — built-in agents, custom agents, and frontmatter fields | +| [MCP Servers Best Practice](best-practice/claude-mcp.md) | Recommended MCP servers for daily use, configuration, scopes, and permission patterns | diff --git a/reports/claude-cli-startup-flags.md b/best-practice/claude-cli-startup-flags.md similarity index 96% rename from reports/claude-cli-startup-flags.md rename to best-practice/claude-cli-startup-flags.md index 10b1be2..9006690 100644 --- a/reports/claude-cli-startup-flags.md +++ b/best-practice/claude-cli-startup-flags.md @@ -1,6 +1,8 @@ -# Claude Code CLI Startup Flags Reference +# CLI Startup Flags Best Practice -A comprehensive reference of all available command-line flags when launching Claude Code from the terminal. +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2002%2C%202026-white?style=flat&labelColor=555) + +Complete reference of all available command-line flags, subcommands, and environment variables when launching Claude Code from the terminal. @@ -9,6 +11,8 @@ A comprehensive reference of all available command-line flags when launching Cla
+--- + ## Table of Contents 1. [Session Management](#session-management) diff --git a/best-practice/claude-mcp.md b/best-practice/claude-mcp.md new file mode 100644 index 0000000..e05cc9c --- /dev/null +++ b/best-practice/claude-mcp.md @@ -0,0 +1,119 @@ +# MCP Servers Best Practice + +![Last Updated](https://img.shields.io/badge/Last_Updated-Mar%2002%2C%202026%2012%3A30%20PM%20PKT-white?style=flat&labelColor=555)
+[![Implemented](https://img.shields.io/badge/Implemented-2ea44f?style=flat)](../.mcp.json) + +MCP (Model Context Protocol) servers extend Claude Code with connections to external tools, databases, and APIs. This guide covers recommended servers for daily use and configuration best practices. + + + + + + +
← Back to Claude Code Best PracticeClaude
+ +--- + +## MCP Servers for Daily Use + +> *"Went overboard with 15 MCP servers thinking more = better. Ended up using only 4 daily."* — [r/mcp](https://reddit.com/r/mcp/comments/1mj0fxs/) (682 upvotes) + +| MCP Server | What It Does | Resources | +|------------|-------------|-----------| +| [**Context7**](https://github.com/upstash/context7) | Fetches up-to-date library docs into context. Prevents hallucinated APIs from outdated training data | [Reddit: "by far the best MCP for coding"](https://reddit.com/r/mcp/comments/1qarjqm/) · [npm](https://www.npmjs.com/package/@upstash/context7-mcp) | +| [**Playwright**](https://github.com/microsoft/playwright-mcp) | Browser automation — implement, test, and verify UI features autonomously. Screenshots, navigation, form testing | [Reddit: essential for frontend](https://reddit.com/r/mcp/comments/1m59pk0/) · [Docs](https://playwright.dev/) | +| [**Claude in Chrome**](https://github.com/nicobailon/claude-code-in-chrome-mcp) | Connects Claude to your real Chrome browser — inspect console, network, DOM. Debug what users actually see | [Reddit: "game changer" for debugging](https://reddit.com/r/mcp/comments/1qarjqm/5_mcps_that_have_genuinely_made_me_10x_faster/nza0i7t/) · [Comparison Report](../reports/claude-in-chrome-v-chrome-devtools-mcp.md) | +| [**DeepWiki**](https://github.com/devanshusemwal/deepwiki-mcp) | Fetches structured wiki-style documentation for any GitHub repo — architecture, API surface, relationships | [Reddit: "put it behind a gateway with Context7"](https://reddit.com/r/mcp/comments/1qarjqm/) | +| [**Excalidraw**](https://github.com/antonpk1/excalidraw-mcp-app) | Generate architecture diagrams, flowcharts, and system designs as hand-drawn Excalidraw sketches from prompts | [GitHub](https://github.com/antonpk1/excalidraw-mcp-app) | + +Research (Context7/DeepWiki) -> Debug (Playwright/Chrome) -> Document (Excalidraw) + +--- + +## Configuration + +MCP servers are configured in `.mcp.json` at the project root (project-scoped) or in `~/.claude.json` (user-scoped). + +### Server Types + +| Type | Transport | Example | +|------|-----------|---------| +| **stdio** | Spawns a local process | `npx`, `python`, binary | +| **http** | Connects to a remote URL | HTTP/SSE endpoint | + +### Example `.mcp.json` + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + }, + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp"] + }, + "deepwiki": { + "command": "npx", + "args": ["-y", "deepwiki-mcp"] + }, + "remote-api": { + "type": "http", + "url": "https://mcp.example.com/mcp" + } + } +} +``` + +### Settings for MCP Servers + +These settings in `.claude/settings.json` control MCP server approval: + +| Key | Type | Description | +|-----|------|-------------| +| `enableAllProjectMcpServers` | boolean | Auto-approve all `.mcp.json` servers without prompting | +| `enabledMcpjsonServers` | array | Allowlist of specific server names to auto-approve | +| `disabledMcpjsonServers` | array | Blocklist of specific server names to reject | + +### Permission Rules for MCP Tools + +MCP tools follow the `mcp____` naming convention in permission rules: + +```json +{ + "permissions": { + "allow": [ + "mcp__*", + "mcp__context7__*", + "mcp__playwright__browser_snapshot" + ], + "deny": [ + "mcp__dangerous-server__*" + ] + } +} +``` + +--- + +## MCP Scopes + +MCP servers can be defined at three levels: + +| Scope | Location | Purpose | +|-------|----------|---------| +| **Project** | `.mcp.json` (repo root) | Team-shared servers, committed to git | +| **User** | `~/.claude.json` (`mcpServers` key) | Personal servers across all projects | +| **Subagent** | Agent frontmatter (`mcpServers` field) | Servers scoped to a specific subagent | + +Precedence: Subagent > Project > User + +--- + +## Sources + +- [MCP Servers — Claude Code Docs](https://code.claude.com/docs/en/mcp) +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) +- [5 MCPs that have genuinely made me 10x faster — r/mcp](https://reddit.com/r/mcp/comments/1qarjqm/) +- [MCP Server Overload Discussion — r/mcp](https://reddit.com/r/mcp/comments/1mj0fxs/)