# Reported issues for docvet

Pod holds 16 of 16 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [docvet](/mcp/docvet).

## Most discussed

### feat: MCP server for agentic AI integration

## Summary

Create a standalone **MCP (Model Context Protocol) server** for docvet, enabling any MCP-compatible AI agent (Claude Code, Cline, Cursor, etc.) to invoke docvet checks as structured tools.

## Background

Split from #63 (Claude Code plugin). The MCP server is a broader integration — it works with any MCP client, not just Claude Code. This is the **direct integration** path for agentic AI adoption.

## Proposed tools

| Tool | Description |
|------|-------------|
| `docvet_check` | Ru

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/149) · 2026-02-26 · closed · 2 comments

### Refactor: move rule catalog out of docvet.mcp so the CLI stops importing the MCP SDK

## Current Structure

- **File(s):** `src/docvet/mcp/_catalog.py`, `src/docvet/mcp/__init__.py`, `src/docvet/cli/_suppression.py`
- **Module/Package:** `docvet.mcp`

`_suppression.py` needs the rule-ID set to validate suppression comments, and gets it via:

```python
try:
    from docvet.mcp._catalog import _RULE_TO_CHECK
except ImportError:
    # MCP extra not installed — rule validation unavailable.
    _RULE_TO_CHECK: dict[str, str] = {}
```

`_catalog.py` is pure data — its only import is `t

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/428) · 2026-08-14 · open · 1 comment

### refactor(mcp): replace _RULE_CATALOG dict with TypedDict

## Problem

`_RULE_CATALOG` is typed as `list[dict[str, str | None]]`, which is too loose. The `guidance` field is always `str` (never `None`), and only `fix_example` is nullable. The union type applies to all values, so the type checker cannot distinguish between always-string fields and the nullable one. This forces `str()` wrappers in `_RULE_TO_CHECK` to narrow the type.

## Proposal

Define a `TypedDict` (e.g., `RuleCatalogEntry`) with field-level types:

```python
class RuleCatalogEntry(Typ

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/278) · 2026-03-05 · closed · 1 comment

### feat: Anthropic marketplace publishing for LSP and MCP integrations

## Summary

Publish docvet's LSP server and MCP server integrations to Anthropic's marketplace/registry to reach Claude users directly.

## Prerequisites

- [x] LSP server implemented (`docvet lsp` — `src/docvet/lsp.py`)
- [ ] MCP server implemented (#149)

## Scope

1. **LSP integration listing** — Package existing `docvet lsp` for Anthropic marketplace with proper metadata, README, and configuration examples
2. **MCP server listing** — Package MCP server (once #149 is complete) for Anthropic m

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/236) · 2026-03-02 · closed · 1 comment

### docs: add Editor Integration page for LSP server and Claude Code plugin

## Context

Epic 24 shipped the LSP server (24.1) and Claude Code plugin (24.2), but the docs site has no page documenting either. The AI Integration page only covers `AGENTS.md`/`CLAUDE.md` discovery files.

## What's needed

Add an "Editor Integration" page (or section) to the docs site covering:

- **LSP server**: `docvet lsp` command, what checks run (enrichment, coverage, griffe — not freshness), how to configure in any LSP-capable editor
- **Claude Code plugin**: `claude plugin install git

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/186) · 2026-02-28 · closed · 1 comment

### docs: add editor integration guide for LSP server

## Context

Story 24.1 shipped the `docvet lsp` command (pygls-based LSP server on STDIO), but no documentation exists for how to configure editors to use it. The story's Dev Notes flagged this as a documentation impact, but no epic story covers it — the docs fell through the cracks in epic planning.

## What's needed

A new docs page (e.g., `docs/site/editor-integration.md` or a section in `ci-integration.md`) covering:

- **Installation**: `pip install docvet[lsp]`
- **VS Code**: `settings.jso

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/183) · 2026-02-28 · closed · 1 comment

### chore: integrate SonarQube analyze_code_snippet into BMAD code review workflow

## Summary

Add a SonarQube automated analysis step to the BMAD code review workflow (`_bmad/bmm/workflows/4-implementation/code-review/instructions.xml`). This uses the `analyze_code_snippet` MCP tool to scan changed `src/**/*.py` files during adversarial code review.

## Motivation

SonarQube scans are currently manual and post-merge only (Community Edition limitation). By integrating `analyze_code_snippet` into the code review workflow, we get automated code quality feedback _before_ merge — 

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/97) · 2026-02-24 · closed · 1 comment

### docs: add breadcrumb back-link from rule pages to parent check page

## Context

Rule reference pages (e.g., `/rules/missing-raises/`) currently have no in-page link back to their parent check page (e.g., `/checks/enrichment/`). The only way back is the nav sidebar.

## Suggestion

Add a breadcrumb or "Part of: [Enrichment Check](../checks/enrichment.md)" link near the metadata table on each rule page. This improves wayfinding, especially for users who land on a rule page from search.

## Origin

Identified during Story 11.3 UX review (party mode).

