Troubleshooting

Quick Diagnostics

Run these commands to quickly diagnose issues:

Check Installation
Check Connectivity
Check Client Logs
Check Configuration

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

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

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”

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:

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

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.

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

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

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

arch-ops doesn't appear

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

Server Won’t Start

uvx not found

Error: command not found: uvx or permission errorsDiagnosis:

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

Solutions:

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

Add to PATH:

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

# Reload shell
source ~/.bashrc  # or ~/.zshrc

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+ requiredCheck current version:

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

Install Python 3.11+:

sudo pacman -S python

sudo apt update
sudo apt install python3.11

brew install python@3.11

# Download from python.org and compile
wget https://www.python.org/ftp/python/3.11.0/Python-3.11.0.tgz
tar -xf Python-3.11.0.tgz
cd Python-3.11.0
./configure && make && sudo make install

Force specific Python version:

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

Missing dependencies

Error: ModuleNotFoundError or package installation failsCommon missing modules:

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

Solutions:

Reinstall completely:
uvx --reinstall arch-ops-server
Upgrade to latest version:
uvx --upgrade arch-ops-server

Clear uv cache:

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

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:

Test server directly:

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

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

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 foundSolution: 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 outSolution:

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

404 from AUR

Error: AUR package not found or HTTP 404Solution:

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

Rate limit errors (429)

Error: Too many requests or HTTP 429Solution:

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:

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

Configuration Issues

Config syntax error

Error: JSON parse error or invalid configurationSolution:

Validate JSON: Use jq or an online JSON validator
Check for trailing commas
Ensure proper JSON formatting
Example valid config:

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

Config not loading

Error: MCP server doesn’t appear in clientSolution:

Restart your MCP client completely
Check config file location:
- Claude: ~/.config/Claude/claude_desktop_config.json
- Cursor: ~/.cursor/mcp_config.json
Verify file has valid JSON
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.

Getting started

Features

Development

Troubleshooting

Quick Diagnostics

Verify Installation

Common Installation Issues

Server Won’t Start

Tools Return Errors

Platform-Specific Issues

On Non-Arch Systems

On Arch Linux

Configuration Issues

Getting Help

Debug Commands

Resources

​Quick Diagnostics

​Verify Installation

​Common Installation Issues

​Server Won’t Start

​Tools Return Errors

​Platform-Specific Issues

​On Non-Arch Systems

​On Arch Linux

​Configuration Issues

​Getting Help

​Debug Commands

​Resources

Quick Diagnostics

Verify Installation

Common Installation Issues

Server Won’t Start

Tools Return Errors

Platform-Specific Issues

On Non-Arch Systems

On Arch Linux

Configuration Issues

Getting Help

Debug Commands

Resources