# Cursor

sitemd ships as a Cursor plugin with rules, skills, and an MCP server. Install the plugin or clone the repo and Cursor's agent gets 35 MCP tools, 12 skills, and auto-attaching rules that surface the right context when you edit pages or settings.

## Install

### Option 1: Cursor Marketplace (recommended)

Search for **sitemd** in the [Cursor Marketplace](https://cursor.com/marketplace) or run:

```text
/add-plugin sitemd
```

This installs the MCP server, rules, and skills automatically.

### Option 2: Clone from GitHub

```bash
git clone https://github.com/sitemd-cc/sitemd.git my-site
cd my-site
./sitemd/install
```

The repo includes `.cursor-plugin/`, `.cursor/rules/`, `.cursor/skills/`, and `.cursor/mcp.json` at the root. Cursor picks them up automatically.

### Option 3: npm

```bash
mkdir my-site && cd my-site
npm init -y
npm install @sitemd-cc/sitemd
```

After install, copy the Cursor config files from the package or add the MCP server manually.

### Option 4: Manual MCP configuration

Add the sitemd MCP server to `.cursor/mcp.json` at your project root:

```json
{
  "mcpServers": {
    "sitemd": {
      "type": "stdio",
      "command": "./sitemd/sitemd",
      "args": ["mcp"],
      "env": {}
    }
  }
}
```

Or add it to `~/.cursor/mcp.json` to make it available across all your Cursor workspaces.

## How sitemd integrates with Cursor

Cursor's plugin system has five extension primitives. sitemd uses three of them:

| Primitive | What sitemd ships | Purpose |
|---|---|---|
| **Rules** | 3 `.mdc` files in `.cursor/rules/` | Context that loads automatically based on what you're editing |
| **Skills** | 12 skill directories in `.cursor/skills/` | Task workflows the agent discovers and runs on demand |
| **MCP Server** | 35 tools via `.cursor/mcp.json` | Programmatic access to pages, settings, deploy, and more |

Rules are always-on or file-pattern-triggered context. Skills are dynamic — the agent reads their descriptions and loads them when the task matches. MCP tools are the actual API calls the agent makes.

## Rules

Rules are `.mdc` files with YAML frontmatter that control when Cursor loads them into the agent's context. sitemd ships three:

### sitemd-project (always on)

```yaml
---
description: sitemd project structure, first steps, and MCP tool reference
alwaysApply: true
---
```

Loaded on every conversation. Gives the agent the project layout, first-steps workflow, and a complete MCP tool reference table. This is the baseline context — the agent always knows what sitemd is and what tools it has.

### sitemd-pages (auto-attaches on page files)

```yaml
---
description: sitemd page format, markdown extensions, and content writing conventions
globs: pages/**/*.md, sitemd/pages/**/*.md
alwaysApply: false
---
```

Loaded only when you open or reference a file in `pages/`. Contains the full page format (frontmatter fields, slug conventions), all markdown extensions (buttons, cards, embeds, galleries, forms, modals), content generation conventions by type (docs, blog, changelog, roadmap), and the groups system.

This is the largest rule (~160 lines) but it only loads when relevant — so it doesn't consume context on non-content tasks.

### sitemd-settings (auto-attaches on settings files)

```yaml
---
description: sitemd settings format and available configuration keys
globs: settings/**/*.md, sitemd/settings/**/*.md
alwaysApply: false
---
```

Loaded when you edit any file in `settings/`. Contains the settings format (YAML frontmatter, inline comments, no markdown body), a table of all 14 settings files with what each controls, and how to read `settings/_schema` to discover valid keys.

## Skills

sitemd ships 12 skills in `.cursor/skills/`. Each is a `SKILL.md` file with a `description` frontmatter field that Cursor reads to decide when to offer the skill. Type the skill name in chat to run it.

| Skill | Usage | What it does |
|---|---|---|
| `/write` | `/write [type] [topic]` | Generate content (page, docs, blog, changelog, roadmap) |
| `/launch` | `/launch [demo\|scratch]` | Start the dev server with live build sync |
| `/deploy` | `/deploy` | Build and deploy to your configured hosting target |
| `/kickstart` | `/kickstart [description]` | Generate a complete first-draft site from one prompt |
| `/clone` | `/clone [url]` | Scrape and import an existing website |
| `/seo` | `/seo [scope]` | Run an SEO health check with scored report |
| `/site` | `/site` | Show project status and available actions |
| `/import` | `/import [file]` | Import a raw markdown file as a formatted page |
| `/og-image` | `/og-image` | Generate a branded social share image |
| `/reload` | `/reload` | Hot-reload the dev server without restart |
| `/shutdown` | `/shutdown` | Stop all running dev servers |
| `/feedback` | `/feedback [type] [title]` | Submit a bug report or feature request |

These are the same skills available in [Claude Code, Codex, and other agents](/docs/skills). The `SKILL.md` format is cross-agent compatible.

## Available MCP tools

sitemd exposes 35 tools through MCP. Here are the ones you'll use most:

| Tool | What it does |
|---|---|
| `sitemd_status` | Check project state, pages, auth, and config |
| `sitemd_pages_create` | Create a new page with frontmatter and content |
| `sitemd_site_context` | Get writing brief, site voice, and syntax reference |
| `sitemd_content_validate` | Check page quality and fix issues |
| `sitemd_deploy` | Build and deploy to your hosting target |
| `sitemd_clone` | Scrape an existing website into editable markdown |
| `sitemd_seo_audit` | Comprehensive SEO health check with scored report |
| `sitemd_config_set` | Set deploy credentials, email keys, analytics IDs |

For the full tool reference, see [MCP Server](/docs/mcp-server).

## Build a site from Cursor

Once the plugin is installed, tell the agent what you want:

> "Build me a documentation site for my API"

The agent calls `sitemd_status`, creates pages with `sitemd_pages_create`, validates with `sitemd_content_validate`, and deploys with `sitemd_deploy`. The rules auto-attach the right syntax reference as pages are created.

You can also work incrementally:

> "Add a blog post about our v2 release"

> "Update the pricing page — we raised the starter plan to $29"

> "Run an SEO audit and fix the issues"

The agent handles the MCP tool calls. You review the results in the dev server preview.

## Authentication

sitemd uses email magic links for login. Run `sitemd_auth_login` and the agent gives you a browser URL to complete authentication. For automated deploys, create an API key with `sitemd_auth_api_key` and store the resulting `SITEMD_TOKEN` in your environment.

See [Authentication](/docs/authentication) for the full flow.