# vardoger MCP server

> Personalize AI coding assistants by analyzing local conversation history to generate tailored system prompt additions.

- Repository: https://github.com/dstrupl/vardoger
- Page: https://hostedmcp.org/servers/dstrupl/vardoger
- Transport: stdio
- Stars: 5
- License: Apache-2.0
- Latest version: 0.4.0

## Install

### Claude Code

```sh
claude mcp add vardoger -- uvx vardoger
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "vardoger": {
      "command": "uvx",
      "args": [
        "vardoger"
      ]
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "vardoger": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "vardoger"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"vardoger","type":"stdio","command":"uvx","args":["vardoger"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "vardoger": {
      "command": "uvx",
      "args": [
        "vardoger"
      ]
    }
  }
}
```

### Codex

```sh
codex mcp add vardoger -- uvx vardoger
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.vardoger]
command = "uvx"
args = ["vardoger"]
```

### Gemini CLI

```sh
gemini mcp add -s user vardoger uvx -- vardoger
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "vardoger": {
      "command": "uvx",
      "args": [
        "vardoger"
      ]
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `VARDOGER_MCP_PLATFORM` | no | no | Override the host platform identifier (cursor, claude-code, codex, copilot, devin, windsurf, cline, openclaw). When unset, vardoger uses the calling host's defaults. |

## Tools (9)

- `vardoger_status`: Check whether the personalization for a platform is up to date. Args: platform: One of cursor, claude-code, codex, openclaw, copilot, windsurf, cline, devin. Empty uses the server default (env var ``VARDOGER_MCP_PLATFORM`` or ``cursor``). Returns: JSON ``StalenessReport`` indicating whether the personalization needs refreshing, how many days since the last update, and how many new or changed conversations exist.
- `vardoger_personalize`: Personalize the AI assistant from its conversation history. Call this tool when the user asks to personalize their assistant, to analyze their conversation history, or mentions "vardoger". Returns step-by-step instructions for the calling model to follow using the other vardoger tools. Args: platform: One of cursor, claude-code, codex, openclaw, copilot, windsurf, cline, devin. Empty uses the server default (env var ``VARDOGER_MCP_PLATFORM`` or ``cursor``). Returns: A markdown walkthrough of the remaining vardoger calls.
- `vardoger_prepare`: Prepare conversation history for analysis. Call without ``batch`` (or with ``batch=0``) to get metadata about how many batches are available. Then call with ``batch=1``, ``batch=2``, etc. to get each batch of conversations along with the summarization prompt. Args: batch: Batch number (1-based). 0 or omitted returns metadata only. platform: One of cursor, claude-code, codex, openclaw, copilot, windsurf, cline, devin. Empty uses the server default. Returns: JSON metadata for ``batch=0``, otherwise the summarize prompt concatenated with the batch's conversation content.
- `vardoger_synthesize_prompt`: Get the synthesis prompt for combining batch summaries. Call this after you have summarized all batches. Use the returned prompt to guide the synthesis of those batch summaries into a final personalization. If the user has previously edited the generated rules, a feedback-context block is prepended so the synthesis respects those edits. Args: platform: One of cursor, claude-code, codex, openclaw, copilot, windsurf, cline, devin. Empty uses the server default. Returns: The synthesis prompt text (optionally prefixed with feedback context).
- `vardoger_write`: Deliver the final personalization — copy-paste by default, file opt-in. Call this after synthesizing all batch summaries. If ``content`` begins with a YAML frontmatter block (as produced by the synthesis prompt), low-confidence rules are annotated with "(tentative)" before delivery. Delivery modes (Cursor): - ``project_path`` empty → default, **no disk write**. Returns a copy-paste block the user pastes into *Cursor Settings → Rules → User Rules*. This is the correct default because vardoger's output is derived from global conversation history, not from any one project. - ``project_path`` set → project-scoped write to ``<project>/.cursor/rules/vardoger.mdc``. The target is validated to actually be a project (``.git``, language manifest, ``AGENTS.md``, or ``.cursor/`` in the directory or an ancestor). Non-project paths are refused rather than written silently. Fixes https://github.com/dstrupl/vardoger/issues/18. For other platforms, ``project_path`` empty still falls back to the platform's usual default (user-global rules directory under ``~``); those platforms don't have Cursor's "$HOME-masquerading-as-workspace" problem. Args: content: The personalization markdown to write (with optional YAML frontmatter). platform: One of cursor, claude-code, codex, openclaw, copilot, windsurf, cline, devin. Empty uses the server default. scope: "global" or "project". Empty selects the platform's default (global for every platform). Ignored for Cursor. project_path: Optional project directory. For Cursor, leaving this empty switches delivery to the User Rules copy-paste block. For other platforms, it's passed through to their writer. Returns: Human-readable confirmation (file written) or a copy-paste block (User Rules delivery).
- `vardoger_preview`: Show a unified diff between a proposed personalization and the current file. Applies the same frontmatter parsing + tentative annotation as ``vardoger_write`` so the preview matches what would be written. Does not modify any files. Args: content: The proposed personalization (with optional YAML frontmatter). platform: One of cursor, claude-code, codex, openclaw, copilot, windsurf, cline, devin. Empty uses the server default. scope: "global" or "project". Empty selects the platform's default. project_path: Optional project directory. Empty uses the current working directory. Returns: A unified diff, or a note if the file is identical / absent.
- `vardoger_feedback`: Record accept/reject feedback for the latest personalization. - ``accept`` simply records that the user confirmed the generation. - ``reject`` also auto-reverts the rules file to the previous generation, or clears it entirely when no prior generation exists. Args: kind: "accept" or "reject". platform: One of cursor, claude-code, codex, openclaw, copilot, windsurf, cline, devin. Empty uses the server default. reason: Optional free-text reason recorded on the feedback event. scope: "global" or "project". Empty selects the platform's default. project_path: Optional project directory. Empty uses the current working directory. Returns: Human-readable confirmation.
- `vardoger_import`: Look for existing Cursor vardoger rule files in given workspaces. vardoger's output is derived from *global* conversation history, so a user with multiple Cursor projects may already have a curated ``vardoger.mdc`` in one of them that's worth reusing (perhaps with edits) instead of regenerating from scratch. The pre-0.4.0 ``vardoger.md`` filename is accepted as a read-only fallback. This tool gives the orchestrating model a way to look one up without blindly scanning the filesystem. The caller (the agent) is expected to supply a short list of candidate workspace roots it already knows about — from the user's open editors, recent-workspaces list, explicit mentions, etc. vardoger deliberately does not walk ``$HOME`` on its own: that would be slow and privacy-sensitive, and the exact same class of blind-filesystem behaviour is what caused https://github.com/dstrupl/vardoger/issues/18. Args: paths: Candidate workspace root paths (strings; tilde expansion applied). Non-strings and empty entries are skipped. Returns: JSON list of ``{"path": "<file>", "content": "<text>"}`` for each workspace where ``<root>/.cursor/rules/vardoger.mdc`` (or the legacy ``vardoger.md`` fallback) exists and was readable. Unreadable or missing entries are omitted silently. Empty list (``"[]"``) if nothing was found.
- `vardoger_compare`: Compare conversation quality before vs. after the latest personalization. Metrics are heuristic signals (correction rate, pushback length, satisfaction tokens, restart rate, emoji rate) bucketed around the most recent generation's timestamp. Args: window_days: Optional symmetric window in days around the cutoff. Use 0 (default) to include all history. platform: One of cursor, claude-code, codex, openclaw, copilot, windsurf, cline, devin. Empty uses the server default. Returns: ``QualityComparison.model_dump_json()`` — a JSON object with ``before``, ``after``, ``delta_notes``, and ``caveats``.

## FAQ

### Does vardoger send my data to a server?

No, vardoger operates no backend, sends no telemetry, and all analysis is performed by the host assistant you invoke.

### Which AI coding assistants are supported?

It supports Cursor, Claude Code, OpenAI Codex, OpenClaw, GitHub Copilot CLI, Devin Local, Windsurf, and Cline.
