tsparticles/mcp-server 完全指南基于 MCP 协议让 AI 助手理解、生成与诊断 tsParticles 粒子配置【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles本文是 tsParticles 官方 MCPModel Context Protocol服务器tsparticles/mcp-server的实战指南覆盖本地 stdio 接入、Claude Desktop 等客户端配置、内置工具/资源/Prompt 的能力说明以及从直连端口到 Docker、Synology 反向代理、Cloudflare Tunnel 的多种远程部署方案。读完本文你将能够把 tsParticles 的包目录、选项结构和插件依赖知识开放给任意 AI 助手用自然语言生成可直接运行的粒子配置并让 AI 自动推断所需的 npm 包与 import 语句。一、这个 MCP 服务器解决了什么问题tsParticles 采用模块化架构引擎 engine 本身不含任何形状绘制器、运动系统和更新器所有能力都以独立 npm 包形式按需加载。这带来一个实际痛点当用户给出一个需求彩纸雨烟花带鼠标连接的粒子背景时人需要手动确定该装哪个 bundle、再补装哪些散包、加载哪些 load 函数。tsparticles/mcp-server就是为消除这一心智负担而生的官方 MCP 服务器详见 integrations/mcp-server/README.md让 AI 助手检索 tsParticles 的完整包目录按分类、按关键词给定一个 options 配置对象推断需要安装哪些插件、交互、更新器、形状包以及对应的 import 语句从自然语言描述直接生成 tsParticles 配置并给出推荐 bundle 与完整使用代码额外提供配置诊断能力定位粒子不可见、交互失效、结构错误、性能隐患等常见问题。服务器基于官方 MCP SDKmodelcontextprotocol/sdk与zod构建以tsparticles/mcp-server发布当前仓库中版本为 4.3.3见 integrations/mcp-server/package.json。二、本地快速开始stdio 模式MCP 服务器默认运行在 stdio 上意味着它作为子进程被 MCP 客户端拉起通过标准输入输出进行 JSON-RPC 通信无需任何网络端口npx tsparticles/mcp-server一个命令即可启动随后可接入任意兼容 MCP 的客户端例如 Claude Desktop、Cursor、VS Code 的 GitHub Copilot Chat以及任何自定义 MCP 客户端。Claude Desktop 配置示例在 Claude Desktop 的配置文件claude_desktop_config.json中添加如下条目{ mcpServers: { tsparticles: { command: npx, args: [tsparticles/mcp-server] } } }保存后重启客户端即可在对话中直接使用本服务器的工具与资源。从源码运行如果希望直接基于仓库运行而非通过 npx可先构建再以 stdio 模式启动仓库使用 pnpm 工作区pnpm install pnpm run build pnpm run start # stdio 模式 pnpm run start:http # HTTP 模式监听 3000 端口三、核心能力一览Tools、Resources、PromptsMCP 协议定义了三种能力维度本服务器三种全部实现。入口文件 integrations/mcp-server/src/index.ts 中通过capabilities: { tools: {}, resources: {}, prompts: {} }声明并通过createMcpServer()工厂函数为每条传输通道创建独立的Server实例。3.1 Tools工具服务器暴露了 4 个工具README 中记录了前 3 个第 4 个diagnose_issues在源码 integrations/mcp-server/src/index.ts 中同样注册并对外可用工具说明suggest_plugins给定一个 tsParticles options 对象返回所需的 npm 包与 import 语句list_packages列出可用包可按分类或关键词过滤get_package_info返回某个具体包的详细信息diagnose_issues分析 options 的常见配置问题返回带严重级别与修复建议的清单所有工具入参都经过 zod schema 运行时校验见 integrations/mcp-server/src/validation.ts参数不合法时返回格式化的 ZodError 文本并以isError: true标记异常不会击穿传输层。suggest_plugins从配置反推依赖这是最核心的工具。传入options对象后suggestPlugins.ts 会遍历optionToPlugin映射表凡是已启用的选项路径就记下对应包解析particles.shape.type与particles.shape.options的键名推断形状包如shape.options.image→tsparticles/shape-image解析particles.effect匹配tsparticles/effect-*效果包处理emitters支持单对象或数组两种写法内部用asArray归一化推断发射器形状包无匹配形状时回退到tsparticles/plugin-emitters-shape-circle解析interactivity配置的每个 mode映射到tsparticles/interaction-external-*等交互包只要存在interactivity配置就无条件补充tsparticles/plugin-interactivity若配置了emitters/absorbers补充对应插件包依据特征包是否全部命中按优先级匹配最合适的 bundletsparticles/all→tsparticles→tsparticles/slim→tsparticles/basic。返回结果结构为{ npmPackages: [tsparticles/plugin-emitters, tsparticles/shape-heart, ...], imports: [ { function: loadEmittersPlugin, from: tsparticles/plugin-emitters } ], suggestedBundle: tsparticles, alreadyInBundle: [tsparticles/plugin-emitters] }其中suggestedBundle表示这些包基本都能由某个 bundle 覆盖alreadyInBundle列出已内含于该 bundle 的包方便你直接loadFull(engine)之类的加载方式。list_packages按分类或关键词检索支持两个可选参数category与query见 listPackages.ts。可用的分类枚举为bundle、plugin、interaction-external、interaction-particles、interaction-light、updater、shape、effect、path、emitter-shape、color、easing、preset。query会同时匹配包名与描述不区分大小写。返回按包名字母序排列并附带total与全部categories列表。实现上始终从包目录复制出新数组再排序避免对共享内存目录的原地修改单进程多会话并发时尤为重要。get_package_info查看单个包的完整档案传入package名称如tsparticles/plugin-absorbers返回分类、描述、加载函数loadFunction、相关的optionKeys、relatedOptions触发该包的配置路径及说明、includedInBundles所有包含它的 bundle因为一个包可同时属于多个 bundle、以及当查询对象本身是 bundle 时的subPackages清单见 getPackageInfo.ts。包不存在时返回明确的错误提示并引导使用list_packages查看全量。diagnose_issues配置体检该工具在 diagnoseIssues.ts 中实现了丰富的静态检查输出按error/warning/info分级、带title、description、fix与relatedPackages的清单。可以诊断的问题包括引擎未加载任何插件仅配置了粒子选项但未加载 bundle 或散包提示至少加载tsparticles/basic粒子不可见particles.opacity.value为 0 且未开启动画、particles.size.value为 0 且无动画缺少运动/颜色/形状插件配置了particles.move但未加载tsparticles/plugin-move使用#RRGGBB颜色但未加载tsparticles/plugin-hex-colorshape.type指向tsparticles/shape-*但未加载或形状名拼写错误交互失效存在interactivity但未加载tsparticles/plugin-interactivity某个 mode 未加载对应交互包配置了particles.links但未加载 links 交互包其他插件缺口emitters、absorbers、backgroundMask、发射器形状等未加载对应包结构与性能particles结构异常不包含任何已知键、粒子数过少 30会显得稀疏、粒子数过多 1000性能警告、fullScreen未开启可能导致画布高度为 0、使用了preset但需确认 preset 包已加载等。3.2 Resources资源服务器提供 3 个只读 Markdown 资源在 index.ts 中注册MIME 类型均为text/markdownURI说明tsparticles://packages完整包目录按分类组织含描述、加载函数与所属 bundletsparticles://options/guidetsParticles 选项结构参考含表格、默认值与示例tsparticles://bundlesbundle 层级与选择建议含使用示例AI 助手可以在生成配置前先读取这些资源从而获得与最新仓库一致的选项结构与包目录包目录本身来自 integrations/mcp-server/src/registry/packages.ts例如interaction-external类目下记录了 attract、bounce、bubble、cannon、connect、destroy、drag、grab、parallax、particle、pause、pop、push、remove、repulse、slow、trail 等包的加载函数与所属 bundle。3.3 Prompts提示词模板服务器暴露唯一一个 Promptgenerate-options参数description必填自然语言描述想要的效果。该 Prompt 仅携带元数据名称、描述、参数真正的系统指引文本存放在 generateOptions.ts 的generateOptionsSystemText中由prompts/get处理器在请求时拼接进单条 user 消息MCP 规范的消息角色只允许user与assistant因此系统指引被折叠进 user 消息首部。generate-options内置的生成规则包括分析请求识别颜色、形状、运动、交互、效果等关键要素善用工具链用list_packages按分类发现包用get_package_info理解具体包生成 options 后用suggest_plugins获取所需 npm 包并读取三个资源以了解选项结构与 bundle 建议bundle 推荐规则简单圆形 基础运动 →tsparticles/basic需要交互hover/click 连线 多种形状 →tsparticles/slim需要发射器/吸收器 更多效果 →tsparticles全部能力 →tsparticles/all彩纸 →tsparticles/confetti烟花 →tsparticles/fireworks轻量粒子 →tsparticles/particles输出格式返回 JSON 对象包含options有效的ISourceOptions、usageengine恒为tsparticles/engine、推荐bundles、imports数组、additionalPackages、html容器与完整code示例关键约束particles.shape.type默认circle非必要不写particles.move.enable默认开启除非用户要求透明背景否则始终包含background.color合适时优先使用preset。四、远程 HTTP 部署stdio 模式只能由本地 MCP 客户端拉起若要提供远程服务可让服务器以 HTTP 端点运行供任何支持 SSE 的 MCP 客户端访问。注意 MCP 端点固定在/mcp路径健康检查端点为/health。安全提示务必阅读HTTP 传输默认没有任何认证设计上仅用于 localhost / 可信网络。如果通过隧道、反向代理、端口转发等方式暴露到外部必须设置认证 token见下文。否则任何能触达该端点的人都能调用所有工具。4.1 认证配置设置 bearer token 后每次对/mcp的请求都必须携带Authorization: Bearer token# 方式一CLI 参数注意 token 会出现在 shell 历史与进程列表中 npx tsparticles/mcp-server --port 3000 --auth-token $(openssl rand -hex 32) # 方式二环境变量推荐避免 token 进入 shell 历史 MCP_AUTH_TOKEN$(openssl rand -hex 32) npx tsparticles/mcp-server --port 3000源码中的优先级为 CLI 参数优先于环境变量index.ts 只会在未传--auth-token时读取MCP_AUTH_TOKEN。认证校验在 http/security.ts 中实现token 提取使用Bearer前缀正则比对使用 Node 的timingSafeEqual做恒定时间比较避免通过响应时间差逐字节爆破 token。若未设置任何 token服务器启动时会在 stderr 打印一条 WARNING见 http/server.ts并回退到仅允许本地来源localhost/127.0.0.1的 Origin 策略——但该 Origin 检查只对浏览器发起的请求有意义非浏览器客户端curl、绝大多数 MCP 客户端根本不发送 Origin 头所以它不是认证的替代品。4.2 限流与会话保护服务器内置基础的内存级每 IP 限流与会话上限相关常量集中在 http/constants.ts项默认值每 IP 请求限流120 次 / 60 秒窗口最大并发 HTTP 会话500请求体上限1 MB会话空闲超时30 分钟每 5 分钟清扫一次HTTP 请求/头/保活超时30s / 15s / 5s限流在认证与 Origin 检查之前执行返回 429 Retry-After防止用请求洪泛暴力破解 token 或耗尽会话表当请求经过可信反向代理时会读取X-Forwarded-For首值作为真实客户端 IPtrustedProxies配置见 http/types.ts。会话通过mcp-session-id头管理支持 GET建立 SSE 流、POST发送消息 / 初始化、DELETE显式终止会话三种方法收到 SIGTERM/SIGINT 时优雅关闭所有会话与 HTTP 服务器。README 同时明确这些只是保护 Node 进程本身的机制公开暴露时仍应在反向代理或 CDN 层做真正的限流。4.3 五种部署方式方式一直接暴露端口无隧道# 在 3000 端口启动 npx tsparticles/mcp-server --port 3000 # 健康检查http://localhost:3000/health # MCP 端点 http://localhost:3000/mcp方式二Docker官方预构建镜像无需本地构建直接从 Docker Hub 拉取运行docker run -d -p 3000:3000 tsparticles/mcp-server固定版本时使用 tag例如 v4.3.1docker run -d -p 3000:3000 tsparticles/mcp-server:v4.3.1带认证 token 运行docker run -d -p 3000:3000 -e MCP_AUTH_TOKEN$(openssl rand -hex 32) tsparticles/mcp-server镜像内部细节可参考 Dockerfile基于node:24-alpine多阶段构建仅安装本包依赖运行时以非 root 用户appuid/gid 1001执行使用tini作为 init 进程并内置/health健康检查30s 间隔、5s 启动宽限、失败 3 次判定不健康。方式三Docker Compose从源码构建# 构建并启动 docker compose up -d # 或启用 Cloudflare Tunnel 配置临时公共 HTTPS 访问 docker compose --profile tunnel upCompose 配置见 docker-compose.ymlmcp-server服务通过SERVER_PORT环境变量默认 3000映射端口MCP_AUTH_TOKEN从环境或同目录.env文件读取参考.env.example并做了容器加固——no-new-privileges、丢弃全部 Linux capabilities、只读根文件系统 /tmptmpfs。cloudflared服务位于tunnelprofile 下默认启动后会打印一个临时 URL形如https://random.trycloudflare.com将 MCP 客户端端点配置为https://random.trycloudflare.com/mcp即可连接。若容器可被本机之外访问隧道/反向代理场景启动前务必设置MCP_AUTH_TOKEN。方式四Docker Synology 反向代理在 Synology NAS 上构建并启动容器docker compose up -d在 DSM 的控制面板 应用程序门户 反向代理中新增规则字段值来源协议HTTPS来源主机名your-nas-domain.example.com来源端口8443启用 HSTS是目标协议HTTP目标主机名localhost目标端口3000将 MCP 客户端端点配置为https://your-nas-domain.example.com:8443/mcp。方式五Docker Cloudflare Tunnel永久域名若想获得固定域名而非随机的trycloudflare.com安装并登录cloudflareddocker run cloudflare/cloudflared tunnel login创建隧道并绑定域名cloudflared tunnel create tsparticles-mcp cloudflared tunnel route dns tsparticles-mcp mcp.yourdomain.com创建配置文件# config.yml tunnel: tsparticles-mcp credentials-file: /root/.cloudflared/tunnel.json ingress: - hostname: mcp.yourdomain.com service: http://localhost:3000 - service: http_status:404启动docker compose up -d mcp-server cloudflared tunnel run tsparticles-mcp最终 MCP 端点为https://mcp.yourdomain.com/mcp。4.4 客户端端点配置要点连接远程 HTTP 服务器时统一使用带/mcp路径的端点 URLhttps://your-server.example.com/mcp若配置了认证 token需在客户端连接设置中将其作为 bearer token 一并发送。注意在浏览器来源场景下默认只放行 localhost / 127.0.0.1 的 Origin如需放行更多前端来源可使用 CLI 参数--allowed-origin接受完整 origin如http://localhost:3000可重复传入多个。五、CLI 参数速查服务器入口的完整参数解析逻辑位于 integrations/mcp-server/src/index.ts参数作用约束--stdio强制 stdio 模式默认与 HTTP 参数互斥--port n或--portn启用 HTTP 模式并指定端口必须是 1–65535 的整数--auth-token token或--auth-tokentoken设置 Bearer 认证 token仅 HTTP 模式可用--allowed-origin origin追加允许的浏览器来源可重复仅 HTTP 模式可用需完整 origin环境变量MCP_AUTH_TOKEN设置认证 tokenCLI 参数优先仅 HTTP 模式生效端口非法、--allowed-origin格式错误不是合法 http/https origin、含用户名密码等、或在 stdio 模式下混用 HTTP 参数都会打印错误并以退出码 1 终止。六、从源码构建与源码导航本地构建三件套pnpm install pnpm run build pnpm run start # stdio 模式 pnpm run start:http # HTTP 模式端口 3000仓库为 pnpm monorepo本模块位于integrations/mcp-server测试使用 vitestpnpm test涵盖工具逻辑、参数校验与 HTTP 安全层如diagnoseIssues.test.ts、getPackageInfo.test.ts、listPackages.test.ts、suggestPlugins.test.ts、security.test.ts、validation.test.ts。若想深入理解或二次开发推荐按以下路径阅读入口与注册integrations/mcp-server/src/index.tsCLI 解析、工具/资源/Prompt 注册、每会话独立 Server 实例HTTP 层integrations/mcp-server/src/http/server.ts健康检查、限流、认证、Origin 检查、会话生命周期与 integrations/mcp-server/src/http/security.ts恒定时间 token 比较、内存限流器工具实现integrations/mcp-server/src/tools/suggestPlugins / listPackages / getPackageInfo / diagnoseIssues包目录数据integrations/mcp-server/src/registry/packages.ts、bundles.ts、pluginOptions.ts、packageMaps.ts选项解析辅助integrations/mcp-server/src/utils/optionPath.ts点路径读取、asArray归一化 emitters/absorbers 的单对象或数组写法提示词系统文本integrations/mcp-server/src/prompts/generateOptions.ts容器化integrations/mcp-server/Dockerfile 与 integrations/mcp-server/docker-compose.yml七、典型工作流小结一个完整的 AI 辅助配置流程通常是AI 助手读取tsparticles://options/guide与tsparticles://packages了解可用的选项结构与包根据你的自然语言需求调用generate-options模板或自行拼装 options生成后用suggest_plugins反推所需 npm 包与 import再用diagnose_issues对配置做一次体检修正粒子不可见交互失效缺插件等问题最终产出tsparticles/engine 推荐 bundle 补充散包的完整安装与运行代码。本地开发用一行npx tsparticles/mcp-server团队共享则按需选择直连端口、Docker、Synology 反向代理或 Cloudflare Tunnel 部署并务必在公网暴露时启用MCP_AUTH_TOKEN。【免费下载链接】tsparticlestsParticles - Easily create highly customizable JavaScript particles effects, confetti explosions and fireworks animations and use them as animated backgrounds for your website. Ready to use components available for React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Solid, Riot and Web Components.项目地址: https://gitcode.com/GitHub_Trending/ts/tsparticles创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考