使用说明（Markdown格式）

• 项目简介

  • 该仓库实现了一个完整的 MCP 服务器，核心职责包括：托管资源、注册并执行工具、定义并渲染提示模板（Prompts），并通过 JSON-RPC 与 MCP 客户端通信。服务器支持多传输协议（stdio、SSE、dual），具备会话管理、能力声明以及可扩展的插件化工具与资源体系。

• 主要功能点

  • MCP 核心能力暴露
    • 资源管理：注册并读取可用资源及其元数据
    • 工具注册与执行：提供可调用的外部功能（如获取组件、获取示例、列出块等）
    • 提示模板：定义与渲染用于与 LLM 交互的 prompts
    • 支持多传输：stdio、Server-Sent Events (SSE)、双传输（stdio + SSE）并发连接
    • 会话与健康管理：会话标识、连接管理、健康端点
  • 服务器端能力声明
    • 通过 MCP SDK 的 Server 实例进行能力声明和请求处理
  • 资源模板与主题/ Tweaks 的集成
    • 支持 tweakcn 相关的主题、预设、目录结构读取与 CSS/ Tailwind 代码合成
  • 框架适配
    • 通过动态加载实现对 React、Svelte、Vue、React Native 等前端框架的组件/资源读取等功能的适配
  • 容错与监控
    • 引入简单的日志、错误处理与断路器（Circuit Breaker）保护外部调用

• 安装步骤

  • 准备

    • 本仓库包含 TypeScript 服务端实现，请确保 Node.js 环境就绪。

  • 安装

    • 安装依赖并准备运行环境（使用 npm/yarn）

  • 运行方式（示例）

    • 快速启动（默认 stdio 传输）
      • npx @jpisnice/shadcn-ui-mcp-server
    • 启用 SSE 传输并自定义端口
      • npx @jpisnice/shadcn-ui-mcp-server --mode sse --port 7423
    • 指定框架以切换实现（如 svelte / vue / react-native）
      • npx @jpisnice/shadcn-ui-mcp-server --framework svelte
      • npx @jpisnice/shadcn-ui-mcp-server --framework vue
      • npx @jpisnice/shadcn-ui-mcp-server --framework react-native
    • 如果需要通过 GitHub API 提高请求额度，请提供 GITHUB_PERSONAL_ACCESS_TOKEN（环境变量或命令行参数）。

• 服务器配置（MCP 客户端使用时的连接配置）

  • 以下 JSON 配置仅用于 MCP 客户端在连接 MCP 服务器时的参数示例，客户端本身不需要本配置来运行。
  • 配置示例（描述性文本，不作为代码块展示）：
    • serverName: "shadcn-ui-mcp-server"
    • command: "node"
    • args: ["build/index.js", "--mode", "sse", "--port", "7423"]
    • 注释说明：
      • serverName 为 MCP 服务器在 MCP 客户端侧的标识，与服务器端名称一致。
      • command 与 args 指定启动 MCP 服务器的方式，示例为通过 Node 直接执行打包后的入口（build/index.js），开启 SSE 模式并监听端口 7423。
      • 客户端可选的参数包括 framework（如 react/svelte/vue/react-native），通过 --framework 指定，以匹配服务器端在启动时的实现框架。

• 基本使用方法

  • 启动后
    • 通过 stdio、SSE 等传输模式与 MCP 客户端连接，客户端可请求资源、调用工具、获取 Prompts 等。
    • 客户端可以通过 Claude Code、VS Code 等工具与服务器建立连接，执行资源查询、组件/块获取、主题应用等操作。
  • 流量与健康
    • 服务器提供健康端点，SSE 连接可实现多客户端并发场景，具备会话/连接管理能力。
  • 日志与故障
    • 服务端会输出日志（INFO/WARN/ERR），便于排错与监控。

• 说明与注意事项

  • MCP 客户端需要通过 JSON-RPC 形式向服务器发起请求，服务器端根据请求类型路由到对应的资源、工具或提示模板处理逻辑。
  • 若要扩展新的资源、工具或 Prompts，可以在相应目录下添加实现，并在服务器启动时自动暴露。
  • 如需 Docker 部署，请参考 README 提供的 SSE 与 Docker 的相关说明。