@fragments-sdk/mcp 0.10.0 → 1.0.1
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 +34 -84
- package/dist/bin.d.ts +1 -0
- package/dist/bin.js +7 -154
- package/dist/bin.js.map +1 -1
- package/dist/index.d.ts +1443 -0
- package/dist/index.js +1107 -207
- package/dist/index.js.map +1 -1
- package/package.json +9 -33
- package/dist/chunk-4SVS3AA3.js +0 -78
- package/dist/chunk-4SVS3AA3.js.map +0 -1
- package/dist/chunk-7D4SUZUM.js +0 -38
- package/dist/chunk-7D4SUZUM.js.map +0 -1
- package/dist/chunk-VRPDT3Y6.js +0 -52
- package/dist/chunk-VRPDT3Y6.js.map +0 -1
- package/dist/chunk-WDQPNHZ2.js +0 -143
- package/dist/chunk-WDQPNHZ2.js.map +0 -1
- package/dist/chunk-YJTMK4JY.js +0 -4270
- package/dist/chunk-YJTMK4JY.js.map +0 -1
- package/dist/constants-BLN4SSNH.js +0 -10
- package/dist/constants-BLN4SSNH.js.map +0 -1
- package/dist/dist-TTCI6TME.js +0 -60962
- package/dist/dist-TTCI6TME.js.map +0 -1
- package/dist/init.js +0 -175
- package/dist/init.js.map +0 -1
- package/dist/rules-JUZ3RABB.js +0 -8
- package/dist/rules-JUZ3RABB.js.map +0 -1
- package/dist/sass.node-4XJK6YBF-CPK77BO6.js +0 -130797
- package/dist/sass.node-4XJK6YBF-CPK77BO6.js.map +0 -1
- package/dist/server.js +0 -13
- package/dist/server.js.map +0 -1
package/README.md
CHANGED
|
@@ -2,113 +2,63 @@
|
|
|
2
2
|
|
|
3
3
|
> **Source-available.** This package is distributed publicly on npm under FSL-1.1-MIT; source stays private. Contribute by filing an issue at https://github.com/fragments-sdk/fragments/issues.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Hosted MCP toolkit for Fragments Cloud. The package name stays
|
|
6
|
+
`@fragments-sdk/mcp`, but the local stdio server has been removed. Fragments MCP
|
|
7
|
+
now runs at:
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## Setup
|
|
10
|
-
|
|
11
|
-
The recommended setup writes both MCP config and IDE rules that teach agents the validator loop:
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
npx @fragments-sdk/mcp@latest init
|
|
9
|
+
```text
|
|
10
|
+
https://app.usefragments.com/api/mcp
|
|
15
11
|
```
|
|
16
12
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
### Cursor
|
|
20
|
-
|
|
21
|
-
Create `.cursor/mcp.json` in your project root:
|
|
13
|
+
Interactive clients authenticate through MCP OAuth discovery:
|
|
22
14
|
|
|
23
|
-
```
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
}
|
|
30
|
-
}
|
|
31
|
-
}
|
|
15
|
+
```text
|
|
16
|
+
/.well-known/oauth-protected-resource/api/mcp
|
|
17
|
+
/.well-known/oauth-authorization-server
|
|
18
|
+
/api/oauth/register
|
|
19
|
+
/api/oauth/authorize
|
|
20
|
+
/api/oauth/token
|
|
32
21
|
```
|
|
33
22
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
Create `.vscode/mcp.json` in your project root:
|
|
23
|
+
Headless CI clients can still authenticate with:
|
|
37
24
|
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
"servers": {
|
|
41
|
-
"fragments": {
|
|
42
|
-
"type": "stdio",
|
|
43
|
-
"command": "npx",
|
|
44
|
-
"args": ["-y", "@fragments-sdk/mcp"]
|
|
45
|
-
}
|
|
46
|
-
}
|
|
47
|
-
}
|
|
25
|
+
```text
|
|
26
|
+
Authorization: Bearer <FRAGMENTS_API_KEY>
|
|
48
27
|
```
|
|
49
28
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
claude mcp add fragments -- npx -y @fragments-sdk/mcp
|
|
54
|
-
```
|
|
29
|
+
The npm package contains the protocol dispatcher, primitive tool registry, test
|
|
30
|
+
fixtures, and a small `fragments-mcp` binary that prints the hosted setup
|
|
31
|
+
instructions.
|
|
55
32
|
|
|
56
|
-
|
|
33
|
+
## MCP Config
|
|
57
34
|
|
|
58
|
-
|
|
35
|
+
Use this shape for clients that support remote HTTP MCP servers:
|
|
59
36
|
|
|
60
37
|
```json
|
|
61
38
|
{
|
|
62
39
|
"mcpServers": {
|
|
63
40
|
"fragments": {
|
|
64
|
-
"
|
|
65
|
-
"
|
|
41
|
+
"type": "http",
|
|
42
|
+
"url": "https://app.usefragments.com/api/mcp",
|
|
43
|
+
"headers": {
|
|
44
|
+
"Authorization": "Bearer ${FRAGMENTS_API_KEY}"
|
|
45
|
+
}
|
|
66
46
|
}
|
|
67
47
|
}
|
|
68
48
|
}
|
|
69
49
|
```
|
|
70
50
|
|
|
71
|
-
### How discovery works
|
|
72
|
-
|
|
73
|
-
The server auto-discovers `fragments.json` through two layers:
|
|
74
|
-
|
|
75
|
-
1. **MCP roots** — In IDEs that support the MCP `roots/list` capability (VS Code, Claude Code), the server automatically detects your workspace root. This means global MCP configs just work.
|
|
76
|
-
2. **cwd fallback** — For IDEs that don't yet support `roots/list` (Cursor), the server uses `process.cwd()`. Project-level configs ensure cwd = your workspace root.
|
|
77
|
-
|
|
78
|
-
Once the project root is known, the server walks up from it, scans `package.json` dependencies for packages with a `"fragments"` field, and resolves through `node_modules` (supporting pnpm, Yarn, and npm).
|
|
79
|
-
|
|
80
|
-
## Validator Loop
|
|
81
|
-
|
|
82
|
-
Ask your AI assistant to follow this loop whenever it generates or edits JSX, class names, style props, or CSS:
|
|
83
|
-
|
|
84
|
-
1. Draft the UI spec or code change.
|
|
85
|
-
2. Call `govern({ spec })`.
|
|
86
|
-
3. If the result asks for revision, call `validate_and_fix({ spec, applyFixes: true })`.
|
|
87
|
-
4. Apply deterministic repairs and run `govern` again.
|
|
88
|
-
5. Before writing hardcoded CSS values, call `tokens.suggest({ property, value })` and use the returned `cssValue` when present.
|
|
89
|
-
|
|
90
51
|
## Tools
|
|
91
52
|
|
|
92
|
-
| Tool
|
|
93
|
-
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `findings_list` | List Cloud governance findings for agent planning |
|
|
98
|
-
| `findings_summary` | Summarize Cloud findings by severity, category, rule, and file |
|
|
99
|
-
| `findings_for_file` | Retrieve open Cloud findings for the file an agent is editing |
|
|
100
|
-
| `swap_to_canonical` | Suggest swaps from raw HTML (`<button>`, `<input>`, `<dialog>`, …) to the project's canonical components when a mapping is at confidence `auto` or `overridden` |
|
|
101
|
-
|
|
102
|
-
## How Token Suggestions Work
|
|
53
|
+
| Tool | Purpose |
|
|
54
|
+
| ------------------------------- | -------------------------------------------------------------------- |
|
|
55
|
+
| `design_system/list_primitives` | List reviewed Cloud primitives with source file paths |
|
|
56
|
+
| `design_system/conform` | Return deterministic design-system rewrites for a code snippet |
|
|
57
|
+
| `design_system/prove_compliant` | Run a validate/fix/revalidate proof loop, with MCP Sampling fallback |
|
|
103
58
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
```
|
|
109
|
-
-p, --project-root <path> Project root (default: cwd)
|
|
110
|
-
--cloud-api-key <key> Cloud API key for org-scoped catalog and findings
|
|
111
|
-
--generate-rules Generate IDE rules files and exit
|
|
112
|
-
```
|
|
59
|
+
`design_system/list_primitives` intentionally takes no arguments. Fragments
|
|
60
|
+
Cloud owns primitive selection; MCP serves the curated result. `conform` and
|
|
61
|
+
`prove_compliant` operate on supplied code only and do not write to the caller's
|
|
62
|
+
filesystem or repository.
|
|
113
63
|
|
|
114
64
|
<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=a02beb71-df11-498d-8e1f-39de2e64ce5b" />
|
package/dist/bin.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
package/dist/bin.js
CHANGED
|
@@ -1,162 +1,15 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
import {
|
|
3
|
-
loadConfigFile,
|
|
4
|
-
resolveDataAdapter,
|
|
5
|
-
resolveSearchApiKey,
|
|
6
|
-
startMcpServer
|
|
7
|
-
} from "./chunk-YJTMK4JY.js";
|
|
8
|
-
import "./chunk-4SVS3AA3.js";
|
|
9
|
-
import "./chunk-7D4SUZUM.js";
|
|
10
2
|
|
|
11
3
|
// src/bin.ts
|
|
12
|
-
var
|
|
13
|
-
|
|
14
|
-
const { runInit } = await import("./init.js");
|
|
15
|
-
const initArgs = args.slice(1);
|
|
16
|
-
let projectRoot2 = process.cwd();
|
|
17
|
-
let clients;
|
|
18
|
-
for (let i = 0; i < initArgs.length; i++) {
|
|
19
|
-
const arg = initArgs[i];
|
|
20
|
-
if (arg === "--project-root" || arg === "-p") {
|
|
21
|
-
projectRoot2 = initArgs[++i] ?? projectRoot2;
|
|
22
|
-
} else if (arg === "--client" || arg === "-c") {
|
|
23
|
-
clients = (initArgs[++i] ?? "").split(",").map((s) => s.trim());
|
|
24
|
-
} else if (arg === "--help" || arg === "-h") {
|
|
25
|
-
console.log(`
|
|
26
|
-
Usage: fragments-mcp init [options]
|
|
4
|
+
var endpoint = process.env.FRAGMENTS_MCP_URL ?? "https://app.usefragments.com/api/mcp";
|
|
5
|
+
console.log(`@fragments-sdk/mcp no longer starts a local stdio server.
|
|
27
6
|
|
|
28
|
-
|
|
29
|
-
Auto-detects Claude Code, Cursor, VS Code, and Windsurf.
|
|
7
|
+
Fragments MCP is now a hosted streamable HTTP connector.
|
|
30
8
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
-c, --client <list> Comma-separated clients: claude,cursor,vscode,windsurf
|
|
34
|
-
(default: auto-detect)
|
|
35
|
-
-h, --help Show this help message
|
|
9
|
+
Use this endpoint in MCP clients that support remote servers:
|
|
10
|
+
${endpoint}
|
|
36
11
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
npx @fragments-sdk/mcp init --client cursor,claude
|
|
12
|
+
For CI and headless contexts, authenticate HTTP requests with:
|
|
13
|
+
Authorization: Bearer <FRAGMENTS_API_KEY>
|
|
40
14
|
`);
|
|
41
|
-
process.exit(0);
|
|
42
|
-
}
|
|
43
|
-
}
|
|
44
|
-
runInit({ projectRoot: projectRoot2, clients });
|
|
45
|
-
process.exit(0);
|
|
46
|
-
}
|
|
47
|
-
var projectRoot = process.cwd();
|
|
48
|
-
var cloudApiKey;
|
|
49
|
-
var source = "auto";
|
|
50
|
-
var generateRules = false;
|
|
51
|
-
var rulesFormats;
|
|
52
|
-
var force = false;
|
|
53
|
-
for (let i = 0; i < args.length; i++) {
|
|
54
|
-
const arg = args[i];
|
|
55
|
-
if (arg === "--project-root" || arg === "-p") {
|
|
56
|
-
projectRoot = args[++i] ?? projectRoot;
|
|
57
|
-
} else if (arg === "--cloud-api-key") {
|
|
58
|
-
cloudApiKey = args[++i];
|
|
59
|
-
} else if (arg === "--source") {
|
|
60
|
-
const next = args[++i];
|
|
61
|
-
if (next === "auto" || next === "fragments-json" || next === "cloud" || next === "bundle" || next === "extract") {
|
|
62
|
-
source = next;
|
|
63
|
-
} else {
|
|
64
|
-
console.error(
|
|
65
|
-
`Invalid source: "${next}". Valid values: auto, fragments-json, cloud, bundle, extract`
|
|
66
|
-
);
|
|
67
|
-
process.exit(1);
|
|
68
|
-
}
|
|
69
|
-
} else if (arg === "--generate-rules") {
|
|
70
|
-
generateRules = true;
|
|
71
|
-
} else if (arg === "--formats") {
|
|
72
|
-
rulesFormats = args[++i];
|
|
73
|
-
} else if (arg === "--force") {
|
|
74
|
-
force = true;
|
|
75
|
-
} else if (arg === "--help" || arg === "-h") {
|
|
76
|
-
console.log(`
|
|
77
|
-
Usage: fragments-mcp [command] [options]
|
|
78
|
-
|
|
79
|
-
Standalone MCP server for design system intelligence.
|
|
80
|
-
Provides UI validation, deterministic repair, token suggestions, and Cloud findings.
|
|
81
|
-
|
|
82
|
-
Commands:
|
|
83
|
-
init Write MCP config for your AI editor(s)
|
|
84
|
-
|
|
85
|
-
Options:
|
|
86
|
-
-p, --project-root <path> Project root directory (default: cwd)
|
|
87
|
-
--cloud-api-key <key> Cloud API key for org-scoped catalog access
|
|
88
|
-
--source <mode> Source override: auto, fragments-json, cloud, bundle, extract
|
|
89
|
-
--generate-rules Generate IDE rules files and exit
|
|
90
|
-
--formats <list> Comma-separated formats: cursor,claude,copilot (default: all)
|
|
91
|
-
--force Overwrite existing rules files
|
|
92
|
-
-h, --help Show this help message
|
|
93
|
-
|
|
94
|
-
Quick start:
|
|
95
|
-
npx @fragments-sdk/mcp init
|
|
96
|
-
`);
|
|
97
|
-
process.exit(0);
|
|
98
|
-
}
|
|
99
|
-
}
|
|
100
|
-
var fileConfig = loadConfigFile(projectRoot) ?? void 0;
|
|
101
|
-
var serverConfig = {
|
|
102
|
-
projectRoot,
|
|
103
|
-
searchApiKey: resolveSearchApiKey({ projectRoot }, fileConfig),
|
|
104
|
-
cloudApiKey,
|
|
105
|
-
source,
|
|
106
|
-
fileConfig
|
|
107
|
-
};
|
|
108
|
-
var { adapter, mode } = resolveDataAdapter(serverConfig, fileConfig);
|
|
109
|
-
if (mode === "extract") {
|
|
110
|
-
console.error(
|
|
111
|
-
"[fragments-mcp] No fragments.json found \u2014 auto-extracting from source."
|
|
112
|
-
);
|
|
113
|
-
}
|
|
114
|
-
if (generateRules) {
|
|
115
|
-
(async () => {
|
|
116
|
-
const { generateRulesFiles } = await import("./rules-JUZ3RABB.js");
|
|
117
|
-
const defaultFormats = ["cursor", "claude", "copilot"];
|
|
118
|
-
const formats = rulesFormats ? rulesFormats.split(",").map((f) => f.trim()) : defaultFormats;
|
|
119
|
-
const validFormats = /* @__PURE__ */ new Set(["cursor", "claude", "copilot"]);
|
|
120
|
-
for (const fmt of formats) {
|
|
121
|
-
if (!validFormats.has(fmt)) {
|
|
122
|
-
console.error(`Invalid format: "${fmt}". Valid formats: cursor, claude, copilot`);
|
|
123
|
-
process.exit(1);
|
|
124
|
-
}
|
|
125
|
-
}
|
|
126
|
-
const data = await adapter.load(projectRoot);
|
|
127
|
-
const { BRAND } = await import("./constants-BLN4SSNH.js");
|
|
128
|
-
const brandName = fileConfig?.brand?.name ?? BRAND.name;
|
|
129
|
-
const files = generateRulesFiles({
|
|
130
|
-
data,
|
|
131
|
-
brandName,
|
|
132
|
-
outputDir: projectRoot,
|
|
133
|
-
formats,
|
|
134
|
-
force
|
|
135
|
-
});
|
|
136
|
-
if (files.length === 0) {
|
|
137
|
-
console.log("No rules files generated.");
|
|
138
|
-
} else {
|
|
139
|
-
console.log(`Generated ${files.length} rules file(s):`);
|
|
140
|
-
for (const file of files) {
|
|
141
|
-
console.log(` ${file}`);
|
|
142
|
-
}
|
|
143
|
-
}
|
|
144
|
-
process.exit(0);
|
|
145
|
-
})().catch((error) => {
|
|
146
|
-
console.error("Failed to generate rules:", error instanceof Error ? error.message : error);
|
|
147
|
-
process.exit(1);
|
|
148
|
-
});
|
|
149
|
-
} else {
|
|
150
|
-
startMcpServer({
|
|
151
|
-
projectRoot,
|
|
152
|
-
searchApiKey: resolveSearchApiKey({ projectRoot }, fileConfig),
|
|
153
|
-
cloudApiKey,
|
|
154
|
-
source,
|
|
155
|
-
fileConfig,
|
|
156
|
-
adapter
|
|
157
|
-
}).catch((error) => {
|
|
158
|
-
console.error("Failed to start MCP server:", error);
|
|
159
|
-
process.exit(1);
|
|
160
|
-
});
|
|
161
|
-
}
|
|
162
15
|
//# sourceMappingURL=bin.js.map
|
package/dist/bin.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\
|
|
1
|
+
{"version":3,"sources":["../src/bin.ts"],"sourcesContent":["#!/usr/bin/env node\n\nconst endpoint = process.env.FRAGMENTS_MCP_URL ?? \"https://app.usefragments.com/api/mcp\";\n\nconsole.log(`@fragments-sdk/mcp no longer starts a local stdio server.\n\nFragments MCP is now a hosted streamable HTTP connector.\n\nUse this endpoint in MCP clients that support remote servers:\n ${endpoint}\n\nFor CI and headless contexts, authenticate HTTP requests with:\n Authorization: Bearer <FRAGMENTS_API_KEY>\n`);\n"],"mappings":";;;AAEA,IAAM,WAAW,QAAQ,IAAI,qBAAqB;AAElD,QAAQ,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA,IAKR,QAAQ;AAAA;AAAA;AAAA;AAAA,CAIX;","names":[]}
|