# md-feedback (npm · md-feedback)

Review markdown plans before AI agents build. Annotate, gate-check, apply fixes, session handoffs.

- Trust score: 66/100 (medium)
- Change this week: −10
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `md-feedback`: 66/100 (this document), [markdown](https://verifymcp.io/servers/yeominux-md-feedback/md-feedback.md), [page](https://verifymcp.io/servers/yeominux-md-feedback/md-feedback)

## Channel facts

- Registry: `npm`
- Package: `md-feedback`
- Version: `1.5.6`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 32/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: the license (SUL-1.0) isn't a recognized OSI-approved license.
  - Actively maintained (last published 133 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 75/100
  - AI-judged instruction clarity (good).
  - Tool/resource definitions use about 2116 tokens (~78/item across 27 items; 27 tools + 0 resources), lean.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 23/100
  - Stability observed for 7 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add yeominux-md-feedback -- npx -y md-feedback
```

### Codex

```bash
codex mcp add yeominux-md-feedback -- npx -y md-feedback
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "yeominux-md-feedback": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "md-feedback"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add yeominux-md-feedback --command npx --arg -y --arg md-feedback
```

### Hermes

```yaml
mcp_servers:
  yeominux-md-feedback:
    command: "npx"
    args: ["-y", "md-feedback"]
```

### Other

```json
{
  "mcpServers": {
    "yeominux-md-feedback": {
      "command": "npx",
      "args": [
        "-y",
        "md-feedback"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 66, +61)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [security improvement] Malware scan: unverified → pass
- [security] Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window).
- [functional regression] License: unverified → fail
- [functional regression] Security disclosure: unverified → fail
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Stability: unverified → 0.20
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] Licence: SUL-1.0

### 2026-08-01 (score 5, −30)

- [security] Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- [functional regression] Security disclosure: fail → unverified
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified

### 2026-07-31 (score 35, −5)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 40, −36)

- [security regression] Known CVEs: partial → unverified
- [security regression] Malware scan: pass → unverified
- [security regression] Provenance: fail → unverified
- [security regression] Install scripts: pass → unverified
- [functional regression] License: fail → unverified
- [functional regression] Dependency health: partial → unverified
- [functional regression] Maintenance: pass → unverified
- [functional] Licence: SUL-1.0

### 2026-07-27 (score 76, +51)

- [security regression] Provenance: unverified → fail
- [security improvement] Known CVEs: unverified → partial
- [security improvement] Install scripts: unverified → pass
- [functional regression] License: unverified → fail
- [functional regression] Security disclosure: unverified → fail
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional] First check of Tool coverage: 100
- [functional] First check of Schema quality: good
- [functional] First check of Schema quality: pass
- [functional] First check of Schema quality: fail
- [functional] Licence: SUL-1.0

### 2026-07-26 (score 25)

First indexed and scored.

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

## MCP tools (27)

### `list_documents` (~63 tokens)

List markdown files in the workspace. Optionally filter to only files that already contain annotations.

Input parameters:

- `annotatedOnly` (boolean): If true, return only files containing USER_MEMO/HIGHLIGHT_MARK annotations
- `maxFiles` (integer): Maximum number of files to return

### `get_policy_status` (~20 tokens)

Return current runtime policy profile and memo-action routing rules.

### `get_workflow_status` (~34 tokens)

Return current workflow phase and transition history for a document.

Input parameters:

- `file` (string, required): Path to the annotated markdown file

### `get_severity_status` (~36 tokens)

Return memo severity overrides and unresolved blocking memo IDs for the document.

Input parameters:

- `file` (string, required): Path to the annotated markdown file

### `get_checkpoints` (~31 tokens)

List all checkpoints in an annotated markdown file.

Input parameters:

- `file` (string, required): Path to the annotated markdown file

### `generate_handoff` (~61 tokens)

Generate a structured handoff document from an annotated markdown file. Anti-compression format: explicit fields, numbers, lists only.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `target` (string): Output format target (default: standalone)

### `get_review_status` (~65 tokens)

Get current review session status: annotation counts, checkpoints, and reviewed sections. Summary-only — returns counts and metadata, not individual memos. Use list_annotations for memo details or get_document_structure for the full parse.

Input parameters:

- `file` (string, required): Path to the annotated markdown file

### `pickup_handoff` (~42 tokens)

Parse an existing handoff document to resume a review session. Returns structured data for session continuity.

Input parameters:

- `file` (string, required): Path to the handoff markdown file

### `list_annotations` (~74 tokens)

List all annotations (USER_MEMO comments) in a markdown file. Returns structured array with id, type, status, owner, text, and color. Lightweight — returns only memo data, no document body or sections. Use get_document_structure for the full parse.

Input parameters:

- `file` (string, required): Path to the annotated markdown file

### `get_document_structure` (~78 tokens)

Parse an annotated markdown file and return v0.4.0 ReviewDocument metadata. By default bodyMd is omitted to reduce context size; set includeBody=true only when full body is required.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `includeBody` (boolean): Include full bodyMd content (larger payload)

### `evaluate_gates` (~43 tokens)

Evaluate all gates in a markdown file against current memo statuses. Returns updated gate statuses without modifying the file.

Input parameters:

- `file` (string, required): Path to the annotated markdown file

### `export_review` (~92 tokens)

Export review feedback in a format optimized for a specific AI coding tool. Targets: claude-code, cursor, codex, copilot, cline, windsurf, roo-code, gemini, antigravity, generic, handoff. Returns formatted markdown ready to save to the appropriate file.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `target` (string, required): Target AI tool format

### `get_memo_changes` (~80 tokens)

Get the implementation history and progress for a memo. Returns all MemoImpl records and progress entries from .md-feedback/progress.json. If memoId is omitted, returns all changes.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `memoId` (string): Optional memo ID to filter by — if omitted, returns all changes

### `create_checkpoint` (~59 tokens)

Create a review checkpoint in an annotated markdown file. Records current annotation counts and reviewed sections.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `note` (string, required): Checkpoint note (e.g., "Phase 1 review done")

### `create_annotation` (~143 tokens)

Create a new review annotation on a markdown file. Finds the anchor text in the document and attaches a review memo. Auto-creates a quality gate and updates cursor.

Input parameters:

- `anchorText` (string, required): The exact text in the document to annotate (must exist in the file)
- `file` (string, required): Path to the annotated markdown file
- `occurrence` (integer): Which occurrence of anchorText to annotate (1-indexed, default 1). Use when the same text appears multiple times.
- `text` (string, required): The review feedback or note to attach
- `type` (string, required): fix = needs change, question = needs clarification, highlight = mark for reference

### `respond_to_memo` (~90 tokens)

Add an AI response to a memo annotation. Inserts a REVIEW_RESPONSE block into the markdown file directly below the memo's anchor text. Automatically sets the memo status to "needs_review" for human approval.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `memoId` (string, required): The memo ID to respond to
- `response` (string, required): The response text (markdown supported)

### `update_memo_status` (~117 tokens)

Update the status of a memo annotation. Writes the change back to the markdown file. Returns the updated memo. Terminal statuses (answered, done, failed, wontfix) require human approval via VS Code.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `memoId` (string, required): The memo ID to update
- `owner` (string): Optionally change the owner
- `status` (string, required): New status. Terminal statuses (answered, done, failed, wontfix) require human approval via VS Code.

### `update_cursor` (~98 tokens)

Update the plan cursor position in a markdown file. The cursor tracks "where we are" in a plan. Only one cursor per document.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `nextAction` (string, required): Description of the next action to take
- `step` (string, required): Current step (e.g., "3/7" or "Phase 2")
- `taskId` (string, required): Current task ID

### `apply_memo` (~290 tokens)

Apply an implementation action to a memo. Supports text_replace (requires occurrence or replaceAll when oldText has multiple matches; optional section-scoped propagation), file_patch (applies unified diff patch — snapshot saved first), and file_create (create a new file). Creates a snapshot before modification, records the implementation, and updates memo status to needs_review.

Input parameters:

- `action` (string, required): Type of implementation action
- `content` (string): For file_create: the file content to write
- `dryRun` (boolean): If true, return preview without writing
- `file` (string, required): Path to the annotated markdown file
- `memoId` (string, required): The memo ID to apply implementation to
- `newText` (string): For text_replace: the replacement text
- `occurrence` (integer): For text_replace: which occurrence to replace (1-indexed). Required when oldText appears multiple times unless replaceAll=true
- `oldText` (string): For text_replace: the text to find and replace
- `patch` (string): For file_patch: unified diff patch content
- `replaceAll` (boolean): For text_replace: replace all occurrences instead of one
- `scope` (string): For text_replace: replacement scope (body = whole document body, section = heading section around memo anchor)
- `targetFile` (string): For file_patch/file_create: target file path

### `link_artifacts` (~75 tokens)

Link file artifacts (source files, configs, etc.) to a memo. Creates a MemoArtifact record in the document.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `files` (array, required): Array of relative file paths to link
- `memoId` (string, required): The memo ID to link artifacts to

### `update_memo_progress` (~120 tokens)

Update the progress of a memo with a status change and message. Writes progress to .md-feedback/progress.json and updates the memo status. Terminal statuses (done, failed) require human approval via VS Code.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `memoId` (string, required): The memo ID to update progress for
- `message` (string, required): Progress message describing what was done or what failed
- `status` (string, required): New progress status. Terminal statuses (done, failed) require human approval via VS Code.

### `rollback_memo` (~72 tokens)

Rollback the latest implementation for a memo. Reverses text_replace operations (swaps before/after), marks the impl as reverted, and sets the memo status back to open.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `memoId` (string, required): The memo ID to rollback

### `batch_apply` (~68 tokens)

Apply multiple implementation operations in a single transaction. Parses the document once, applies all operations sequentially, then writes once. Each operation follows the same format as apply_memo.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `operations` (array, required): Array of operations to apply

### `advance_workflow_phase` (~63 tokens)

Advance workflow phase in strict sequence: scope -> root_cause -> implementation -> verification.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `note` (string): Optional transition note
- `toPhase` (string, required): Next phase to move to

### `set_memo_severity` (~67 tokens)

Set severity override for a memo. Defaults remain: fix=blocking, question/highlight=non_blocking.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `memoId` (string, required): Memo ID to classify
- `severity` (string, required): Severity override

### `request_approval_checkpoint` (~67 tokens)

Create an approval checkpoint for a high-risk action before execution.

Input parameters:

- `file` (string, required): Path to the annotated markdown file
- `reason` (string, required): Reason for approval request
- `tool` (string, required): High-risk tool name (e.g., batch_apply, rollback_memo)

### `approve_checkpoint` (~68 tokens)

Approve a pending high-risk checkpoint. Grants one execution for the approved tool.

Input parameters:

- `approvedBy` (string, required): Approver identity
- `file` (string, required): Path to the annotated markdown file
- `reason` (string, required): Approval rationale
- `tool` (string, required): Tool name being approved

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/yeominux-md-feedback/md-feedback#diagnostics

## Score history

- 2026-08-03: 66
- 2026-08-02: 66
- 2026-08-01: 5
- 2026-07-31: 35
- 2026-07-30: 40
- 2026-07-28: 76
- 2026-07-27: 76
- 2026-07-26: 25

## Links

- npm package: https://www.npmjs.com/package/md-feedback
- Socket report: https://socket.dev/npm/package/md-feedback
- Repository: https://github.com/yeominux/md-feedback
- Changelog RSS feed: https://verifymcp.io/servers/yeominux-md-feedback/md-feedback/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/yeominux-md-feedback/md-feedback/changelog.json
- HTML version of this page: https://verifymcp.io/servers/yeominux-md-feedback/md-feedback