@skoor/create-custom-widget 0.0.1 → 0.0.2
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 +10 -0
- package/bin/create-custom-widget.js +42 -1
- package/lib/auth.js +59 -0
- package/package.json +1 -1
- package/template/.vscode/mcp.json +1 -1
- package/template/AGENTS.md +2 -1
- package/template/README.md +12 -1
package/README.md
CHANGED
|
@@ -32,6 +32,16 @@ npm run dev
|
|
|
32
32
|
|
|
33
33
|
The full development workflow is in the README of `@skoor/dashboard-bridge`, section "Widget development workflow".
|
|
34
34
|
|
|
35
|
+
## MCP server credentials
|
|
36
|
+
|
|
37
|
+
The SKOOR MCP server expects an `Authorization` header with Basic auth. Generate it instead of base64-encoding it by hand:
|
|
38
|
+
|
|
39
|
+
```shell
|
|
40
|
+
npx @skoor/create-custom-widget@latest mcp-auth [--user <name>]
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The password is always asked for with hidden input and never stored or accepted as an argument. The command prints the value for the VS Code prompt and the `SKOOR_MCP_AUTHORIZATION` export for Claude Code (PowerShell syntax on Windows).
|
|
44
|
+
|
|
35
45
|
## Updating AGENTS.md in existing projects
|
|
36
46
|
|
|
37
47
|
The rules in `AGENTS.md` sit between `<!-- skoor:managed vN -->` and `<!-- /skoor:managed -->`. Update them in place:
|
|
@@ -5,6 +5,7 @@ import { stdin, stdout } from "node:process";
|
|
|
5
5
|
import { createInterface } from "node:readline/promises";
|
|
6
6
|
import { parseArgs } from "node:util";
|
|
7
7
|
|
|
8
|
+
import { basicAuthorization, exportCommand, readHidden, validateUser } from "../lib/auth.js";
|
|
8
9
|
import { pickLatest, planUpdate } from "../lib/managed-block.js";
|
|
9
10
|
import {
|
|
10
11
|
DEFAULT_MCP_URL,
|
|
@@ -21,6 +22,7 @@ const pkg = JSON.parse(await readFile(new URL("../package.json", import.meta.url
|
|
|
21
22
|
const HELP = `Usage:
|
|
22
23
|
npm create @skoor/custom-widget@latest [directory] -- [options]
|
|
23
24
|
npx @skoor/create-custom-widget@latest update-agents [directory] [options]
|
|
25
|
+
npx @skoor/create-custom-widget@latest mcp-auth [options]
|
|
24
26
|
|
|
25
27
|
Create a widget project:
|
|
26
28
|
--name <@scope/name> package name, using the scope assigned to you
|
|
@@ -32,6 +34,10 @@ Update the managed rules block in AGENTS.md (update-agents):
|
|
|
32
34
|
--check only report; exit code 1 if an update is available
|
|
33
35
|
--force insert the block if AGENTS.md has no markers
|
|
34
36
|
|
|
37
|
+
Print the Authorization header for the SKOOR MCP server (mcp-auth):
|
|
38
|
+
--user <name> SKOOR username (otherwise prompted)
|
|
39
|
+
The password is always prompted, hidden, and never stored.
|
|
40
|
+
|
|
35
41
|
-h, --help show this help
|
|
36
42
|
-v, --version show the version
|
|
37
43
|
`;
|
|
@@ -98,6 +104,31 @@ async function ask(rl, question, { defaultValue, validate }) {
|
|
|
98
104
|
}
|
|
99
105
|
}
|
|
100
106
|
|
|
107
|
+
async function mcpAuth({ user }) {
|
|
108
|
+
if (!stdin.isTTY) throw new UsageError("mcp-auth needs an interactive terminal to ask for the password.");
|
|
109
|
+
if (user) {
|
|
110
|
+
const error = validateUser(user);
|
|
111
|
+
if (error) throw new UsageError(`--user: ${error}`);
|
|
112
|
+
} else {
|
|
113
|
+
const rl = createInterface({ input: stdin, output: stdout });
|
|
114
|
+
try {
|
|
115
|
+
user = await ask(rl, "SKOOR username", { validate: validateUser });
|
|
116
|
+
} finally {
|
|
117
|
+
rl.close();
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const password = await readHidden("SKOOR password (hidden): ");
|
|
122
|
+
const value = basicAuthorization(user, password);
|
|
123
|
+
|
|
124
|
+
console.log("\nAuthorization header for the SKOOR MCP server. Treat it like the password.\n");
|
|
125
|
+
console.log("VS Code (paste when .vscode/mcp.json asks for it):");
|
|
126
|
+
console.log(` ${value}\n`);
|
|
127
|
+
console.log("Claude Code (run in the shell you start claude from, or add to your shell profile):");
|
|
128
|
+
console.log(` ${exportCommand(value)}`);
|
|
129
|
+
return 0;
|
|
130
|
+
}
|
|
131
|
+
|
|
101
132
|
async function create(positional, { name, instance, yes, force }) {
|
|
102
133
|
const interactive = !yes && stdin.isTTY;
|
|
103
134
|
if (!interactive && !name) throw new UsageError("--name is required when not prompting.");
|
|
@@ -148,6 +179,8 @@ async function create(positional, { name, instance, yes, force }) {
|
|
|
148
179
|
console.log(" npm login --registry=https://registry.skoor.com # once per machine");
|
|
149
180
|
console.log(" npm install");
|
|
150
181
|
console.log(" npm run dev");
|
|
182
|
+
console.log("\nFor the SKOOR MCP server, generate the Authorization header with:");
|
|
183
|
+
console.log(" npx @skoor/create-custom-widget@latest mcp-auth");
|
|
151
184
|
if (!mcpUrl) console.log("\nSet your SKOOR instance URL in .vscode/mcp.json and .mcp.json.");
|
|
152
185
|
console.log("\nRead AGENTS.md and node_modules/@skoor/dashboard-bridge/README.md before you start.");
|
|
153
186
|
return 0;
|
|
@@ -160,6 +193,7 @@ async function main(argv) {
|
|
|
160
193
|
options: {
|
|
161
194
|
name: { type: "string" },
|
|
162
195
|
instance: { type: "string" },
|
|
196
|
+
user: { type: "string" },
|
|
163
197
|
yes: { type: "boolean", short: "y" },
|
|
164
198
|
force: { type: "boolean" },
|
|
165
199
|
check: { type: "boolean" },
|
|
@@ -181,6 +215,10 @@ async function main(argv) {
|
|
|
181
215
|
if (positionals.length > 2) throw new UsageError("update-agents takes at most one directory.");
|
|
182
216
|
return updateAgents(path.resolve(positionals[1] ?? "."), values);
|
|
183
217
|
}
|
|
218
|
+
if (positionals[0] === "mcp-auth") {
|
|
219
|
+
if (positionals.length > 1) throw new UsageError("mcp-auth takes no arguments.");
|
|
220
|
+
return mcpAuth(values);
|
|
221
|
+
}
|
|
184
222
|
if (positionals.length > 1) throw new UsageError("Expected at most one directory.");
|
|
185
223
|
return create(positionals[0], values);
|
|
186
224
|
}
|
|
@@ -188,7 +226,10 @@ async function main(argv) {
|
|
|
188
226
|
try {
|
|
189
227
|
process.exitCode = await main(process.argv.slice(2));
|
|
190
228
|
} catch (error) {
|
|
191
|
-
if (error
|
|
229
|
+
if (error.code === "ABORT") {
|
|
230
|
+
console.error(error.message);
|
|
231
|
+
process.exitCode = 130;
|
|
232
|
+
} else if (error instanceof UsageError || error.code?.startsWith?.("ERR_PARSE_ARGS")) {
|
|
192
233
|
console.error(`${error.message}\n\n${HELP}`);
|
|
193
234
|
process.exitCode = 2;
|
|
194
235
|
} else {
|
package/lib/auth.js
ADDED
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
// Builds the Authorization header for the SKOOR MCP server (HTTP Basic, RFC 7617).
|
|
2
|
+
|
|
3
|
+
/** Returns an error message, or null if `user` can be used for Basic auth. */
|
|
4
|
+
export function validateUser(user) {
|
|
5
|
+
if (!user) return "A username is required.";
|
|
6
|
+
if (user.includes(":")) return "The username must not contain ':'.";
|
|
7
|
+
return null;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
/** "user", "pass" -> "Basic dXNlcjpwYXNz" */
|
|
11
|
+
export function basicAuthorization(user, password) {
|
|
12
|
+
const error = validateUser(user);
|
|
13
|
+
if (error) throw new Error(error);
|
|
14
|
+
return `Basic ${Buffer.from(`${user}:${password}`, "utf8").toString("base64")}`;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** Shell command that sets the variable `.mcp.json` reads, for the current platform. */
|
|
18
|
+
export function exportCommand(value, platform = process.platform) {
|
|
19
|
+
return platform === "win32"
|
|
20
|
+
? `$env:SKOOR_MCP_AUTHORIZATION = '${value}'`
|
|
21
|
+
: `export SKOOR_MCP_AUTHORIZATION='${value}'`;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
// Bracketed-paste markers that some terminals wrap around pasted text.
|
|
25
|
+
const PASTE_MARKERS = /\x1b\[20[01]~/g;
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Reads a line from a TTY without echoing it.
|
|
29
|
+
* Rejects with `{ code: "ABORT" }` on Ctrl+C.
|
|
30
|
+
*/
|
|
31
|
+
export function readHidden(prompt, { input = process.stdin, output = process.stdout } = {}) {
|
|
32
|
+
return new Promise((resolve, reject) => {
|
|
33
|
+
let value = "";
|
|
34
|
+
output.write(prompt);
|
|
35
|
+
input.setRawMode(true);
|
|
36
|
+
input.setEncoding("utf8");
|
|
37
|
+
input.resume();
|
|
38
|
+
|
|
39
|
+
const finish = (error) => {
|
|
40
|
+
input.off("data", onData);
|
|
41
|
+
input.setRawMode(false);
|
|
42
|
+
input.pause();
|
|
43
|
+
output.write("\n");
|
|
44
|
+
if (error) reject(error);
|
|
45
|
+
else resolve(value);
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
const onData = (chunk) => {
|
|
49
|
+
for (const char of chunk.replace(PASTE_MARKERS, "")) {
|
|
50
|
+
if (char === "\r" || char === "\n" || char === "\u0004") return finish();
|
|
51
|
+
if (char === "\u0003") return finish(Object.assign(new Error("Cancelled."), { code: "ABORT" }));
|
|
52
|
+
if (char === "\u007f" || char === "\b") value = [...value].slice(0, -1).join("");
|
|
53
|
+
else if (char >= " ") value += char;
|
|
54
|
+
}
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
input.on("data", onData);
|
|
58
|
+
});
|
|
59
|
+
}
|
package/package.json
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
{
|
|
13
13
|
"type": "promptString",
|
|
14
14
|
"id": "skoor-mcp-authorization",
|
|
15
|
-
"description": "Authorization header for the SKOOR MCP server
|
|
15
|
+
"description": "Authorization header for the SKOOR MCP server. Generate it with: npx @skoor/create-custom-widget@latest mcp-auth",
|
|
16
16
|
"password": true
|
|
17
17
|
}
|
|
18
18
|
]
|
package/template/AGENTS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# AGENTS.md
|
|
2
2
|
|
|
3
|
-
<!-- skoor:managed
|
|
3
|
+
<!-- skoor:managed v2 -->
|
|
4
4
|
## SKOOR widget rules
|
|
5
5
|
|
|
6
6
|
This project is a SKOOR dashboard custom widget.
|
|
@@ -9,6 +9,7 @@ This project is a SKOOR dashboard custom widget.
|
|
|
9
9
|
- Then read `node_modules/@skoor/dashboard-bridge/README.md`, especially "Widget development workflow", before implementing anything. It is the authoritative guide. If it disagrees with this file, the README applies, including its instructions for updating this block.
|
|
10
10
|
- Communicate with SKOOR only through `@skoor/dashboard-bridge`. Never call SKOOR backend APIs directly from the widget.
|
|
11
11
|
- Never commit credentials, tokens or API keys, also not in `.vscode/mcp.json` or `.mcp.json`.
|
|
12
|
+
- If the SKOOR MCP server is not connected or rejects requests with 401, ask the user to run `npx @skoor/create-custom-widget@latest mcp-auth` in their own terminal and follow its output. Never ask for the SKOOR username or password in the chat, never run `mcp-auth` yourself, and never write the `Authorization` value into a file.
|
|
12
13
|
- Never hand-edit `data/data-queries.json`. Regenerate it with the MCP export tool.
|
|
13
14
|
<!-- /skoor:managed -->
|
|
14
15
|
|
package/template/README.md
CHANGED
|
@@ -22,7 +22,18 @@ Read `AGENTS.md` and the "Widget development workflow" section in `node_modules/
|
|
|
22
22
|
|
|
23
23
|
## MCP server
|
|
24
24
|
|
|
25
|
-
`.vscode/mcp.json` (VS Code) and `.mcp.json` (Claude Code) point to the SKOOR MCP server. Neither file contains credentials.
|
|
25
|
+
`.vscode/mcp.json` (VS Code) and `.mcp.json` (Claude Code) point to the SKOOR MCP server. Neither file contains credentials. Both need an `Authorization` header, which you generate with:
|
|
26
|
+
|
|
27
|
+
```shell
|
|
28
|
+
npx @skoor/create-custom-widget@latest mcp-auth
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
It asks for your SKOOR username and password (hidden), stores nothing and prints:
|
|
32
|
+
|
|
33
|
+
- the value to paste when VS Code asks for the `Authorization` header
|
|
34
|
+
- an `export SKOOR_MCP_AUTHORIZATION=...` command for Claude Code. Run it in the shell you start `claude` from, or add it to your shell profile.
|
|
35
|
+
|
|
36
|
+
The value contains your password in reversible form. Do not commit it or put it into project files.
|
|
26
37
|
|
|
27
38
|
## Updating AGENTS.md
|
|
28
39
|
|