{"_id":"@tsparticles/mcp-server","_rev":"26-38d75c8a3eb47f829b85e94c11ef7963","name":"@tsparticles/mcp-server","dist-tags":{"latest":"4.6.0"},"versions":{"4.5.4":{"name":"@tsparticles/mcp-server","version":"4.5.4","keywords":["tsparticles","mcp","model-context-protocol","ai","llm","particles"],"author":{"name":"Matteo Bruni"},"license":"MIT","_id":"@tsparticles/mcp-server@4.5.4","maintainers":[{"name":"matteobruni","email":"ar3s@icloud.com"}],"homepage":"https://particles.js.org","bugs":{"url":"https://github.com/tsparticles/tsparticles/issues"},"bin":{"tsparticles-mcp":"dist/index.js"},"dist":{"shasum":"c955b329830e9e572efecb0087b03f408d8d4ddc","tarball":"https://registry.npmjs.org/@tsparticles/mcp-server/-/mcp-server-4.5.4.tgz","fileCount":75,"integrity":"sha512-UFp7jwU6e1RJoJATFGV6GQrK78t9V0z/r97rGkDjd831qsKiALvO/Kgf6zp8FBp5eFF6r7l70r4No0t+csA5Gg==","signatures":[{"sig":"MEYCIQDuqckvZDjNwAgPYnFVfukF75tEJogQ4NJTpnwiP2JuzQIhAK4JZ9m361B4HQ+4/L8PmXpdSrq8Wv08rW9qIS4IQ+51","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEUCIC2Q7IgudFsoJZEiiIayTUPUOTYlkBbBzrGHnvFT3rPUAiEAij4NWxwXA7VJGZ2qDbM/bJIapZ2JE+hMAlBfIpK4Puw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@tsparticles%2fmcp-server@4.5.4","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":424725},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","gitHead":"5e64940e7c1e1c02c6bcc62bdd011590e1fb171f","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .js,.jsx,.ts,.tsx --fix","test":"vitest run","build":"tsc --project tsconfig.build.json","start":"node dist/index.js","lint:ci":"eslint src --ext .js,.jsx,.ts,.tsx","prepack":"pnpm run build","start:http":"node dist/index.js --port 3000","test:watch":"vitest"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"27f346c4-8091-4e1c-af1d-1dba07c5d5be"}},"prettier":"@tsparticles/prettier-config","repository":{"url":"git+https://github.com/tsparticles/tsparticles.git","type":"git","directory":"integrations/mcp-server"},"_npmVersion":"lerna/10.1.2/node@v26.13.0+x64 (linux)","description":"MCP server for tsParticles - generate options from natural language and suggest required plugins","directories":{},"_nodeVersion":"26.13.0","dependencies":{"zod":"^4.6.7","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.14.0","vitest":"^5.1.0","typescript":"^6.0.3","@types/node":"^26.6.6","@tsparticles/eslint-config":"4.5.4"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_4.5.4_1794390364453_0.7033372072287465","host":"s3://npm-registry-packages-npm-production"}},"4.6.0":{"_id":"@tsparticles/mcp-server@4.6.0","bin":{"tsparticles-mcp":"dist/index.js"},"bugs":{"url":"https://github.com/tsparticles/tsparticles/issues"},"dist":{"shasum":"b63580e2ccf809b74b64b3973b4de3017f2692a8","tarball":"https://registry.npmjs.org/@tsparticles/mcp-server/-/mcp-server-4.6.0.tgz","fileCount":75,"integrity":"sha512-k+HD6uWpuokVs1JPPNc91WTb7FubkXxnm6mAeDwRrrKH5bQO5+OsntG3TZxeQwPylGVJJZvUEi9En7DpSTrENQ==","signatures":[{"sig":"MEYCIQC691XaZIha8rd2Zf79D4eB8AQlGuvgEO6UPL/HmjS9ZAIhALeMQSgGrhLI3+YkfWs99opBuqc8DszzRL4iQE7leaOs","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHcBZPB/FQh61dOgiBvYcYFm1LYuCzKsOJtPUswj4RUKAiEA0jK+6FxwevEjUA5xMCPZt5YzfRncoYpdFpmeILrSbCI="}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@tsparticles%2fmcp-server@4.6.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":425094},"main":"./dist/index.js","name":"@tsparticles/mcp-server","type":"module","types":"./dist/index.d.ts","author":{"name":"Matteo Bruni"},"gitHead":"8c572f3f979a0115f6ff489cbedecffd8dec68ef","license":"MIT","scripts":{"dev":"tsc --watch","lint":"eslint src --ext .js,.jsx,.ts,.tsx --fix","test":"vitest run","build":"tsc --project tsconfig.build.json","start":"node dist/index.js","lint:ci":"eslint src --ext .js,.jsx,.ts,.tsx","prepack":"pnpm run build","start:http":"node dist/index.js --port 3000","test:watch":"vitest"},"version":"4.6.0","_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"27f346c4-8091-4e1c-af1d-1dba07c5d5be"}},"homepage":"https://particles.js.org","keywords":["tsparticles","mcp","model-context-protocol","ai","llm","particles"],"prettier":"@tsparticles/prettier-config","repository":{"url":"git+https://github.com/tsparticles/tsparticles.git","type":"git","directory":"integrations/mcp-server"},"_npmVersion":"lerna/10.1.2/node@v26.13.1+x64 (linux)","description":"MCP server for tsParticles - generate options from natural language and suggest required plugins","directories":{},"maintainers":[{"name":"matteobruni","email":"ar3s@icloud.com"}],"_nodeVersion":"26.13.1","dependencies":{"zod":"^4.6.7","@modelcontextprotocol/sdk":"^1.32.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.14.0","vitest":"^5.1.0","typescript":"^6.0.3","@types/node":"^26.6.6","@tsparticles/eslint-config":"4.6.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_4.6.0_1794591761032_0.4103741093762262"}}},"time":{"created":"2026-06-06T18:06:33.793Z","modified":"2026-11-13T17:42:41.599Z","0.1.0":"2026-06-06T18:06:34.138Z","4.1.3":"2026-06-07T14:46:43.198Z","4.2.0":"2026-06-17T15:00:33.293Z","4.2.1":"2026-06-19T00:35:55.844Z","4.3.0":"2026-06-27T19:22:13.746Z","4.3.1":"2026-07-01T11:13:03.709Z","4.3.2":"2026-07-10T10:30:22.675Z","4.4.0":"2026-08-31T00:21:53.968Z","4.5.0":"2026-10-25T17:47:55.425Z","4.5.1":"2026-11-02T09:50:22.598Z","4.5.2":"2026-11-05T23:47:29.353Z","4.5.3":"2026-11-06T15:51:20.879Z","4.5.4":"2026-11-11T09:46:04.547Z","4.6.0":"2026-11-13T17:42:41.152Z"},"bugs":{"url":"https://github.com/tsparticles/tsparticles/issues"},"author":{"name":"Matteo Bruni"},"license":"MIT","homepage":"https://particles.js.org","keywords":["tsparticles","mcp","model-context-protocol","ai","llm","particles"],"repository":{"url":"git+https://github.com/tsparticles/tsparticles.git","type":"git","directory":"integrations/mcp-server"},"description":"MCP server for tsParticles - generate options from natural language and suggest required plugins","maintainers":[{"name":"matteobruni","email":"ar3s@icloud.com"}],"readme":"# @tsparticles/mcp-server\n\n[MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for [tsParticles](https://particles.js.org). Lets AI assistants inspect package catalogs, suggest required plugins and bundles from options, and generate tsParticles configurations from natural language.\n\n## Quick Start (local)\n\n```bash\nnpx @tsparticles/mcp-server\n```\n\nThe server runs on stdio and can be connected to any MCP-compatible client:\n\n- [Claude Desktop](https://claude.ai/download)\n- [Cursor](https://cursor.sh)\n- [VS Code with GitHub Copilot](https://code.visualstudio.com/docs/copilot/chat/mcp)\n- Any custom MCP client\n\n### Claude Desktop configuration\n\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"tsparticles\": {\n      \"command\": \"npx\",\n      \"args\": [\"@tsparticles/mcp-server\"]\n    }\n  }\n}\n```\n\n### Tools\n\n| Tool               | Description                                                                            |\n| ------------------ | -------------------------------------------------------------------------------------- |\n| `suggest_plugins`  | Given a tsParticles options object, returns the npm packages and imports needed        |\n| `list_packages`    | Lists available packages, optionally filtered by category or search query              |\n| `get_package_info` | Returns detailed info about a specific package                                         |\n| `diagnose_issues`  | Analyzes options for configuration problems and performance issues                     |\n| `generate_code`    | Generate complete code from a natural language description with smart bundle selection |\n\n### Resources\n\n| URI                           | Description                 |\n| ----------------------------- | --------------------------- |\n| `tsparticles://packages`      | Complete package catalog    |\n| `tsparticles://options/guide` | Options structure reference |\n| `tsparticles://bundles`       | Bundle selection guide      |\n\n### Prompt\n\n| Name               | Description                                                       |\n| ------------------ | ----------------------------------------------------------------- |\n| `generate-options` | Generates tsParticles options from a natural language description |\n\n## Deploy (remote HTTP)\n\nThe server can also run as an HTTP endpoint, accessible by any MCP client that supports SSE.\n\nHTTP mode binds to `127.0.0.1` by default. Binding to any other interface requires an auth token;\nstartup fails if a non-loopback host is configured without one. Use HTTPS at a trusted reverse\nproxy or tunnel when connecting over an untrusted network.\n\n### Authentication\n\nSet a bearer token to require `Authorization: Bearer <token>` on every request to `/mcp` when\nbinding beyond loopback:\n\n```bash\nexport MCP_AUTH_TOKEN=\"$(openssl rand -hex 32)\"\nnpx @tsparticles/mcp-server --port 3000 --host 0.0.0.0\n```\n\nThe CLI reads the exported `MCP_AUTH_TOKEN` automatically. Configure your MCP client to send the\nsame value in the `Authorization: Bearer <token>` header. The exported token remains available in\nyour shell for copying into the client configuration. On loopback, no token is required; origin\nchecks still restrict browser-originated requests, but are not authentication and do not protect\nnon-browser clients.\n\n### Rate limiting\n\nMCP traffic and unauthenticated requests have separate in-memory rate limits, so failed\nauthentication attempts cannot consume the MCP request budget. The server also limits each client\nIP to 10 sessions and caps the process at 500 sessions. These controls are process-local and do not\nreplace rate limiting at a reverse proxy or CDN.\n\nWhen running behind a reverse proxy, pass each proxy's IP with `--trusted-proxy <IP>` (repeat the\nflag for multiple hops) or set `MCP_TRUSTED_PROXIES` to a comma-separated list. The edge proxy must\noverwrite or append the connecting client IP to `X-Forwarded-For`; the server walks the trusted\nproxy chain from right to left to resolve the client address.\n\n### Option 1: Direct access (no tunnel)\n\n```bash\n# Start on port 3000 (loopback only)\nnpx @tsparticles/mcp-server --port 3000\n# Health check: http://localhost:3000/health\n# MCP endpoint:  http://localhost:3000/mcp\n```\n\n### Option 2: Docker (pre-built image)\n\nThe container listens on all interfaces, so provide a token:\n\n```bash\nexport MCP_AUTH_TOKEN=\"$(openssl rand -hex 32)\"\ndocker run -d -p 3000:3000 -e MCP_AUTH_TOKEN tsparticles/mcp-server\n```\n\n### Option 3: Docker Compose (build from source)\n\n```bash\n# Set a token, then build and start\nexport MCP_AUTH_TOKEN=\"$(openssl rand -hex 32)\"\ndocker compose up -d\n\n# Or with Cloudflare Tunnel for public HTTPS access\ndocker compose --profile tunnel up\n```\n\n`MCP_AUTH_TOKEN` is required by Compose because the container binds to all interfaces. Set it in\nyour environment or in a `.env` file next to `docker-compose.yml` before starting the server or\nthe tunnel. If all traffic arrives through a reverse proxy, set `MCP_TRUSTED_PROXIES` to the\ncomma-separated IP addresses of every trusted proxy hop so rate limits and session quotas use the\nreal client address. The edge proxy must overwrite or append the connecting client IP to\n`X-Forwarded-For`.\n\nThis prints a temporary URL like `https://random.trycloudflare.com`. Configure your MCP client with `https://random.trycloudflare.com/mcp` as the endpoint.\n\n### Option 4: Docker + Synology Reverse Proxy\n\nIf you have a Synology NAS:\n\n1. Build the image and start the container:\n\n```bash\ndocker compose up -d\n```\n\n2. On DSM, go to **Control Panel > Application Portal > Reverse Proxy** and add:\n\n| Field                | Value                       |\n| -------------------- | --------------------------- |\n| Source protocol      | HTTPS                       |\n| Source hostname      | your-nas-domain.example.com |\n| Source port          | 8443                        |\n| Enable HSTS          | yes                         |\n| Destination protocol | HTTP                        |\n| Destination hostname | localhost                   |\n| Destination port     | 3000                        |\n\n3. Configure your MCP client with `https://your-nas-domain.example.com:8443/mcp`.\n\n### Option 5: Docker + Cloudflare Tunnel (permanent)\n\nFor a permanent URL (instead of the random `trycloudflare.com`):\n\n1. Install `cloudflared` and log in:\n\n```bash\ndocker run cloudflare/cloudflared tunnel login\n```\n\n2. Create a tunnel and route your domain:\n\n```bash\ncloudflared tunnel create tsparticles-mcp\ncloudflared tunnel route dns tsparticles-mcp mcp.yourdomain.com\n```\n\n3. Create a config file:\n\n```yaml\n# config.yml\ntunnel: tsparticles-mcp\ncredentials-file: /root/.cloudflared/tunnel.json\ningress:\n  - hostname: mcp.yourdomain.com\n    service: http://localhost:3000\n  - service: http_status:404\n```\n\n4. Run:\n\n```bash\ndocker compose up -d mcp-server\ncloudflared tunnel run tsparticles-mcp\n```\n\nYour MCP endpoint will be `https://mcp.yourdomain.com/mcp`.\n\n## Client endpoint configuration\n\nWhen connecting to a remote HTTP server, use the endpoint URL with `/mcp` path:\n\n```\nhttps://your-server.example.com/mcp\n```\n\n## Build from source\n\n```bash\npnpm install\npnpm run build\npnpm run start        # stdio mode\npnpm run start:http   # HTTP mode on port 3000\n```\n","readmeFilename":"README.md"}