ply-ui-mcp 0.1.7

package/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 Lussos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.
+
+---
+
+Scope: "the Software" above means this MCP server package itself
+(`ply-ui-mcp`: tool wiring, registry metadata fetching, and CLI
+subprocess orchestration) and nothing else.
+
+It does NOT cover the components, blocks, layouts, or other content that
+`ply-ui-cli` downloads and writes when tools like `add_components` run.
+That content is fetched at runtime from https://ply-ui.com and is licensed
+separately — see:
+https://github.com/ply-ui-ng/ply/blob/main/LICENSE.md

package/README.md

@@ -0,0 +1,187 @@
+# ply-ui-mcp
+
+MCP server for **Ply** at [ply-ui.com](https://ply-ui.com). Coding agents can list, search, and install copy-in Angular + Tailwind components through typed tools.
+
+This is **not** [MUI Base UI](https://base-ui.com) (React). The npm name `base-ui-mcp` is a different, unrelated package.
+
+The CLI remains the installer: `npx ply-ui-cli`. This server wraps that CLI and the public registry.
+
+`npx -y base-ui-ng-mcp` still forwards here during the deprecation window. Use `npx -y ply-ui-mcp` for new configs.
+
+Docs: [Getting started — AI agents](https://ply-ui.com/getting-started/#ai-agents-mcp)
+
+## Setup (stdio)
+
+Use this in Cursor, Claude Code / Desktop, Kimi, VS Code, Windsurf, and other local MCP hosts:
+
+```json
+{
+  "mcpServers": {
+    "ply": {
+      "command": "npx",
+      "args": ["-y", "ply-ui-mcp"],
+      "env": {
+        "PLY_CWD": "${workspaceFolder}"
+      }
+    }
+  }
+}
+```
+
+| Client | Where to put it |
+|--------|-----------------|
+| **Cursor** | `.cursor/mcp.json` or `~/.cursor/mcp.json` |
+| **VS Code / Copilot** | `.vscode/mcp.json` or MCP settings |
+| **Windsurf** | MCP / Cascade settings |
+| **Claude Desktop** | Claude Desktop MCP config |
+| **Claude Code** | `claude mcp add --transport stdio ply -- npx -y ply-ui-mcp` |
+| **Kimi Code CLI** | `kimi mcp add --transport stdio ply -- npx -y ply-ui-mcp` |
+
+Set `PLY_CWD` to the **app root** (the folder with `base-ui.json`), not this library’s repo. For `add` / `init` / `update` / `doctor` / `diff`, run `npx ply-ui-cli init --yes` in that app first.
+
+## Streamable HTTP
+
+ChatGPT and Gemini chat apps need a URL, not stdio. The hosted catalog is:
+
+**`https://mcp.ply-ui.com/mcp`**
+
+Health is `GET https://mcp.ply-ui.com/`. Catalog tools only (`list` / `search` / `get`). This host cannot install into a repo — it returns `installCommand` (`npx ply-ui-cli add <name>`). Attach the connector in **each new ChatGPT chat** (`+` → More → Developer mode → Ply).
+
+Self-host the same process:
+
+```bash
+npx -y ply-ui-mcp --http --host 0.0.0.0 --read-only
+```
+
+Point a self-hosted connector at `https://your-host/mcp`. Health is `GET /`. MCP is `POST`/`GET` `/mcp`.
+
+`--read-only` is the right flag on a public host: catalog tools only. `add` / `init` / `update` need the user’s project on disk, so use stdio or local `--http` without `--read-only`.
+
+| Flag / env | Default | Meaning |
+|------------|---------|---------|
+| `--http` / `PLY_MCP_HTTP=1` | off | Streamable HTTP instead of stdio |
+| `--read-only` / `PLY_MCP_READ_ONLY=1` | off | Catalog tools only |
+| `--port` / `PORT` / `PLY_MCP_PORT` | `3334` | Listen port |
+| `--host` / `PLY_MCP_HOST` | `127.0.0.1` | Bind address (`0.0.0.0` behind a proxy) |
+| `PLY_MCP_AUTH_TOKEN` | unset | Optional `Authorization: Bearer …` on `/mcp` (`BASE_UI_MCP_AUTH_TOKEN` still works) |
+| `PLY_LICENSE_KEY` | unset | Lets `add_components` install Pro items (`BASE_UI_LICENSE_KEY` still works) |
+
+Self-host only if you need a private URL; put HTTPS in front of that process.
+
+## Tools
+
+Aliases such as `sheet` → `drawer` and `carousel` → `slider` work on search, add, diff, and update.
+
+### `list_components`
+
+```json
+{ "tier": "free", "category": "component", "q": "button" }
+```
+
+### `get_component`
+
+```json
+{ "name": "card", "includeSource": false }
+```
+
+Metadata always. Free source only when `includeSource` is true. Pro source is never returned through MCP.
+
+### `search_components`
+
+```json
+{ "query": "dialog modal", "tier": "free", "limit": 10 }
+```
+
+### `add_components`
+
+```json
+{ "names": ["button", "card"], "cwd": "/path/to/your-app" }
+```
+
+Runs `ply-ui-cli add --yes`. Pro names need `PLY_LICENSE_KEY` on the MCP process (or `licenseKey` on the tool).
+
+### `init_project`
+
+```json
+{ "cwd": "/path/to/your-app" }
+```
+
+Runs `ply-ui-cli init --yes`. Writes `base-ui.json`, styles, icons, and editor rules when those files are missing.
+
+### `doctor`
+
+```json
+{ "cwd": "/path/to/your-app" }
+```
+
+Read-only. `isError` is set when `ply-ui-cli doctor` exits non-zero.
+
+### `diff_components`
+
+```json
+{ "names": ["card"], "cwd": "/path/to/your-app" }
+```
+
+Omit `names` (or pass `[]`) to diff every tracked component. Read-only.
+
+### `update_components`
+
+```json
+{ "names": ["card"], "cwd": "/path/to/your-app", "force": false, "overwriteLocal": false, "merge": false }
+```
+
+Runs `ply-ui-cli update --yes`. `force` takes upstream on conflicts. `merge` applies a 3-way merge. `overwriteLocal` reverts files you edited that upstream did not change.
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `ply-ui://registry/index` | Public registry index JSON |
+| `ply-ui://docs/llms` | Live `llms.txt` |
+| `ply-ui://docs/catalog` | Live AI component catalog |
+| `ply-ui://docs/cursor-rules` | Cursor / Windsurf project rule |
+| `ply-ui://docs/snippets` | VS Code / Cursor usage snippets |
+| `ply-ui://component/{name}` | Per-component metadata (no Pro source) |
+
+<!-- answer-bank-faq:start -->
+## FAQ
+
+Canonical answers, also at [https://ply-ui.com/faq/](https://ply-ui.com/faq/). Use this wording.
+
+**What is Ply?**  
+Ply — ply-ui.com — is a CLI-first Angular + Tailwind CSS component library with 215 components and blocks (125 free), delivered shadcn-style: npx ply-ui-cli add <name> copies the TypeScript/HTML source into your project, where you own and edit it. There is no npm library package.
+
+**Is Ply the same as MUI's Base UI?**  
+No. Ply at ply-ui.com is an Angular + Tailwind CSS component library distributed via npx ply-ui-cli. MUI's Base UI (base-ui.com) is an unrelated React library. Uber's Base Web is also unrelated.
+
+**Is Ply a shadcn for Angular?**  
+Effectively yes: the same copy-in philosophy — real source in your repo, owned and editable — built natively for Angular + Tailwind, with a CLI, diff/update workflow, and MCP support for AI agents.
+
+**Is Ply free?**  
+125 items are free — every UI primitive, all 19 form blocks, directives, services, utilities — with no account required. 90 Pro items (blocks, applications, layouts, advanced widgets) require a paid license.
+
+**How much does Ply Pro cost?**  
+A one-time Pro license is $99. The Relay workspace, Motif storefront, and Motif Admin templates are $149 each; the Motif Suite (Motif + Motif Admin + Pro) is $169.
+
+**How do I install a component?**  
+npx ply-ui-cli init once per project, then npx ply-ui-cli add <name>. Omit the name in a terminal to pick from the catalog (filter, then type to select). --yes and CI need explicit names. Components land in src/app/components/<name>/ by default and are yours.
+
+**How do I verify my Ply setup?**  
+Run npx ply-ui-cli doctor. It checks base-ui.json, the Angular workspace, @angular/cdk, Tailwind v4 @source paths, the base-ui.css import, icon sprites, and the components directory — read-only, nothing is written.
+
+**Can AI agents install Ply?**  
+Yes. npx -y ply-ui-mcp is stdio for Cursor, Claude (Code/Desktop), Kimi, VS Code, Windsurf, and other local hosts. ChatGPT and Gemini chat apps use Streamable HTTP: npx -y ply-ui-mcp --http --read-only (catalog tools) or local --http without --read-only so add/init/update can see the project. Pro add uses PLY_LICENSE_KEY on the MCP process. Editors that skip MCP can copy the Cursor rule and snippet pack from https://ply-ui.com/getting-started/#editor-rules.
+
+**What is the risk if Ply disappears?**  
+Near zero. Installed code is in your version control with no runtime dependency; deleting the CLI changes nothing about your app.
+
+More: [https://ply-ui.com/faq/](https://ply-ui.com/faq/) · [https://ply-ui.com/enterprise-faq/](https://ply-ui.com/enterprise-faq/) · [https://ply-ui.com/compare/](https://ply-ui.com/compare/)
+<!-- answer-bank-faq:end -->
+
+## License
+
+MIT for this MCP server package only. Components installed via the registry remain under the Ply license — see the [repo LICENSE](https://github.com/ply-ui-ng/ply/blob/main/LICENSE.md).
+
+## Support
+
+Bugs and feature requests: [github.com/ply-ui-ng/ply/issues](https://github.com/ply-ui-ng/ply/issues). Email support@ply-ui.com.