quality-mcp/readme.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."

# Quality MCP Server 🏍️

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."

> **📚 Recommended Reading**: _Zen and the Art of Motorcycle Maintenance_ by Robert M. Pirsig - This project embodies the philosophy of quality as a way of being, not just a technical achievement. The book's exploration of "Quality" as an undefinable but recognizable concept aligns perfectly with our approach to code analysis and improvement.

**🐛 [Report Issues](https://bitbucket.org/grahampheath/quality-mcp/issues?status=new&status=open)**

## Documentation

- **[Setup Guide](setup.md)**
- **[Troubleshooting](troubleshooting.md)**
- **[Development Guide](development.md)**
- **[Contributing](contributing.md)**

## Quick Start

```bash
# Install globally
npm install -g quality-mcp

# Or install locally
npm install quality-mcp

# Setup DCD (recommended - open source)
# Global install:
quality-mcp setup-dcd
# Local install:
npm exec quality-mcp setup-dcd

# Test it works (from source checkout)
cd quality-mcp
npm test
```

## Installation

### From npm (Recommended)

```bash
npm install -g quality-mcp
```

### From source

```bash
git clone https://bitbucket.org/grahampheath/quality-mcp.git
cd quality-mcp
npm install
#
# Run setup scripts from the repo root:
#   npm run setup-dcd
#   npm run setup
```

## Usage

Add to your MCP client (like Cursor):

```json
{
  "mcpServers": {
    "quality-mcp": {
      "command": "/path/to/node",
      "args": ["/path/to/quality-mcp/src/index.js"],
      "env": {
        "DCD_EXECUTABLE": "dcd"
      }
    }
  }
}
```

### ChatGPT Codex MCP config (TOML)

Add to your Codex config (e.g., `~/.codex/config.toml`):

```toml
[mcp_servers.quality-mcp]
command = "/path/to/node"
args = ["/path/to/quality-mcp/src/index.js"]
env = { DCD_EXECUTABLE = "dcd" }
```

Then use in your AI assistant:

> "Find duplicate code in my src/ directory"

## Tools Available

- **`analyze_duplicates_dcd`** - Find duplicates in files/directories
- **`scan_repository_dcd`** - Scan entire repository
- **`get_plugin_status`** - Check what's available

## Setup Options

### DCD (Recommended - Open Source)

```bash
go install github.com/boyter/dcd@latest
```

### Simian (Commercial License Required)

Download from [Simian website](https://www.harukizaemon.com/simian/) and set `SIMIAN_EXECUTABLE` env var.

## Documentation

- **[Setup Guide](setup.md)** - Detailed installation instructions
- **[Troubleshooting](troubleshooting.md)** - Common issues and fixes

## Development

```bash
npm test          # Run tests
npm run lint      # Check code style
npm run test:dcd  # Test DCD integration
```

## Release

```bash
# Quick release
npm run release:patch  # Bug fixes
npm run release:minor  # New features
npm run release:major  # Breaking changes

# Commit messages
npm run commit         # Interactive
git commit -m "feat: add feature"  # Manual
```

## License

MIT License - see [LICENSE](LICENSE) file.