@magnolia/mgnl-ds-mcp-server 1.0.0

package/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2026 Magnolia International Ltd.
+(http://www.magnolia-cms.com). All rights reserved.
+
+
+The software is dual-licensed under both the Magnolia
+Network Agreement and the GNU General Public License.
+You may elect to use one or the other of these licenses.
+
+The software is distributed in the hope that it will be
+useful, but AS-IS and WITHOUT ANY WARRANTY; without even the
+implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE, TITLE, or NONINFRINGEMENT.
+Redistribution, except as permitted by whichever of the GPL
+or MNA you select, is prohibited.
+
+1. For the GPL license (GPL), you can redistribute and/or
+modify this file under the terms of the GNU General
+Public License, Version 3, as published by the Free Software
+Foundation.  You should have received a copy of the GNU
+General Public License, Version 3 along with this program;
+if not, write to the Free Software Foundation, Inc., 51
+Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+
+2. For the Magnolia Network Agreement (MNA), this file
+and the accompanying materials are made available under the
+terms of the MNA which accompanies this distribution, and
+is available at http://www.magnolia-cms.com/mna.html

package/README.md

@@ -0,0 +1,42 @@
+# Magnolia DS — Storybook MCP server
+
+An [MCP](https://modelcontextprotocol.io/) server that exposes the [Magnolia Design System Storybook](https://ds.magnolia-cloud.com) to AI agents, so they build UI with **real** components, props, and usage instead of guessing. It runs locally via `npx` — your MCP client spawns it over stdio; there’s nothing to host.
+
+It reuses the documentation tools from [`@storybook/mcp`](https://www.npmjs.com/package/@storybook/mcp) and points them at **published** manifests (`components.json` / `docs.json`) over HTTPS. So it holds **no state**, needs **no credentials**, and can never drift from what’s live.
+
+## Install
+
+Claude Code:
+
+```bash
+claude mcp add magnolia-ds -- npx -y @magnolia/mgnl-ds-mcp-server
+```
+
+Cursor / VS Code / other clients — add to the `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "magnolia-ds": {
+      "command": "npx",
+      "args": ["-y", "@magnolia/mgnl-ds-mcp-server"]
+    }
+  }
+}
+```
+
+That’s it. `npx` fetches the latest published version on each launch, the client manages the process over stdio, and the server reads the live manifests.
+
+## MCP Tools
+
+- `list-all-documentation` — list every component and docs entry (IDs + summaries).
+- `get-documentation` — full docs for one component/entry (props, stories, code snippets).
+- `get-documentation-for-story` — docs for a specific story variant.
+
+Try it: ask your agent _"using the Magnolia design system, render a loading Button"_.
+
+## Configuration
+
+| Setting                     | env              | default                                         |
+| --------------------------- | ---------------- | ----------------------------------------------- |
+| manifests base (URL or dir) | `MANIFESTS_PATH` | `https://ds.magnolia-cloud.com/react/manifests` |

package/bin/mcp.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { McpServer } from 'tmcp';
+import { ValibotJsonSchemaAdapter } from '@tmcp/adapter-valibot';
+import { StdioTransport } from '@tmcp/transport-stdio';
+import {
+  STORYBOOK_MCP_INSTRUCTIONS,
+  addListAllDocumentationTool,
+  addGetStoryDocumentationTool,
+  addGetDocumentationTool,
+} from '@storybook/mcp';
+import { createManifestProvider } from '../src/manifests.mjs';
+
+const manifestsPath =
+  process.env.MANIFESTS_PATH ?? 'https://ds.magnolia-cloud.com/react/manifests';
+
+const pkg = JSON.parse(
+  await readFile(new URL('../package.json', import.meta.url), 'utf8'),
+);
+
+// Mirrors @storybook/mcp's createStorybookMcpHandler server construction.
+const server = new McpServer(
+  {
+    name: 'magnolia-ds',
+    version: pkg.version,
+    description: 'Magnolia Design System Storybook documentation',
+  },
+  {
+    adapter: new ValibotJsonSchemaAdapter(),
+    instructions: STORYBOOK_MCP_INSTRUCTIONS,
+    capabilities: { tools: { listChanged: true } },
+  },
+).withContext();
+
+await addListAllDocumentationTool(server);
+await addGetStoryDocumentationTool(server);
+await addGetDocumentationTool(server);
+
+new StdioTransport(server).listen({
+  manifestProvider: createManifestProvider(manifestsPath),
+});

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@magnolia/mgnl-ds-mcp-server",
+  "version": "1.0.0",
+  "description": "Magnolia Design System Storybook MCP server to be run locally via npx so AI agents build UI with real components.",
+  "author": "Magnolia International",
+  "license": "See license in LICENSE.txt",
+  "private": false,
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "ssh://git@gitlab.magnolia-platform.com:9022/ds/mgnl-ds-mcp-server.git"
+  },
+  "bin": {
+    "mgnl-ds-mcp-server": "./bin/mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "src/manifests.mjs",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/mcp.mjs",
+    "lint": "eslint . && prettier --check .",
+    "lint:prettier": "prettier . -w",
+    "test": "vitest run",
+    "test:integration": "cross-env RUN_INTEGRATION=1 vitest run",
+    "release": "semantic-release"
+  },
+  "release": {
+    "branches": [
+      "main"
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "conventionalcommits"
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "conventionalcommits"
+        }
+      ],
+      "@semantic-release/changelog",
+      [
+        "@semantic-release/npm",
+        {
+          "npmPublish": true
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "package.json",
+            "CHANGELOG.md"
+          ]
+        }
+      ]
+    ],
+    "tagFormat": "${version}"
+  },
+  "dependencies": {
+    "@storybook/mcp": "^0.7.0",
+    "@tmcp/adapter-valibot": "^0.1.6",
+    "@tmcp/transport-stdio": "^0.4.3",
+    "tmcp": "^1.19.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "cross-env": "^10.1.0",
+    "eslint": "^10.6.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "globals": "^17.7.0",
+    "prettier": "^3.9.4",
+    "semantic-release": "^25.0.5",
+    "vitest": "^4.1.9"
+  }
+}

package/src/manifests.mjs

@@ -0,0 +1,26 @@
+// Manifest provider for the Magnolia DS Storybook MCP server.
+//
+// `@storybook/mcp` is a LIBRARY (no CLI). Its tools read the Storybook manifests (`components.json` / `docs.json`) through a `manifestProvider` we supply via the server context. This builds that provider for two sources, picked from `manifestsPath`:
+// - a remote base URL (e.g. https://ds.magnolia-cloud.com/react/manifests) — the default: it `fetch`es the already-public manifests, so it needs no credentials and can never drift from what's deployed.
+// - a local directory — handy for testing against `storybook-static/manifests`.
+import { readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+
+export function createManifestProvider(manifestsPath) {
+  const base = manifestsPath.replace(/\/+$/, ''); // no trailing slash → no `//file.json`
+  const isRemote = base.startsWith('http://') || base.startsWith('https://');
+
+  return async (_request, path) => {
+    const fileName = basename(path);
+    if (isRemote) {
+      const res = await fetch(`${base}/${fileName}`);
+      if (!res.ok) {
+        throw new Error(
+          `Failed to fetch manifest ${base}/${fileName}: ${res.status} ${res.statusText}`,
+        );
+      }
+      return await res.text();
+    }
+    return await readFile(resolve(base, fileName), 'utf-8');
+  };
+}