fix: ship one hosted mcp server in every plugin (#264)

Author: FrkAk

README.md

@@ -33,7 +33,7 @@ Then install the plugin for your agent (Claude Code, Codex, Cursor, or Antigravi
 
 ## Self-host
 
-Self-hosting is free under AGPL-3.0. You can run the Piyaz server yourself and point the plugin's `piyaz-local` server at it. You need [Bun](https://bun.sh) and [Docker](https://docs.docker.com/get-docker/) for PostgreSQL. Full setup and upgrade steps are in the [self-host guide](https://docs.piyaz.ai/docs/self-hosting/run-locally).
+Self-hosting is free under AGPL-3.0. You can run the Piyaz server yourself and register an MCP server in your editor that points at it. You need [Bun](https://bun.sh) and [Docker](https://docs.docker.com/get-docker/) for PostgreSQL. Full setup and upgrade steps are in the [self-host guide](https://docs.piyaz.ai/docs/self-hosting/run-locally).
 
 ---
 

components/home/GetStartedModal.tsx

@@ -50,31 +50,38 @@ const HOSTED_CLI_INSTALLS: readonly CliInstall[] = [
   },
 ];
 
+/**
+ * Every plugin ships one MCP server pointing at the hosted app. Each self-host
+ * note therefore registers a second server against the reader's own instance
+ * rather than editing the plugin's bundled config, which lives in a
+ * version-scoped cache the next plugin update overwrites.
+ */
 const SELF_HOST_CLI_INSTALLS: readonly CliInstall[] = [
   {
     name: "Claude Code",
     install:
-      "claude plugin marketplace add ./plugins/claude-code\nclaude plugin install piyaz@piyaz-local",
+      "claude plugin marketplace add ./plugins/claude-code\nclaude plugin install piyaz@piyaz-local\nclaude mcp add -s user --transport http piyaz-self-hosted http://localhost:3000/api/mcp",
     setupNote:
-      "Authenticate with /mcp, select piyaz-local, and complete the browser sign-in against http://localhost:3000.",
+      "Run /mcp, select piyaz-self-hosted, and complete the browser sign-in against your own instance.",
   },
   {
     name: "Codex",
-    install: "codex plugin marketplace add ./plugins",
+    install:
+      "codex plugin marketplace add ./plugins\ncodex mcp add piyaz-self-hosted --url http://localhost:3000/api/mcp",
     setupNote:
-      "Run /plugin, search for piyaz, install, then restart Codex. Select piyaz-local for http://localhost:3000/api/mcp.",
+      "Run /plugin, install Piyaz, restart Codex, then authenticate against piyaz-self-hosted.",
   },
   {
     name: "Antigravity",
     install: "cp -r ./plugins/antigravity ~/.gemini/config/plugins/piyaz",
     setupNote:
-      "Run /mcp, select piyaz-local, Authenticate, and complete the browser sign-in against http://localhost:3000.",
+      'Add {"piyaz-self-hosted": {"serverUrl": "http://localhost:3000/api/mcp"}} to mcpServers in ~/.gemini/config/mcp_config.json, then run /mcp and Authenticate.',
   },
   {
     name: "Cursor",
     install: 'ln -s "$(pwd)/plugins/cursor" ~/.cursor/plugins/local/piyaz',
     setupNote:
-      "Restart Cursor. The MCP server and skills load automatically; piyaz-local points at http://localhost:3000/api/mcp.",
+      'Add {"piyaz-self-hosted": {"url": "http://localhost:3000/api/mcp"}} to mcpServers in ~/.cursor/mcp.json, then restart Cursor.',
   },
 ];
 

plugins/antigravity/mcp_config.json

@@ -2,9 +2,6 @@
   "mcpServers": {
     "piyaz": {
       "serverUrl": "https://app.piyaz.ai/api/mcp"
-    },
-    "piyaz-local": {
-      "serverUrl": "http://localhost:3000/api/mcp"
     }
   }
 }

plugins/claude-code/.mcp.json

@@ -2,11 +2,7 @@
   "mcpServers": {
     "piyaz": {
       "type": "http",
-      "url": "${PIYAZ_URL:-https://app.piyaz.ai}/api/mcp"
-    },
-    "piyaz-local": {
-      "type": "http",
-      "url": "http://localhost:3000/api/mcp"
+      "url": "https://app.piyaz.ai/api/mcp"
     }
   }
 }

plugins/codex/.mcp.json

@@ -3,10 +3,6 @@
     "piyaz": {
       "type": "http",
       "url": "https://app.piyaz.ai/api/mcp"
-    },
-    "piyaz-local": {
-      "type": "http",
-      "url": "http://localhost:3000/api/mcp"
     }
   }
 }

plugins/cursor/mcp.json

@@ -2,9 +2,6 @@
   "mcpServers": {
     "piyaz": {
       "url": "https://app.piyaz.ai/api/mcp"
-    },
-    "piyaz-local": {
-      "url": "http://localhost:3000/api/mcp"
     }
   }
 }

tests/plugins/manifests.test.ts

@@ -54,14 +54,12 @@ test("Antigravity plugin marker exists and is named piyaz", () => {
   expect(p.name).toBe("piyaz");
 });
 
-test("Antigravity mcp_config uses serverUrl (never url/httpUrl) for both servers", () => {
+test("Antigravity mcp_config uses serverUrl (never url/httpUrl)", () => {
   const cfg = readJson("plugins/antigravity/mcp_config.json");
   const hosted = cfg.mcpServers.piyaz;
-  const local = cfg.mcpServers["piyaz-local"];
   expect(hosted.serverUrl).toContain("app.piyaz.ai");
   expect(hosted.url).toBeUndefined();
   expect(hosted.httpUrl).toBeUndefined();
-  expect(local.serverUrl).toContain("localhost:3000");
 });
 
 test("Antigravity bundles every shared skill", () => {
@@ -81,16 +79,19 @@ test("Antigravity bundles every shared skill", () => {
   }
 });
 
+/**
+ * Every brand ships exactly one MCP server, the hosted one. A bundled
+ * localhost server is dead config for hosted users and surfaces as a
+ * connection error against a server they never run.
+ */
 test.each([
   "plugins/claude-code/.mcp.json",
   "plugins/codex/.mcp.json",
   "plugins/cursor/mcp.json",
-])("%s declares hosted piyaz + local piyaz-local", (path) => {
+  "plugins/antigravity/mcp_config.json",
+])("%s declares exactly one hosted piyaz server", (path) => {
   const cfg = readJson(path);
-  expect(cfg.mcpServers.piyaz).toBeDefined();
-  expect(cfg.mcpServers["piyaz-local"]).toBeDefined();
+  expect(Object.keys(cfg.mcpServers)).toEqual(["piyaz"]);
   expect(JSON.stringify(cfg.mcpServers.piyaz)).toContain("app.piyaz.ai");
-  expect(JSON.stringify(cfg.mcpServers["piyaz-local"])).toContain(
-    "localhost:3000",
-  );
+  expect(JSON.stringify(cfg)).not.toContain("localhost");
 });