CleanSlice MCP Server

MCP (Model Context Protocol) server that gives AI coding agents access to the CleanSlice architecture documentation. Connect it to Claude, Cursor, Windsurf, or any MCP-compatible client so the AI knows how to build apps using CleanSlice conventions.

Installation

<details> <summary><b>Install in Claude Code</b></summary>

Run this command. See Claude Code MCP docs for more info.

claude mcp add --scope user --transport http cleanslice https://mcp.cleanslice.org/mcp

Remove --scope user to install for the current project only.

Tip: enforce MCP usage with CLAUDE.md

To make sure Claude Code always consults the CleanSlice MCP before writing any code, add the following to your project's CLAUDE.md:

## CleanSlice MCP — Required

Before writing or modifying any code you MUST consult the CleanSlice MCP:

1. Call `get-started` to load the core architecture rules.
2. Call `list-categories` to see available documentation areas.
3. Call `search` with at least 2 task-relevant queries covering:
   (a) core implementation details for the feature you are building,
   (b) edge cases, constraints, or standards that apply.

Do NOT guess conventions — always verify against MCP results first.

This ensures the agent reads CleanSlice docs at the start of every task, not after the fact.

Optional: add a Stop hook as a safety net

To catch cases where the agent skips the MCP despite the CLAUDE.md instruction, add this to .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "timeout": 180,
            "prompt": "You are a verification subagent. Your job: ensure the main Claude Code agent used the `cleanslice` MCP knowledge sufficiently and did not guess.\n\nContext JSON:\n$ARGUMENTS\n\nVerification requirements:\n1) Identify what the user asked for (deliverables + constraints) from the conversation/transcript in $ARGUMENTS.\n2) Verify the agent consulted the `cleanslice` MCP server for relevant knowledge BEFORE finalizing:\n   - Must call `cleanslice` \"get-started\" at least once (or equivalent) to confirm the server's purpose and usage.\n   - Must call \"list-categories\" to understand the available knowledge areas.\n   - Must call \"search\" with task-relevant queries (at least 2 searches) covering: (a) core implementation details, (b) edge cases / constraints.\n3) Validate coverage:\n   - If any required category is relevant but not checked, fail.\n   - If answers include specifics that are not supported by MCP results, fail.\n4) Output STRICT JSON only:\n   - If everything is verified: {\"ok\": true}\n   - If anything is missing/unsupported: {\"ok\": false, \"reason\": \"What is missing + exact MCP calls the main agent must run next (e.g., run list-categories, then search for X/Y, then update the solution).\"}\n\nImportant:\n- `cleanslice` tools will appear as MCP tools. Use whatever exact tool names are available in this environment (they follow the mcp__<server>__<tool> naming pattern).\n- Do not allow stopping until MCP-backed evidence is sufficient."
          }
        ]
      }
    ]
  }
}

</details>

<details> <summary><b>Install in Cursor</b></summary>

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

Paste the following into your Cursor ~/.cursor/mcp.json file. You may also install in a specific project by creating .cursor/mcp.json in your project folder. See Cursor MCP docs for more info.

{
  "mcpServers": {
    "cleanslice": {
      "type": "http",
      "url": "https://mcp.cleanslice.org/mcp"
    }
  }
}

Tip: enforce MCP usage with a Cursor rule

Create .cursor/rules/cleanslice.mdc in your project to make Cursor always consult the MCP before writing code:

