fix: resolve MCP server availability discrepancy issue

bin/claude-mcp-diagnostic

@@ -0,0 +1,120 @@
+#!/bin/bash
+# Claude MCP Diagnostic Tool
+# Diagnoses MCP server availability issues
+
+set -euo pipefail
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+RED='\033[0;31m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+DIVIDER="========================================"
+
+echo -e "${BLUE}${DIVIDER}${NC}"
+echo -e "${BLUE}Claude Code MCP Server Diagnostic${NC}"
+echo -e "${BLUE}${DIVIDER}${NC}\n"
+
+# 1. Check Claude Code installation
+echo -e "${YELLOW}1. Claude Code Installation:${NC}"
+if command -v claude &>/dev/null; then
+    CLAUDE_VERSION=$(claude --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' || echo "unknown")
+    echo -e "${GREEN}✓ Claude Code installed (version: $CLAUDE_VERSION)${NC}"
+else
+    echo -e "${RED}✗ Claude Code not installed${NC}"
+    exit 1
+fi
+echo ""
+
+# 2. Check MCP configuration file
+echo -e "${YELLOW}2. MCP Configuration File:${NC}"
+DOT_DEN="${DOT_DEN:-$HOME/ppv/pillars/dotfiles}"
+GLOBAL_MCP_CONFIG="$DOT_DEN/mcp/mcp.json"
+
+if [[ -f "$GLOBAL_MCP_CONFIG" ]]; then
+    echo -e "${GREEN}✓ MCP config found: $GLOBAL_MCP_CONFIG${NC}"
+
+    # Show configured servers
+    if command -v jq &>/dev/null; then
+        echo -e "\n  Configured servers in mcp.json:"
+        jq -r '.mcpServers | keys[]' "$GLOBAL_MCP_CONFIG" 2>/dev/null | sed 's/^/    - /'
+    else
+        echo -e "${YELLOW}  (Install jq to see server list)${NC}"
+    fi
+else
+    echo -e "${RED}✗ MCP config not found at: $GLOBAL_MCP_CONFIG${NC}"
+fi
+echo ""
+
+# 3. Check Claude alias
+echo -e "${YELLOW}3. Claude Alias Configuration:${NC}"
+ALIAS_DEF=$(alias claude 2>/dev/null || echo "none")
+if [[ "$ALIAS_DEF" != "none" ]]; then
+    echo -e "${GREEN}✓ Claude alias configured:${NC}"
+    echo "  $ALIAS_DEF"
+else
+    echo -e "${RED}✗ Claude alias not configured${NC}"
+fi
+echo ""
+
+# 4. Test MCP server listing
+echo -e "${YELLOW}4. Claude MCP Server List:${NC}"
+echo "Running: claude mcp list"
+if claude mcp list 2>/dev/null; then
+    echo -e "${GREEN}✓ MCP servers listed successfully${NC}"
+else
+    echo -e "${RED}✗ Failed to list MCP servers${NC}"
+fi
+echo ""
+
+# 5. Check for stale cache
+echo -e "${YELLOW}5. Checking for Stale Cache:${NC}"
+CACHE_DIRS=(
+    "$HOME/.claude/statsig"
+    "$HOME/.cache/claude"
+    "$HOME/.local/share/claude"
+)
+
+CACHE_FOUND=false
+for dir in "${CACHE_DIRS[@]}"; do
+    if [[ -d "$dir" ]]; then
+        echo -e "  Found cache directory: $dir"
+        CACHE_FOUND=true
+    fi
+done
+
+if ! $CACHE_FOUND; then
+    echo -e "  No cache directories found"
+fi
+echo ""
+
+# 6. Check for environment variables
+echo -e "${YELLOW}6. MCP-related Environment Variables:${NC}"
+env | grep -i mcp || echo "  None found"
+echo ""
+
+# 7. Recommendations
+echo -e "${BLUE}${DIVIDER}${NC}"
+echo -e "${BLUE}Recommendations:${NC}"
+echo -e "${BLUE}${DIVIDER}${NC}"
+
+echo -e "\n1. To clear potential cache issues:"
+echo -e "   ${GREEN}rm -rf ~/.claude/statsig/*${NC}"
+echo -e "   ${GREEN}pkill -f claude || true${NC}"
+echo -e "   ${GREEN}source ~/.bashrc${NC}"
+
+echo -e "\n2. To verify MCP server availability:"
+echo -e "   ${GREEN}claude mcp list${NC}"
+echo -e "   ${GREEN}claude mcp info <server-name>${NC}"
+
+echo -e "\n3. To add/remove MCP servers:"
+echo -e "   ${GREEN}Edit: $GLOBAL_MCP_CONFIG${NC}"
+echo -e "   ${GREEN}Then: source setup.sh${NC}"
+
+echo -e "\n4. If servers still appear after removal:"
+echo -e "   - Claude Code may have cached the server list"
+echo -e "   - Try restarting your terminal session"
+echo -e "   - Run: ${GREEN}claude logout && claude login${NC}"
+
+echo -e "\n${BLUE}${DIVIDER}${NC}"

docs/mcp-client-integration.md

@@ -2,6 +2,8 @@
 
 This guide documents how to integrate new MCP (Model Context Protocol) clients with the dotfiles repository infrastructure.
 
+> **Important**: Before integrating MCP servers, review the [MCP Server Availability Guide](mcp-server-availability.md) to understand which servers are actually available vs. which only appear in tool approval lists.
+
 ## Overview
 
 The dotfiles repository provides an AI provider-agnostic system for managing MCP servers and global context. This allows multiple AI coding assistants (Amazon Q, Claude Code, etc.) to share the same configuration and knowledge base.

docs/mcp-environment.md

@@ -2,6 +2,8 @@
 
 This document describes the environment-specific MCP server configuration system implemented in the dotfiles repository.
 
+> **Note**: For information about which MCP servers are actually available vs. which appear in Claude Code's approval list, see [MCP Server Availability Guide](mcp-server-availability.md).
+
 ## Overview
 
 The system allows you to automatically enable or disable certain MCP servers based on your environment (work, personal, development, production). This is particularly useful for:

docs/mcp-server-availability.md

@@ -0,0 +1,108 @@
+# MCP Server Availability Guide
+
+## Currently Connected MCP Servers
+
+As of the latest configuration, the following MCP servers are **actually connected and available**:
+
+### ✅ Available
+- **playwright** - Browser automation server
+  - Functions: `mcp__playwright__*`
+  - Capabilities: Browser navigation, clicking, form filling, screenshots, etc.
+  - Configuration: See `mcp/mcp.json`
+
+### ❌ NOT Available (Despite Appearing in Tool Approval List)
+
+The following MCP servers appear in Claude Code's internal tool approval list but are **NOT actually connected**:
+
+#### GitHub Write Server
+- `mcp__github-write__get_issue`
+- `mcp__github-write__get_issue_comments`
+- `mcp__github-write__list_pull_requests`
+- `mcp__github-write__search_issues`
+- `mcp__github-write__search_pull_requests`
+
+**Alternative**: Use `gh` CLI commands via Bash tool instead.
+
+#### Git Server
+- `mcp__git__git_worktree_add`
+- `mcp__git__git_add`
+- `mcp__git__git_commit`
+- `mcp__git__git_batch`
+- `mcp__git__git_status`
+- `mcp__git__git_log`
+- `mcp__git__git_create_branch`
+- `mcp__git__git_diff_unstaged`
+- `mcp__git__git_checkout`
+- `mcp__git__git_rm`
+- `mcp__git__git_show`
+
+**Alternative**: Use `git` commands via Bash tool instead.
+
+## Why This Discrepancy Exists
+
+Claude Code's internal tool approval list includes these MCP server functions as "approved" for future use, but they require the actual MCP servers to be:
+1. Installed on the system
+2. Configured in `mcp/mcp.json`
+3. Running and accessible
+
+Currently, only the Playwright MCP server meets all these requirements.
+
+### Known Issue: Stale Cache
+
+Claude Code may cache MCP server information, causing it to report servers as available even after they've been removed from `mcp/mcp.json`. This is automatically handled by `setup.sh` which clears the cache when updating MCP configuration.
+
+If you manually edit `mcp/mcp.json`, you should:
+1. Clear the cache: `rm -rf ~/.claude/statsig/*`
+2. Restart your terminal session
+3. Verify with: `claude mcp list`
+
+## How to Add MCP Servers
+
+To add additional MCP servers:
+
+1. Install the server package:
+   ```bash
+   npm install -g @modelcontextprotocol/server-github
+   # or
+   npm install -g @modelcontextprotocol/server-git
+   ```
+
+2. Add configuration to `mcp/mcp.json`:
+   ```json
+   {
+     "mcpServers": {
+       "playwright": { /* existing config */ },
+       "github": {
+         "command": "mcp-server-github",
+         "args": [],
+         "env": {
+           "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+         }
+       }
+     }
+   }
+   ```
+
+3. Restart Claude Code to pick up the new configuration
+
+## Checking Available MCP Servers
+
+To verify which MCP servers are actually available:
+
+1. Check the configuration:
+   ```bash
+   cat mcp/mcp.json
+   ```
+
+2. Ask Claude directly:
+   ```
+   What MCP servers do you have access to?
+   ```
+
+   **Note**: Claude should only report servers that are actually configured and running, not those merely in the approval list.
+
+## Related Documentation
+
+- [MCP Environment Setup](mcp-environment.md)
+- [MCP Client Integration](mcp-client-integration.md)
+- [Setting up all MCP servers](../mcp/setup-all-mcp-servers.sh)

setup.sh

@@ -359,6 +359,14 @@ if [[ -f "$DOT_DEN/mcp/mcp.json" ]]; then
   # Create symlink to unified MCP config
   ln -sf "$DOT_DEN/mcp/mcp.json" "$HOME/.config/claude/claude_desktop_config.json"
   echo -e "${GREEN}✓ Claude Desktop MCP config symlinked to mcp/mcp.json${NC}"
+
+  # Clear Claude Code's stale MCP cache to ensure it picks up config changes
+  # This prevents Claude from reporting removed servers as still available
+  if [[ -d "$HOME/.claude/statsig" ]]; then
+    echo "Clearing Claude Code cache to sync MCP server availability..."
+    rm -rf "$HOME/.claude/statsig"/* 2>/dev/null || true
+    echo -e "${GREEN}✓ Claude Code cache cleared${NC}"
+  fi
 fi
 
 # OpenAI Codex Configuration (includes trivial npm install)