Troubleshooting

Common issues, diagnostic commands, and solutions for Arch MCP Server.

Quick Diagnostics

Run these commands to quickly diagnose issues:

Check Installation

Verify all components are installed correctly:

# Check uv/uvx installation
uv --version
uvx --version

# Check Python version (need 3.11+)
python --version
python3 --version

# Test arch-ops-server directly
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx arch-ops-server

# Check if server can be found
which arch-ops-server
uvx --help arch-ops-server

Expected: All version commands return valid versions, server responds with tools list

Check Connectivity

Test network access to Arch services:

# Test Arch Wiki access
curl -I https://wiki.archlinux.org

# Test AUR access
curl -I https://aur.archlinux.org

# Test AUR RPC API
curl "https://aur.archlinux.org/rpc?v=5&type=info&arg=yay"

# Check general connectivity
ping -c 3 archlinux.org

# Test DNS resolution
nslookup wiki.archlinux.org

Expected: All services return 200 OK or 301/302 redirects

Check Client Logs

View MCP client logs for errors:

# Claude Desktop (macOS)
tail -f ~/Library/Logs/Claude/mcp*.log

# Claude Desktop (Linux)
tail -f ~/.config/Claude/logs/mcp*.log

# Cursor (macOS/Linux)
tail -f ~/.cursor/logs/mcp*.log

# VS Code - Check Output panel (View → Output → MCP)

# Filter for errors only
grep -i error ~/.config/Claude/logs/mcp*.log

Look for error messages containing “arch-ops”, “spawn”, or “ENOENT”

Check Configuration

Verify MCP client configuration:

# Claude Desktop (macOS)
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Claude Desktop (Linux)
cat ~/.config/Claude/claude_desktop_config.json

# Cursor
cat ~/.cursor/mcp.json

# Validate JSON syntax
python -m json.tool < claude_desktop_config.json

# Check file permissions
ls -la ~/.config/Claude/claude_desktop_config.json

Common issues: trailing commas in JSON, wrong quotes, missing braces

---

Verify Installation

After installing and configuring the Arch MCP Server:

1. Check client settings

   Go to settings tab and look for MCP tools icon in your client.

   Location varies by client:

   • Claude Desktop: Settings → Features → Model Context Protocol
   • Cursor: Settings → MCP Servers
   • VS Code: MCP extension sidebar
2. Find arch-ops server

   You should see “arch-ops” listed as a connected MCP server.

   Status should be: Connected (green indicator)

   If status shows “Disconnected” (red), see troubleshooting below.

3. Test a simple query

   Try a basic query to verify the server responds:

   Search the Arch Wiki for 'installation guide'
   

   Expected: Results from Arch Wiki with titles and links

4. Test a tool

   Try a specific tool to verify functionality:

   Use search_aur to find packages matching "neofetch"
   

   Expected: List of AUR packages with vote counts

Common Installation Issues

Server shows as disconnected

1. Verify uvx is installed: uvx --version
2. Check Python version: python --version (need 3.11+)
3. Reinstall: uvx --reinstall arch-ops-server
4. Restart your MCP client

arch-ops doesn't appear

1. Check config file has valid JSON (no trailing commas)
2. Verify file location is correct for your client
3. Completely quit and restart the client (not just reload)

Server Won’t Start

uvx not found

Error: command not found: uvx or permission errors

Diagnosis:

which uvx
which uv
echo $PATH | grep -o "[^:]*bin"

Solutions:

1. Install uv/uvx:

   # Arch Linux
   sudo pacman -S uv
   
   # Homebrew
   brew install uv
   
   # pip
   pip install uv
   
   # Direct install
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. Add to PATH:

   # Add to ~/.bashrc or ~/.zshrc
   export PATH="$HOME/.local/bin:$PATH"
   
   # Reload shell
   source ~/.bashrc  # or ~/.zshrc
   

3. Verify installation:

   uvx --version
   which uvx
   

The uv installer automatically adds to PATH, but you may need to restart your terminal.

Python version error

Error: Python 3.11+ required

Check current version:

python --version
python3 --version
python3.11 --version

Install Python 3.11+:

Arch Linux

sudo pacman -S python

Force specific Python version:

uvx --python python3.11 arch-ops-server

Missing dependencies

Error: ModuleNotFoundError or package installation fails

Common missing modules:

