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

Install in Claude Code

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

Terminal

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:

markdown

## 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.
4. Call `read-doc` to read the full document when search snippets aren't enough.

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:

config.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.\n   - May call \"read-doc\" to get full document content when search snippets are insufficient.\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."
          }
        ]
      }
    ]
  }
}

Install in Cursor

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.

config.json

{
  "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:

markdown

---
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.
4. Call `read-doc` to read the full document when search snippets aren't enough.

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

Install in Windsurf

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

config.json

{
  "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:

markdown

## 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.
4. Call `read-doc` to read the full document when search snippets aren't enough.

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

Install in VS Code (Copilot)

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

config.json

{
  "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:

markdown

## 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.
4. Call `read-doc` to read the full document when search snippets aren't enough.

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

Install in Claude Desktop

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

config.json

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

Install in Opencode

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

config.json

{
  "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:

markdown

## 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.
4. Call `read-doc` to read the full document when search snippets aren't enough.

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

Run Locally

bash

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.

Available Tools

Tool	Description
`get-started`	Returns the essential CleanSlice rules and conventions. Call this first.
`list-categories`	Lists all documentation categories available for search filtering
`search`	Search docs by query, category, framework, phase, or tags. Returns snippets (keyword-in-context excerpts) and document paths
`read-doc`	Read the full content of a specific document by path. Use after `search` to get complete docs

Recommended workflow

Code

get-started            → learn the core rules
list-categories        → discover what's available
search(query: "...")   → find relevant docs (returns snippets)
read-doc(path: "...")  → read full document when snippets aren't enough

The search tool returns 1-3 keyword-in-context snippets per result instead of full document content. This keeps responses compact (~3-5K instead of ~95K) while showing the most relevant sections. Use read-doc with the path from search results to fetch the complete document when needed.

Environment Variables

Variable	Default	Description
`PORT`	`8080`	Server port
`NODE_ENV`	-	Set to `dev` for debug/verbose logging
`DOCS_PATH`	Auto-discover	Path to bundled docs directory
`GITHUB_REPO`	`CleanSlice/docs`	Fallback GitHub repo for docs
`GITHUB_BRANCH`	`main`	GitHub branch to fetch from
`GITHUB_TOKEN`	-	GitHub token (optional, for higher rate limits)
`GITHUB_CACHE_TTL`	`3600`	GitHub content cache TTL in seconds
`CORS_ORIGIN`	`*`	Allowed CORS origin(s)

Docker

Terminal

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