# zoxide-doctor MCP server

`@agoes/zoxide-doctor-mcp` gives MCP clients one local, read-only tool for diagnosing zoxide installation and shell setup. It wraps the published [`zoxide-doctor`](https://zoxide.org/tools/zoxide-doctor/) diagnostic core; it does not install zoxide or modify shell configuration files.

This is an independent community integration. It is not affiliated with or endorsed by the official zoxide project.

## What it does

- Checks whether `zoxide` and optional `fzf` are on `PATH`.
- Checks that `zoxide init` produces shell initialization code.
- Returns a machine-readable JSON report, including the matching zoxide.org setup and troubleshooting guides.
- Reads conventional shell profile paths only when the MCP caller sets `scan_config: true`.

## Install for an MCP client

Use an MCP client configuration that starts the local stdio server with `npx`:

```json
{
  "mcpServers": {
    "zoxide-doctor": {
      "command": "npx",
      "args": ["-y", "@agoes/zoxide-doctor-mcp"]
    }
  }
}
```

The server exposes one tool:

```text
diagnose_zoxide({ shell?: "bash" | "zsh" | "fish" | "powershell" | "nushell" | "elvish" | "tcsh" | "xonsh" | "posix", scan_config?: boolean })
```

`scan_config` is opt-in because it reads conventional shell-profile files. The tool never writes files or changes shell state.

## Development

```bash
npm install
npm run lint
npm test
npm run validate:metadata
npm run pack:check
npm run smoke
```

`server.json` is kept version-locked to `package.json` and sets the MCP Registry `websiteUrl` to the [zoxide-doctor guide](https://zoxide.org/tools/zoxide-doctor/).

## License

MIT