@efolusi/meridian-mcp 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +63 -0
  2. package/package.json +11 -0
  3. package/server.mjs +119 -0
package/README.md ADDED
@@ -0,0 +1,63 @@
1
+ # @efolusi/meridian-mcp
2
+
3
+ An [MCP](https://modelcontextprotocol.io) server that gives an AI coding agent
4
+ first-hand knowledge of the Meridian design system, so it builds correct Meridian
5
+ UI instead of guessing. It exposes the same generated registry the docs site uses.
6
+
7
+ ## Tools
8
+
9
+ | Tool | What it returns |
10
+ |---|---|
11
+ | `list_components` | Every UI component with a one-line description and categories. Optional `category` filter. |
12
+ | `get_component` | One component's full detail: description, Meridian dependencies, and each file's real content — the `.jsx` source, the `.d.ts` types, and the `.prompt.md` usage guide. |
13
+ | `search_components` | Components matching a keyword across name, title, description and category. |
14
+ | `get_tokens` | Design tokens (colour, typography, spacing, effects) in light, dark and compact. Optional `group` filter. |
15
+
16
+ ## Data source
17
+
18
+ No repository needed. By default the server reads the **hosted** registry, so it
19
+ works standalone:
20
+
21
+ - `MERIDIAN_SOURCE=https://meridian.efolusi.com` — the default.
22
+ - `MERIDIAN_SOURCE=/path/to/meridian` — a local checkout or a vendored copy, if
23
+ you prefer offline / pinned data.
24
+
25
+ ## Add it to your agent
26
+
27
+ It speaks stdio. Point your agent's MCP config at the command. Once published you
28
+ can use `npx`; from a checkout use `node /path/to/meridian/mcp/server.mjs`.
29
+
30
+ **Claude Code**
31
+
32
+ ```bash
33
+ claude mcp add meridian -- npx -y @efolusi/meridian-mcp
34
+ ```
35
+
36
+ **Claude Desktop / Cursor / any stdio MCP client** (`mcpServers` config):
37
+
38
+ ```json
39
+ {
40
+ "mcpServers": {
41
+ "meridian": {
42
+ "command": "npx",
43
+ "args": ["-y", "@efolusi/meridian-mcp"],
44
+ "env": { "MERIDIAN_SOURCE": "https://meridian.efolusi.com" }
45
+ }
46
+ }
47
+ }
48
+ ```
49
+
50
+ Then ask your agent things like *"list Meridian form components"*, *"show me the
51
+ DatePicker props and usage"*, or *"build an Efolusi settings page with Meridian"* —
52
+ it will pull the real source and tokens before writing code.
53
+
54
+ ## Run locally / develop
55
+
56
+ ```bash
57
+ cd mcp
58
+ npm install
59
+ MERIDIAN_SOURCE=.. node server.mjs # read the local registry
60
+ node smoke.mjs # quick end-to-end check of every tool
61
+ ```
62
+
63
+ MIT licensed.
package/package.json ADDED
@@ -0,0 +1,11 @@
1
+ {
2
+ "name": "@efolusi/meridian-mcp",
3
+ "version": "0.1.0",
4
+ "description": "MCP server exposing the Meridian design system registry (components, source, types, usage guides, tokens) to AI coding agents.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "bin": { "meridian-mcp": "./server.mjs" },
8
+ "files": ["server.mjs", "README.md"],
9
+ "dependencies": { "@modelcontextprotocol/sdk": "^1.0.0" },
10
+ "keywords": ["mcp", "meridian", "design-system", "efolusi"]
11
+ }
package/server.mjs ADDED
@@ -0,0 +1,119 @@
1
+ #!/usr/bin/env node
2
+ // Meridian MCP server — exposes the design system's registry to an AI coding
3
+ // agent so it can build correct Meridian UI without guessing: the component
4
+ // list, each component's real source / types / usage guide, and the tokens.
5
+ //
6
+ // Data source (no repo needed by default):
7
+ // MERIDIAN_SOURCE = https://meridian.efolusi.com (default — the hosted site)
8
+ // MERIDIAN_SOURCE = /path/to/meridian (a local checkout / vendored copy)
9
+ // Either way it reads the same generated files: site/registry.json, the
10
+ // per-component site/registry/<name>.json (source embedded), and tokens.json.
11
+ //
12
+ // Run: npx @efolusi/meridian-mcp (or: node server.mjs)
13
+ // Add it to your agent's MCP config as a stdio server pointing at this command.
14
+
15
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
16
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
17
+ import { z } from 'zod';
18
+ import fs from 'node:fs/promises';
19
+ import path from 'node:path';
20
+
21
+ const SOURCE = (process.env.MERIDIAN_SOURCE || 'https://meridian.efolusi.com').replace(/\/$/, '');
22
+ const isURL = /^https?:\/\//.test(SOURCE);
23
+
24
+ // Read a repo-relative JSON file from either the hosted site or a local checkout.
25
+ async function readJSON(rel) {
26
+ if (isURL) {
27
+ const res = await fetch(`${SOURCE}/${rel}`);
28
+ if (!res.ok) throw new Error(`${res.status} fetching ${rel}`);
29
+ return res.json();
30
+ }
31
+ return JSON.parse(await fs.readFile(path.join(SOURCE, rel), 'utf8'));
32
+ }
33
+
34
+ let _index = null;
35
+ async function index() {
36
+ if (!_index) _index = await readJSON('site/registry.json');
37
+ return _index;
38
+ }
39
+ // UI components only (the registry also carries blocks and starters).
40
+ async function components() {
41
+ return (await index()).items.filter((it) => it.type === 'registry:ui');
42
+ }
43
+ async function component(name) {
44
+ return readJSON(`site/registry/${String(name).toLowerCase()}.json`);
45
+ }
46
+
47
+ const server = new McpServer({ name: 'meridian', version: '0.1.0' });
48
+
49
+ server.registerTool(
50
+ 'list_components',
51
+ {
52
+ title: 'List Meridian components',
53
+ description: 'List every Meridian UI component with its one-line description and categories. Start here to see what exists before building a screen.',
54
+ inputSchema: { category: z.string().optional().describe('Optional category filter, e.g. "forms", "ai", "overlay".') },
55
+ },
56
+ async ({ category }) => {
57
+ let items = await components();
58
+ if (category) items = items.filter((it) => (it.categories || []).some((c) => c.toLowerCase() === category.toLowerCase()));
59
+ const lines = items.map((it) => `- ${it.title || it.name}${(it.categories || []).length ? ` [${it.categories.join(', ')}]` : ''} — ${it.description || ''}`);
60
+ return { content: [{ type: 'text', text: `${items.length} components (source: ${SOURCE})\n${lines.join('\n')}` }] };
61
+ }
62
+ );
63
+
64
+ server.registerTool(
65
+ 'get_component',
66
+ {
67
+ title: 'Get a Meridian component',
68
+ description: "Full detail for one component by name: description, dependencies, and every file's real content — the .jsx source, the .d.ts types, and the .prompt.md usage guide. Use this before writing code that uses the component.",
69
+ inputSchema: { name: z.string().describe('Component name, e.g. "Button", "DatePicker", "NumberInput".') },
70
+ },
71
+ async ({ name }) => {
72
+ let c;
73
+ try {
74
+ c = await component(name);
75
+ } catch {
76
+ return { content: [{ type: 'text', text: `No component named "${name}". Call list_components to see valid names.` }], isError: true };
77
+ }
78
+ const dep = (c.registryDependencies || []).length ? `\nMeridian dependencies (copy these too if vendoring): ${c.registryDependencies.join(', ')}` : '';
79
+ const files = (c.files || [])
80
+ .map((f) => `\n\n### ${f.path} (${f.type})\n\`\`\`\n${f.content}\n\`\`\``)
81
+ .join('');
82
+ return { content: [{ type: 'text', text: `# ${c.title || c.name}\n${c.description || ''}${dep}${files}` }] };
83
+ }
84
+ );
85
+
86
+ server.registerTool(
87
+ 'search_components',
88
+ {
89
+ title: 'Search Meridian components',
90
+ description: 'Find components by a keyword across name, title, description and category — e.g. "date", "chart", "upload", "agent".',
91
+ inputSchema: { query: z.string().describe('Keyword to search for.') },
92
+ },
93
+ async ({ query }) => {
94
+ const q = query.toLowerCase();
95
+ const hits = (await components()).filter((it) =>
96
+ [it.name, it.title, it.description, ...(it.categories || [])].filter(Boolean).some((s) => String(s).toLowerCase().includes(q))
97
+ );
98
+ if (!hits.length) return { content: [{ type: 'text', text: `No components match "${query}".` }] };
99
+ return { content: [{ type: 'text', text: hits.map((it) => `- ${it.title || it.name} — ${it.description || ''}`).join('\n') }] };
100
+ }
101
+ );
102
+
103
+ server.registerTool(
104
+ 'get_tokens',
105
+ {
106
+ title: 'Get Meridian design tokens',
107
+ description: 'The design tokens (colors, typography, spacing, effects) in light, dark and compact. Use semantic tokens in generated CSS — never hardcode hex.',
108
+ inputSchema: { group: z.string().optional().describe('Optional group filter, e.g. "color", "spacing", "typography".') },
109
+ },
110
+ async ({ group }) => {
111
+ const tokens = await readJSON('tokens.json');
112
+ const text = JSON.stringify(group ? { [group]: tokens[group] ?? tokens } : tokens, null, 2);
113
+ return { content: [{ type: 'text', text }] };
114
+ }
115
+ );
116
+
117
+ const transport = new StdioServerTransport();
118
+ await server.connect(transport);
119
+ console.error(`meridian-mcp ready (source: ${SOURCE})`);