diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1868735..e6420ba 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -285,8 +285,9 @@ Optional MCP servers for extended capabilities. |--------|---------|--------| | Context7 | Library documentation lookup | Optional | | Sequential | Multi-step reasoning tools | Optional | -| Puppeteer | Browser automation | Optional | -| Magic | UI component generation | Optional | +| Playwright | Browser automation (Microsoft) | Optional | +| Memory | Persistent knowledge graph | Optional | +| Filesystem | Secure file operations | Optional | Setup: See `.claude/mcp/README.md` diff --git a/.claude/commands/brainstorm.md b/.claude/commands/brainstorm.md index ee127d6..b873a8f 100644 --- a/.claude/commands/brainstorm.md +++ b/.claude/commands/brainstorm.md @@ -180,6 +180,36 @@ After design is complete: | 4 | 8-10 | Comprehensive | | 5 | 10+ | Exhaustive, all angles | +## MCP Integration + +This command leverages MCP servers for enhanced brainstorming: + +### Sequential Thinking - Structured Exploration (Primary) +``` +ALWAYS use Sequential Thinking for brainstorming: +- Explore design options systematically +- Track pros/cons for each approach +- Revise conclusions based on user feedback +- Build confidence in final design incrementally +``` + +### Memory - Design Persistence +``` +Store design decisions for continuity: +- Create entities for design concepts +- Store user preferences and constraints +- Recall previous design patterns +- Build knowledge graph of architecture decisions +``` + +### Context7 - Technology Options +``` +When exploring technology choices: +- Fetch current documentation for options +- Compare library capabilities accurately +- Understand trade-offs with real data +``` + ## When NOT to Use - Clear "mechanical" processes with known implementation diff --git a/.claude/commands/feature.md b/.claude/commands/feature.md index 6031685..bfaa4b9 100644 --- a/.claude/commands/feature.md +++ b/.claude/commands/feature.md @@ -200,6 +200,47 @@ git diff --staged /feature --format=concise "add logging utility" ``` +## MCP Integration + +This command leverages MCP servers for enhanced capabilities: + +### Context7 - Library Documentation +When researching unfamiliar libraries or frameworks: +``` +Use Context7's resolve-library-id and get-library-docs tools to fetch +current documentation for any libraries involved in the feature. +``` + +### Sequential Thinking - Structured Planning +For complex feature breakdowns: +``` +Use Sequential Thinking's sequentialthinking tool for step-by-step +analysis when decomposing requirements or designing architecture. +``` + +### Memory - Context Persistence +Store and recall project context: +``` +- Store architectural decisions made during planning +- Recall user preferences from previous sessions +- Remember patterns used in similar features +``` + +### Filesystem - File Operations +For creating and modifying files: +``` +- Use directory_tree to understand project structure +- Use search_files to find related implementations +- Use read_file and write_file for file operations +``` + +### Playwright - E2E Testing +For features with UI components: +``` +Use Playwright for browser-based E2E testing of the implemented feature. +Validate user flows and interactions in real browser environment. +``` + ## Variations diff --git a/.claude/commands/fix.md b/.claude/commands/fix.md index 6ad5328..ecfa01a 100644 --- a/.claude/commands/fix.md +++ b/.claude/commands/fix.md @@ -262,6 +262,53 @@ for item in items: | `performance` | Speed, memory, efficiency | | `reliability` | Error handling, edge cases | +## MCP Integration + +This command leverages MCP servers for enhanced debugging: + +### Sequential Thinking - Root Cause Analysis (Primary) +``` +ALWAYS use Sequential Thinking for debugging: +- Trace execution path step-by-step +- Form and test hypotheses systematically +- Track confidence in each potential cause +- Revise understanding as evidence emerges +``` + +### Memory - Bug Context +``` +Store and recall debugging context: +- Remember similar bugs from previous sessions +- Recall fix patterns that worked before +- Store root cause analysis for future reference +- Create relations between bugs and affected components +``` + +### Playwright - Browser Testing +``` +For UI/frontend bugs: +- Reproduce the bug in browser environment +- Test fix across different browsers +- Verify visual regressions are resolved +- Automate regression test for the fix +``` + +### Context7 - Library Issues +``` +When debugging library-related issues: +- Fetch current documentation for correct usage +- Check for known issues or breaking changes +- Find correct patterns and examples +``` + +### Filesystem - Code Search +``` +For tracing bug across codebase: +- Use search_files to find related code +- Use read_file to examine suspicious areas +- Track changes with file history +``` + ## Variations diff --git a/.claude/commands/index.md b/.claude/commands/index.md index 164db3c..d8763c8 100644 --- a/.claude/commands/index.md +++ b/.claude/commands/index.md @@ -120,3 +120,25 @@ After generating the index, inform the user: 2. Number of files indexed 3. Key components discovered 4. Suggest using `/load` to load specific components into context + +## MCP Integration + +This command leverages MCP servers for enhanced indexing: + +### Filesystem - Project Scanning (Primary) +``` +ALWAYS use Filesystem for project scanning: +- Use directory_tree for full structure view +- Use list_directory for targeted exploration +- Use search_files to find specific patterns +- Use get_file_info for file metadata +``` + +### Memory - Project Knowledge +``` +Store project structure in knowledge graph: +- Create entities for key modules +- Store component relationships +- Recall structure in future sessions +- Build project understanding over time +``` diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md index 961f311..87de153 100644 --- a/.claude/commands/plan.md +++ b/.claude/commands/plan.md @@ -285,6 +285,44 @@ Use `/execute-plan [plan-file]` for subagent-driven execution with code review g | `deep-research` | Complex features needing investigation | | `implementation` | Quick plans for clear tasks | +## MCP Integration + +This command leverages MCP servers for enhanced planning: + +### Sequential Thinking - Structured Planning (Primary) +``` +ALWAYS use Sequential Thinking for task decomposition: +- Break complex tasks into logical thought sequences +- Track dependencies between steps +- Revise plan as understanding deepens +- Use for risk identification and mitigation planning +``` + +### Memory - Decision Persistence +``` +Store and recall planning context: +- Remember decisions from previous planning sessions +- Recall user preferences for task sizing +- Store architectural patterns for reuse +- Create entities for major features/components +``` + +### Context7 - Technology Research +``` +When planning involves unfamiliar technologies: +- Fetch current documentation for accurate estimates +- Understand API patterns before estimating complexity +- Identify potential integration challenges +``` + +### Filesystem - Codebase Analysis +``` +For accurate file identification: +- Use directory_tree to understand project structure +- Use search_files to find existing patterns +- Identify files to create vs modify +``` + ## Variations diff --git a/.claude/commands/research.md b/.claude/commands/research.md index 8874098..181f4af 100644 --- a/.claude/commands/research.md +++ b/.claude/commands/research.md @@ -61,6 +61,34 @@ Research: **$ARGUMENTS** | 4 | Comprehensive with trade-offs | | 5 | Exhaustive with citations | +## MCP Integration + +This command leverages MCP servers for enhanced research: + +### Context7 - Library Documentation (Primary) +``` +ALWAYS use Context7 for library/framework research: +1. Use resolve-library-id to find the library ID +2. Use get-library-docs with topic parameter for focused docs +3. Use mode='code' for API references, mode='info' for concepts +``` + +### Sequential Thinking - Structured Analysis +``` +For complex research requiring step-by-step reasoning: +- Use sequentialthinking tool to break down analysis +- Track confidence scores for each finding +- Revise conclusions as new information emerges +``` + +### Memory - Persistent Research +``` +Store research findings for future reference: +- Create entities for researched technologies +- Add observations with pros/cons/recommendations +- Link related technologies with relations +``` + ## Output ```markdown diff --git a/.claude/commands/review.md b/.claude/commands/review.md index 30a86b6..85f1ba1 100644 --- a/.claude/commands/review.md +++ b/.claude/commands/review.md @@ -291,6 +291,45 @@ Found **1 critical issue** (security), **2 recommendations**, and **2 suggestion | `quality` | Readability, maintainability | | `testing` | Coverage, test patterns | +## MCP Integration + +This command leverages MCP servers for enhanced code review: + +### Playwright - Visual/UI Review +``` +For reviewing UI changes: +- Render and screenshot components +- Compare visual changes across browsers +- Verify responsive behavior +- Check accessibility in real browser +``` + +### Memory - Review Context +``` +Store and recall review context: +- Remember past review decisions +- Recall user's coding standards +- Store patterns approved/rejected previously +- Track recurring issues across reviews +``` + +### Sequential Thinking - Systematic Analysis +``` +For thorough code analysis: +- Step through complex logic systematically +- Track multiple concerns in parallel +- Build comprehensive issue list +- Revise severity as context emerges +``` + +### Filesystem - Code Access +``` +For reviewing file changes: +- Use read_file to examine code +- Use search_files to find related patterns +- Check for similar issues across codebase +``` + ## Variations diff --git a/.claude/commands/test.md b/.claude/commands/test.md index 107a36b..35169e3 100644 --- a/.claude/commands/test.md +++ b/.claude/commands/test.md @@ -288,6 +288,44 @@ pytest tests/services/auth.test.ts -v | `jest` | JavaScript | | `playwright` | E2E (any) | +## MCP Integration + +This command leverages MCP servers for enhanced testing: + +### Playwright - E2E Testing (Primary for UI) +``` +For E2E and browser tests: +- Use Playwright for cross-browser testing +- Automate user flow verification +- Capture screenshots for visual testing +- Test on different device emulations +``` + +### Filesystem - Test File Management +``` +For test file operations: +- Use directory_tree to find test directories +- Use search_files to find existing tests +- Use read_file to check test patterns +- Use write_file to create new test files +``` + +### Context7 - Testing Best Practices +``` +For framework-specific testing: +- Fetch current testing library docs +- Get latest assertions and matchers +- Find recommended testing patterns +``` + +### Memory - Test Patterns +``` +Recall testing context: +- Remember project testing conventions +- Recall mock patterns used previously +- Store common test fixtures +``` + ## Variations diff --git a/.claude/mcp/README.md b/.claude/mcp/README.md index 87ea10b..8211643 100644 --- a/.claude/mcp/README.md +++ b/.claude/mcp/README.md @@ -8,8 +8,9 @@ Model Context Protocol (MCP) servers extend Claude Code capabilities with specia |--------|---------|--------| | Context7 | Up-to-date library documentation | Optional | | Sequential | Multi-step reasoning tools | Optional | -| Puppeteer | Browser automation | Optional | -| Magic | UI component generation | Optional | +| Playwright | Browser automation (Microsoft) | Optional | +| Memory | Persistent knowledge graph | Optional | +| Filesystem | Secure file operations | Optional | ## Installation @@ -21,14 +22,48 @@ Model Context Protocol (MCP) servers extend Claude Code capabilities with specia MCP servers are configured in your Claude Code settings: -**Location**: `~/.claude/settings.json` (user) or `.claude/settings.json` (project) +**Location**: `~/.claude/settings.json` (user) or `.mcp.json` (project) ### Quick Setup -1. Copy the desired configuration from the server-specific JSON files -2. Add to your `settings.json` under `mcpServers` +1. Copy the configuration for your platform (see below) +2. Add to your `.mcp.json` or `settings.json` under `mcpServers` 3. Restart Claude Code +## Platform-Specific Configuration + +MCP server configuration differs between platforms: + +### Linux / macOS + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +### Windows + +Windows requires the `cmd /c` wrapper to execute npx: + +```json +{ + "mcpServers": { + "context7": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp"] + } + } +} +``` + +> **Note**: The `.mcp.json` included in this repository uses Windows syntax. Linux/macOS users should use the configurations in this README. + ## Server Configurations ### Context7 (Documentation Lookup) @@ -40,7 +75,7 @@ Provides up-to-date documentation for libraries and frameworks. "mcpServers": { "context7": { "command": "npx", - "args": ["-y", "@context7/mcp-server"] + "args": ["-y", "@upstash/context7-mcp"] } } } @@ -48,6 +83,10 @@ Provides up-to-date documentation for libraries and frameworks. **Usage**: Ask about any library and get current documentation. +**Tools**: +- `resolve-library-id` - Find library IDs for documentation lookup +- `get-library-docs` - Fetch documentation for a specific library + ### Sequential Thinking Provides structured reasoning tools for complex problem-solving. @@ -65,16 +104,19 @@ Provides structured reasoning tools for complex problem-solving. **Usage**: Complex analysis with step-by-step reasoning. -### Puppeteer (Browser Automation) +**Tools**: +- `sequentialthinking` - Dynamic problem-solving through thought sequences -Enables browser automation for testing and web interaction. +### Playwright (Browser Automation) + +Microsoft's browser automation using accessibility tree for fast, LLM-friendly interaction. ```json { "mcpServers": { - "puppeteer": { + "playwright": { "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-puppeteer"] + "args": ["-y", "@playwright/mcp"] } } } @@ -82,44 +124,149 @@ Enables browser automation for testing and web interaction. **Usage**: Web testing, screenshots, form automation. -### Magic (UI Generation) +**Key Features**: +- Fast and lightweight - uses accessibility tree, not pixels +- LLM-friendly - no vision models needed +- Supports Chrome, Firefox, WebKit, Edge +- Device emulation and profile management -Generates UI components from descriptions. +**Command-Line Options**: +- `--browser ` - Browser to use (chrome, firefox, webkit, msedge) +- `--headless` - Run browser in headless mode +- `--viewport-size ` - Viewport size (e.g., "1280x720") +- `--device ` - Device to emulate (e.g., "iPhone 15") + +### Memory (Persistent Knowledge Graph) + +Maintains persistent memory across sessions using a local knowledge graph. ```json { "mcpServers": { - "magic": { + "memory": { "command": "npx", - "args": ["-y", "@anthropic/magic-mcp-server"] + "args": ["-y", "@modelcontextprotocol/server-memory"] } } } ``` -**Usage**: Generate React/Vue components from descriptions. +**Usage**: Remember information across conversations and sessions. + +**Tools**: +- `create_entities` - Create new entities in the knowledge graph +- `create_relations` - Create relationships between entities +- `add_observations` - Add observations to entities +- `delete_entities` - Remove entities from the graph +- `delete_observations` - Remove observations +- `delete_relations` - Remove relationships +- `read_graph` - Read the entire knowledge graph +- `search_nodes` - Search for entities +- `open_nodes` - Open specific entities by name + +### Filesystem (Secure File Operations) + +Enables secure file operations with configurable access controls. + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] + } + } +} +``` + +**Usage**: Read, write, and manage files with access controls. + +**Tools**: +- `read_file` - Read file contents +- `read_multiple_files` - Read multiple files at once +- `write_file` - Write content to a file +- `edit_file` - Make edits to a file +- `create_directory` - Create a new directory +- `list_directory` - List directory contents +- `directory_tree` - Get directory tree structure +- `move_file` - Move or rename files +- `search_files` - Search for files by pattern +- `get_file_info` - Get file metadata + +**Note**: The last argument specifies the allowed directory (`.` for current directory). ## Full Configuration Example +### Linux / macOS + ```json { "mcpServers": { "context7": { "command": "npx", - "args": ["-y", "@context7/mcp-server"] + "args": ["-y", "@upstash/context7-mcp"] }, "sequential": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] }, - "puppeteer": { + "playwright": { "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-puppeteer"] + "args": ["-y", "@playwright/mcp"] + }, + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"] + }, + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] } } } ``` +### Windows + +```json +{ + "mcpServers": { + "context7": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp"] + }, + "sequential": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "playwright": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@playwright/mcp"] + }, + "memory": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"] + }, + "filesystem": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "."] + } + } +} +``` + +## Optional Additional Servers + +These servers can be added for extended functionality: + +| Server | Package | Purpose | +|--------|---------|---------| +| Fetch | `mcp-server-fetch` (uvx) | Web content fetching | +| Brave Search | `@modelcontextprotocol/server-brave-search` | Web search (requires API key) | +| PostgreSQL | `@modelcontextprotocol/server-postgres` | Database access | +| Sentry | `@sentry/mcp-server` | Error tracking | +| GitHub | `@github/mcp-server` | GitHub API operations | + ## Verification After configuration, verify servers are loaded: @@ -150,11 +297,13 @@ After configuration, verify servers are loaded: - MCP servers run with your user permissions - Review server source before installing -- Puppeteer has browser access - use carefully +- Playwright has browser access - use carefully - Context7 makes network requests to documentation sources +- Filesystem server restricts access to specified directories ## Resources - [MCP Protocol Documentation](https://modelcontextprotocol.io/) - [Available MCP Servers](https://github.com/modelcontextprotocol/servers) +- [Microsoft Playwright MCP](https://github.com/microsoft/playwright-mcp) - [Claude Code MCP Guide](https://docs.anthropic.com/claude-code/mcp) diff --git a/.claude/modes/brainstorm.md b/.claude/modes/brainstorm.md index 3293734..65bd093 100644 --- a/.claude/modes/brainstorm.md +++ b/.claude/modes/brainstorm.md @@ -80,6 +80,34 @@ Once I understand these, I can provide better recommendations. --- +## MCP Integration + +This mode leverages MCP servers for enhanced brainstorming: + +### Sequential Thinking (Primary) +``` +ALWAYS use Sequential Thinking in brainstorm mode: +- Explore design options systematically +- Track trade-offs for each approach +- Build confidence in recommendations incrementally +- Allow for revisions and backtracking +``` + +### Memory +``` +Persist design decisions: +- Store design concepts and rationale +- Remember user preferences from previous sessions +- Build project design knowledge over time +``` + +### Context7 +``` +For informed technology choices: +- Fetch docs to compare library options +- Ground recommendations in real capabilities +``` + ## Combines Well With - `/brainstorm` command diff --git a/.claude/modes/deep-research.md b/.claude/modes/deep-research.md index f111757..78d7c46 100644 --- a/.claude/modes/deep-research.md +++ b/.claude/modes/deep-research.md @@ -124,6 +124,35 @@ Or use command flag: --- +## MCP Integration + +This mode leverages MCP servers for comprehensive research: + +### Sequential Thinking (Primary) +``` +ALWAYS use Sequential Thinking in deep-research mode: +- Structure analysis into logical thought sequences +- Track confidence scores for each finding +- Revise conclusions as evidence emerges +- Document reasoning chain for transparency +``` + +### Context7 +``` +For library/technology research: +- Fetch current documentation with get-library-docs +- Use mode='info' for conceptual understanding +- Verify findings against authoritative sources +``` + +### Memory +``` +Build persistent research knowledge: +- Store research findings as entities +- Create relations between discovered concepts +- Recall previous research in future sessions +``` + ## Combines Well With - `/research` command diff --git a/.claude/modes/implementation.md b/.claude/modes/implementation.md index fca4886..14e9fdf 100644 --- a/.claude/modes/implementation.md +++ b/.claude/modes/implementation.md @@ -112,6 +112,35 @@ Continuing with [choice]. Let me know if you'd prefer different. --- +## MCP Integration + +This mode leverages MCP servers for efficient implementation: + +### Filesystem (Primary) +``` +ALWAYS use Filesystem in implementation mode: +- Use read_file to check existing code +- Use write_file to create new files +- Use edit_file for modifications +- Use search_files to find patterns to follow +``` + +### Context7 +``` +For accurate library usage: +- Fetch current API documentation +- Use mode='code' for API references +- Get correct patterns and examples +``` + +### Memory +``` +Recall implementation context: +- Remember established patterns +- Recall user preferences +- Store decisions for consistency +``` + ## Combines Well With - `/execute-plan` command diff --git a/.claude/modes/review.md b/.claude/modes/review.md index cfba28c..1538657 100644 --- a/.claude/modes/review.md +++ b/.claude/modes/review.md @@ -137,6 +137,43 @@ Or use command flag: --- +## MCP Integration + +This mode leverages MCP servers for thorough review: + +### Playwright +``` +For UI/frontend reviews: +- Render and verify visual changes +- Test responsive behavior +- Check accessibility +- Capture screenshots for comparison +``` + +### Sequential Thinking +``` +For systematic code analysis: +- Step through logic methodically +- Track multiple concerns +- Build comprehensive issue list +``` + +### Memory +``` +Apply consistent review standards: +- Recall past review decisions +- Remember approved patterns +- Track recurring issues +``` + +### Filesystem +``` +For thorough code examination: +- Use read_file to examine code +- Use search_files to find related patterns +- Check consistency across codebase +``` + ## Combines Well With - `/review` command diff --git a/.claude/settings.json b/.claude/settings.json index 4dcf6ec..e604e6c 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -23,48 +23,14 @@ ], "deny": [] }, - "mcpServers": { - "_comment": "Uncomment servers to enable. See .claude/mcp/README.md for setup.", - "_context7": { - "command": "npx", - "args": ["-y", "@context7/mcp-server"] - }, - "_sequential": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] - }, - "_puppeteer": { - "command": "npx", - "args": ["-y", "@modelcontextprotocol/server-puppeteer"] - }, - "_magic": { - "command": "npx", - "args": ["-y", "@anthropic/magic-mcp-server"] - } - }, "hooks": { "PostToolUse": [ { - "matcher": { - "tool": "Write", - "files": ["*.py"] - }, + "matcher": "Write", "hooks": [ { "type": "command", - "command": "ruff check --fix $FILE 2>/dev/null || true" - } - ] - }, - { - "matcher": { - "tool": "Write", - "files": ["*.ts", "*.tsx"] - }, - "hooks": [ - { - "type": "command", - "command": "npx eslint --fix $FILE 2>/dev/null || true" + "command": "if [[ \"$FILE\" == *.py ]]; then ruff check --fix \"$FILE\" 2>/dev/null || true; elif [[ \"$FILE\" == *.ts || \"$FILE\" == *.tsx ]]; then npx eslint --fix \"$FILE\" 2>/dev/null || true; fi" } ] } diff --git a/.claude/skills/methodology/brainstorming/SKILL.md b/.claude/skills/methodology/brainstorming/SKILL.md index 32750eb..06ac575 100644 --- a/.claude/skills/methodology/brainstorming/SKILL.md +++ b/.claude/skills/methodology/brainstorming/SKILL.md @@ -156,3 +156,35 @@ After design is validated: 4. Use `executing-plans` skill for implementation --- + +## MCP Integration + +This skill leverages MCP servers for enhanced brainstorming: + +### Sequential Thinking (Primary) +``` +Use Sequential Thinking for structured exploration: +- Track design options as thought sequences +- Build confidence in recommendations incrementally +- Allow for revisions as user provides feedback +- Document reasoning chain for design decisions +``` + +### Memory +``` +Persist design decisions across sessions: +- Store design concepts as entities +- Create relations between components +- Recall user preferences from previous sessions +- Build project design knowledge over time +``` + +### Context7 +``` +For informed technology choices: +- Fetch current library documentation +- Compare capabilities accurately +- Ground recommendations in real data +``` + +--- diff --git a/.claude/skills/methodology/sequential-thinking/SKILL.md b/.claude/skills/methodology/sequential-thinking/SKILL.md index 6a24609..b484de9 100644 --- a/.claude/skills/methodology/sequential-thinking/SKILL.md +++ b/.claude/skills/methodology/sequential-thinking/SKILL.md @@ -201,6 +201,39 @@ Use skill: sequential-thinking --- +## MCP Integration + +This skill is powered by the Sequential Thinking MCP server: + +### Using the MCP Tool +``` +The Sequential Thinking MCP server provides the `sequentialthinking` tool. +Use it for: +- Breaking complex problems into thought sequences +- Tracking confidence and revising conclusions +- Building evidence chains with explicit reasoning +- Maintaining state across multiple reasoning steps +``` + +### Tool Parameters +``` +thought: Your current thinking step +thoughtNumber: Current step number +totalThoughts: Estimated total steps needed +nextThoughtNeeded: Whether more steps are needed +isRevision: If revising previous thinking +needsMoreThoughts: If more analysis needed +``` + +### Integration Pattern +``` +1. Start with initial thought defining the question +2. Gather evidence in subsequent thoughts +3. Form hypotheses with probability estimates +4. Test and verify in later thoughts +5. Conclude with confidence score +``` + ## Combines Well With - Deep research mode diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..a3b624a --- /dev/null +++ b/.mcp.json @@ -0,0 +1,24 @@ +{ + "mcpServers": { + "context7": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp"] + }, + "sequential": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "playwright": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@playwright/mcp"] + }, + "memory": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"] + }, + "filesystem": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "."] + } + } +} diff --git a/README.md b/README.md index 8ac42a1..126a718 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ A comprehensive toolkit for Claude Code to accelerate development workflows for - **7 Behavioral Modes** - Task-specific response optimization - **Command Flag System** - Combinable `--flag` syntax for customization - **Token Optimization** - 30-70% cost savings with compressed output modes -- **MCP Integrations** - Context7, Sequential Thinking, Puppeteer, Magic +- **MCP Integrations** - Context7, Sequential Thinking, Playwright, Memory, Filesystem - **Context Management** - Project indexing, checkpoints, parallel tasks ## Quick Start @@ -215,14 +215,49 @@ Reduce costs by 30-70% with compressed output modes: ## MCP Integrations -Optional MCP servers for extended capabilities: +MCP servers extend Claude Kit with powerful capabilities. They are **automatically used** when configured. -| Server | Purpose | -|--------|---------| -| Context7 | Up-to-date library documentation | -| Sequential | Multi-step reasoning tools | -| Puppeteer | Browser automation | -| Magic | UI component generation | +| Server | Package | Purpose | +|--------|---------|---------| +| Context7 | `@upstash/context7-mcp` | Up-to-date library documentation | +| Sequential | `@modelcontextprotocol/server-sequential-thinking` | Multi-step reasoning | +| Playwright | `@playwright/mcp` | Browser automation (Microsoft) | +| Memory | `@modelcontextprotocol/server-memory` | Persistent knowledge graph | +| Filesystem | `@modelcontextprotocol/server-filesystem` | Secure file operations | + +### How MCP Servers Enhance Commands + +| Command | MCP Servers Used | Enhancement | +|---------|------------------|-------------| +| `/feature` | Context7, Sequential, Filesystem | Accurate docs, structured planning, safe file ops | +| `/fix` | Sequential, Memory, Playwright | Step-by-step debugging, context recall, browser testing | +| `/test` | Playwright, Filesystem | E2E browser tests, test file management | +| `/plan` | Sequential, Memory | Structured breakdown, remembers decisions | +| `/research` | Context7, Sequential | Real-time docs, thorough analysis | +| `/brainstorm` | Sequential, Memory | Creative exploration, persistent ideas | +| `/index` | Filesystem | Project structure scanning | + +### MCP + Mode Combinations + +| Mode | Primary MCP | Best For | +|------|-------------|----------| +| `brainstorm` | Sequential + Memory | Design sessions with persistent ideas | +| `deep-research` | Sequential + Context7 | Thorough technical investigation | +| `implementation` | Filesystem + Context7 | Focused coding with accurate docs | +| `review` | Playwright + Memory | UI review with context | +| `orchestration` | All 5 | Complex multi-step parallel work | + +### Example: Full Feature Development + +```bash +/feature Add user profile with avatar upload +``` + +1. **Context7** → Fetches latest React/Next.js file upload docs +2. **Sequential** → Plans component structure step-by-step +3. **Memory** → Recalls your UI patterns from previous sessions +4. **Filesystem** → Creates files in correct locations +5. **Playwright** → Tests the upload flow in browser Setup: See `.claude/mcp/README.md` diff --git a/website/astro.config.mjs b/website/astro.config.mjs index c5a3efa..7075377 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -105,6 +105,19 @@ export default defineConfig({ }, ], }, + { + label: 'MCP Integrations', + collapsed: false, + items: [ + { label: 'Overview', slug: 'mcp/overview' }, + { label: 'Context7', slug: 'mcp/context7' }, + { label: 'Sequential Thinking', slug: 'mcp/sequential' }, + { label: 'Playwright', slug: 'mcp/playwright' }, + { label: 'Memory', slug: 'mcp/memory' }, + { label: 'Filesystem', slug: 'mcp/filesystem' }, + { label: 'Command Integration', slug: 'mcp/integration' }, + ], + }, { label: 'Modes', collapsed: false, diff --git a/website/src/content/docs/index.mdx b/website/src/content/docs/index.mdx index ecabc02..5b42ee9 100644 --- a/website/src/content/docs/index.mdx +++ b/website/src/content/docs/index.mdx @@ -34,8 +34,8 @@ Claude Kit transforms Claude Code into a production-ready AI development team. P Pre-built knowledge for Python, TypeScript, React, FastAPI, testing, security, and more. - - Open source, MIT licensed. No subscriptions, no limits. Your kit, your rules. + + Real-time docs, persistent memory, browser testing, and more via Model Context Protocol. @@ -149,14 +149,14 @@ Claude Kit provides the structure, patterns, and automation that makes Claude Co description="Complete documentation for all 27+ commands" href="/claudekit/commands/overview/" /> + - diff --git a/website/src/content/docs/mcp/context7.md b/website/src/content/docs/mcp/context7.md new file mode 100644 index 0000000..d8ae96e --- /dev/null +++ b/website/src/content/docs/mcp/context7.md @@ -0,0 +1,123 @@ +--- +title: Context7 +description: Real-time library documentation lookup with Context7 MCP server. +--- + +# Context7 + +Context7 provides up-to-date documentation for libraries and frameworks, ensuring Claude has accurate API references instead of outdated training data. + +## Configuration + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + } + } +} +``` + +## Available Tools + +### resolve-library-id + +Finds the Context7-compatible library ID for documentation lookup. + +**Parameters:** +- `libraryName` — Library name to search for + +**Example:** +``` +resolve-library-id("react") +→ Returns: "/facebook/react" +``` + +### get-library-docs + +Fetches documentation for a specific library. + +**Parameters:** +- `context7CompatibleLibraryID` — Library ID from resolve-library-id +- `topic` (optional) — Focus area (e.g., "hooks", "routing") +- `mode` — `code` for API references, `info` for concepts +- `page` — Pagination (1-10) + +**Example:** +``` +get-library-docs("/facebook/react", topic="hooks", mode="code") +→ Returns: Current React hooks documentation with examples +``` + +## Use Cases + +### Research Libraries + +``` +/research Next.js App Router +``` +Context7 fetches current Next.js documentation for accurate analysis. + +### Feature Development + +``` +/feature Add authentication with NextAuth +``` +Context7 provides current NextAuth API for correct implementation. + +### Debugging Library Issues + +``` +/fix "useEffect cleanup not working" +``` +Context7 retrieves correct useEffect patterns from React docs. + +## Command Integration + +| Command | How Context7 Helps | +|---------|-------------------| +| `/feature` | Accurate library APIs for implementation | +| `/research` | Current documentation for analysis | +| `/fix` | Correct patterns for debugging library issues | +| `/plan` | Accurate estimates based on real API complexity | + +## Best Practices + +### Specify Topics + +For focused results, use the `topic` parameter: +``` +get-library-docs("/vercel/next.js", topic="app-router") +``` + +### Use Correct Mode + +- `mode="code"` — API references, code examples +- `mode="info"` — Conceptual guides, architecture + +### Handle Pagination + +If context is insufficient, try additional pages: +``` +get-library-docs(..., page=2) +``` + +## Troubleshooting + +### Library Not Found + +If `resolve-library-id` returns no results: +- Check spelling +- Try alternative names (e.g., "nextjs" vs "next.js") +- Some libraries may not be indexed + +### Outdated Results + +Context7 indexes popular libraries. Less common libraries may have delayed updates. + +## Resources + +- [Context7 Documentation](https://context7.com) +- [Upstash Context7 MCP](https://github.com/upstash/context7-mcp) diff --git a/website/src/content/docs/mcp/filesystem.md b/website/src/content/docs/mcp/filesystem.md new file mode 100644 index 0000000..5e2faab --- /dev/null +++ b/website/src/content/docs/mcp/filesystem.md @@ -0,0 +1,196 @@ +--- +title: Filesystem +description: Secure file operations with access controls. +--- + +# Filesystem + +Filesystem MCP enables secure file operations with configurable access boundaries. It complements Claude Code's built-in file handling with additional capabilities. + +## Configuration + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] + } + } +} +``` + +The last argument (`.`) specifies the allowed directory. Claude can only access files within this directory. + +### Access Control Examples + +```json +// Allow entire project +"args": ["-y", "@modelcontextprotocol/server-filesystem", "."] + +// Allow only src directory +"args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"] + +// Allow multiple directories +"args": ["-y", "@modelcontextprotocol/server-filesystem", "./src", "./tests"] +``` + +## Available Tools + +### Reading + +| Tool | Description | +|------|-------------| +| `read_file` | Read file contents | +| `read_multiple_files` | Read multiple files at once | +| `get_file_info` | Get file metadata (size, modified, etc.) | + +### Writing + +| Tool | Description | +|------|-------------| +| `write_file` | Write content to file | +| `edit_file` | Make targeted edits to file | + +### Directory Operations + +| Tool | Description | +|------|-------------| +| `list_directory` | List directory contents | +| `directory_tree` | Get full directory tree | +| `create_directory` | Create new directory | + +### File Management + +| Tool | Description | +|------|-------------| +| `move_file` | Move or rename files | +| `search_files` | Search for files by pattern | + +## Use Cases + +### Project Indexing + +``` +/index +``` +Filesystem: +1. Uses `directory_tree` to scan project +2. Uses `list_directory` for detailed info +3. Uses `get_file_info` for file metadata + +### Bulk Operations + +``` +/refactor Move utilities to shared folder +``` +Filesystem: +1. Uses `search_files` to find utility files +2. Uses `move_file` to relocate them +3. Uses `read_file` to update imports + +### Test File Management + +``` +/test Generate tests for auth service +``` +Filesystem: +1. Uses `directory_tree` to find test directories +2. Uses `search_files` to find existing tests +3. Uses `write_file` to create new test files + +## Command Integration + +| Command | How Filesystem Helps | +|---------|---------------------| +| `/index` | Scans project structure | +| `/feature` | Creates new files in correct locations | +| `/test` | Manages test file creation | +| `/refactor` | Moves and reorganizes files | + +## Example Workflow + +### Scanning Project + +```javascript +// Get project structure +directory_tree(".") +→ Returns hierarchical view of all files + +// Get specific directory contents +list_directory("./src/services") +→ Returns files with metadata + +// Search for patterns +search_files("*.test.ts") +→ Returns all test files +``` + +### File Operations + +```javascript +// Read file +read_file("./src/auth/service.ts") +→ Returns file contents + +// Write new file +write_file("./src/auth/types.ts", "export interface User {...}") +→ Creates new file + +// Move file +move_file("./src/utils/helper.ts", "./src/shared/helper.ts") +→ Relocates file +``` + +## Security + +### Access Boundaries + +Filesystem respects the configured directory boundaries: +- Cannot read files outside allowed directories +- Cannot write to system directories +- Cannot access parent directories with `../` + +### Best Practices + +1. **Limit scope** — Only allow directories needed for the task +2. **Use project root** — `.` is usually sufficient +3. **Avoid sensitive paths** — Don't allow access to credentials or secrets + +## Comparison with Built-in Tools + +| Feature | Built-in | Filesystem MCP | +|---------|----------|----------------| +| Read files | ✓ | ✓ | +| Write files | ✓ | ✓ | +| Directory tree | Limited | Full tree view | +| File search | Via Glob | Pattern search | +| Bulk operations | Sequential | Batch capable | +| Access control | Permission-based | Directory-based | + +## Troubleshooting + +### Permission Denied + +If operations fail: +1. Check allowed directory in configuration +2. Verify file permissions +3. Ensure path is within allowed scope + +### File Not Found + +If search returns empty: +1. Verify file exists +2. Check file extension in pattern +3. Confirm path is relative to allowed directory + +### Path Issues + +Always use forward slashes and relative paths: +- "./src/file.ts" not ".\src\file.ts" +- Avoid absolute paths + +## Resources + +- [MCP Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) +- [File System Security Best Practices](https://owasp.org/www-community/vulnerabilities/Path_Traversal) diff --git a/website/src/content/docs/mcp/integration.md b/website/src/content/docs/mcp/integration.md new file mode 100644 index 0000000..c5a8b9e --- /dev/null +++ b/website/src/content/docs/mcp/integration.md @@ -0,0 +1,220 @@ +--- +title: Command Integration +description: How MCP servers enhance Claude Kit commands and modes. +--- + +# Command Integration + +MCP servers are automatically used by Claude Kit commands and modes. This guide shows which servers enhance each command and how they work together. + +## Commands + MCP Servers + +### Development Commands + +| Command | MCP Servers | Enhancement | +|---------|-------------|-------------| +| `/feature` | Context7, Sequential, Memory, Filesystem, Playwright | Full development workflow with docs, planning, persistence | +| `/fix` | Sequential, Memory, Playwright, Context7, Filesystem | Systematic debugging with browser testing | +| `/test` | Playwright, Filesystem, Context7, Memory | E2E tests, file management, testing patterns | +| `/review` | Playwright, Memory, Sequential, Filesystem | Visual review, consistent standards | + +### Planning Commands + +| Command | MCP Servers | Enhancement | +|---------|-------------|-------------| +| `/plan` | Sequential, Memory, Context7, Filesystem | Structured breakdown, persistent decisions | +| `/brainstorm` | Sequential, Memory, Context7 | Organized exploration, design persistence | +| `/research` | Context7, Sequential, Memory | Real-time docs, thorough analysis | + +### Utility Commands + +| Command | MCP Servers | Enhancement | +|---------|-------------|-------------| +| `/index` | Filesystem, Memory | Project scanning, structure persistence | + +## Modes + MCP Servers + +| Mode | Primary MCP | Best For | +|------|-------------|----------| +| **brainstorm** | Sequential + Memory | Design sessions with persistent ideas | +| **deep-research** | Sequential + Context7 | Thorough technical investigation | +| **implementation** | Filesystem + Context7 | Focused coding with accurate docs | +| **review** | Playwright + Memory | UI review with consistent standards | +| **orchestration** | All 5 | Complex multi-step parallel work | + +## Example Workflows + +### Full Feature Development + +```bash +/feature Add user profile with avatar upload +``` + +**MCP Flow:** +1. **Context7** — Fetches React file upload documentation +2. **Sequential** — Plans component structure step-by-step +3. **Memory** — Recalls UI patterns from previous features +4. **Filesystem** — Creates files in correct locations +5. **Playwright** — Tests upload flow in browser + +### Complex Debugging + +```bash +/fix Authentication fails intermittently on mobile +``` + +**MCP Flow:** +1. **Memory** — Recalls auth architecture from previous sessions +2. **Sequential** — Analyzes race conditions systematically +3. **Playwright** — Tests on mobile device emulation +4. **Context7** — Checks session handling best practices + +### Research & Planning + +```bash +/research --mode=deep-research JWT vs Session authentication +``` + +**MCP Flow:** +1. **Sequential** — Structures comparison step-by-step +2. **Context7** — Fetches current JWT and session library docs +3. **Memory** — Stores findings for future reference + +### Project Indexing + +```bash +/index +``` + +**MCP Flow:** +1. **Filesystem** — Scans project with `directory_tree` +2. **Memory** — Stores structure as knowledge graph + +## Server Synergy + +### Context7 + Memory + +**Pattern:** Research → Store → Recall + +``` +Session 1: /research React Server Components +→ Context7 fetches RSC documentation +→ Memory stores key patterns + +Session 2: /feature Add data fetching +→ Memory recalls RSC patterns +→ Implementation uses correct approach +``` + +### Sequential + Memory + +**Pattern:** Analyze → Decide → Remember + +``` +/brainstorm Database migration strategy +→ Sequential explores options step-by-step +→ Memory stores final decision +→ Future sessions recall the decision +``` + +### Playwright + Context7 + +**Pattern:** Test → Verify → Document + +``` +/test E2E checkout flow +→ Playwright automates browser testing +→ Context7 provides testing library docs +→ Tests use correct assertions +``` + +### Filesystem + Memory + +**Pattern:** Scan → Store → Navigate + +``` +/index +→ Filesystem scans project structure +→ Memory creates project knowledge graph +→ Future commands know where files are +``` + +## Configuration Tips + +### Platform Note + +Configuration differs by platform: +- **Linux/macOS**: Use `"command": "npx"` directly +- **Windows**: Use `"command": "cmd"` with `"/c", "npx"` in args + +Examples below show Linux/macOS syntax. For Windows, see [MCP Overview](/claudekit/mcp/overview/). + +### Minimal Setup + +For basic usage, Context7 and Sequential are most impactful: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + }, + "sequential": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + } + } +} +``` + +### Full Setup + +For complete Claude Kit integration, use all 5 servers: + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + }, + "sequential": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp"] + }, + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"] + }, + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] + } + } +} +``` + +## Performance Notes + +### First Run + +First run downloads npm packages (one-time). Subsequent starts are faster. + +### Startup Order + +Servers start in parallel. All should be ready within seconds. + +### Resource Usage + +Each server runs as a separate process. Total overhead is minimal but consider disabling unused servers for resource-constrained environments. + +## Next Steps + +- [MCP Overview](/claudekit/mcp/overview/) — Setup and configuration +- [Commands Overview](/claudekit/commands/overview/) — All available commands +- [Modes Overview](/claudekit/modes/overview/) — Behavioral modes diff --git a/website/src/content/docs/mcp/memory.md b/website/src/content/docs/mcp/memory.md new file mode 100644 index 0000000..c406806 --- /dev/null +++ b/website/src/content/docs/mcp/memory.md @@ -0,0 +1,197 @@ +--- +title: Memory +description: Persistent knowledge graph for context across sessions. +--- + +# Memory + +Memory MCP maintains a persistent knowledge graph across sessions, enabling Claude to remember decisions, patterns, and preferences over time. + +## Configuration + +```json +{ + "mcpServers": { + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"] + } + } +} +``` + +## Core Concepts + +### Entities + +Named items in the knowledge graph (e.g., "AuthService", "UserModel"). + +### Observations + +Facts about entities (e.g., "uses JWT tokens", "requires database"). + +### Relations + +Connections between entities (e.g., "AuthService" → "uses" → "UserRepository"). + +## Available Tools + +### Entity Management + +| Tool | Description | +|------|-------------| +| `create_entities` | Create new entities | +| `delete_entities` | Remove entities | +| `open_nodes` | Open specific entities by name | +| `search_nodes` | Search for entities | + +### Observations + +| Tool | Description | +|------|-------------| +| `add_observations` | Add facts to entities | +| `delete_observations` | Remove observations | + +### Relations + +| Tool | Description | +|------|-------------| +| `create_relations` | Link entities together | +| `delete_relations` | Remove links | + +### Graph Operations + +| Tool | Description | +|------|-------------| +| `read_graph` | Read entire knowledge graph | + +## Use Cases + +### Project Architecture + +``` +/index +``` +Memory stores: +- Entity: "src/api" — "Contains REST endpoints" +- Entity: "src/services" — "Business logic layer" +- Relation: "api" → "depends on" → "services" + +### Design Decisions + +``` +/brainstorm Authentication strategy +``` +Memory stores: +- Entity: "AuthDecision" +- Observation: "Chose JWT over sessions for scalability" +- Observation: "User prefers stateless auth" + +### Bug Patterns + +``` +/fix Race condition in checkout +``` +Memory stores: +- Entity: "CheckoutBug" +- Observation: "Caused by async state update" +- Observation: "Fixed with mutex lock" + +## Command Integration + +| Command | How Memory Helps | +|---------|-----------------| +| `/brainstorm` | Remembers design decisions | +| `/plan` | Recalls previous task patterns | +| `/fix` | Stores bug patterns for future reference | +| `/index` | Persists project structure | + +## Example Workflow + +### Storing Design Decisions + +**Session 1:** +``` +/brainstorm Authentication for mobile app +→ Decision: Use OAuth with refresh tokens +→ Memory stores this decision +``` + +**Session 2:** +``` +/feature Add logout functionality +→ Memory recalls: "Uses OAuth with refresh tokens" +→ Claude knows to invalidate refresh token +``` + +### Building Project Knowledge + +**Over time:** +``` +create_entities(["AuthService", "UserRepository", "TokenManager"]) + +add_observations("AuthService", [ + "Handles OAuth flow", + "Uses refresh tokens", + "Integrates with Google/GitHub" +]) + +create_relations([ + {"from": "AuthService", "to": "TokenManager", "type": "uses"}, + {"from": "AuthService", "to": "UserRepository", "type": "queries"} +]) +``` + +**Later query:** +``` +search_nodes("auth") +→ Returns full context about authentication architecture +``` + +## Best Practices + +### Use Descriptive Names + +Entity names should be clear and consistent: +- "AuthService" not "AS" +- "PaymentFlow" not "pmt" + +### Add Context to Observations + +Include why, not just what: +- "Uses JWT because stateless scales better" +- "Chose Postgres for ACID compliance" + +### Create Meaningful Relations + +Relations should express real dependencies: +- "depends on", "uses", "calls", "creates" + +### Review Regularly + +Use `read_graph` periodically to review stored knowledge and prune outdated information. + +## Data Persistence + +Memory data is stored locally and persists between sessions. The knowledge graph grows over time as you work with Claude Kit. + +## Troubleshooting + +### Graph Getting Large + +If the graph becomes unwieldy: +1. Use `search_nodes` to find specific entities +2. Delete outdated entities with `delete_entities` +3. Remove stale observations + +### Missing Context + +If Claude doesn't recall something: +- Check if entity exists with `search_nodes` +- Observations may not have been stored +- Entity names may differ + +## Resources + +- [MCP Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) +- [Knowledge Graph Concepts](https://en.wikipedia.org/wiki/Knowledge_graph) diff --git a/website/src/content/docs/mcp/overview.md b/website/src/content/docs/mcp/overview.md new file mode 100644 index 0000000..67f0380 --- /dev/null +++ b/website/src/content/docs/mcp/overview.md @@ -0,0 +1,136 @@ +--- +title: MCP Integrations +description: Extend Claude Kit with Model Context Protocol servers for enhanced capabilities. +--- + +# MCP Integrations + +Model Context Protocol (MCP) servers extend Claude Kit with powerful capabilities like real-time documentation, persistent memory, and browser automation. + +## What is MCP? + +MCP (Model Context Protocol) is an open standard that allows AI assistants to connect with external tools and data sources. Claude Kit includes pre-configured MCP servers that enhance your development workflow. + +## Available Servers + +| Server | Package | Purpose | +|--------|---------|---------| +| **Context7** | `@upstash/context7-mcp` | Real-time library documentation | +| **Sequential** | `@modelcontextprotocol/server-sequential-thinking` | Structured problem-solving | +| **Playwright** | `@playwright/mcp` | Browser automation | +| **Memory** | `@modelcontextprotocol/server-memory` | Persistent knowledge graph | +| **Filesystem** | `@modelcontextprotocol/server-filesystem` | Secure file operations | + +## Quick Setup + +### 1. Create Configuration + +Create a `.mcp.json` file in your project root. Choose your platform: + +#### Linux / macOS + +```json +{ + "mcpServers": { + "context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"] + }, + "sequential": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp"] + }, + "memory": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-memory"] + }, + "filesystem": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] + } + } +} +``` + +#### Windows + +Windows requires the `cmd /c` wrapper: + +```json +{ + "mcpServers": { + "context7": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@upstash/context7-mcp"] + }, + "sequential": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-sequential-thinking"] + }, + "playwright": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@playwright/mcp"] + }, + "memory": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"] + }, + "filesystem": { + "command": "cmd", + "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "."] + } + } +} +``` + +### 2. Prerequisites + +- Node.js 18+ +- npx available in PATH + +### 3. Verify Installation + +Start a new Claude Code session. MCP servers will load automatically. Test with: + +``` +Ask Claude about React hooks using Context7 +``` + +## Benefits + +### Real-Time Documentation +Context7 fetches current library documentation, eliminating outdated API references from training data. + +### Structured Reasoning +Sequential Thinking enables step-by-step analysis with confidence tracking for complex debugging and planning. + +### Browser Testing +Playwright provides cross-browser automation for E2E testing without separate test infrastructure. + +### Persistent Context +Memory server maintains knowledge across sessions, remembering your patterns and preferences. + +### Safe File Operations +Filesystem server provides controlled file access with security boundaries. + +## How It Works + +MCP servers are **automatically used** when configured. Claude Kit commands and modes include explicit guidance for optimal MCP usage. + +For example, when you run `/research react hooks`: +1. Context7 fetches current React documentation +2. Sequential Thinking structures the analysis +3. Memory stores findings for future reference + +## Next Steps + +- [Context7](/claudekit/mcp/context7/) — Library documentation lookup +- [Sequential Thinking](/claudekit/mcp/sequential/) — Structured reasoning +- [Playwright](/claudekit/mcp/playwright/) — Browser automation +- [Memory](/claudekit/mcp/memory/) — Persistent knowledge +- [Filesystem](/claudekit/mcp/filesystem/) — File operations +- [Command Integration](/claudekit/mcp/integration/) — How MCP enhances commands diff --git a/website/src/content/docs/mcp/playwright.md b/website/src/content/docs/mcp/playwright.md new file mode 100644 index 0000000..63682cf --- /dev/null +++ b/website/src/content/docs/mcp/playwright.md @@ -0,0 +1,198 @@ +--- +title: Playwright +description: Browser automation for testing and web interaction. +--- + +# Playwright + +Playwright MCP provides browser automation using accessibility tree for fast, LLM-friendly interaction. Built by Microsoft, it enables cross-browser testing without vision models. + +## Configuration + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp"] + } + } +} +``` + +### Command-Line Options + +| Option | Description | Example | +|--------|-------------|---------| +| `--browser` | Browser to use | `chrome`, `firefox`, `webkit`, `msedge` | +| `--headless` | Run without UI | Flag only | +| `--viewport-size` | Window size | `1280x720` | +| `--device` | Device emulation | `iPhone 15`, `Pixel 7` | + +**Example with options:** +```json +{ + "playwright": { + "command": "npx", + "args": ["-y", "@playwright/mcp", "--browser", "chrome", "--headless"] + } +} +``` + +## Available Tools + +### Navigation + +| Tool | Description | +|------|-------------| +| `browser_navigate` | Go to a URL | +| `browser_go_back` | Navigate back | +| `browser_go_forward` | Navigate forward | +| `browser_wait` | Wait for page load | + +### Interaction + +| Tool | Description | +|------|-------------| +| `browser_click` | Click element | +| `browser_type` | Type text | +| `browser_fill` | Fill input field | +| `browser_select_option` | Select dropdown option | +| `browser_press_key` | Press keyboard key | + +### Content + +| Tool | Description | +|------|-------------| +| `browser_snapshot` | Get accessibility tree | +| `browser_take_screenshot` | Capture screenshot | +| `browser_get_text` | Get element text | + +### Tabs + +| Tool | Description | +|------|-------------| +| `browser_tab_list` | List open tabs | +| `browser_tab_new` | Open new tab | +| `browser_tab_select` | Switch to tab | +| `browser_tab_close` | Close tab | + +## Use Cases + +### E2E Testing + +``` +/test e2e Login flow should redirect to dashboard +``` +Playwright: +1. Navigates to login page +2. Fills credentials +3. Clicks submit +4. Verifies dashboard redirect + +### UI Review + +``` +/review Visual regression on mobile +``` +Playwright: +1. Opens page with device emulation +2. Takes screenshots +3. Compares with expected layout + +### Form Testing + +``` +/test Form validation for user registration +``` +Playwright: +1. Fills form with various inputs +2. Tests validation messages +3. Verifies submission behavior + +## Command Integration + +| Command | How Playwright Helps | +|---------|---------------------| +| `/test` | E2E browser tests | +| `/fix` | Reproduce UI bugs in browser | +| `/review` | Visual verification of changes | +| `/feature` | Test new UI features | + +## Example Workflow + +### Testing Login Flow + +```javascript +// Playwright MCP workflow +browser_navigate("https://app.example.com/login") +browser_fill("#email", "test@example.com") +browser_fill("#password", "password123") +browser_click("#login-button") +browser_wait() // Wait for navigation +browser_take_screenshot("after-login.png") +``` + +### Mobile Testing + +```javascript +// With device emulation (--device "iPhone 15") +browser_navigate("https://app.example.com") +browser_snapshot() // Get accessibility tree +browser_take_screenshot("mobile-view.png") +``` + +## Key Features + +### Accessibility Tree + +Playwright uses the accessibility tree instead of pixels: +- **Faster** — No image processing needed +- **LLM-friendly** — Structured element data +- **Cross-browser** — Works identically everywhere + +### Device Emulation + +Test on different devices without physical hardware: +- iPhone, iPad, Pixel, Galaxy +- Custom viewport sizes +- Touch vs mouse input + +### Profile Management + +Playwright can maintain browser state across sessions for authenticated testing. + +## Best Practices + +### Use Headless Mode + +For automated testing, use `--headless` to run without UI overhead. + +### Wait for Elements + +Always use `browser_wait` or wait for specific elements before interaction. + +### Accessibility First + +Use accessibility tree (`browser_snapshot`) to understand page structure before clicking. + +## Troubleshooting + +### Element Not Found + +If clicking fails: +1. Use `browser_snapshot` to see available elements +2. Check if element needs scrolling +3. Wait for dynamic content to load + +### Browser Not Starting + +- Ensure browser is installed +- Check Node.js version (18+) +- Try different browser with `--browser` + +## Resources + +- [Playwright MCP](https://github.com/microsoft/playwright-mcp) +- [Playwright Documentation](https://playwright.dev) +- [Device Descriptors](https://playwright.dev/docs/emulation#devices) diff --git a/website/src/content/docs/mcp/sequential.md b/website/src/content/docs/mcp/sequential.md new file mode 100644 index 0000000..b1920ba --- /dev/null +++ b/website/src/content/docs/mcp/sequential.md @@ -0,0 +1,157 @@ +--- +title: Sequential Thinking +description: Structured problem-solving with step-by-step reasoning. +--- + +# Sequential Thinking + +Sequential Thinking provides structured reasoning tools for complex problem-solving, enabling step-by-step analysis with confidence tracking and revision capabilities. + +## Configuration + +```json +{ + "mcpServers": { + "sequential": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] + } + } +} +``` + +## Available Tools + +### sequentialthinking + +Dynamic problem-solving through structured thought sequences. + +**Parameters:** + +| Parameter | Description | +|-----------|-------------| +| `thought` | Current thinking step | +| `thoughtNumber` | Current step number (1, 2, 3...) | +| `totalThoughts` | Estimated total steps needed | +| `nextThoughtNeeded` | Whether more steps are needed | +| `isRevision` | If this revises previous thinking | +| `revisesThought` | Which thought is being reconsidered | +| `branchFromThought` | Branching point for alternative paths | +| `needsMoreThoughts` | If more analysis is needed | + +## Use Cases + +### Complex Debugging + +``` +/fix Intermittent authentication failures +``` +Sequential Thinking: +1. Defines the question clearly +2. Gathers evidence systematically +3. Forms hypotheses with probabilities +4. Tests most likely cause first +5. Documents conclusion with confidence + +### Architecture Decisions + +``` +/brainstorm Database migration strategy +``` +Sequential Thinking: +1. Explores options step-by-step +2. Tracks trade-offs for each approach +3. Revises conclusions based on feedback +4. Builds confidence incrementally + +### Root Cause Analysis + +``` +/research Why is the build slow? +``` +Sequential Thinking: +1. Breaks problem into investigation steps +2. Documents evidence at each step +3. Adjusts hypothesis as facts emerge +4. Provides confidence-scored conclusion + +## Command Integration + +| Command | How Sequential Thinking Helps | +|---------|------------------------------| +| `/fix` | Systematic root cause analysis | +| `/plan` | Structured task decomposition | +| `/brainstorm` | Organized design exploration | +| `/research` | Step-by-step investigation | + +## Mode Integration + +| Mode | Integration | +|------|-------------| +| `deep-research` | Primary tool for thorough analysis | +| `brainstorm` | Structures creative exploration | +| `review` | Systematic code examination | + +## Example Workflow + +### Debugging Session + +**Thought 1:** Define the problem +``` +"What is causing authentication to fail intermittently for some users?" +→ Confidence: N/A (question definition) +``` + +**Thought 2:** Gather evidence +``` +"Checking logs shows failures occur during peak hours, +primarily for users with special characters in passwords." +→ Confidence: 7/10 +``` + +**Thought 3:** Form hypothesis +``` +"Hypothesis A: URL encoding issue with special characters. +Evidence: Failure pattern matches special char passwords. +Probability: 80%" +→ Confidence: 8/10 +``` + +**Thought 4:** Test hypothesis +``` +"Tested with password 'test@123' - fails. +Tested with 'test123' - works. +Hypothesis confirmed." +→ Confidence: 9/10 +``` + +**Thought 5:** Conclusion +``` +"Root cause: URL encoding mangles special characters. +Fix: Use base64 encoding instead. +Confidence: 9/10" +→ nextThoughtNeeded: false +``` + +## Best Practices + +### Start with Clear Questions + +Define what you're investigating before gathering evidence. + +### Track Confidence + +Explicitly state confidence levels to identify when more investigation is needed. + +### Allow Revisions + +Use `isRevision` and `revisesThought` to refine understanding as new information emerges. + +### Branch When Needed + +Use `branchFromThought` to explore alternative hypotheses without losing the main thread. + +## Resources + +- [MCP Sequential Thinking](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking) +- [Sequential Thinking Skill](/claudekit/skills/methodology/sequential-thinking/)