FoundryVTT/MCP_SERVERS_GUIDE.md

# MCP Servers - Complete Guide

> **Comprehensive documentation for all Model Context Protocol (MCP) servers used in Claude Code**
> **Version**: 1.0.0 | **Last Updated**: 2025-10-20

---

## Table of Contents

1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Installation & Setup](#installation--setup)
4. [Available MCP Servers](#available-mcp-servers)
5. [Usage Guide](#usage-guide)
6. [Configuration](#configuration)
7. [Best Practices](#best-practices)
8. [Troubleshooting](#troubleshooting)
9. [Advanced Topics](#advanced-topics)

---

## Overview

### What Are MCP Servers?

**Model Context Protocol (MCP)** servers extend Claude Code's capabilities by providing:
- External integrations (databases, browsers, desktop automation)
- Enhanced code navigation and analysis
- Persistent and temporary memory systems
- Real-time documentation access
- Complex reasoning capabilities

### MCP Servers in This Project

This project includes **8 fully configured MCP servers**:

| # | Server | Type | Purpose |
|---|--------|------|---------|
| 1 | **Serena** | Python (uvx) | Code navigation + persistent memory |
| 2 | **Sequential Thinking** | Node.js (npx) | Complex reasoning engine |
| 3 | **Database Server** | Node.js (npx) | SQL Server integration |
| 4 | **Context7** | Node.js (npx) | Library documentation |
| 5 | **Memory** | Node.js (npx) | Knowledge graph (session) |
| 6 | **Fetch** | Python (uvx) | Web content retrieval |
| 7 | **Windows MCP** | Python (uv) | Desktop automation |
| 8 | **Playwright** | Node.js (npx) | Browser automation |

### MCP vs Core Tools

**Core Tools** (built-in):
- Read, Write, Edit - File operations
- Glob, Grep - File search
- Bash - Shell commands
- WebSearch, WebFetch - Web access

**MCP Servers** (extended):
- Semantic code navigation
- Persistent knowledge storage
- Complex reasoning
- Browser/desktop automation
- Database access

---

## Quick Start

### One-Command Setup

**Windows (PowerShell)**:
```powershell
.\.claude\tools\setup-all-mcp-servers.ps1
```

**Linux/Mac (Bash)**:
```bash
./.claude/tools/setup-all-mcp-servers.sh
```

### Verify Installation

```bash
# Test all servers
.\.claude\tools\test-mcp-servers.ps1

# Or check individual servers
claude mcp list
claude mcp test serena
```

### Quick Test

```bash
# In Claude Code
> "Use Serena to find the UserService class"
> "Create a knowledge graph of the authentication flow"
> "Get the latest React documentation"
```

---

## Installation & Setup

### Prerequisites

The setup script checks for and guides installation of:

1. **Node.js** (v18+) - For npm-based servers
   - Download: https://nodejs.org/

2. **Python 3** (3.8+) - For Python-based servers
   - Download: https://www.python.org/

3. **uv** - Python package manager
   - Auto-installed by setup script
   - Manual: `curl -LsSf https://astral.sh/uv/install.sh | sh`

4. **Git** (optional, recommended)
   - For cloning repositories
   - Download: https://git-scm.com/

### Automated Setup Process

The setup script:
1. ✅ Checks prerequisites
2. ✅ Installs all 8 MCP servers
3. ✅ Creates required directories
4. ✅ Validates configuration
5. ✅ Provides next steps

**Time Required**: ~5-10 minutes

### Manual Installation

If automated setup fails, install servers individually:

#### Serena
```bash
uvx --from "git+https://github.com/oraios/serena" serena --help
```

#### Sequential Thinking
```bash
npx -y @modelcontextprotocol/server-sequential-thinking
```

#### Database Server
```bash
npx -y @executeautomation/database-server
```

#### Context7
```bash
npx -y @upstash/context7-mcp
```

#### Memory
```bash
npx -y @modelcontextprotocol/server-memory
```

#### Fetch
```bash
uvx mcp-server-fetch
```

#### Windows MCP
```bash
git clone https://github.com/lekt9/windows-mcp.git .windows-mcp
cd .windows-mcp
uv sync
```

#### Playwright
```bash
npx -y @playwright/mcp
npx playwright install  # Install browsers
```

### Post-Setup Configuration

After running setup, configure secrets:

#### 1. Enable MCP Servers
Already configured in `.claude/settings.json`:
```json
{
  "enableAllProjectMcpServers": true
}
```

#### 2. Context7 API Key (Optional)
Edit `.mcp.json`:
```json
"context7": {
  "env": {
    "CONTEXT7_API_KEY": "your-api-key-here"
  }
}
```
Get key at: https://context7.com/

#### 3. Database Connection (Optional)
Edit `.mcp.json`:
```json
"database-server": {
  "args": [
    "--server", "your-server",
    "--database", "your-database",
    "--user", "your-username",
    "--password", "your-password",
    "--trustServerCertificate"
  ]
}
```

#### 4. Restart Claude Code
Close and reopen Claude Code to load servers.

---

## Available MCP Servers

### 1. Serena MCP

**Purpose**: Semantic code analysis and persistent memory

**Type**: Python (uvx)

**Repository**: https://github.com/oraios/serena

**Configuration**:
```json
{
  "command": "uvx",
  "args": [
    "--from", "git+https://github.com/oraios/serena",
    "serena", "start-mcp-server",
    "--context", "ide-assistant",
    "--project", "Claude Code Setup"
  ]
}
```

#### Code Navigation Tools

**`find_symbol`** - Locate code symbols by name/pattern
```bash
# Find a class
find_symbol("UserService")

# Find with pattern
find_symbol("*Service")

# Find with depth (include methods)
find_symbol("UserService", depth=1, include_body=true)
```

**`find_referencing_symbols`** - Find all references to a symbol
```bash
# Find who uses this function
find_referencing_symbols("authenticate", "src/auth/service.ts")
```

**`get_symbols_overview`** - Get file structure
```bash
# Get high-level view of file
get_symbols_overview("src/services/user.ts")
```

**`search_for_pattern`** - Search for code patterns
```bash
# Find pattern across codebase
search_for_pattern("async.*await", paths_include_glob="**/*.ts")
```

**`rename_symbol`** - Safely rename across codebase
```bash
# Rename everywhere
rename_symbol("oldName", "src/file.ts", "newName")
```

**`replace_symbol_body`** - Replace function/class body
```bash
# Replace entire method
replace_symbol_body("methodName", "src/file.ts", new_body)
```

**`insert_after_symbol`** / **`insert_before_symbol`** - Add code
```bash
# Add new method after existing one
insert_after_symbol("existingMethod", "src/file.ts", new_method_code)
```

#### Persistent Memory Tools

**Storage**: `.serena/memories/` (survives across sessions)

**`write_memory`** - Store persistent project information
```bash
write_memory("adr-001-architecture", "Decision: Use microservices...")
```

**`read_memory`** - Recall stored information
```bash
read_memory("adr-001-architecture")
```

**`list_memories`** - Browse all memories
```bash
list_memories()
```

**`delete_memory`** - Remove outdated information
```bash
delete_memory("outdated-info")
```

#### Use Serena Memory For

✅ **Long-term project knowledge**:
- Architectural Decision Records (ADRs)
- Code review findings and summaries
- Lessons learned from implementations
- Project-specific patterns discovered
- Technical debt registry
- Security audit results
- Performance optimization notes
- Migration documentation
- Incident post-mortems

❌ **Do NOT use for**:
- Temporary analysis state
- Current conversation context
- Session-specific tracking

#### Memory File Naming Conventions

**ADRs (Architectural Decision Records)**:
```
adr-001-database-choice-postgresql
adr-002-authentication-jwt-strategy
adr-003-api-versioning-approach
```

**Code Reviews**:
```
code-review-2024-10-15-payment-service
code-review-2025-10-20-auth-refactor
```

**Lessons Learned**:
```
lesson-async-error-handling
lesson-database-connection-pooling
lesson-api-rate-limiting
```

**Patterns**:
```
pattern-repository-implementation
pattern-error-response-format
pattern-logging-strategy
```

**Technical Debt**:
```
debt-legacy-api-authentication
debt-payment-service-refactor-needed
```

**Security**:
```
security-audit-2024-10-full
security-vulnerability-xss-fixed
security-pattern-input-validation
```

**Performance**:
```
performance-optimization-query-caching
performance-analysis-api-endpoints
```

---

### 2. Sequential Thinking MCP

**Purpose**: Chain-of-thought reasoning for complex problems

**Type**: Node.js (npx)

**Package**: `@modelcontextprotocol/server-sequential-thinking`

**Configuration**:
```json
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
}
```

#### Capabilities

**`sequentialthinking`** - Multi-step reasoning tool

**Features**:
- Dynamic thought count adjustment
- Revision of previous thoughts
- Branch exploration
- Hypothesis generation and verification
- Flexible problem-solving

**Parameters**:
- `thought` - Current thinking step
- `thought_number` - Current step number
- `total_thoughts` - Estimated total (adjustable)
- `next_thought_needed` - Continue or stop
- `is_revision` - Is this revising previous thought
- `branch_id` - Identifier for exploration branches

#### Use Cases

✅ **Best for**:
- Complex architectural decisions
- Multi-step debugging
- Design pattern selection
- Security threat analysis
- Algorithm optimization
- System design problems

**Example Flow**:
1. Start with initial estimate of needed thoughts
2. Work through problem step-by-step
3. Revise previous thoughts if needed
4. Adjust total thoughts as understanding deepens
5. Generate hypothesis
6. Verify hypothesis
7. Provide final answer

---

### 3. Database Server MCP

**Purpose**: SQL Server database interaction

**Type**: Node.js (npx)

**Package**: `@executeautomation/database-server`

**Configuration**:
```json
{
  "command": "npx",
  "args": [
    "-y", "@executeautomation/database-server",
    "--sqlserver",
    "--server", "your-server",
    "--database", "your-database",
    "--user", "your-username",
    "--password", "your-password",
    "--trustServerCertificate"
  ]
}
```

#### Available Tools

**`read_query`** - Execute SELECT queries
```sql
SELECT * FROM Users WHERE active = 1
```

**`write_query`** - Execute INSERT, UPDATE, DELETE
```sql
UPDATE Users SET last_login = GETDATE() WHERE id = 123
```

**`create_table`** - Create new tables
```sql
CREATE TABLE Products (
  id INT PRIMARY KEY,
  name VARCHAR(255),
  price DECIMAL(10,2)
)
```

**`alter_table`** - Modify table schema
```sql
ALTER TABLE Products ADD description TEXT
```

**`drop_table`** - Remove tables (with confirmation)
```bash
drop_table("old_table", confirm=true)
```

**`list_tables`** - Get all tables in database
```bash
list_tables()
```

**`describe_table`** - View table schema
```bash
describe_table("Users")
```

**`export_query`** - Export results to CSV/JSON
```bash
export_query("SELECT * FROM Users", format="csv")
```

**`append_insight`** - Add business insight to memo
```bash
append_insight("Sales increased 20% after new feature")
```

**`list_insights`** - View all insights
```bash
list_insights()
```

#### Use Cases

✅ **Best for**:
- Database schema exploration
- Query development and testing
- Data analysis
- Business intelligence
- Database migrations
- Performance testing

---

### 4. Context7 MCP

**Purpose**: Real-time library documentation access

**Type**: Node.js (npx)

**Package**: `@upstash/context7-mcp`

**Website**: https://context7.com/

**Configuration**:
```json
{
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp"],
  "env": {
    "CONTEXT7_API_KEY": "your-api-key-here"
  }
}
```

#### Available Tools

**`resolve-library-id`** - Find library identifier
```bash
# Find library ID
resolve-library-id("react")
# Returns: "/facebook/react"

resolve-library-id("next.js")
# Returns: "/vercel/next.js"
```

**Selection Criteria**:
- Name similarity (exact matches prioritized)
- Description relevance
- Documentation coverage (code snippets count)
- Trust score (7-10 prioritized)

**`get-library-docs`** - Get current documentation
```bash
# Get React docs
get-library-docs("/facebook/react", topic="hooks")

# Get specific version
get-library-docs("/vercel/next.js/v14.3.0", topic="routing")

# Control token usage
get-library-docs("/mongodb/docs", tokens=10000)
```

**Parameters**:
- `context7CompatibleLibraryID` - Library ID from resolve-library-id
- `topic` - Focus area (optional)
- `tokens` - Max tokens (default: 5000)

#### Use Cases

✅ **Best for**:
- Learning new frameworks
- Getting up-to-date API references
- Finding best practices
- Code examples from official docs
- Version-specific documentation

**Example Workflow**:
```bash
# 1. Find library
resolve-library-id("supabase")

# 2. Get docs
get-library-docs("/supabase/supabase", topic="authentication")

# 3. Use in code
# Claude now has current Supabase auth docs
```

---

### 5. Memory MCP (Knowledge Graph)

**Purpose**: Temporary in-memory knowledge graph

**Type**: Node.js (npx)

**Package**: `@modelcontextprotocol/server-memory`

**Storage**: In-memory, **cleared after session ends**

**Configuration**:
```json
{
  "command": "powershell",
  "args": [
    "-ExecutionPolicy", "Bypass",
    "-File", ".\.claude\tools\start-memory.ps1"
  ]
}
```

#### Available Tools

**`create_entities`** - Create entities in graph
```javascript
create_entities([
  {
    name: "PaymentService",
    entityType: "Service",
    observations: [
      "Handles Stripe integration",
      "Located in src/services/payment.ts",
      "Depends on DatabaseService"
    ]
  },
  {
    name: "UserAuthentication",
    entityType: "Feature",
    observations: [
      "Uses JWT tokens",
      "Session timeout: 24 hours"
    ]
  }
])
```

**`create_relations`** - Define relationships
```javascript
create_relations([
  {
    from: "PaymentService",
    to: "DatabaseService",
    relationType: "depends_on"
  },
  {
    from: "UserAuthentication",
    to: "SessionManager",
    relationType: "uses"
  }
])
```

**`add_observations`** - Add details to entities
```javascript
add_observations([
  {
    entityName: "PaymentService",
    contents: [
      "Implemented retry logic",
      "Added webhook support"
    ]
  }
])
```

**`search_nodes`** - Search knowledge graph
```bash
search_nodes("payment")
```

**`read_graph`** - View entire graph
```bash
read_graph()
```

**`open_nodes`** - Retrieve specific entities
```bash
open_nodes(["PaymentService", "UserAuthentication"])
```

**`delete_entities`** - Remove entities
```bash
delete_entities(["OldFeature"])
```

**`delete_relations`** - Remove relationships
```javascript
delete_relations([
  {from: "A", to: "B", relationType: "uses"}
])
```

**`delete_observations`** - Remove specific observations
```javascript
delete_observations([
  {
    entityName: "PaymentService",
    observations: ["outdated info"]
  }
])
```

#### Use Cases

✅ **Best for**:
- Current conversation context
- Temporary analysis during task
- Entity relationships in current work
- Cross-file refactoring state (temporary)
- Session-specific tracking

❌ **Do NOT use for**:
- Long-term knowledge (use Serena instead)
- ADRs or lessons learned
- Project patterns
- Anything needed next week

#### Memory vs Serena Decision Tree

**Question**: Should this information exist next week?
- **YES** → Use Serena `write_memory`
- **NO** → Use Memory graph

**Storage Location**: `.memory-mcp/knowledge_graph.json` (managed by PowerShell script)

---

### 6. Fetch MCP

**Purpose**: Web content retrieval and conversion

**Type**: Python (uvx)

**Package**: `mcp-server-fetch`

**Configuration**:
```json
{
  "command": "uvx",
  "args": ["mcp-server-fetch"]
}
```

#### Available Tools

**`fetch`** - Retrieve and process URLs

**Parameters**:
- `url` - URL to fetch (required)
- `max_length` - Max characters (default: 5000)
- `start_index` - Start position (for pagination)
- `raw` - Get raw HTML instead of markdown

**Features**:
- Converts HTML to markdown
- Pagination support for long content
- Automatic HTTPS upgrade
- Self-cleaning 15-minute cache

**Examples**:
```bash
# Fetch documentation
fetch("https://docs.example.com/api")

# Get raw HTML
fetch("https://example.com", raw=true)

# Paginated content
fetch("https://long-page.com", start_index=5000, max_length=5000)
```

#### Use Cases

✅ **Best for**:
- API documentation scraping
- Web content analysis
- Integration documentation
- Blog post research
- Technical article retrieval

**Note**: When URL redirects to different host, tool informs you. Make new request with redirect URL.

---

### 7. Windows MCP

**Purpose**: Windows desktop automation

**Type**: Python (uv)

**Repository**: https://github.com/lekt9/windows-mcp

**Platform**: Windows only (won't affect other servers on Mac/Linux)

**Configuration**:
```json
{
  "command": "uv",
  "args": [
    "--directory", "./.windows-mcp",
    "run", "main.py"
  ]
}
```

#### Available Tools

**`Launch-Tool`** - Launch applications
```bash
Launch-Tool("notepad")
Launch-Tool("calculator")
Launch-Tool("chrome")
```

**`Powershell-Tool`** - Execute PowerShell commands
```bash
Powershell-Tool("Get-Process | Where-Object {$_.Name -like 'chrome*'}")
```

**`State-Tool`** - Capture desktop state
```bash
# Get UI elements, focused apps, interactive elements
State-Tool(use_vision=false)

# Include visual screenshot
State-Tool(use_vision=true)
```

**`Clipboard-Tool`** - Clipboard operations
```bash
# Copy text
Clipboard-Tool(mode="copy", text="Hello World")

# Paste (retrieve)
Clipboard-Tool(mode="paste")
```

**`Click-Tool`** - Click UI elements
```bash
# Left click at coordinates
Click-Tool(loc=[100, 200])

# Right click
Click-Tool(loc=[100, 200], button="right")

# Double click
Click-Tool(loc=[100, 200], clicks=2)
```

**`Type-Tool`** - Type text into fields
```bash
# Type text (append)
Type-Tool(loc=[100, 200], text="Hello")

# Clear and type
Type-Tool(loc=[100, 200], text="Hello", clear=true)

# Type and press Enter
Type-Tool(loc=[100, 200], text="search query", press_enter=true)
```

**`Resize-Tool`** - Resize/move windows
```bash
# Resize window
Resize-Tool(size=[800, 600])

# Move window
Resize-Tool(loc=[100, 100])
```

**`Switch-Tool`** - Switch to application
```bash
Switch-Tool("notepad")
Switch-Tool("chrome")
```

**`Scroll-Tool`** - Scroll content
```bash
# Scroll down at location
Scroll-Tool(loc=[400, 300], direction="down", wheel_times=3)

# Scroll horizontally
Scroll-Tool(type="horizontal", direction="right")
```

**`Drag-Tool`** - Drag and drop
```bash
Drag-Tool(from_loc=[100, 100], to_loc=[200, 200])
```

**`Move-Tool`** - Move mouse cursor
```bash
Move-Tool(to_loc=[300, 400])
```

**`Shortcut-Tool`** - Keyboard shortcuts
```bash
# Copy
Shortcut-Tool(["ctrl", "c"])

# Alt+Tab
Shortcut-Tool(["alt", "tab"])

# Windows+R
Shortcut-Tool(["win", "r"])
```

**`Key-Tool`** - Press individual keys
```bash
Key-Tool("enter")
Key-Tool("escape")
Key-Tool("f5")
```

**`Wait-Tool`** - Pause execution
```bash
Wait-Tool(duration=5)  # Wait 5 seconds
```

**`Scrape-Tool`** - Scrape webpage to markdown
```bash
Scrape-Tool("https://example.com")
```

#### Use Cases

✅ **Best for**:
- GUI automation
- Desktop testing
- Windows-specific operations
- Application interaction
- Screen automation workflows

---

### 8. Playwright MCP

**Purpose**: Browser automation and testing

**Type**: Node.js (npx)

**Package**: `@playwright/mcp`

**Website**: https://playwright.dev/

**Configuration**:
```json
{
  "command": "npx",
  "args": ["-y", "@playwright/mcp"]
}
```

**Additional Setup**: Run `npx playwright install` to install browsers

#### Available Tools

**Navigation**:
- `browser_navigate` - Navigate to URL
- `browser_navigate_back` - Go back

**Interaction**:
- `browser_click` - Click elements
- `browser_type` - Type text
- `browser_fill_form` - Fill multiple form fields
- `browser_select_option` - Select dropdown options
- `browser_hover` - Hover over elements
- `browser_drag` - Drag and drop

**Keyboard**:
- `browser_press_key` - Press keys
- `browser_evaluate` - Execute JavaScript

**Capture**:
- `browser_snapshot` - Accessibility snapshot (better than screenshot)
- `browser_take_screenshot` - Take visual screenshot

**Monitoring**:
- `browser_console_messages` - Get console logs
- `browser_network_requests` - View network traffic

**Window Management**:
- `browser_tabs` - Manage tabs (list, create, close, select)
- `browser_resize` - Resize browser window
- `browser_close` - Close browser

**Advanced**:
- `browser_file_upload` - Upload files
- `browser_handle_dialog` - Handle alerts/confirms
- `browser_wait_for` - Wait for conditions

#### Usage Examples

**Basic Navigation**:
```javascript
// Navigate and capture
browser_navigate("https://example.com")
browser_snapshot()

// Take screenshot
browser_take_screenshot(filename="page.png")
```

**Form Interaction**:
```javascript
// Fill form
browser_fill_form([
  {name: "username", type: "textbox", ref: "input#user", value: "john"},
  {name: "password", type: "textbox", ref: "input#pass", value: "secret"},
  {name: "remember", type: "checkbox", ref: "input#rem", value: "true"}
])

// Click submit
browser_click(element="Submit button", ref="button[type='submit']")
```

**Testing Workflow**:
```javascript
// 1. Navigate
browser_navigate("https://app.example.com/login")

// 2. Fill and submit
browser_type(element="Username field", ref="input#user", text="test@example.com")
browser_type(element="Password field", ref="input#pass", text="password")
browser_click(element="Login button", ref="button.login")

// 3. Wait and verify
browser_wait_for(text="Welcome")
browser_snapshot()

// 4. Check network
browser_network_requests()
```

**Tab Management**:
```javascript
// List tabs
browser_tabs(action="list")

// Create new tab
browser_tabs(action="new")

// Switch to tab
browser_tabs(action="select", index=1)

// Close tab
browser_tabs(action="close", index=2)
```

#### Use Cases

✅ **Best for**:
- E2E testing
- Web scraping
- UI automation
- Browser-based workflows
- Screenshot capture
- Network monitoring
- Console debugging

---

## Usage Guide

### Quick Decision Tree

**Need to navigate code?**
→ Use **Serena** code functions

**Need to store knowledge long-term?**
→ Use **Serena** `write_memory`

**Building temporary context for current task?**
→ Use **Memory** graph

**Need current library docs?**
→ Use **Context7**

**Complex problem requiring deep thought?**
→ Use **Sequential Thinking**

**Need to automate browser?**
→ Use **Playwright**

**Need Windows desktop automation?**
→ Use **Windows MCP**

**Need to query database?**
→ Use **Database Server**

**Need to scrape web content?**
→ Use **Fetch**

### Usage by Agent Type

#### Architect Agent
```markdown
## MCP Usage

**Serena**:
- `get_symbols_overview` - Understand current architecture
- `find_symbol` - Locate key components
- `write_memory` - Store ADRs:
  - "adr-001-microservices-architecture"
  - "adr-002-database-choice-postgresql"

**Memory**:
- `create_entities` - Components being designed
- `create_relations` - Model dependencies
- `add_observations` - Document design rationale

Note: After design finalized, store in Serena memory as ADR
```

#### Code Reviewer Agent
```markdown
## MCP Usage

**Serena**:
- `find_symbol` - Locate reviewed code
- `find_referencing_symbols` - Impact analysis
- `write_memory` - Store review findings:
  - "code-review-2024-10-payment-service"

**Memory**:
- `create_entities` - Issues found (Critical, Warning, Suggestion)
- `create_relations` - Link issues to code locations
- `add_observations` - Fix recommendations

Note: Summary stored in Serena memory after review
```

#### Security Analyst Agent
```markdown
## MCP Usage

**Serena**:
- `find_symbol` - Locate security-sensitive code
- `search_for_pattern` - Find potential vulnerabilities
- `write_memory` - Store audit results:
  - "security-audit-2024-10-full-scan"
  - "vulnerability-sql-injection-fixed"

**Memory**:
- `create_entities` - Vulnerabilities found
- `create_relations` - Link to affected code
- `add_observations` - Document severity and remediation
```

#### Test Engineer Agent
```markdown
## MCP Usage

**Serena**:
- `find_symbol` - Locate code to test
- `find_referencing_symbols` - Understand dependencies
- `write_memory` - Store test patterns:
  - "test-pattern-async-handlers"
  - "test-pattern-database-mocking"

**Memory**:
- `create_entities` - Test cases being generated
- `create_relations` - Link tests to code under test

**Playwright**:
- Browser testing automation
```

### Usage in Slash Commands

#### /implement Command
```markdown
## MCP Usage

**Serena**:
- `find_symbol` - Locate existing patterns
- `find_referencing_symbols` - Understand dependencies
- `rename_symbol` - Refactor safely
- `write_memory` - Store lessons:
  - "lesson-payment-integration-stripe"
  - "pattern-error-handling-async"

**Memory**:
- `create_entities` - Track features being implemented
- `create_relations` - Model integration points

**Context7**:
- `get-library-docs` - Current framework docs
```

#### /analyze Command
```markdown
## MCP Usage

**Serena**:
- `get_symbols_overview` - Understand structure
- `find_symbol` - Locate complex code
- `search_for_pattern` - Find duplicates
- `write_memory` - Store findings:
  - "analysis-2024-10-technical-debt"
  - "analysis-complexity-hotspots"

**Memory**:
- `create_entities` - Files/functions analyzed
- `create_relations` - Model dependencies
- `add_observations` - Document metrics
```

---

## Configuration

### Main Configuration File

**Location**: `.mcp.json` (project root)

**Format**:
```json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/oraios/serena",
        "serena", "start-mcp-server",
        "--context", "ide-assistant",
        "--project", "ProjectName"
      ]
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "database-server": {
      "command": "npx",
      "args": [
        "-y", "@executeautomation/database-server",
        "--sqlserver",
        "--server", "server-name",
        "--database", "db-name",
        "--user", "username",
        "--password", "password",
        "--trustServerCertificate"
      ]
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {
        "CONTEXT7_API_KEY": "your-key"
      }
    },
    "memory": {
      "command": "powershell",
      "args": [
        "-ExecutionPolicy", "Bypass",
        "-File", ".\.claude\tools\start-memory.ps1"
      ]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory", "./.windows-mcp",
        "run", "main.py"
      ]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}
```

### Claude Settings Configuration

**Location**: `.claude/settings.json`

**Enable MCP Servers**:
```json
{
  "enableAllProjectMcpServers": true
}
```

**Enable Specific Servers**:
```json
{
  "mcpServers": {
    "serena": {"enabled": true},
    "memory": {"enabled": true},
    "context7": {"enabled": true}
  }
}
```

### Environment Variables

**Context7 API Key**:
```bash
# Option 1: In .mcp.json (not recommended for git)
"env": {"CONTEXT7_API_KEY": "ctx7sk-..."}

# Option 2: System environment variable (recommended)
export CONTEXT7_API_KEY="ctx7sk-..."
```

**Database Credentials**:
```bash
# Use environment variables for security
export DB_SERVER="server-name"
export DB_USER="username"
export DB_PASSWORD="password"

# Reference in .mcp.json
"args": ["--server", "${DB_SERVER}", "--user", "${DB_USER}"]
```

---

## Best Practices

### Memory Management

**Use Serena Memory For**:
- ✅ Architectural Decision Records
- ✅ Code review summaries
- ✅ Lessons learned
- ✅ Project patterns
- ✅ Technical debt tracking
- ✅ Security findings
- ✅ Performance notes

**Use Memory Graph For**:
- ✅ Current conversation context
- ✅ Temporary analysis state
- ✅ Session-specific tracking
- ✅ Cross-file refactoring state

**DON'T Mix Them**:
- ❌ Don't store temporary info in Serena
- ❌ Don't expect Memory graph to persist

### Code Navigation Efficiency

**Good Practice** (efficient):
```bash
# 1. Get overview first
get_symbols_overview("src/service.ts")

# 2. Target specific symbols
find_symbol("UserService/authenticate", include_body=true)

# 3. Find references if needed
find_referencing_symbols("authenticate", "src/service.ts")
```

**Bad Practice** (wasteful):
```bash
# Reading entire files unnecessarily
Read("src/service.ts")  # 1000 lines
Read("src/utils.ts")    # 500 lines
Read("src/auth.ts")     # 800 lines
```

### Documentation Lookup Pattern

**Correct Workflow**:
```bash
# 1. Always resolve library ID first
resolve-library-id("react")
# Returns: /facebook/react

# 2. Then get docs
get-library-docs("/facebook/react", topic="hooks")
```

**Incorrect** (won't work):
```bash
# Don't skip resolve step
get-library-docs("react")  # ERROR: not a valid ID
```

### Browser Automation Best Practices

**Use Snapshots, Not Screenshots**:
```bash
# Good: Accessibility snapshot (faster, more data)
browser_snapshot()

# Use screenshots only when visual verification needed
browser_take_screenshot()
```

**Wait for Content**:
```bash
# Good: Wait for specific text
browser_wait_for(text="Welcome")

# Avoid arbitrary delays
browser_wait_for(time=5)  # Use only when necessary
```

### Database Query Safety

**Always Use Parameterized Queries**:
```sql
-- Good
SELECT * FROM Users WHERE id = @userId

-- Bad (SQL injection risk)
SELECT * FROM Users WHERE id = ${userInput}
```

**Test Before Write**:
```bash
# 1. Test with read_query
read_query("SELECT * FROM Users WHERE ...")

# 2. Verify results

# 3. Then write_query
write_query("UPDATE Users SET ...")
```

---

## Troubleshooting

### MCP Server Not Starting

**Problem**: Server fails to connect

**Solutions**:
1. Check `.mcp.json` syntax:
   ```bash
   cat .mcp.json | jq .
   ```

2. Test command manually:
   ```bash
   npx -y @modelcontextprotocol/server-memory
   uvx mcp-server-fetch
   ```

3. Check Claude Code logs:
   - Windows: `.claude\logs\`
   - Linux/Mac: `.claude/logs/`

4. Verify prerequisites installed:
   ```bash
   node --version  # Should be 18+
   python --version  # Should be 3.8+
   npm --version
   uv --version
   ```

5. Restart Claude Code after config changes

### Serena Memory Not Persisting

**Problem**: Memories disappear between sessions

**Check**:
1. Verify storage location exists:
   ```bash
   ls .serena/memories/
   ```

2. Check memory was actually written:
   ```bash
   list_memories()
   ```

3. Ensure using `write_memory`, not Memory graph:
   ```bash
   # Correct (persists)
   write_memory("my-memory", "content")

   # Wrong (session only)
   create_entities([{name: "my-memory", ...}])
   ```

### Memory Graph Empty After Restart

**This is normal!** Memory graph is **session-only storage**.

**If you need persistence**: Use Serena `write_memory` instead.

### Context7 Not Working

**Problem**: Library docs not retrieved

**Solutions**:
1. Check API key configured:
   ```bash
   cat .mcp.json | jq '.mcpServers.context7.env'
   ```

2. Get free API key: https://context7.com/

3. Always resolve library ID first:
   ```bash
   # Required first step
   resolve-library-id("library-name")
   ```

4. Use correct ID format:
   ```bash
   # Correct
   get-library-docs("/facebook/react")

   # Wrong
   get-library-docs("react")
   ```

### Playwright Browsers Not Installed

**Problem**: Browser automation fails

**Solution**:
```bash
npx playwright install
npx playwright install chromium  # Just Chromium
```

**Verify**:
```bash
npx playwright --version
```

### Windows MCP Not Working on Mac/Linux

**This is normal!** Windows MCP is Windows-only.

**It won't break other servers** - they'll continue working.

**On Mac/Linux**: Simply ignore Windows MCP server errors.

### Database Connection Failed

**Problem**: Cannot connect to SQL Server

**Solutions**:
1. Verify connection details:
   ```bash
   # Test connection manually
   sqlcmd -S server -U user -P password -d database
   ```

2. Check `.mcp.json` configuration:
   ```json
   "--server", "correct-server-name",
   "--database", "correct-db-name",
   "--user", "correct-username",
   "--password", "correct-password"
   ```

3. Add `--trustServerCertificate` if using self-signed certs

4. Check network connectivity and firewall rules

### Permission Errors

**Problem**: MCP server command denied

**Solutions**:
1. Check file permissions:
   ```bash
   # Linux/Mac
   chmod +x .claude/tools/*.sh

   # Windows PowerShell
   Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
   ```

2. Verify tool allowed in `.claude/settings.json`:
   ```json
   {
     "permissions": {
       "allowed": ["mcp__serena__*", "mcp__memory__*"]
     }
   }
   ```

### Command Not Found (npx/uvx)

**Problem**: Setup script can't find package managers

**Solutions**:
1. Install Node.js: https://nodejs.org/
2. Install Python and uv:
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

3. Restart terminal after installation

4. Verify installation:
   ```bash
   npx --version
   uvx --version
   ```

---

## Advanced Topics

### Custom MCP Server Configuration

You can add your own MCP servers to `.mcp.json`:

```json
{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["./my-server/index.js"],
      "env": {
        "MY_CONFIG": "value"
      }
    }
  }
}
```

### MCP Server Development

Create custom MCP servers:
- **Documentation**: https://modelcontextprotocol.io/
- **SDK**: https://github.com/modelcontextprotocol/servers
- **Examples**: https://github.com/modelcontextprotocol/servers/tree/main/src

### Performance Optimization

**Parallel MCP Calls**:
```bash
# Claude can call multiple MCP servers in parallel
# when operations are independent
```

**Token Efficiency**:
- Use Serena symbols instead of full file reads
- Use Memory graph for temporary context
- Leverage Grep/Glob before reading

**Caching**:
- Context7 and Fetch have built-in caching
- Memory graph caches for session duration

### Security Considerations

**Secrets Management**:
- ❌ Never commit API keys to git
- ✅ Use environment variables
- ✅ Use `.claude/settings.local.json` (gitignored)

**Database Access**:
- Use read-only accounts when possible
- Parameterize all queries
- Audit database operations

**Browser Automation**:
- Be cautious with authentication in Playwright
- Don't expose credentials in screenshots
- Review captured network requests

### Integration with CI/CD

**Headless Mode** (optional):
```bash
# Run Claude Code in CI pipeline
claude --headless --session ci-build

# Use MCP servers in automation
# Example: Database migrations, E2E tests
```

### Updating MCP Servers

**Update All Servers**:
```bash
# Re-run setup script (idempotent)
.\.claude\tools\setup-all-mcp-servers.ps1
```

**Update Individual Server**:
```bash
# npm-based servers (auto-update with -y flag)
npx -y @modelcontextprotocol/server-memory

# Python-based servers
uvx --from "git+https://github.com/oraios/serena" serena

# Windows MCP (git-based)
cd .windows-mcp
git pull
uv sync
```

### Monitoring and Logging

**Check Server Status**:
```bash
claude mcp list
claude mcp test <server-name>
```

**View Logs**:
```bash
# All logs
ls .claude/logs/

# MCP-specific logs
cat .claude/logs/mcp-*.log
```

**Debug Mode**:
Add to `.claude/settings.json`:
```json
{
  "debug": true,
  "logLevel": "debug"
}
```

---

## Additional Resources

### Official Documentation

- **Claude Code**: https://docs.claude.com/en/docs/claude-code/
- **MCP Specification**: https://modelcontextprotocol.io/
- **Serena**: https://github.com/oraios/serena
- **Context7**: https://context7.com/
- **Playwright**: https://playwright.dev/

### Project Documentation

- **Quick Start**: [QUICKSTART.md](QUICKSTART.md)
- **Complete Setup**: [CLAUDE_CODE_SETUP_COMPLETE.md](CLAUDE_CODE_SETUP_COMPLETE.md)
- **Usage Templates**: [.claude/agents/MCP_USAGE_TEMPLATES.md](.claude/agents/MCP_USAGE_TEMPLATES.md)

### Setup Scripts

- **Windows Setup**: [.claude/tools/setup-all-mcp-servers.ps1](.claude/tools/setup-all-mcp-servers.ps1)
- **Linux/Mac Setup**: [.claude/tools/setup-all-mcp-servers.sh](.claude/tools/setup-all-mcp-servers.sh)
- **Test Script**: [.claude/tools/test-mcp-servers.ps1](.claude/tools/test-mcp-servers.ps1)

---

## Summary

This guide covers all 8 MCP servers configured in this project:

1. ✅ **Serena** - Code navigation + persistent memory
2. ✅ **Sequential Thinking** - Complex reasoning
3. ✅ **Database Server** - SQL Server integration
4. ✅ **Context7** - Library documentation
5. ✅ **Memory** - Knowledge graph (session)
6. ✅ **Fetch** - Web content retrieval
7. ✅ **Windows MCP** - Desktop automation
8. ✅ **Playwright** - Browser automation

### Quick Commands Reference

```bash
# Setup
.\.claude\tools\setup-all-mcp-servers.ps1

# Test
.\.claude\tools\test-mcp-servers.ps1

# Check status
claude mcp list
claude mcp test <server-name>

# View logs
cat .claude/logs/mcp-*.log
```

### Key Takeaways

- **Serena Memory** = Long-term knowledge (persists)
- **Memory Graph** = Session-only context (temporary)
- **Context7** = Real-time library docs (requires API key)
- **Playwright** = Browser automation (requires browser install)
- **Windows MCP** = Windows-only (safe to ignore on Mac/Linux)

---

**Version**: 1.0.0
**Last Updated**: 2025-10-20
**Maintained by**: Claude Code Setup Project

**For latest information**: See official documentation at https://docs.claude.com/en/docs/claude-code/

---

*This comprehensive guide consolidates all MCP server documentation from multiple sources into a single reference. For setup automation, see the tools in `.claude/tools/`.*