• httpx - HTTP client library
• beautifulsoup4 - HTML parsing
• markdownify - HTML to Markdown conversion
• mcp - MCP SDK

Solutions:

1. Reinstall completely:

   uvx --reinstall arch-ops-server
   

2. Upgrade to latest version:

   uvx --upgrade arch-ops-server
   

3. Clear uv cache:

   uv cache clean
   uvx --reinstall arch-ops-server
   

4. Manual installation:

   uv pip install arch-ops-server
   arch-ops-server
   

If issues persist, check if you have conflicting Python package managers (pip, conda, pipx).

MCP server doesn't connect

Error: Server shows in tools but says “disconnected”

Diagnosis steps:

1. Test server directly:

   # Should output JSON-RPC response
   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | uvx arch-ops-server
   

2. Check client logs:

   # macOS
   tail -n 50 ~/Library/Logs/Claude/mcp*.log | grep arch-ops
   
   # Linux
   tail -n 50 ~/.config/Claude/logs/mcp*.log | grep arch-ops
   

3. Verify configuration:

   # Check JSON syntax
   python -m json.tool < ~/.config/Claude/claude_desktop_config.json
   

Common causes:

• Syntax error in config file
• Wrong command path in config
• Server crashes on startup
• Permission issues

Solutions:

• Fix JSON syntax errors (trailing commas, quotes)
• Use full path: "/usr/local/bin/uvx" instead of "uvx"
• Restart client completely (quit and relaunch)
• Check client logs for specific error messages

Expected log output: "arch-ops server connected successfully"

Tools Return Errors

checkupdates not found

Error: command 'checkupdates' not found

Solution: This is Arch-only and requires pacman-contrib:

sudo pacman -S pacman-contrib

On non-Arch systems, this tool is not available.

Timeout errors

Error: TimeoutError or request timed out

Solution:

1. Check internet connection: ping google.com
2. Try a simpler query first
3. Verify Arch Wiki and AUR are accessible:
   • Wiki: xh https://wiki.archlinux.org/api.php
   • AUR: xh https://aur.archlinux.org/rpc
4. Increase timeout if needed (requires code change)

404 from AUR

Error: AUR package not found or HTTP 404

Solution:

1. Double-check package name spelling
2. Try searching instead: Search AUR for 'package-name'
3. The AUR might be temporarily down (rare)
4. Try again in a few minutes

Rate limit errors (429)

Error: Too many requests or HTTP 429

Solution:

• AUR has rate limiting
• Wait a few minutes before retrying
• Don’t spam requests
• Share your use case (it’s reasonable)

Platform-Specific Issues

On Non-Arch Systems

Feature	Status	Workaround
Wiki search & reading	✅ Full	Works perfectly
AUR search & PKGBUILD	✅ Full	Works perfectly
Official package info	⚠️ Remote API	Uses online API instead of local pacman
Update checking	❌ Not available	Requires Arch Linux

On Arch Linux

All features available. If something isn’t working:

1. Check system is updated: sudo pacman -Syu
2. Verify dependencies: which pacman checkupdates yay paru
3. Test locally: pacman -Si python (should work)

Configuration Issues

Config syntax error

Error: JSON parse error or invalid configuration

Solution:

1. Validate JSON: Use jq or an online JSON validator
2. Check for trailing commas
3. Ensure proper JSON formatting
4. Example valid config:

{
  "mcpServers": {
    "arch-ops": {
      "command": "uvx",
      "args": ["arch-ops-server"]
    }
  }
}

Config not loading

Error: MCP server doesn’t appear in client

Solution:

1. Restart your MCP client completely
2. Check config file location:
   • Claude: ~/.config/Claude/claude_desktop_config.json
   • Cursor: ~/.cursor/mcp_config.json
3. Verify file has valid JSON
4. Clear client cache if available

Getting Help

Debug Commands

# Test server directly (for debugging)
uvx arch-ops-server

# Check uvx installation
uvx --version

# Reinstall if needed
uvx --reinstall arch-ops-server

# View recent logs
journalctl -xe  # system logs
tail -f ~/.config/Claude/logs  # Claude logs (if available)

Resources

• Arch Wiki Issues: Check Arch Wiki
• AUR Issues: Check AUR
• MCP Protocol: Review MCP Docs
• Bug Reports: Open an issue on GitHub
• Feature Requests: GitHub discussions

---

Still stuck? Check the server logs, verify your config is correct, and ensure all prerequisites are installed.