quality-mcp/troubleshooting.md

An MCP server that analyzes to your codebase, with plugin support for DCD and Simian. 🏍️ "The only Zen you find on the tops of mountains is the Zen you bring up there."

# Troubleshooting

## Common Issues

### "0 tools enabled" or Red Dot in MCP Client

**Most likely cause**: Path issues in your MCP configuration.

**Fix**: Use absolute paths:

```json
{
  "mcpServers": {
    "quality-mcp": {
      "command": "/home/username/.nvm/versions/node/v22.x.x/bin/node",
      "args": ["/full/path/to/quality-mcp/src/index.js"],
      "env": {
        "DCD_EXECUTABLE": "dcd"
      }
    }
  }
}
```

**Find your Node.js path**:

```bash
which node
```

### "DCD not found"

**Fix**: Install DCD and add to PATH:

```bash
go install github.com/boyter/dcd@latest
export PATH=$PATH:$(go env GOPATH)/bin
```

### "Simian failed"

**Fix**: Check Simian installation and license:

1. Verify JAR file exists at the path in `SIMIAN_EXECUTABLE`
2. Ensure you have a valid Simian license
3. Consider using DCD instead (free and open source)

### No Duplicates Found

**Try these**:

- Lower the `matchLength` parameter (e.g., 3-6 lines)
- Check that you're analyzing the right file types
- Make sure the directory contains code files

### Server Won't Start

**Check**:

- Node.js is installed and in PATH
- All dependencies are installed (`npm install`)
- Port isn't already in use
- File permissions are correct

## Getting Help

1. **Check logs**: Look for error messages in your MCP client logs
2. **Test manually**: Run `npm run test:dcd` to verify DCD works
3. **Verify paths**: Make sure all paths in your config are absolute and correct
4. **Restart client**: Restart your MCP client after configuration changes

## Still Stuck?

- Check the [development guide](development.md) for advanced debugging
- Open an issue on GitHub with your error messages and configuration