---
description: CleanSlice architecture rules
globs: **/*.{ts,vue,prisma}
alwaysApply: true
---

## CleanSlice MCP — Required

Before writing or modifying any code you MUST consult the CleanSlice MCP:

1. Call `get-started` to load the core architecture rules.
2. Call `list-categories` to see available documentation areas.
3. Call `search` with at least 2 task-relevant queries covering:
   (a) core implementation details for the feature you are building,
   (b) edge cases, constraints, or standards that apply.

Do NOT guess conventions — always verify against MCP results first.

</details>

<details> <summary><b>Install in Windsurf</b></summary>

Add to your Windsurf MCP config file. See Windsurf MCP docs for more info.

{
  "mcpServers": {
    "cleanslice": {
      "type": "http",
      "serverUrl": "https://mcp.cleanslice.org/mcp"
    }
  }
}

Tip: enforce MCP usage with a Windsurf rule

Create .windsurf/rules/cleanslice.md in your project to make Windsurf always consult the MCP before writing code:

## CleanSlice MCP — Required

Before writing or modifying any code you MUST consult the CleanSlice MCP:

1. Call `get-started` to load the core architecture rules.
2. Call `list-categories` to see available documentation areas.
3. Call `search` with at least 2 task-relevant queries covering:
   (a) core implementation details for the feature you are building,
   (b) edge cases, constraints, or standards that apply.

Do NOT guess conventions — always verify against MCP results first.

</details>

<details> <summary><b>Install in VS Code (Copilot)</b></summary>

Add to .vscode/mcp.json in your project. See VS Code MCP docs for more info.

{
  "servers": {
    "cleanslice": {
      "type": "http",
      "url": "https://mcp.cleanslice.org/mcp"
    }
  }
}

Tip: enforce MCP usage with Copilot instructions

Create .github/copilot-instructions.md in your project root to make Copilot always consult the MCP before writing code:

## CleanSlice MCP — Required

Before writing or modifying any code you MUST consult the CleanSlice MCP:

1. Call `get-started` to load the core architecture rules.
2. Call `list-categories` to see available documentation areas.
3. Call `search` with at least 2 task-relevant queries covering:
   (a) core implementation details for the feature you are building,
   (b) edge cases, constraints, or standards that apply.

Do NOT guess conventions — always verify against MCP results first.

</details>

<details> <summary><b>Install in Claude Desktop</b></summary>

Add to your claude_desktop_config.json. See Claude Desktop MCP docs for more info.

{
  "mcpServers": {
    "cleanslice": {
      "type": "http",
      "url": "https://mcp.cleanslice.org/mcp"
    }
  }
}

</details>

<details> <summary><b>Install in Opencode</b></summary>

Add this to your Opencode configuration file. See Opencode MCP docs for more info.

{
  "mcp": {
    "cleanslice": {
      "type": "remote",
      "url": "https://mcp.cleanslice.org/mcp",
      "enabled": true
    }
  }
}

Tip: enforce MCP usage with AGENTS.md

Create AGENTS.md in your project root to make Opencode always consult the MCP before writing code:

## CleanSlice MCP — Required

Before writing or modifying any code you MUST consult the CleanSlice MCP:

1. Call `get-started` to load the core architecture rules.
2. Call `list-categories` to see available documentation areas.
3. Call `search` with at least 2 task-relevant queries covering:
   (a) core implementation details for the feature you are building,
   (b) edge cases, constraints, or standards that apply.

Do NOT guess conventions — always verify against MCP results first.

</details>

<details> <summary><b>Run Locally</b></summary>

git clone https://github.com/CleanSlice/mcp.git
cd mcp
npm install
npm run dev

Then point your MCP client to http://localhost:8080/mcp.

</details>

Available Tools

Tool	Description
get-started	Returns the essential CleanSlice rules and conventions
list-categories	Lists all documentation categories
search	Search the docs by query, category, framework, phase, or tags

Environment Variables

Variable	Default	Description
PORT	8080	Server port
DOCS_PATH	Auto-discover	Path to bundled docs directory
GITHUB_REPO	CleanSlice/docs	Fallback GitHub repo for docs
GITHUB_TOKEN	-	GitHub token (optional, for higher rate limits)
CORS_ORIGIN	*	Allowed CORS origin(s)

Docker

docker build -t cleanslice-mcp .
docker run -p 8080:8080 cleanslice-mcp

Endpoints

Endpoint	Description
GET /sse	SSE transport (for Claude Desktop, Cursor)
POST /messages	SSE message handler
POST /mcp	Streamable HTTP transport
GET /health	Health check
GET /api	Swagger docs