@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.
- package/README.md +63 -0
- package/package.json +11 -0
- 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})`);
|