@sparkwire/mcp 0.0.0-stage → 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/data/docs.json +4963 -0
- package/data/r/accordion.json +26 -0
- package/data/r/alert.json +26 -0
- package/data/r/avatar.json +26 -0
- package/data/r/base.json +55 -0
- package/data/r/button.json +33 -0
- package/data/r/card.json +26 -0
- package/data/r/charts.json +40 -0
- package/data/r/checkbox.json +27 -0
- package/data/r/combobox.json +30 -0
- package/data/r/command-palette.json +29 -0
- package/data/r/dashboard.json +34 -0
- package/data/r/data-table.json +39 -0
- package/data/r/date-picker.json +56 -0
- package/data/r/drawer.json +29 -0
- package/data/r/dropdown.json +30 -0
- package/data/r/field.json +26 -0
- package/data/r/file-upload.json +28 -0
- package/data/r/headless.json +27 -0
- package/data/r/indicators.json +26 -0
- package/data/r/input-base.json +21 -0
- package/data/r/menu.json +32 -0
- package/data/r/modal.json +29 -0
- package/data/r/navigation.json +26 -0
- package/data/r/number-field.json +30 -0
- package/data/r/provider.json +47 -0
- package/data/r/radio-group.json +26 -0
- package/data/r/select.json +21 -0
- package/data/r/settings.json +37 -0
- package/data/r/sidebar.json +30 -0
- package/data/r/sign-in.json +31 -0
- package/data/r/slider.json +29 -0
- package/data/r/spark.json +26 -0
- package/data/r/stepper.json +26 -0
- package/data/r/styles.json +17 -0
- package/data/r/switch.json +26 -0
- package/data/r/tabs.json +29 -0
- package/data/r/textarea.json +28 -0
- package/data/r/textfield.json +57 -0
- package/data/r/time-picker.json +32 -0
- package/data/r/toast.json +26 -0
- package/data/r/toggle-group.json +29 -0
- package/data/r/tooltip.json +29 -0
- package/data/r/utils.json +63 -0
- package/data/registry.json +1219 -0
- package/package.json +40 -4
- package/src/server.mjs +179 -0
- package/README.md +0 -3
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sparkwire/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "MCP server for Spark UI: lets AI coding agents look up components, props, install commands and source.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"sparkwire-mcp": "./src/server.mjs"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"src",
|
|
11
|
+
"data"
|
|
12
|
+
],
|
|
13
|
+
"engines": {
|
|
14
|
+
"node": ">=18"
|
|
15
|
+
},
|
|
16
|
+
"scripts": {
|
|
17
|
+
"prepack": "node ./scripts/bundle-data.mjs"
|
|
18
|
+
},
|
|
19
|
+
"keywords": [
|
|
20
|
+
"mcp",
|
|
21
|
+
"model-context-protocol",
|
|
22
|
+
"react",
|
|
23
|
+
"components",
|
|
24
|
+
"spark-ui",
|
|
25
|
+
"sparkwire"
|
|
26
|
+
],
|
|
27
|
+
"license": "MIT",
|
|
28
|
+
"repository": {
|
|
29
|
+
"type": "git",
|
|
30
|
+
"url": "git+https://github.com/phoenix-am/spark-ui.git",
|
|
31
|
+
"directory": "packages/mcp"
|
|
32
|
+
},
|
|
33
|
+
"dependencies": {
|
|
34
|
+
"@modelcontextprotocol/sdk": "^1.32.2",
|
|
35
|
+
"zod": "^4.6.7"
|
|
36
|
+
},
|
|
37
|
+
"homepage": "https://github.com/phoenix-am/spark-ui#readme",
|
|
38
|
+
"publishConfig": {
|
|
39
|
+
"access": "public",
|
|
40
|
+
"provenance": true
|
|
41
|
+
}
|
|
42
|
+
}
|
package/src/server.mjs
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Spark UI MCP server. Gives AI coding agents real answers about the
|
|
4
|
+
* library: which components exist, their props, how to install and import
|
|
5
|
+
* them, and their source.
|
|
6
|
+
*
|
|
7
|
+
* Add to an MCP client (Claude Code, Cursor, VS Code...):
|
|
8
|
+
* { "mcpServers": { "sparkwire": { "command": "npx", "args": ["-y", "@sparkwire/mcp"] } } }
|
|
9
|
+
*
|
|
10
|
+
* Data is bundled at publish time. Set SPARKWIRE_REGISTRY to a folder or
|
|
11
|
+
* URL (the one holding docs.json and r/) to use another version.
|
|
12
|
+
*/
|
|
13
|
+
import fs from 'node:fs';
|
|
14
|
+
import path from 'node:path';
|
|
15
|
+
import { fileURLToPath } from 'node:url';
|
|
16
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
17
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
18
|
+
import { z } from 'zod';
|
|
19
|
+
|
|
20
|
+
const here = path.dirname(fileURLToPath(import.meta.url));
|
|
21
|
+
// Bundled data in the published package; the repo's registry/ during development.
|
|
22
|
+
const LOCAL = [path.resolve(here, '../data'), path.resolve(here, '../../../registry')].find((p) => fs.existsSync(path.join(p, 'docs.json')));
|
|
23
|
+
const SOURCE = process.env.SPARKWIRE_REGISTRY ?? LOCAL;
|
|
24
|
+
|
|
25
|
+
async function read(rel) {
|
|
26
|
+
if (/^https?:\/\//.test(SOURCE)) {
|
|
27
|
+
const res = await fetch(`${SOURCE.replace(/\/$/, '')}/${rel}`);
|
|
28
|
+
if (!res.ok) throw new Error(`${res.status} for ${rel}`);
|
|
29
|
+
return res.json();
|
|
30
|
+
}
|
|
31
|
+
return JSON.parse(fs.readFileSync(path.join(SOURCE, rel), 'utf8'));
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
const docs = await read('docs.json');
|
|
35
|
+
const entries = docs.components;
|
|
36
|
+
|
|
37
|
+
/** Find an entry by registry name ("date-picker"), component ("DatePicker", "Calendar") or a loose match. */
|
|
38
|
+
function find(query) {
|
|
39
|
+
const q = query.trim().toLowerCase().replace(/^@sparkwire\//, '');
|
|
40
|
+
const flat = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
|
|
41
|
+
return (
|
|
42
|
+
entries.find((e) => e.name === q) ??
|
|
43
|
+
entries.find((e) => e.components.some((c) => flat(c.name) === flat(q))) ??
|
|
44
|
+
entries.find((e) => flat(e.name) === flat(q)) ??
|
|
45
|
+
(q === 'select' ? entries.find((e) => e.name === 'dropdown') : undefined)
|
|
46
|
+
);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const text = (t) => ({ content: [{ type: 'text', text: t }] });
|
|
50
|
+
const notFound = (q) =>
|
|
51
|
+
text(`No Spark UI component matches "${q}". Available: ${entries.map((e) => e.name).join(', ')}. Use search_components to search by feature.`);
|
|
52
|
+
|
|
53
|
+
function formatProps(c, { includeDeprecated }) {
|
|
54
|
+
const props = c.props.filter((p) => includeDeprecated || !p.deprecated);
|
|
55
|
+
if (!props.length) return 'No props.';
|
|
56
|
+
return props
|
|
57
|
+
.map((p) => {
|
|
58
|
+
const desc = (p.description || '').replace(/@deprecated\s*/, '').replace(/\n+/g, ' ');
|
|
59
|
+
return `- \`${p.name}${p.required ? '' : '?'}\`: \`${p.type}\`${p.default !== undefined ? ` = \`${p.default}\`` : ''}${p.deprecated ? ' (deprecated)' : ''}${desc ? ` ${desc}` : ''}`;
|
|
60
|
+
})
|
|
61
|
+
.join('\n');
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function formatEntry(e, opts) {
|
|
65
|
+
return [
|
|
66
|
+
`# ${e.title} (\`${e.name}\`)`,
|
|
67
|
+
e.summary,
|
|
68
|
+
'',
|
|
69
|
+
'## Import',
|
|
70
|
+
'```tsx',
|
|
71
|
+
e.import,
|
|
72
|
+
"import '@sparkwire/core/styles.css'; // once, in your root layout",
|
|
73
|
+
'```',
|
|
74
|
+
'## Install',
|
|
75
|
+
`- npm package: \`npm install @sparkwire/core\``,
|
|
76
|
+
`- Copy the source: \`${e.install.copy}\` then \`${e.install.copiedImport}\``,
|
|
77
|
+
`- With shadcn: \`${e.install.shadcn}\` (needs the @sparkwire registry in components.json)`,
|
|
78
|
+
'',
|
|
79
|
+
...e.components.flatMap((c) => [`## ${c.name}`, c.description, '', '### Props', formatProps(c, opts), '']),
|
|
80
|
+
`Examples: ${e.storybook}`,
|
|
81
|
+
].join('\n');
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
const SETUP = `# Setting up Spark UI
|
|
85
|
+
|
|
86
|
+
1. Install: \`npm install @sparkwire/core\` (peer: react 18 or 19).
|
|
87
|
+
2. Import the styles once, e.g. in app/layout.tsx: \`import '@sparkwire/core/styles.css';\`
|
|
88
|
+
3. Pick a mode with an attribute on <html> or any wrapper: \`data-spark-theme="dark" | "light" | "system"\`. No provider is required, and it works in React Server Components.
|
|
89
|
+
4. Optional, app-wide settings:
|
|
90
|
+
\`\`\`tsx
|
|
91
|
+
import { SparkProvider } from '@sparkwire/core';
|
|
92
|
+
<SparkProvider
|
|
93
|
+
locale="hi-IN" // dates, digits, right-to-left
|
|
94
|
+
components={{
|
|
95
|
+
Button: { defaultProps: { variant: 'outlined' } },
|
|
96
|
+
Switch: { classNames: { bulb: 'my-bulb' } }, // extra classes on inner parts
|
|
97
|
+
}}
|
|
98
|
+
>
|
|
99
|
+
{children}
|
|
100
|
+
</SparkProvider>
|
|
101
|
+
\`\`\`
|
|
102
|
+
5. Theme: override CSS variables (e.g. \`--spark-energy-current\`, \`--spark-radius-medium\`) on any selector, or use \`createTheme()\` and \`themeToCss()\` from @sparkwire/styles.
|
|
103
|
+
|
|
104
|
+
Styling hooks: every component takes \`className\`; most take \`classNames\` for inner parts; state is exposed as data attributes (\`data-state\`, \`data-open\`, \`data-invalid\`, \`data-disabled\`, \`data-focus-visible\`) for plain CSS or Tailwind (\`data-[state=on]:...\`).
|
|
105
|
+
|
|
106
|
+
Choosing components: pick a value → Dropdown (alias Select); search then pick → Combobox; run actions → Menu. Forms: inputs take \`name\` and work with FormData and React Hook Form. Dates are JS Date objects; DatePicker submits ISO YYYY-MM-DD.
|
|
107
|
+
|
|
108
|
+
Note: the npm scope is @sparkwire. Packages under @spark-ui belong to a different library (Leboncoin's Spark).`;
|
|
109
|
+
|
|
110
|
+
const server = new McpServer({ name: 'sparkwire', version: docs.version ?? '0.1.0' });
|
|
111
|
+
|
|
112
|
+
server.registerTool(
|
|
113
|
+
'list_components',
|
|
114
|
+
{ title: 'List components', description: 'List every Spark UI component with a one-line summary.' },
|
|
115
|
+
async () => text(entries.map((e) => `- ${e.name}: ${e.summary} (exports ${e.components.map((c) => c.name).join(', ')})`).join('\n')),
|
|
116
|
+
);
|
|
117
|
+
|
|
118
|
+
server.registerTool(
|
|
119
|
+
'get_component',
|
|
120
|
+
{
|
|
121
|
+
title: 'Get component docs',
|
|
122
|
+
description: 'Props, description, import and install commands for one component, e.g. "DatePicker", "date-picker", "Menu", "Select".',
|
|
123
|
+
inputSchema: {
|
|
124
|
+
name: z.string().describe('Component or registry name'),
|
|
125
|
+
includeDeprecated: z.boolean().optional().describe('Also list deprecated props (default false)'),
|
|
126
|
+
},
|
|
127
|
+
},
|
|
128
|
+
async ({ name, includeDeprecated = false }) => {
|
|
129
|
+
const e = find(name);
|
|
130
|
+
return e ? text(formatEntry(e, { includeDeprecated })) : notFound(name);
|
|
131
|
+
},
|
|
132
|
+
);
|
|
133
|
+
|
|
134
|
+
server.registerTool(
|
|
135
|
+
'search_components',
|
|
136
|
+
{
|
|
137
|
+
title: 'Search components',
|
|
138
|
+
description: 'Find components by feature or prop, e.g. "date range", "searchable select", "loading", "right-to-left".',
|
|
139
|
+
inputSchema: { query: z.string() },
|
|
140
|
+
},
|
|
141
|
+
async ({ query }) => {
|
|
142
|
+
const words = query.toLowerCase().split(/\s+/).filter((w) => w.length > 1);
|
|
143
|
+
const score = (e) => {
|
|
144
|
+
const hay = [e.name, e.title, e.summary, ...e.components.flatMap((c) => [c.name, c.description, ...c.props.map((p) => `${p.name} ${p.description}`)])].join(' ').toLowerCase();
|
|
145
|
+
return words.reduce((n, w) => n + (hay.includes(w) ? 1 : 0), 0);
|
|
146
|
+
};
|
|
147
|
+
const hits = entries.map((e) => [e, score(e)]).filter(([, s]) => s > 0).sort((a, b) => b[1] - a[1]).slice(0, 6);
|
|
148
|
+
return text(hits.length ? hits.map(([e]) => `- ${e.name}: ${e.summary}`).join('\n') : `Nothing matches "${query}". Try list_components.`);
|
|
149
|
+
},
|
|
150
|
+
);
|
|
151
|
+
|
|
152
|
+
server.registerTool(
|
|
153
|
+
'get_component_source',
|
|
154
|
+
{
|
|
155
|
+
title: 'Get component source',
|
|
156
|
+
description: 'The source files of a component, as copied by `npx sparkwire add`. Use to explain internals or customise a copy.',
|
|
157
|
+
inputSchema: { name: z.string(), file: z.string().optional().describe('Only this file, e.g. "Menu.tsx"') },
|
|
158
|
+
},
|
|
159
|
+
async ({ name, file }) => {
|
|
160
|
+
const e = find(name) ?? { name: name.toLowerCase() };
|
|
161
|
+
let item;
|
|
162
|
+
try {
|
|
163
|
+
item = await read(`r/${e.name}.json`);
|
|
164
|
+
} catch {
|
|
165
|
+
return notFound(name);
|
|
166
|
+
}
|
|
167
|
+
const files = item.files.filter((f) => !file || f.path.endsWith(file));
|
|
168
|
+
const deps = `Depends on: ${item.registryDependencies.join(', ') || 'nothing else'}${item.dependencies.length ? `; npm: ${item.dependencies.join(', ')}` : ''}`;
|
|
169
|
+
return text([deps, ...files.map((f) => `\n// ${f.path}\n${f.content}`)].join('\n'));
|
|
170
|
+
},
|
|
171
|
+
);
|
|
172
|
+
|
|
173
|
+
server.registerTool(
|
|
174
|
+
'get_setup',
|
|
175
|
+
{ title: 'Setup guide', description: 'How to install Spark UI, import styles, choose light/dark mode, set app-wide defaults and theme it.' },
|
|
176
|
+
async () => text(SETUP),
|
|
177
|
+
);
|
|
178
|
+
|
|
179
|
+
await server.connect(new StdioServerTransport());
|
package/README.md
DELETED