## Scope

- 1

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/69) · 2026-02-22 · closed · 1 comment

## Most recent

### refactor(mcp): extract rule catalog to _catalog.py

## Problem

`src/docvet/mcp.py` is 938 lines — 1.9x the 500-line module size gate. The `_RULE_CATALOG` list alone is 405 lines (43% of the file) and is a distinct concern from the MCP server logic.

## Analysis

| Concern | Lines | % |
|---------|-------|---|
| Imports + rule catalog | 522 | 56% |
| Check runners + helpers | 294 | 31% |
| MCP tools + server | 122 | 13% |

## Proposed Change

Extract `_RULE_CATALOG`, `RuleCatalogEntry`, and `_RULE_TO_CHECK` into `mcp/_catalog.py` (~410 lines). Co

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/375) · 2026-03-23 · closed · 0 comments

### Story 30.2: TypedDict for _RULE_CATALOG

## Story

As a **developer working on the MCP module**,
I want `_RULE_CATALOG` to use a TypedDict with per-field types,
so that the type checker correctly narrows field types and `str()` wrappers in `_RULE_TO_CHECK` become unnecessary.

## Acceptance Criteria

1. `_RULE_CATALOG` uses a `RuleCatalogEntry` TypedDict with fields: `name: str`, `check: str`, `description: str`, `category: str`, `guidance: str`, `fix_example: str | None`
2. `str()` wrappers removed from `_RULE_TO_CHECK` derivation
3. 

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/290) · 2026-03-05 · closed · 0 comments

### Story 29.3: Documentation and Marketplace Publishing

## Story

As a **Claude user or AI tool developer**,
I want to find docvet's MCP server on the official MCP registry and in the docs,
so that I can discover and set up docvet integration with minimal friction.

## Acceptance Criteria

1. **Given** a user visits the docs site, **When** they navigate to Editor Integration, **Then** an "MCP Server" section documents: installation, starting the server, available tools and parameters, example response schema, and MCP vs LSP comparison.

2. **Given** 

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/268) · 2026-03-04 · closed · 0 comments

### Story 29.2: CLI Wiring and Tests

## Story

As a **developer setting up docvet's MCP server**,
I want a `docvet mcp` subcommand that starts the MCP server,
so that I can configure MCP clients to connect to docvet easily.

## Acceptance Criteria

1. `docvet mcp` starts MCP server on stdio when `mcp` dependency installed
2. `docvet mcp` without `mcp` package shows clear error message and exits with code 1
3. MCP `docvet_check` response matches `docvet check --format json` structure
4. MCP `docvet_rules` lists all 20 rules with nam

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/266) · 2026-03-04 · closed · 0 comments

### Story 29.1: Core MCP Server Implementation

## Story

As an **AI agent (Claude Code, Cursor, etc.)**,
I want to invoke docvet checks via MCP protocol and receive structured findings,
so that I can analyze docstring quality programmatically without parsing CLI output.

## Acceptance Criteria

1. MCP client connects via stdio, calls `docvet_check` with path → runs all enabled checks, returns structured findings + summary
2. `docvet_check` with `checks` filter → only specified checks run
3. `docvet_check` with presence → includes `presence_c

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/260) · 2026-03-03 · closed · 0 comments

### Story 26.2: Add Editor Integration Page

## Story

As a **developer setting up docvet in their editor**,
I want a docs page explaining LSP server configuration and Claude Code plugin installation,
so that I can get real-time docstring diagnostics without reading source code.

## Acceptance Criteria

1. **Given** the docs site **When** a user navigates to the Editor Integration page **Then** the page documents the `docvet lsp` command, which checks run (enrichment, coverage, griffe — not freshness), and how to configure in any LSP-capab

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/212) · 2026-02-28 · closed · 0 comments

### feat: VS Code extension for docstring diagnostics

## Summary

Create a **VS Code extension** for docvet that publishes docstring quality findings to the Problems panel and exposes tools to Copilot agent mode via the Language Model Tools API.

## Motivation

VS Code is the dominant Python editor. Two integration surfaces matter:

1. **Diagnostics in Problems panel** — human developers see docstring issues inline. Copilot agent mode reads VS Code diagnostics and self-corrects automatically.
2. **Language Model Tools API** — the extension can cont

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/160) · 2026-02-27 · open · 0 comments

### feat: add --format json structured output for agent consumption

## Summary

Add a `--format json` flag to `docvet check` and all subcommands, producing structured JSON output that AI agents can parse programmatically.

## Motivation

Agents parse JSON natively. Terminal-formatted output requires pattern matching and is fragile. Structured output enables agents to:
- Programmatically iterate over findings
- Map findings to specific files and lines
- Understand severity and category without parsing prose
- Integrate docvet into automated fix loops

## Proposed

[Read the thread](https://github.com/Alberto-Codes/docvet/issues/151) · 2026-02-26 · closed · 0 comments

The remaining reports are on [the project's issue tracker](https://github.com/Alberto-Codes/docvet/issues).