torbjorn/my-pal-mcp-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c3e63c0c7f1556f4b6686f9c6f30e4bb4a48c7c
my-pal-mcp-server/docs/troubleshooting.md
Beehive Innovations 4151c3c3a5 Migration from Docker to Standalone Python Server (#73) 
* Migration from docker to standalone server
Migration handling
Fixed tests
Use simpler in-memory storage
Support for concurrent logging to disk
Simplified direct connections to localhost

* Migration from docker / redis to standalone script
Updated tests
Updated run script
Fixed requirements
Use dotenv
Ask if user would like to install MCP in Claude Desktop once
Updated docs

* More cleanup and references to docker removed

* Cleanup

* Comments

* Fixed tests

* Fix GitHub Actions workflow for standalone Python architecture

- Install requirements-dev.txt for pytest and testing dependencies
- Remove Docker setup from simulation tests (now standalone)
- Simplify linting job to use requirements-dev.txt
- Update simulation tests to run directly without Docker

Fixes unit test failures in CI due to missing pytest dependency.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Remove simulation tests from GitHub Actions

- Removed simulation-tests job that makes real API calls
- Keep only unit tests (mocked, no API costs) and linting
- Simulation tests should be run manually with real API keys
- Reduces CI costs and complexity

GitHub Actions now only runs:
- Unit tests (569 tests, all mocked)
- Code quality checks (ruff, black)

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Fixed tests

* Fixed tests

---------

Co-authored-by: Claude <noreply@anthropic.com>
2025-06-18 23:41:22 +04:00

2.8 KiB
Raw Blame History

Troubleshooting Guide

Quick Debugging Steps

If you're experiencing issues with the Zen MCP Server, follow these steps:

1. Check MCP Connection

Open Claude Desktop and type /mcp to see if zen is connected:

  • ✅ If zen appears in the list, the connection is working
  • ❌ If not listed or shows an error, continue to step 2

2. Launch Claude with Debug Mode

Close Claude Desktop and restart with debug logging:

# macOS/Linux
claude --debug

# Windows (in WSL2)
claude.exe --debug

Look for error messages in the console output, especially:

  • API key errors
  • Python/environment issues
  • File permission errors

3. Verify API Keys

Check that your API keys are properly set:

# Check your .env file
cat .env

# Ensure at least one key is set:
# GEMINI_API_KEY=your-key-here
# OPENAI_API_KEY=your-key-here

If you need to update your API keys, edit the .env file and then restart Claude for changes to take effect.

4. Check Server Logs

View the server logs for detailed error information:

# View recent logs
tail -n 100 logs/mcp_server.log

# Follow logs in real-time
tail -f logs/mcp_server.log

# Or use the -f flag when starting to automatically follow logs
./run-server.sh -f

# Search for errors
grep "ERROR" logs/mcp_server.log

See Logging Documentation for more details on accessing logs.

5. Common Issues

"Connection failed" in Claude Desktop

  • Ensure the server path is correct in your Claude config
  • Run ./run-server.sh to verify setup and see configuration
  • Check that Python is installed: python3 --version

"API key environment variable is required"

  • Add your API key to the .env file
  • Restart Claude Desktop after updating .env

File path errors

  • Always use absolute paths: /Users/you/project/file.py
  • Never use relative paths: ./file.py

Python module not found

  • Run ./run-server.sh to reinstall dependencies
  • Check virtual environment is activated: should see .zen_venv in the Python path

6. Environment Issues

Virtual Environment Problems

# Reset environment completely
rm -rf .zen_venv
./run-server.sh

Permission Issues

# Ensure script is executable
chmod +x run-server.sh

7. Still Having Issues?

If the problem persists after trying these steps:

  1. Reproduce the issue - Note the exact steps that cause the problem
  2. Collect logs - Save relevant error messages from Claude debug mode and server logs
  3. Open a GitHub issue with:
    • Your operating system
    • Python version: python3 --version
    • Error messages from logs
    • Steps to reproduce
    • What you've already tried

Windows Users

Important: Windows users must use WSL2. Install it with:

wsl --install -d Ubuntu

Then follow the standard setup inside WSL2.