npm package: @noleemits/duke-spine-builder-mcp
Description: Duke Spine Builder MCP server - Deuk-specific design rules, validation, and component builder tools for the Deuk Spine Institute website
Author: Noleemits
Latest version: 2.6.1

# Duke Spine Builder MCP

Deuk-specific design rules and validation tools for the [Deuk Spine Institute](https://deukspine.com) website.

## What It Does

Provides 9 specialized tools for Claude to work with the Deuk Spine Institute WordPress site:

1. **`health_check`** — Verify connection to the WordPress plugin
2. **`get_design_rules`** — All Deuk design conventions (buttons, colors, spacing, boilerplate)
3. **`get_button`** — Context-aware button generator (hero = yellow, light bg = blue, dark bg = yellow)
4. **`validate_page`** — Validate Elementor pages against Deuk standards
5. **`extract_content`** — Extract all content from a page for refactoring
6. **`import_template`** — Import full Elementor JSON templates
7. **`list_components`** — List all available Deuk design components
8. **`add_component`** — Add a single component to a page with variable substitution
9. **`build_page`** — Build an entire page from a component array (recommended)

## Requirements

- **Node.js** 18+ ([download here](https://nodejs.org))
- **Claude Desktop** or **Claude.ai** with MCP connector support
- **WordPress plugins** (must be activated on your site):
  - [Noleemits Vision Builder](https://www.npmjs.com/package/@noleemits/vision-builder-mcp) (generic WP/Elementor operations)
  - Duke Spine Builder (Deuk-specific tools — this package)

## Transport Modes

### stdio (default) — for Claude Desktop

The server communicates via standard input/output. This is the default mode used by Claude Desktop.

```bash
# Auto-installed by Claude Desktop via npx
npx -y @noleemits/duke-spine-builder-mcp
```

### HTTP/SSE — for Claude.ai web connectors

Run as an HTTP server with Server-Sent Events transport. Includes **heartbeat every 25 seconds** to prevent idle disconnections from proxies/CDNs.

```bash
# Start HTTP/SSE server on port 3100 (default)
node index.js --http

# Custom port
node index.js --http --port=8080
```

Endpoints:
- `GET /sse` — SSE stream (MCP protocol + keepalive heartbeat)
- `POST /message?sessionId=...` — JSON-RPC messages
- `GET /health` — Server health check

For Claude.ai, point your connector to `https://your-server:3100/sse`.

## Setup

### 1. Create WordPress Application Password

1. Log into WordPress Admin
2. Click your name (top right) -> **Edit Profile**
3. Scroll to **Application Passwords**
4. Name: `Duke MCP` -> **Add New**
5. Copy the password (you only see it once!)

### 2. Configure Claude Desktop (stdio mode)

Open **Claude Desktop** -> **Settings** (gear icon) -> **Developer** -> **Edit Config**

Add BOTH servers:

```json
{
  "mcpServers": {
    "vision-builder": {
      "command": "npx",
      "args": ["-y", "@noleemits/vision-builder-mcp"],
      "env": {
        "WP_URL": "https://your-site.com",
        "WP_USER": "your-username",
        "WP_APP_PASSWORD": "your-app-password"
      }
    },
    "duke-spine-builder": {
      "command": "npx",
      "args": ["-y", "@noleemits/duke-spine-builder-mcp"],
      "env": {
        "WP_URL": "https://your-site.com",
        "WP_USER": "your-username",
        "WP_APP_PASSWORD": "your-app-password"
      }
    }
  }
}
```

### 3. Restart Claude Desktop

Close completely and reopen.

### 4. Test It

Type in Claude Desktop:

```
Run a health check
```

You should see:
- Duke Spine Builder: ACTIVE
- Plugin version, Elementor status, component count

## Example Commands

Once configured, you can ask Claude:

**Browse the site:**
- "Show me all the pages"
- "What's on the Lower Back Pain page?"

**Edit content:**
- "Update the title of page 123"
- "Create a new draft page called 'Herniated Disc Treatment'"

**Work with design:**
- "Show me the Deuk design rules"
- "Validate page 123 against our standards"
- "Extract content from page 456 so we can rebuild it"
- "Get me a hero button that says 'Start Free MRI Review'"
- "List all available components"
- "Build page 789 with hero, stats bar, comparison table, and CTA"

Claude already knows all the Deuk Spine design rules — button colors, spacing, fonts, section layouts. You don't need to remember any of that.

## Troubleshooting

**"Duke Spine Builder: NOT RESPONDING"**
- Make sure both WordPress plugins are activated
- Check your username and app password are correct
- Verify `WP_URL` points to the correct site

**"Cannot find module"**
- Make sure you have Node.js 18+ installed
- Try running: `npx -y @noleemits/duke-spine-builder-mcp` manually to see errors

**Claude doesn't show the tools**
- Make sure you saved the config file
- Make sure you restarted Claude Desktop completely (not just closed the window)

**Connector keeps disconnecting (Claude.ai)**
- Switch to HTTP/SSE mode: `node index.js --http`
- The heartbeat prevents idle timeout disconnections
- Check `/health` endpoint to verify the server is running

## Version History

- **2.3.0** — Fix Claude Desktop disconnections: process.stdin.resume(), keepalive timer, dynamic SSE imports, pinned SDK to ^1.26.0
- **2.2.0** — HTTP/SSE transport with heartbeat, global error handlers, fetch timeout
- **2.1.0** — 9 tools (added component library, build_page, add_component)
- **2.0.0** — Separate Duke package (5 Deuk-specific tools only)
- **1.x** — Combined package (deprecated)

## License

MIT