cursor-doctor

Cursor Doctor

An MCP server that audits a project for documentation, rules, skills, and other knowledge artifacts. It compares what exists against a reference concept catalog and produces a prescription plan (cursor-doctor-prescription-plan.md) with frontmatter todos listing missing or incomplete elements. The plan always ends with an Update Artifacts todo so that rules, skills, and docs stay in sync after every session.

Repo mascot & logo

Installation

Add the server to your project's MCP config (or use it globally via Cursor settings):

Using npx (no local install):

{
  "mcpServers": {
    "cursor-doctor": {
      "command": "npx",
      "args": ["-y", "cursor-doctor@latest"]
    }
  }
}

Local development (from this repo):

{
  "mcpServers": {
    "cursor-doctor": {
      "command": "node",
      "args": ["/path/to/cursor-doctor/dist/index.js"]
    }
  }
}

Config lives in .cursor/mcp.json (project) or in Cursor’s user MCP configuration.

Using the MCP server

1. Install the server (add it to .cursor/mcp.json as in Installation above).
2. Create a skill for the doctor command

Prompt Cursor to create a skill file for the command "doctor" or "cursor doctor" that:

• Calls the cursor-doctor-self MCP server in planning mode.
• Uses the generate_prescription tool so the project is audited and cursor-doctor-prescription-plan.md is written with frontmatter-style todos in the plan.
• Works through the plan using those frontmatter todos as the task list.

The repo tracks a skill and rules so the workflow is consistent; see Tracked Cursor artifacts below.

Tracked Cursor artifacts

These files are committed in this repo so the doctor command and expectations stay consistent:

| File | Purpose | |------|--------| | .cursor/skills/cursor-doctor/SKILL.md | Skill for "doctor" / "cursor doctor": calls cursor-doctor-self in planning mode, uses frontmatter todos from the prescription plan. | | .cursor/rules/cursor-doctor.mdc | Rule applied when editing the prescription plan or rules/skills: use the doctor workflow and complete Update Artifacts. | | .cursor/rules/required-cursor-doctor-skill.mdc | Rule (always apply): the cursor-doctor skill must exist at .cursor/skills/cursor-doctor/SKILL.md; if missing, recreate it from this README. |

Reference these in your workflow; do not remove them without updating the README.

Tools

| Tool | Purpose | |------|--------| | audit_project | Scans the project for markdown, rules (.mdc), skills (SKILL.md), and config files. Returns paths and summaries for semantic matching, plus a list of gaps (concepts that have no matching artifact). | | read_document | Returns the full content of a file. Use a path from the audit result to inspect an artifact. | | generate_prescription | Runs an audit, then writes cursor-doctor-prescription-plan.md to the project root with YAML frontmatter todos (missing/incomplete concepts and the always-final “Update Artifacts” step). |

Concept Catalog

The server checks for 23 concepts in 6 tiers. Artifacts are matched by file patterns (e.g. README.md, .cursor/rules/*.mdc) and by content signals (keywords in the first lines of a file) so that differently named files can still satisfy a concept.

• Tier 1 – Foundation: README, project-overview rule, file-locations rule, agent-workflow rule.
• Tier 2 – Architecture: Architecture doc, data model doc, API spec (e.g. OpenAPI).
• Tier 3 – Development conventions: Backend, frontend, database, and lessons-learnt rules.
• Tier 4 – AI knowledge and skills: AGENTS doc, knowledge-base skill, code-generation skill, operational skills, dependency-management skill.
• Tier 5 – Quality and documentation: Testing spec, accessibility doc, style guide, UI documentation.
• Tier 6 – Infrastructure: MCP config, container config, CI/CD config.
• Final – Artifact sync: “Update Artifacts” is always appended as the last todo so that after any plan or coding session the AI is prompted to review and update rules, skills, and docs.

Prescription format

cursor-doctor-prescription-plan.md has:

1. YAML frontmatter with:

• title, project, audited_at, health_score, total_concepts, found, missing, incomplete
• todos: list of id, tier, status (missing | incomplete | found | action), concept, priority, and optionally found_at, details, prompt

1. Body with a short summary and a reminder that the final todo is always “Update Artifacts”.

Each todo for a missing or incomplete concept includes a prompt that instructs the AI to create or update the artifact (e.g. by mining the codebase). The artifact-sync todo always has status: action and a prompt to review and update all cursor-doctor artifacts at the end of the session.

Build and run

npm install
npm run build

The server runs over stdio; Cursor (or another MCP client) starts it and communicates via stdin/stdout. To run the built server directly:

node dist/index.js

(It will wait for JSON-RPC on stdin; normal use is through Cursor’s MCP integration.)

Version bump on commit

A pre-commit hook (via Husky) bumps the npm package patch version before each commit. The commit you push will therefore include the updated package.json (and package-lock.json). Hooks are installed when you run npm install (the prepare script runs husky). To skip the bump for a single commit, use git commit --no-verify.

Publishing

1. Publish to npm (for npx cursor-doctor)

So users can install with npx cursor-doctor@latest, publish the package to npm:

npm login          # once, if not already logged in
./publish.sh       # builds and runs npm publish
./publish.sh --dry-run   # test without publishing

2. List on the Cursor MCP Marketplace (cursor.store)

To appear in the Cursor MCP Marketplace so people can discover and install from cursor.store:

1. Publish to npm first (step above), so the install snippet works.

1. Submit your listing at cursor.store/mcp/new (free). You’ll need:

• Name: e.g. Cursor Doctor
• Slug: e.g. cursor-doctor
• Short & long description: what it does (audit docs/rules/skills, generate prescription plan).
• Category: e.g. DevTools or Productivity
• Tags: e.g. documentation, cursor, mcp, audit, rules, skills
• Author/maintainer: your name or handle
• Repository URL: your GitHub (or other) repo
• Install snippet (for Cursor .cursor/mcp.json):

     {
       "mcpServers": {
         "cursor-doctor": {
           "command": "npx",
           "args": ["-y", "cursor-doctor@latest"]
         }
       }
     }

• Permission level: Low (read-only: scans filesystem, returns JSON; no shell, no network except what Cursor does).

1. Optional: After the listing exists, you can claim it (e.g. via GitHub) on cursor.store to add a verified badge, better description, and screenshots.

Full rules and requirements: cursor.store/rules.

License

MIT