关于 CleanSlice
CleanSlice MCP Server 为 AI 编码 Agent 提供 CleanSlice 架构文档,面向采用 NestJS 和 Nuxt 全栈约定的开发者。它支持按类别和查询检索文档,并可进一步读取完整内容。
主要功能
- 01获取核心架构规则
- 02列出文档类别
- 03按查询和标签搜索
- 04读取完整文档
适用场景
- 01按 CleanSlice 约定实现功能
- 02编码前查找架构指导
- 03检索特定框架或阶段的文档
MCP 相关
这是一个 MCP 服务,通过远程 HTTP 或本地运行方式向客户端提供架构文档检索和读取工具。
配置
远程服务无需本地安装。选择你使用的客户端,复制配置或使用一键安装。
https://mcp.cleanslice.org/mcpclaude mcp add --transport http cleanslice https://mcp.cleanslice.org/mcp{"mcpServers":{"cleanslice":{"type":"http","url":"https://mcp.cleanslice.org/mcp"}}}在 Cursor 中打开{"servers":{"cleanslice":{"type":"http","url":"https://mcp.cleanslice.org/mcp"}}}在 VS Code 中打开{"mcpServers":{"cleanslice":{"type":"http","url":"https://mcp.cleanslice.org/mcp"}}}{"mcpServers":{"cleanslice":{"serverUrl":"https://mcp.cleanslice.org/mcp"}}}命令在终端中运行;JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。
工具
4此工具无需参数。
详细介绍
CleanSlice MCP 服务
MCP(Model Context Protocol)服务,可让 AI 编码 Agent 访问 CleanSlice 架构文档。将其连接到 Claude、Cursor、Windsurf 或任何兼容 MCP 的客户端,让 AI 了解如何按照 CleanSlice 约定构建应用。
安装
在 Claude Code 中安装
运行此命令。更多信息请参阅 Claude Code MCP 文档。
claude mcp add --scope user --transport http cleanslice https://mcp.cleanslice.org/mcp
移除
--scope user,即可仅为当前项目安装。
提示:使用 CLAUDE.md 强制使用 MCP
若要确保 Claude Code 在编写任何代码之前始终查阅 CleanSlice MCP,请将以下内容添加到项目的 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.
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.
这样可确保 Agent 在每项任务开始时(而不是事后)读取 CleanSlice 文档。
可选:添加 Stop hook 作为安全保障
若要捕获 Agent 忽略 CLAUDE.md 指令、跳过 MCP 的情况,请将以下内容添加到 .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.\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."
}
]
}
]
}
}
在 Cursor 中安装
前往:Settings -> Cursor Settings -> MCP -> Add new global MCP server
将以下内容粘贴到 Cursor 的 ~/.cursor/mcp.json 文件中。你也可以在项目文件夹中创建 .cursor/mcp.json,为特定项目安装。更多信息请参阅 Cursor MCP 文档。
{
"mcpServers": {
"cleanslice": {
"type": "http",
"url": "https://mcp.cleanslice.org/mcp"
}
}
}
提示:使用 Cursor 规则强制使用 MCP
在项目中创建 .cursor/rules/cleanslice.mdc,让 Cursor 在编写代码前始终查阅 MCP:
---
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.
在 Windsurf 中安装
添加到 Windsurf MCP 配置文件中。更多信息请参阅 Windsurf MCP 文档。
{
"mcpServers": {
"cleanslice": {
"type": "http",
"serverUrl": "https://mcp.cleanslice.org/mcp"
}
}
}
提示:使用 Windsurf 规则强制使用 MCP
在项目中创建 .windsurf/rules/cleanslice.md,让 Windsurf 在编写代码前始终查阅 MCP:
## 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.
在 VS Code(Copilot)中安装
添加到项目中的 .vscode/mcp.json。更多信息请参阅 VS Code MCP 文档。
{
"servers": {
"cleanslice": {
"type": "http",
"url": "https://mcp.cleanslice.org/mcp"
}
}
}
提示:使用 Copilot 指令强制使用 MCP
在项目根目录中创建 .github/copilot-instructions.md,让 Copilot 在编写代码前始终查阅 MCP:
## 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.
在 Claude Desktop 中安装
添加到 claude_desktop_config.json。更多信息请参阅 Claude Desktop MCP 文档。
{
"mcpServers": {
"cleanslice": {
"type": "http",
"url": "https://mcp.cleanslice.org/mcp"
}
}
}
在 Opencode 中安装
将以下内容添加到 Opencode 配置文件中。更多信息请参阅 Opencode MCP 文档。
{
"mcp": {
"cleanslice": {
"type": "remote",
"url": "https://mcp.cleanslice.org/mcp",
"enabled": true
}
}
}
提示:使用 AGENTS.md 强制使用 MCP
在项目根目录中创建 AGENTS.md,让 Opencode 在编写代码前始终查阅 MCP:
## 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.
本地运行
git clone https://github.com/CleanSlice/mcp.git
cd mcp
bun install
bun run dev
然后将 MCP 客户端指向 http://localhost:8080/mcp。
可用工具
| 工具 | 描述 |
|---|---|
get-started | 返回 CleanSlice 的核心规则和约定。请先调用此工具。 |
list-categories | 列出可用于搜索筛选的所有文档类别 |
search | 按查询词、类别、框架、阶段或标签搜索文档。返回片段(包含关键词上下文的摘录)和文档路径 |
read-doc | 按路径读取指定文档的完整内容。使用 search 后调用此工具以获取完整文档 |
推荐工作流
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
search 工具会为每个结果返回 1–3 段包含关键词上下文的片段,而不是完整文档内容。这样可以让响应保持精简(约 3–5K,而不是约 95K),同时展示最相关的部分。需要时,使用 read-doc 和搜索结果中的 path 获取完整文档。
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
PORT | 8080 | 服务端口 |
NODE_ENV | - | 设置为 dev,以启用调试/详细日志 |
DOCS_PATH | 自动发现 | 捆绑文档目录的路径 |
GITHUB_REPO | CleanSlice/docs | 文档的备用 GitHub 仓库 |
GITHUB_BRANCH | main | 要从中获取内容的 GitHub 分支 |
GITHUB_TOKEN | - | GitHub 令牌(可选,用于提高速率限制) |
GITHUB_CACHE_TTL | 3600 | GitHub 内容缓存 TTL,单位为秒 |
CORS_ORIGIN | * | 允许的 CORS 来源 |
Docker
docker build -t cleanslice-mcp .
docker run -p 8080:8080 cleanslice-mcp
端点
| 端点 | 描述 |
|---|---|
GET /sse | SSE 传输(用于 Claude Desktop、Cursor) |
POST /messages | SSE 消息处理程序 |
POST /mcp | Streamable HTTP 传输 |
GET /health | 健康检查 |
GET /api | Swagger 文档 |
架构文档同步
docs/architecture/ 中的四份可靠性指南由网站仓库中的 docs/architecture/ 文件(相邻检出目录 ../docs/docs/architecture)生成。编辑规范文档后,运行 node scripts/sync-architecture-docs.mjs;发布前运行 node scripts/sync-architecture-docs.mjs --check。对于其他检出目录布局,请传入 --source=/absolute/path/to/architecture。如果副本缺失或内容不一致,检查就会失败。请将生成的资源包与 MCP 变更一同提交,以便独立部署也能搜索/读取相同版本的内容。
get-started 会直接加载 00-quickstart/get-started.md,并优先使用本地文件,必要时回退到远程文件。如果文件不可用,它会明确报错,而不会返回空规则。捆绑知识集成测试会验证真实的加载、搜索和渲染后的启动内容。在本地更新文件不会更新托管的 MCP:请通过常规授权发布流程构建/测试、发布文档并部署 MCP。
评论
一个开放协议,规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话,MCP 服务负责提供工具、资源和提示模板,两者通过标准消息通信,同一个服务可以被不同客户端复用。