@mantine/mcp-server

技能简介

@mantine/mcp-server 是 Mantine UI 组件库官方发布的 Model Context Protocol（MCP）服务器，旨在为 AI 编码助手提供 Mantine 组件库实时、准确的文档查询能力。Mantine 是目前最受开发者欢迎的 React 组件库之一，提供了从基础 UI 组件（Button、Input、Modal）到高级功能组件（Form、Notifications、RichTextEditor）在内的 100 多个组件，以及 hooks 库、form 管理、日期处理等周边生态。在 AI 辅助编程场景中，开发者经常面临"这个 Mantine 组件有哪些 Props 可用"、"某个 Props 的正确类型是什么"、"如何在 Mantine 中实现某种 UI 效果"等需要查阅文档的问题——这类问题通常发生在编码过程中，打断查阅文档的上下文切换成本极高。@mantine/mcp-server 通过 MCP 协议将这些文档查询能力直接嵌入 AI 编码助手的工作流，开发者只需在 AI 对话中描述需求，AI 即可实时查询正确的组件文档并给出符合 Mantine 最佳实践的代码建议。该服务器配置极简、环境依赖少，是前端开发者和 AI 编程助手用户的效率利器。

核心能力

• Mantine 组件文档查询：通过 get_item_doc 工具获取任意 Mantine 组件的完整文档，包括组件描述、所有可用 Props、Props 类型定义及默认值，AI 无需离开编辑器即可查阅权威文档。
• Mantine Hooks 查询：通过 list_items 工具列出 Mantine 提供的所有可用 hooks，并可通过 get_item_props 获取单个 hook 的参数和返回值类型信息，帮助 AI 在函数组件中正确使用 Mantine 状态管理工具。
• 属性结构查询：通过 get_item_props 工具查询组件的完整属性树结构，包括嵌套组件（如 Modal 的 Header、Body、Footer）的独立 Props，使 AI 能够精确理解复合组件的组成方式。
• 语义文档搜索：通过 search_docs 工具以自然语言关键词搜索 Mantine 文档，返回最相关的组件或 hooks 推荐，解决"不知道该用哪个组件"的探索性问题。
• 完全本地化运行：文档数据来自 Mantine 官方导出的静态 JSON 数据文件（MANTINE_MCP_DATA_URL，默认指向 mantine.dev/mcp），无需互联网连接亦可使用（数据文件可本地缓存或部署在私域服务器），AI 模型查询完全在本地完成，无隐私泄露风险。
• 可配置超时和端点：支持通过环境变量 MANTINE_MCP_DATA_URL 自定义文档数据源地址，以及通过 MANTINE_MCP_TIMEOUT_MS 配置 HTTP 请求超时时间（默认 10000ms），适配不同网络环境和企业内网场景。

安装配置

前置条件：Node.js 运行环境（npx 或全局 npm 安装）。

方式一：npx 即时启动（最简方式）

# 在 AI 助手的 MCP 配置中添加
npx @mantine/mcp-server

方式二：全局安装

npm install -g @mantine/mcp-server
# 安装后任意终端均可直接执行

环境变量配置（如需自定义）

# 指定自定义文档数据源（内网部署场景）
export MANTINE_MCP_DATA_URL=http://localhost:8080/mantine-mcp-data

# 调整超时时间（网络较慢环境）
export MANTINE_MCP_TIMEOUT_MS=30000

VS Code Cline 配置示例

{
  "mcpServers": {
    "mantine-mcp": {
      "command": "npx",
      "args": ["-y", "@mantine/mcp-server"]
    }
  }
}

Claude Code 配置

claude mcp add mantine -- npx -y @mantine/mcp-server

使用步骤

1. 配置 MCP 服务器：在 AI 编码助手（Cline / Claude Code / Copilot 等）的 MCP 配置中添加 @mantine/mcp-server 条目，保存后助手自动连接。首次连接时会获取 Mantine 文档索引（约数 MB），后续查询均基于本地缓存。
2. 查询组件文档：在 AI 对话中描述需要的 UI 需求，例如"我需要一个带标题和关闭按钮的模态框，Mantine 怎么实现？"——AI 将通过 MCP 工具查询 Modal 组件文档，并给出包含 Header、Body、Footer 配置的完整示例代码。
3. 探索可用 Hooks：提问"如何在 Mantine 中管理表单状态？"——AI 通过 list_items 列出 Mantine hooks 并定位到 useForm 或 @mantine/form 相关方案。
4. 查阅 Props 细节：当 AI 给出组件代码后，可追问"Modal 的 props 中 closeOnClickOutside 是什么类型？默认值是？"——AI 通过 get_item_props 获取精确的 Props 类型定义。
5. 搜索相关组件：当不确定具体组件名称时，使用"Mantine 中实现下拉菜单有哪些方案？"——AI 通过 search_docs 语义搜索 Mantine 文档，返回 Menu、Select、Combobox 等相关组件及各自适用场景。

适用场景

• React + Mantine 项目开发：开发者在使用 Mantine 构建 React 应用时，在 AI 编码助手中实时获取组件用法和最佳实践，减少查阅文档的上下文切换，保持心流状态。
• AI 结对编程前端场景：AI 助手在生成包含 Mantine 组件的代码时，自动查询组件当前版本的 Props 定义和类型约束，避免生成已废弃或不兼容的 API 调用。
• Mantine 版本升级辅助：当项目需要升级 Mantine 版本时，AI 助手可借助该 MCP 服务器快速比对新旧版本 Props 差异，生成迁移建议代码。
• 企业内部 Mantine 组件库文档服务：通过将 MANTINE_MCP_DATA_URL 指向企业内部文档站点，为在无外网访问权限的开发环境中工作的工程师提供 Mantine 文档查询能力。
• 前端新手学习 Mantine：初学者通过自然语言提问让 AI 助手引导探索 Mantine 组件生态，系统性地学习组件选择和用法，无需在文档站和编辑器之间来回跳转。

适用人群

• 使用 Mantine 组件库构建 React 应用的开发者
• 在前端项目中引入 AI 编码助手的团队
• 需要维护或升级 Mantine 项目的工程师
• 使用 Claude Code / Cline / GitHub Copilot 等 AI 助手的前端开发者
• React 技术栈的前端全栈工程师

工作原理

@mantine/mcp-server 的工作原理围绕 Mantine 官方提供的静态文档数据展开：

文档索引获取阶段：服务器启动时，从 MANTINE_MCP_DATA_URL（默认 mantine.dev/mcp）获取 Mantine 组件和 hooks 的完整文档索引文件，该文件包含所有组件名称、描述、Props 定义、类型信息及相互引用的结构化数据。数据以静态 JSON 格式提供，支持本地缓存或部署到私有服务器。

工具调用阶段：当 AI 模型通过 MCP 协议调用 list_items、get_item_doc、get_item_props 或 search_docs 时，服务器根据工具名称和参数在本地索引中执行相应查询：列表工具返回结构化数据；搜索工具对文档文本和组件名称进行全文或语义匹配，返回最相关结果。

结果返回阶段：所有工具调用结果以标准 MCP 协议格式返回给 AI 模型，AI 模型将查询到的文档内容融入其回复中，给出准确、实时的 Mantine 用法指导。

由于所有文档查询均在本地数据文件上执行，无需调用任何外部 API，也不涉及用户代码或项目信息的任何上传和传输。