@pithyjs/mcp 0.0.0-stage → 0.1.0-beta.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/LICENSE +21 -0
- package/README.md +223 -2
- package/dist/cli.d.ts +3 -0
- package/dist/cli.js +74 -0
- package/dist/errors/catalog.d.ts +48 -0
- package/dist/errors/catalog.js +252 -0
- package/dist/guard.d.ts +41 -0
- package/dist/guard.js +140 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +4 -0
- package/dist/knowledge.d.ts +157 -0
- package/dist/knowledge.js +163 -0
- package/dist/lookup.d.ts +47 -0
- package/dist/lookup.js +69 -0
- package/dist/pidl.d.ts +27 -0
- package/dist/pidl.js +251 -0
- package/dist/scaffold.d.ts +54 -0
- package/dist/scaffold.js +280 -0
- package/dist/search.d.ts +37 -0
- package/dist/search.js +129 -0
- package/dist/server.d.ts +25 -0
- package/dist/server.js +126 -0
- package/dist/snapshot.json +1 -0
- package/dist/template.d.ts +26 -0
- package/dist/template.js +66 -0
- package/dist/tokens.d.ts +71 -0
- package/dist/tokens.js +420 -0
- package/package.json +56 -3
package/dist/search.js
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.search", "title": "MCP Search", "category": "feature", "risk": "low" } */
|
|
2
|
+
import { entryCitations } from './knowledge.js';
|
|
3
|
+
/** @codexApi {"parent":"pithy.mcp.search","name":"MAX_SEARCH_LIMIT","stability":"experimental","signature":"50"} */
|
|
4
|
+
/** The most hits one search returns. */
|
|
5
|
+
export const MAX_SEARCH_LIMIT = 50;
|
|
6
|
+
/**
|
|
7
|
+
* Lowercased words of `text`, split on camelCase, punctuation and spaces.
|
|
8
|
+
*
|
|
9
|
+
* @param text - Any text.
|
|
10
|
+
* @returns Its words, in order.
|
|
11
|
+
*/
|
|
12
|
+
/** @codexApi {"parent":"pithy.mcp.search","name":"tokenize","stability":"experimental","signature":"(text: string) => string[]"} */
|
|
13
|
+
export function tokenize(text) {
|
|
14
|
+
return text
|
|
15
|
+
.replace(/([a-z0-9])([A-Z])/g, '$1 $2')
|
|
16
|
+
.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
|
|
17
|
+
.toLowerCase()
|
|
18
|
+
.split(/[^a-z0-9]+/)
|
|
19
|
+
.filter(Boolean);
|
|
20
|
+
}
|
|
21
|
+
const words = (...texts) => new Set(texts.flatMap(t => (t ? tokenize(t) : [])));
|
|
22
|
+
const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : [];
|
|
23
|
+
function buildDocs(k) {
|
|
24
|
+
const docs = [];
|
|
25
|
+
for (const e of k.entries) {
|
|
26
|
+
const citations = entryCitations(e);
|
|
27
|
+
docs.push({
|
|
28
|
+
hit: {
|
|
29
|
+
kind: 'entry',
|
|
30
|
+
id: e.id,
|
|
31
|
+
title: e.title ?? e.id,
|
|
32
|
+
summary: null,
|
|
33
|
+
citations,
|
|
34
|
+
},
|
|
35
|
+
names: [e.id, e.title ?? ''],
|
|
36
|
+
fields: [
|
|
37
|
+
[words(e.id), 3],
|
|
38
|
+
[words(e.title), 3],
|
|
39
|
+
[words(...e.tags), 2],
|
|
40
|
+
[words(...e.apis.map(a => a.name)), 1],
|
|
41
|
+
],
|
|
42
|
+
});
|
|
43
|
+
for (const a of e.apis) {
|
|
44
|
+
docs.push({
|
|
45
|
+
hit: {
|
|
46
|
+
kind: 'api',
|
|
47
|
+
id: `${e.id} ${a.name}`,
|
|
48
|
+
title: a.name,
|
|
49
|
+
entryId: e.id,
|
|
50
|
+
summary: a.summary,
|
|
51
|
+
citations: a.place
|
|
52
|
+
? [{ entryId: e.id, file: a.place.file, line: a.place.line }]
|
|
53
|
+
: citations,
|
|
54
|
+
},
|
|
55
|
+
names: [a.name],
|
|
56
|
+
fields: [
|
|
57
|
+
[words(a.name), 4],
|
|
58
|
+
[words(e.title, ...e.tags), 1],
|
|
59
|
+
[words(a.summary), 1],
|
|
60
|
+
],
|
|
61
|
+
});
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
for (const c of k.components) {
|
|
65
|
+
const ai = (c.spec.ai ?? {});
|
|
66
|
+
const synonyms = strings(ai.synonyms);
|
|
67
|
+
const description = typeof c.spec.description === 'string' ? c.spec.description : null;
|
|
68
|
+
docs.push({
|
|
69
|
+
hit: {
|
|
70
|
+
kind: 'component',
|
|
71
|
+
id: c.name,
|
|
72
|
+
title: String(c.spec.displayName ?? c.name),
|
|
73
|
+
summary: description,
|
|
74
|
+
citations: [{ file: c.file }],
|
|
75
|
+
},
|
|
76
|
+
names: [c.name, c.id, ...synonyms],
|
|
77
|
+
fields: [
|
|
78
|
+
[words(c.name, c.id), 4],
|
|
79
|
+
[words(...synonyms), 2],
|
|
80
|
+
[words(description), 1],
|
|
81
|
+
],
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
return docs;
|
|
85
|
+
}
|
|
86
|
+
const cache = new WeakMap();
|
|
87
|
+
/**
|
|
88
|
+
* Ranks entries, APIs and components against `query`. Each query word scores
|
|
89
|
+
* the best-weighted field holding it (half for a prefix match), and a whole
|
|
90
|
+
* name equal to the query scores 10 more. Ties sort by id, so results are
|
|
91
|
+
* deterministic.
|
|
92
|
+
*
|
|
93
|
+
* @param k - The knowledge to search.
|
|
94
|
+
* @param query - Free text.
|
|
95
|
+
* @param limit - At most this many hits, capped at {@link MAX_SEARCH_LIMIT}.
|
|
96
|
+
* @returns Hits with a score above zero, best first.
|
|
97
|
+
*/
|
|
98
|
+
/** @codexApi {"parent":"pithy.mcp.search","name":"search","stability":"experimental","signature":"(k: Knowledge, query: string, limit?: number) => SearchHit[]"} */
|
|
99
|
+
export function search(k, query, limit = 10) {
|
|
100
|
+
const q = tokenize(query);
|
|
101
|
+
const max = Math.max(0, Math.min(Math.floor(limit), MAX_SEARCH_LIMIT));
|
|
102
|
+
if (q.length === 0 || max === 0)
|
|
103
|
+
return [];
|
|
104
|
+
let docs = cache.get(k);
|
|
105
|
+
if (!docs)
|
|
106
|
+
cache.set(k, (docs = buildDocs(k)));
|
|
107
|
+
const whole = query.trim().toLowerCase();
|
|
108
|
+
const hits = [];
|
|
109
|
+
for (const d of docs) {
|
|
110
|
+
let score = 0;
|
|
111
|
+
for (const w of q) {
|
|
112
|
+
let best = 0;
|
|
113
|
+
for (const [set, weight] of d.fields) {
|
|
114
|
+
if (set.has(w))
|
|
115
|
+
best = Math.max(best, weight);
|
|
116
|
+
else if (w.length >= 3 && [...set].some(s => s.startsWith(w)))
|
|
117
|
+
best = Math.max(best, weight / 2);
|
|
118
|
+
}
|
|
119
|
+
score += best;
|
|
120
|
+
}
|
|
121
|
+
if (score === 0)
|
|
122
|
+
continue;
|
|
123
|
+
if (d.names.some(n => n.toLowerCase() === whole))
|
|
124
|
+
score += 10;
|
|
125
|
+
hits.push({ ...d.hit, score });
|
|
126
|
+
}
|
|
127
|
+
hits.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
|
|
128
|
+
return hits.slice(0, max);
|
|
129
|
+
}
|
package/dist/server.d.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.server", "title": "PithyJS MCP Server", "category": "feature", "risk": "medium" } */
|
|
2
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
3
|
+
import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
|
|
4
|
+
import type { Knowledge } from './knowledge.js';
|
|
5
|
+
/** @codexApi {"parent":"pithy.mcp.server","name":"TOOL_NAMES","stability":"experimental","signature":"readonly string[]"} */
|
|
6
|
+
/** Every tool the server registers. */
|
|
7
|
+
export declare const TOOL_NAMES: readonly ["search", "get_api", "get_component", "get_tokens", "validate_template", "check_tokens", "validate_pidl", "explain_error", "scaffold_route", "scaffold_component"];
|
|
8
|
+
/**
|
|
9
|
+
* An MCP server whose tools and resources answer from `knowledge`. Connect it
|
|
10
|
+
* with {@link connectPithyServer}, which guards every tool's input.
|
|
11
|
+
*
|
|
12
|
+
* @param knowledge - The snapshot (public mode) or a live build (repo mode).
|
|
13
|
+
* @returns The server, not yet connected.
|
|
14
|
+
*/
|
|
15
|
+
/** @codexApi {"parent":"pithy.mcp.server","name":"createPithyServer","stability":"experimental","signature":"(knowledge: Knowledge) => McpServer"} */
|
|
16
|
+
export declare function createPithyServer(knowledge: Knowledge): McpServer;
|
|
17
|
+
/**
|
|
18
|
+
* Connects `server` to `transport` through {@link guardTransport}, so every
|
|
19
|
+
* tool call's raw arguments pass `guardInput` before any schema parses them.
|
|
20
|
+
*
|
|
21
|
+
* @param server - From {@link createPithyServer}.
|
|
22
|
+
* @param transport - Stdio, or an in-memory transport in tests.
|
|
23
|
+
*/
|
|
24
|
+
/** @codexApi {"parent":"pithy.mcp.server","name":"connectPithyServer","stability":"experimental","signature":"(server: McpServer, transport: Transport) => Promise<void>"} */
|
|
25
|
+
export declare function connectPithyServer(server: McpServer, transport: Transport): Promise<void>;
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.server", "title": "PithyJS MCP Server", "category": "feature", "risk": "medium" } */
|
|
2
|
+
import { readFileSync } from 'node:fs';
|
|
3
|
+
import { McpServer, ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
4
|
+
import { z } from 'zod';
|
|
5
|
+
import { explainError } from './errors/catalog.js';
|
|
6
|
+
import { guardTransport } from './guard.js';
|
|
7
|
+
import { getApi, getComponent } from './lookup.js';
|
|
8
|
+
import { validatePidl } from './pidl.js';
|
|
9
|
+
import { scaffoldComponent, scaffoldRoute, takenComponentNames, } from './scaffold.js';
|
|
10
|
+
import { MAX_SEARCH_LIMIT, search } from './search.js';
|
|
11
|
+
import { checkTemplate } from './template.js';
|
|
12
|
+
import { checkTokens, getTokens } from './tokens.js';
|
|
13
|
+
/** @codexApi {"parent":"pithy.mcp.server","name":"TOOL_NAMES","stability":"experimental","signature":"readonly string[]"} */
|
|
14
|
+
/** Every tool the server registers. */
|
|
15
|
+
export const TOOL_NAMES = [
|
|
16
|
+
'search',
|
|
17
|
+
'get_api',
|
|
18
|
+
'get_component',
|
|
19
|
+
'get_tokens',
|
|
20
|
+
'validate_template',
|
|
21
|
+
'check_tokens',
|
|
22
|
+
'validate_pidl',
|
|
23
|
+
'explain_error',
|
|
24
|
+
'scaffold_route',
|
|
25
|
+
'scaffold_component',
|
|
26
|
+
];
|
|
27
|
+
const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
|
|
28
|
+
// No tool writes files or reaches the network; scaffolds return files.
|
|
29
|
+
const READ_ONLY = {
|
|
30
|
+
readOnlyHint: true,
|
|
31
|
+
destructiveHint: false,
|
|
32
|
+
idempotentHint: true,
|
|
33
|
+
openWorldHint: false,
|
|
34
|
+
};
|
|
35
|
+
const json = (value) => ({
|
|
36
|
+
content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
|
|
37
|
+
});
|
|
38
|
+
// A malformed escape stays as written, so the lookup reports it not found.
|
|
39
|
+
const decode = (v) => {
|
|
40
|
+
const s = String(v);
|
|
41
|
+
try {
|
|
42
|
+
return decodeURIComponent(s);
|
|
43
|
+
}
|
|
44
|
+
catch {
|
|
45
|
+
return s;
|
|
46
|
+
}
|
|
47
|
+
};
|
|
48
|
+
const resource = (uri, value) => ({
|
|
49
|
+
contents: [
|
|
50
|
+
{
|
|
51
|
+
uri: uri.href,
|
|
52
|
+
mimeType: 'application/json',
|
|
53
|
+
text: JSON.stringify(value, null, 2),
|
|
54
|
+
},
|
|
55
|
+
],
|
|
56
|
+
});
|
|
57
|
+
/**
|
|
58
|
+
* An MCP server whose tools and resources answer from `knowledge`. Connect it
|
|
59
|
+
* with {@link connectPithyServer}, which guards every tool's input.
|
|
60
|
+
*
|
|
61
|
+
* @param knowledge - The snapshot (public mode) or a live build (repo mode).
|
|
62
|
+
* @returns The server, not yet connected.
|
|
63
|
+
*/
|
|
64
|
+
/** @codexApi {"parent":"pithy.mcp.server","name":"createPithyServer","stability":"experimental","signature":"(knowledge: Knowledge) => McpServer"} */
|
|
65
|
+
export function createPithyServer(knowledge) {
|
|
66
|
+
const k = knowledge;
|
|
67
|
+
const server = new McpServer({ name: 'pithyjs', version: VERSION }, {
|
|
68
|
+
instructions: 'PithyJS framework knowledge. Answers carry citations; a "found: false" result means the knowledge has no such thing, so do not guess. Scaffold tools return files and write nothing.',
|
|
69
|
+
});
|
|
70
|
+
// The SDK's generic signatures exhaust the root tsconfig's checker
|
|
71
|
+
// (TS2589, then out of memory), so registration goes through these.
|
|
72
|
+
const register = server.registerTool.bind(server);
|
|
73
|
+
const tool = (name, description, inputSchema, run) => register(name, { description, inputSchema, annotations: READ_ONLY }, run);
|
|
74
|
+
const readable = server.registerResource.bind(server);
|
|
75
|
+
tool('search', 'Search PithyJS entries, APIs and ui-kit components. Hits carry citations.', {
|
|
76
|
+
query: z.string().min(1).max(500),
|
|
77
|
+
limit: z.number().int().min(1).max(MAX_SEARCH_LIMIT).optional(),
|
|
78
|
+
}, ({ query, limit }) => json({ results: search(k, query, limit ?? 10) }));
|
|
79
|
+
tool('get_api', 'Look up a Codex entry by id (e.g. "pithy.babel.validate-template") or an API by name (e.g. "validateTemplate"): signature, docs, examples from @codex:example tests, citations.', { query: z.string().min(1).max(300) }, ({ query }) => json(getApi(k, query)));
|
|
80
|
+
tool('get_component', 'Get a ui-kit component\'s PIDL spec (props, slots, tokens, a11y, AI guidance) by name, e.g. "Button".', { name: z.string().min(1).max(200) }, ({ name }) => json(getComponent(k, name)));
|
|
81
|
+
tool('get_tokens', 'List design-system token names, optionally one family such as "color", "space" or "radius".', { category: z.string().max(50).optional() }, ({ category }) => json(getTokens(k, category)));
|
|
82
|
+
tool('validate_template', "Check html`` templates in a .ts module, or a .pithy file, for component attributes that will not reach the component as meant (the Vite plugin's check).", {
|
|
83
|
+
code: z.string().max(1_000_000),
|
|
84
|
+
filename: z.string().max(500).optional(),
|
|
85
|
+
}, async ({ code, filename }) => json(await checkTemplate(code, filename)));
|
|
86
|
+
tool('check_tokens', 'Check CSS/SCSS for unknown design tokens (with did-you-mean), raw colors (hex, rgb(), hsl(), oklch()…) and physical properties (margin/padding/border sides and corner radii, inset sides, width/height, and left/right in text-align, float and clear).', { css: z.string().max(1_000_000) }, ({ css }) => json(checkTokens(css, k.tokens.names)));
|
|
87
|
+
tool('validate_pidl', 'Validate a PIDL component spec (object or JSON text).', { spec: z.unknown() }, ({ spec }) => json(validatePidl(spec)));
|
|
88
|
+
tool('explain_error', 'Explain a PithyJS error or warning message from a curated catalog that cites where each is emitted.', { message: z.string().min(1).max(10_000) }, ({ message }) => json(explainError(k, message)));
|
|
89
|
+
tool('scaffold_route', 'Files for a route under src/routes (page.ts, optional loader.ts and layout.ts). Returns { files: [{ path, contents }] }; writes nothing.', {
|
|
90
|
+
path: z.string().max(300),
|
|
91
|
+
options: z
|
|
92
|
+
.object({
|
|
93
|
+
loader: z.boolean().optional(),
|
|
94
|
+
layout: z.boolean().optional(),
|
|
95
|
+
})
|
|
96
|
+
.optional(),
|
|
97
|
+
}, ({ path, options }) => json(scaffoldRoute(path, options)));
|
|
98
|
+
tool('scaffold_component', 'Files for a ui-kit-composed component: .ts returning { el, destroy }, token-only SCSS and a .pidl.json. Returns { files }; writes nothing.', {
|
|
99
|
+
name: z.string().max(64),
|
|
100
|
+
kind: z.enum(['atom', 'molecule', 'organism', 'section']).optional(),
|
|
101
|
+
}, ({ name, kind }) => json(scaffoldComponent(name, kind, takenComponentNames(k))));
|
|
102
|
+
readable('entry', new ResourceTemplate('pithy://entry/{id}', { list: undefined }), {
|
|
103
|
+
description: 'A Codex entry as get_api returns it.',
|
|
104
|
+
mimeType: 'application/json',
|
|
105
|
+
}, (uri, { id }) => resource(uri, getApi(k, decode(id))));
|
|
106
|
+
readable('component', new ResourceTemplate('pithy://component/{name}', { list: undefined }), {
|
|
107
|
+
description: "A component's PIDL spec as get_component returns it.",
|
|
108
|
+
mimeType: 'application/json',
|
|
109
|
+
}, (uri, { name }) => resource(uri, getComponent(k, decode(name))));
|
|
110
|
+
readable('tokens', 'pithy://tokens', {
|
|
111
|
+
description: 'Every design-system token name.',
|
|
112
|
+
mimeType: 'application/json',
|
|
113
|
+
}, uri => resource(uri, getTokens(k)));
|
|
114
|
+
return server;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* Connects `server` to `transport` through {@link guardTransport}, so every
|
|
118
|
+
* tool call's raw arguments pass `guardInput` before any schema parses them.
|
|
119
|
+
*
|
|
120
|
+
* @param server - From {@link createPithyServer}.
|
|
121
|
+
* @param transport - Stdio, or an in-memory transport in tests.
|
|
122
|
+
*/
|
|
123
|
+
/** @codexApi {"parent":"pithy.mcp.server","name":"connectPithyServer","stability":"experimental","signature":"(server: McpServer, transport: Transport) => Promise<void>"} */
|
|
124
|
+
export function connectPithyServer(server, transport) {
|
|
125
|
+
return server.connect(guardTransport(transport));
|
|
126
|
+
}
|