mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor(docs): normalize documentation naming to lowercase for PEP8 compliance (#434)
* refactor(docs): rename directories to lowercase for PEP8 compliance - Developer-Guide → developer-guide - Getting-Started → getting-started - Reference → reference - Templates → templates - User-Guide → user-guide - User-Guide-jp → user-guide-jp - User-Guide-kr → user-guide-kr - User-Guide-zh → user-guide-zh This change aligns with Python PEP8 package naming conventions. All 43 files affected. * refactor: rename root documentation files to lowercase - CHANGELOG.md → changelog.md - CODE_OF_CONDUCT.md → code_of_conduct.md - CONTRIBUTING.md → contributing.md - SECURITY.md → security.md Aligns with Python package naming conventions (PEP8). README files remain uppercase as per convention. * refactor: move documentation files to docs/ for cleaner root Moved OSS standard files to docs/: - CHANGELOG.md → docs/CHANGELOG.md - CODE_OF_CONDUCT.md → docs/CODE_OF_CONDUCT.md - CONTRIBUTING.md → docs/CONTRIBUTING.md - SECURITY.md → docs/SECURITY.md Root now contains only essential files: ✓ README files (表紙: en, ja, kr, zh) ✓ LICENSE (法的要件) ✓ Build configs (pyproject.toml, setup.py, MANIFEST.in) ✓ VERSION Rationale: Cleaner root structure following modern Python project conventions. All detailed documentation consolidated in docs/ directory. * refactor: update documentation links after restructure Auto-updated internal documentation links to reflect new structure: - docs/ subdirectories now lowercase (PEP8) - Root files moved to docs/ - All cross-references updated This commit includes linter-generated link updates. * chore(docs): keep OSS-standard uppercase root files (CHANGELOG, CODE_OF_CONDUCT, CONTRIBUTING, SECURITY) * chore(docs): remove duplicated PR docs from repo root (moved under docs) * docs: rename pm-agent-implementation-status.md -> PM_AGENT.md for clarity * docs: update links to PM_AGENT.md after rename --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local>
This commit is contained in:
kazuki nakai
@@ -1,339 +0,0 @@
|
||||
# SuperClaude MCP Servers Guide 🔌
|
||||
|
||||
## Overview
|
||||
|
||||
MCP (Model Context Protocol) servers extend Claude Code's capabilities through specialized tools. SuperClaude integrates 8 MCP servers and provides Claude with instructions on when to activate them based on your tasks.
|
||||
|
||||
### 🔍 Reality Check
|
||||
- **What MCP servers are**: External Node.js processes that provide additional tools
|
||||
- **What they aren't**: Built-in SuperClaude functionality
|
||||
- **How activation works**: Claude reads instructions to use appropriate servers based on context
|
||||
- **What they provide**: Real tools that extend Claude Code's native capabilities
|
||||
|
||||
**Core Servers:**
|
||||
- **context7**: Official library documentation and patterns
|
||||
- **sequential-thinking**: Multi-step reasoning and analysis
|
||||
- **magic**: Modern UI component generation
|
||||
- **playwright**: Browser automation and E2E testing
|
||||
- **morphllm-fast-apply**: Pattern-based code transformations
|
||||
- **serena**: Semantic code understanding and project memory
|
||||
- **tavily**: Web search and real-time information retrieval
|
||||
- **chrome-devtools**: Performance analysis and debugging
|
||||
|
||||
## Quick Start
|
||||
|
||||
**Setup Verification**: MCP servers activate automatically. For installation and troubleshooting, see [Installation Guide](../Getting-Started/installation.md) and [Troubleshooting](../Reference/troubleshooting.md).
|
||||
|
||||
**Auto-Activation Logic:**
|
||||
|
||||
| Request Contains | Servers Activated |
|
||||
|-----------------|------------------|
|
||||
| Library imports, API names | **context7** |
|
||||
| `--think`, debugging | **sequential-thinking** |
|
||||
| `component`, `UI`, frontend | **magic** |
|
||||
| `test`, `e2e`, `browser` | **playwright** |
|
||||
| Multi-file edits, refactoring | **morphllm-fast-apply** |
|
||||
| Large projects, sessions | **serena** |
|
||||
| `/sc:research`, `latest`, `current` | **tavily** |
|
||||
| `performance`, `debug`, `LCP` | **chrome-devtools** |
|
||||
|
||||
## Server Details
|
||||
|
||||
### context7 📚
|
||||
**Purpose**: Official library documentation access
|
||||
**Triggers**: Import statements, framework keywords, documentation requests
|
||||
**Requirements**: Node.js 16+, no API key
|
||||
|
||||
```bash
|
||||
# Automatic activation
|
||||
/sc:implement "React authentication system"
|
||||
# → Provides official React patterns
|
||||
|
||||
# Manual activation
|
||||
/sc:analyze auth-system/ --c7
|
||||
```
|
||||
|
||||
### sequential-thinking 🧠
|
||||
**Purpose**: Structured multi-step reasoning and systematic analysis
|
||||
**Triggers**: Complex debugging, `--think` flags, architectural analysis
|
||||
**Requirements**: Node.js 16+, no API key
|
||||
|
||||
```bash
|
||||
# Automatic activation
|
||||
/sc:troubleshoot "API performance issues"
|
||||
# → Enables systematic root cause analysis
|
||||
|
||||
# Manual activation
|
||||
/sc:analyze --think-hard architecture/
|
||||
```
|
||||
|
||||
### magic ✨
|
||||
**Purpose**: Modern UI component generation from 21st.dev patterns
|
||||
**Triggers**: UI requests, `/ui` commands, component development
|
||||
**Requirements**: Node.js 16+, TWENTYFIRST_API_KEY ()
|
||||
|
||||
```bash
|
||||
# Automatic activation
|
||||
/sc:implement "responsive dashboard component"
|
||||
# → Generates accessible UI with modern patterns
|
||||
|
||||
# API key setup
|
||||
export TWENTYFIRST_API_KEY="your_key_here"
|
||||
```
|
||||
|
||||
### playwright 🎭
|
||||
**Purpose**: Real browser automation and E2E testing
|
||||
**Triggers**: Browser testing, E2E scenarios, visual validation
|
||||
**Requirements**: Node.js 16+, no API key
|
||||
|
||||
```bash
|
||||
# Automatic activation
|
||||
/sc:test --type e2e "user login flow"
|
||||
# → Enables browser automation testing
|
||||
|
||||
# Manual activation
|
||||
/sc:validate "accessibility compliance" --play
|
||||
```
|
||||
|
||||
### morphllm-fast-apply 🔄
|
||||
**Purpose**: Efficient pattern-based code transformations
|
||||
**Triggers**: Multi-file edits, refactoring, framework migrations
|
||||
**Requirements**: Node.js 16+, MORPH_API_KEY
|
||||
|
||||
```bash
|
||||
# Automatic activation
|
||||
/sc:improve legacy-codebase/ --focus maintainability
|
||||
# → Applies consistent patterns across files
|
||||
|
||||
# API key setup
|
||||
export MORPH_API_KEY="your_key_here"
|
||||
```
|
||||
|
||||
### serena 🧭
|
||||
**Purpose**: Semantic code understanding with project memory
|
||||
**Triggers**: Symbol operations, large codebases, session management
|
||||
**Requirements**: Python 3.9+, uv package manager, no API key
|
||||
|
||||
```bash
|
||||
# Automatic activation
|
||||
/sc:load existing-project/
|
||||
# → Builds project understanding and memory
|
||||
|
||||
# Manual activation
|
||||
/sc:refactor "extract UserService" --serena
|
||||
```
|
||||
|
||||
### tavily 🔍
|
||||
**Purpose**: Web search and real-time information retrieval for research
|
||||
**Triggers**: `/sc:research` commands, "latest" information requests, current events, fact-checking
|
||||
**Requirements**: Node.js 16+, TAVILY_API_KEY (free tier available at https://app.tavily.com)
|
||||
|
||||
```bash
|
||||
# Automatic activation
|
||||
/sc:research "latest AI developments 2024"
|
||||
# → Performs intelligent web research
|
||||
|
||||
# Manual activation
|
||||
/sc:analyze "market trends" --tavily
|
||||
|
||||
# API key setup (get free key at https://app.tavily.com)
|
||||
export TAVILY_API_KEY="tvly-your_api_key_here"
|
||||
```
|
||||
|
||||
### chrome-devtools 📊
|
||||
**Purpose**: Performance analysis, debugging, and real-time browser inspection
|
||||
**Triggers**: Performance auditing, debugging layout issues (e.g., CLS), slow loading times (LCP), console errors, network requests
|
||||
**Requirements**: Node.js 16+, no API key
|
||||
|
||||
```bash
|
||||
# Automatic activation
|
||||
/sc:debug "page is loading slowly"
|
||||
# → Enables performance analysis with Chrome DevTools
|
||||
|
||||
# Manual activation
|
||||
/sc:analyze --performance "homepage"
|
||||
```
|
||||
|
||||
**Capabilities:**
|
||||
- **Web Search**: Comprehensive searches with ranking and filtering
|
||||
- **News Search**: Time-filtered current events and updates
|
||||
- **Content Extraction**: Full-text extraction from search results
|
||||
- **Domain Filtering**: Include/exclude specific domains
|
||||
- **Multi-Hop Research**: Iterative searches based on findings (up to 5 hops)
|
||||
|
||||
**Research Depth Control:**
|
||||
- `--depth quick`: 5-10 sources, basic synthesis
|
||||
- `--depth standard`: 10-20 sources, structured report (default)
|
||||
- `--depth deep`: 20-40 sources, comprehensive analysis
|
||||
- `--depth exhaustive`: 40+ sources, academic-level research
|
||||
|
||||
## Configuration
|
||||
|
||||
**MCP Configuration File (`~/.claude.json`):**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"context7": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@upstash/context7-mcp@latest"]
|
||||
},
|
||||
"sequential-thinking": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
|
||||
},
|
||||
"magic": {
|
||||
"command": "npx",
|
||||
"args": ["@21st-dev/magic"],
|
||||
"env": {"TWENTYFIRST_API_KEY": "${TWENTYFIRST_API_KEY}"}
|
||||
},
|
||||
"playwright": {
|
||||
"command": "npx",
|
||||
"args": ["@playwright/mcp@latest"]
|
||||
},
|
||||
"morphllm-fast-apply": {
|
||||
"command": "npx",
|
||||
"args": ["@morph-llm/morph-fast-apply"],
|
||||
"env": {"MORPH_API_KEY": "${MORPH_API_KEY}"}
|
||||
},
|
||||
"serena": {
|
||||
"command": "uvx",
|
||||
"args": ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "ide-assistant"]
|
||||
},
|
||||
"tavily": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "tavily-mcp@latest"],
|
||||
"env": {"TAVILY_API_KEY": "${TAVILY_API_KEY}"}
|
||||
},
|
||||
"chrome-devtools": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "chrome-devtools-mcp@latest"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
**Server Control:**
|
||||
```bash
|
||||
# Enable specific servers
|
||||
/sc:analyze codebase/ --c7 --seq
|
||||
|
||||
# Disable all MCP servers
|
||||
/sc:implement "simple function" --no-mcp
|
||||
|
||||
# Enable all servers
|
||||
/sc:design "complex architecture" --all-mcp
|
||||
```
|
||||
|
||||
**Multi-Server Coordination:**
|
||||
```bash
|
||||
# Full-stack development
|
||||
/sc:implement "e-commerce checkout"
|
||||
# → Sequential: workflow analysis
|
||||
# → Context7: payment patterns
|
||||
# → Magic: UI components
|
||||
# → Serena: code organization
|
||||
# → Playwright: E2E testing
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Common Issues:**
|
||||
- **No servers connected**: Check Node.js: `node --version` (need v16+)
|
||||
- **Context7 fails**: Clear cache: `npm cache clean --force`
|
||||
- **Magic/Morphllm errors**: Expected without API keys (paid services)
|
||||
- **Server timeouts**: Restart Claude Code session
|
||||
|
||||
**Quick Fixes:**
|
||||
```bash
|
||||
# Reset connections
|
||||
# Restart Claude Code session
|
||||
|
||||
# Check dependencies
|
||||
node --version # Should show v16+
|
||||
|
||||
# Test without MCP
|
||||
/sc:command --no-mcp
|
||||
|
||||
# Check configuration
|
||||
ls ~/.claude.json
|
||||
```
|
||||
|
||||
**API Key Configuration:**
|
||||
```bash
|
||||
# For Magic server (required for UI generation)
|
||||
export TWENTYFIRST_API_KEY="your_key_here"
|
||||
|
||||
# For Morphllm server (required for bulk transformations)
|
||||
export MORPH_API_KEY="your_key_here"
|
||||
|
||||
# For Tavily server (required for web search - free tier available)
|
||||
export TAVILY_API_KEY="tvly-your_key_here"
|
||||
|
||||
# Add to shell profile for persistence
|
||||
echo 'export TWENTYFIRST_API_KEY="your_key"' >> ~/.bashrc
|
||||
echo 'export MORPH_API_KEY="your_key"' >> ~/.bashrc
|
||||
echo 'export TAVILY_API_KEY="your_key"' >> ~/.bashrc
|
||||
```
|
||||
|
||||
**Environment Variable Usage:**
|
||||
- ✅ `TWENTYFIRST_API_KEY` - Required for Magic MCP server functionality
|
||||
- ✅ `MORPH_API_KEY` - Required for Morphllm MCP server functionality
|
||||
- ✅ `TAVILY_API_KEY` - Required for Tavily MCP server functionality (free tier available)
|
||||
- ❌ Other env vars in docs - Examples only, not used by framework
|
||||
- 📝 Magic and Morphllm are paid services, Tavily has free tier, framework works without them
|
||||
|
||||
## Server Combinations
|
||||
|
||||
**No API Keys (Free)**:
|
||||
- context7 + sequential-thinking + playwright + serena
|
||||
|
||||
**1 API Key**:
|
||||
- Add magic for professional UI development
|
||||
|
||||
**2 API Keys**:
|
||||
- Add morphllm-fast-apply for large-scale refactoring
|
||||
|
||||
**Common Workflows:**
|
||||
- **Learning**: context7 + sequential-thinking
|
||||
- **Web Development**: magic + context7 + playwright
|
||||
- **Enterprise Refactoring**: serena + morphllm + sequential-thinking
|
||||
- **Complex Analysis**: sequential-thinking + context7 + serena
|
||||
- **Deep Research**: tavily + sequential-thinking + serena + playwright
|
||||
- **Current Events**: tavily + context7 + sequential-thinking
|
||||
- **Performance Tuning**: chrome-devtools + sequential-thinking + playwright
|
||||
|
||||
## Integration
|
||||
|
||||
**With SuperClaude Commands:**
|
||||
- Analysis commands automatically use Sequential + Serena
|
||||
- Implementation commands use Magic + Context7
|
||||
- Testing commands use Playwright + Sequential
|
||||
- Research commands use Tavily + Sequential + Playwright
|
||||
|
||||
**With Behavioral Modes:**
|
||||
- Brainstorming Mode: Sequential for discovery
|
||||
- Task Management: Serena for persistence
|
||||
- Orchestration Mode: Optimal server selection
|
||||
- Deep Research Mode: Tavily + Sequential + Playwright coordination
|
||||
|
||||
**Performance Control:**
|
||||
- Automatic resource management based on system load
|
||||
- Concurrency control: `--concurrency N` (1-15)
|
||||
- Priority-based server selection under constraints
|
||||
|
||||
## Related Resources
|
||||
|
||||
**Essential Reading:**
|
||||
- [Commands Guide](commands.md) - Commands that activate MCP servers
|
||||
- [Quick Start Guide](../Getting-Started/quick-start.md) - MCP setup guide
|
||||
|
||||
**Advanced Usage:**
|
||||
- [Behavioral Modes](modes.md) - Mode-MCP coordination
|
||||
- [Agents Guide](agents.md) - Agent-MCP integration
|
||||
- [Session Management](session-management.md) - Serena workflows
|
||||
|
||||
**Technical References:**
|
||||
- [Examples Cookbook](../Reference/examples-cookbook.md) - MCP workflow patterns
|
||||
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Integration details
|
||||
Reference in New Issue
Block a user